diff options
Diffstat (limited to 'docs/apps.md')
| -rw-r--r-- | docs/apps.md | 57 |
1 files changed, 54 insertions, 3 deletions
diff --git a/docs/apps.md b/docs/apps.md index 7ce1e73..7819dc9 100644 --- a/docs/apps.md +++ b/docs/apps.md @@ -146,6 +146,12 @@ 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. @@ -170,6 +176,37 @@ table. Changing it broadcasts `apps_enabled_ack` to everyone already connected 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 one arrives, which `visibleApps` reads as "show everything registered" — a @@ -187,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 @@ -196,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 @@ -216,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 |