diff options
Diffstat (limited to 'docs/apps.md')
| -rw-r--r-- | docs/apps.md | 101 |
1 files changed, 83 insertions, 18 deletions
diff --git a/docs/apps.md b/docs/apps.md index ef8cc1a..7819dc9 100644 --- a/docs/apps.md +++ b/docs/apps.md @@ -130,9 +130,10 @@ any app with similar per-group local state. ## 3. Enable/disable: the mechanism -Same shape as `member_upload` (`meshbay-draft-v6.md` §2.1b) — an +Same shape as a root's `writable` flag (`refactor-groups.md` §1.1) — an operator-signed setting, stored on the node, enforced by absence rather than -by the client's honesty. +by the client's honesty. It used to be described against `member_upload`, +which was the group-wide upload switch; that was removed in the same refactor. **Node side** (`meshbay_node/roster.py`): ```python @@ -145,11 +146,22 @@ async def set_enabled_apps(group_id, apps, set_by="") -> list[str]: ... from exactly one place: `webrtc_server.py`'s `_admin_exec_apps_enabled`, after `_verify_admin_sig` — nothing is applied before the signature checks out. +**An app's directories are the same shape one level down** (2026-09-06): +`ops.set_app_directories(state, group_id, app_key, paths)`, stored under +`<app_key>_directories`, reached by one MNP message (`app_directories`) and one +loopback route. Adding an app adds no function, no message type and no route — +which is what "plugin architecture" has to mean to be worth the phrase. + `_do_apps_enabled` in `webrtc_server.py` validates before it ever issues a challenge: - `apps` non-empty — the operator can never lock a group down to nothing. -- every entry in `WebRTCPeerSession.ALLOWED_APPS` (`{"chat", "files"}` today) - — **this is the line a new app's node-side registration touches.** +- every entry in `WebRTCPeerSession.ALLOWED_APPS` + (`{"chat", "files", "video", "music", "photo"}` today) — **this is the line + a new app's node-side registration touches.** +- `files` is added to the list if it is absent, at both writers + (`_do_apps_enabled` and `ops.set_enabled_apps`, both at the front so the two + agree). It is not a toggle: MNP permits root exploration regardless of what + this list says, so hiding the tab only ever misled. The whole set is signed in one message (`apps_enabled`, `OP_APPS_ENABLED` in `meshbay_common.adminop`) rather than one op per app — ticking several boxes @@ -158,11 +170,42 @@ sorted, comma-joined app list (`"chat,files"`), built the same way on both sides so the operator's browser and the node arrive at identical bytes to sign/verify. -`enabled_apps` rides in `handshake_ack` and `node_status`, next to -`member_upload`. Changing it broadcasts `apps_enabled_ack` to everyone already -connected — `transport.js`'s `onAppsEnabled` — so a disabled tab disappears -without waiting for a reconnection, the same as `member_upload`'s live -broadcast. +`enabled_apps` rides in `handshake_ack` and `node_status`, next to the roots +table. Changing it broadcasts `apps_enabled_ack` to everyone already connected +— `transport.js`'s `onAppsEnabled` — so a disabled tab disappears without +waiting for a reconnection. The root ops (`root_update_ack`, `root_eject_ack`, +`root_plug_ack`) broadcast the same way, through `onRootsChanged`. + +### 3b. An app's settings + +Each app that has settings exports a component from +`static/<app>-app-settings.js` and names it in its `apps.js` entry. The Settings +page renders one collapsible section per registry entry, with the app's own +on/off switch in the header — the toggle *is* the enablement control, rather +than a checkbox list somewhere else that could disagree with it. + +Every pane takes the same props, and nothing else: `roots`, `dirs`, `settings`, +`saveDirectories` (bound to this app), `transport`, `signFn`. The split is the +point — **what every app has, the page does generically; what one app alone +has, the pane does itself.** Pointing an app at folders goes through +`saveDirectories`; a TMDB credential or a link-preview switch is the pane's own +business, made with the transport it is handed. An app that only needs +directories therefore touches neither `group-settings.js` nor `group-page.js`, +and `test_app_settings_plugin.py` fails if either of them starts naming apps +again. + +Two constraints that are not obvious: + +- **A pane must not import `group-settings.js`.** That is a cycle + (`group-settings` → `apps` → pane → `group-settings`), and ES modules answer + it with a temporal-dead-zone `ReferenceError` at first render — the component + does not appear, with nothing in the console to say why. The shared widgets + (`CollapsibleSection`, `ToggleSwitch`, `useSaver`) live in `settings-ui.js` + for this reason. +- **A new module must be added to `_ASSETS`** in `meshbay_hub/api/webapp.py`. + A file reached through the registry is not imported by name anywhere, so + nothing else would notice it changing, and a browser would go on serving the + cached copy. `test_asset_versioning` enforces it. **Client side:** `apps.js`'s `visibleApps(enabledKeys)` filters the registry; `group-page.js` calls it with `enabledApps` state (from the ack, `null` until @@ -181,8 +224,17 @@ registry, so a newly-registered app gets a checkbox for free. `icon.js` — do not re-implement `formatSize`, the download pipeline, or `Icon`. 2. **Register it** in `apps.js`'s `APPS` array: `{ key, icon, labelKey, - Component }`. `key` is the wire identifier — it must match what you add to - the node's allow-list next. + Component, Settings? }`. `key` is the wire identifier — it must match what + you add to the node's allow-list next, and it is also the row an app's + directories are stored under (`<key>_directories`). One identifier per app, + everywhere; `test_app_settings_plugin.py` checks the registry against + `ALLOWED_APPS`. +2b. **`<name>-app-settings.js`**, if the app has anything to configure, + exporting a component that takes `{ roots, dirs, settings, + saveDirectories, transport, signFn }` and nothing else (§3b). Folders go + through `saveDirectories`; anything only this app has, it does itself with + the transport. **Do not import `group-settings.js`** — that is a cycle, and + it fails as a component that silently does not render. 3. **Node-side allow-list**: add the key to `ALLOWED_APPS` in `webrtc_server.py`. Without this the node refuses `apps_enabled` for any set naming it (`"Unknown app(s): ..."`), so an operator can never turn it @@ -190,7 +242,7 @@ registry, so a newly-registered app gets a checkbox for free. 4. **i18n**: at minimum, a `group.tab_<name>` key (the tab's tooltip/label, reused as the Settings checkbox label) in all ten `static/locales/*.js` files. `test_locales.py` holds them to the same key set. -5. **`webapp.py`'s `_ASSETS`** tuple: add the new file. This is the +5. **`webapp.py`'s `_ASSETS`** tuple: add both new files. This is the cache-busting hash's input list — a file imported by the page but missing here can change without the served URL changing, which is the exact bug class `test_asset_versioning.py` exists for. Forgetting this step used to be @@ -210,6 +262,11 @@ registry, so a newly-registered app gets a checkbox for free. No protocol change, no hub change, no `daemon.py` change — steps 3 and 6 are the only node-side touches, and both are allow-lists, not new wire messages. +Directories in particular need nothing server-side at all: `app_directories` is +one generic op keyed by the app's name (§3), and an app storing its folders +under a key nobody wrote code for is the case +`test_app_directories.py::test_an_app_nobody_wrote_code_for_stores_its_directories` +pins. ## 5. What does not exist yet @@ -234,9 +291,17 @@ the only node-side touches, and both are allow-lists, not new wire messages. machinery again; unlike Videos/Music it needs several root folders per group rather than one, has a single album-grid view with no third-party matching step, and reads EXIF locally on the node instead. -- **The offline/loopback settings path.** `member_upload` can be toggled two - ways: over a live MNP connection, or (Electron only) via the node's local - HTTP API when MNP isn't connected (`platform.node.call('PUT', .../member- - upload')`, `group-settings.js`). `apps_enabled` only has the MNP path today. - Adding the loopback twin is a `meshbay_node.ui` endpoint plus a - `group-settings.js` branch, mirroring the existing `member_upload` one. +- **The offline/loopback settings path.** A root's flags can be changed two + ways: over a live MNP connection (any browser, anywhere), or — Electron + only, and only when MNP is not connected — via the node's local HTTP API + (`platform.node.call('PATCH', '/api/groups/<id>/roots/<name>')`, + `SharedDirectoriesTable` in `group-settings.js`). `apps_enabled` only has + the MNP path today. Adding the loopback twin is a `meshbay_node.ui` endpoint + plus a branch in the table's `run()` helper, mirroring the root ops. + + **MNP is the path that must exist, not the fallback.** The operator of a + node is not necessarily sitting at it. The first version of the shared + directories table read its roots exclusively from the loopback API, which + resolves to "not available" in a browser — so the whole section rendered for + nobody on the web, while the controls it replaced had worked there. Any + operator-facing setting added here needs the MNP route first. |