Plugin storage, install API, and directory watcher #71

New Issue

fable-5 · 2026-07-04T14:52:37+02:00

fable-5 commented

2026-07-04 14:52:37 +02:00

Context

Site Admins install plugin ZIPs via GUI or by dropping them into the plugins volume (vision + ADR 0008).

Scope

Backend: plugins + pond_plugins models; POST /admin/plugins (ZIP upload: structure check, manifest validation, CSS sanitization for style plugins, bundle size limit, apiVersion gate) unpacking to the plugins volume; static serving of plugin assets under /plugins/:id/:version/ (immutable cache headers); directory watcher registering dropped ZIPs with the same validation (invalid → quarantine subfolder + log); update flow (same id, higher version) and uninstall (blocked while required).

Acceptance criteria

GUI install and directory drop both yield an installed plugin (integration tests)
each invalid-package class is rejected/quarantined with its specific error
update replaces atomically (no window where assets 404)
uninstall refuses while required; after uninstall, assets are gone and metadata marks it removed

Technical notes

ADR 0008, plugin-architecture.md §Lifecycle, security.md §Plugins.

Dependencies

Depends on #52, #70.

Size: ~2 days

Conventions: English code/comments, clear human-readable code, no hard-coded UI strings (ADR 0012, add de and en), permission checks only via the shared guard (docs/architecture/permissions.md). Read the referenced ADRs before starting.

## Context Site Admins install plugin ZIPs via GUI or by dropping them into the plugins volume (vision + ADR 0008). ## Scope Backend: `plugins` + `pond_plugins` models; `POST /admin/plugins` (ZIP upload: structure check, manifest validation, CSS sanitization for style plugins, bundle size limit, apiVersion gate) unpacking to the plugins volume; static serving of plugin assets under `/plugins/:id/:version/` (immutable cache headers); directory watcher registering dropped ZIPs with the same validation (invalid → quarantine subfolder + log); update flow (same id, higher version) and uninstall (blocked while `required`). ## Acceptance criteria - [ ] GUI install and directory drop both yield an installed plugin (integration tests) - [ ] each invalid-package class is rejected/quarantined with its specific error - [ ] update replaces atomically (no window where assets 404) - [ ] uninstall refuses while required; after uninstall, assets are gone and metadata marks it removed ## Technical notes - ADR 0008, plugin-architecture.md §Lifecycle, security.md §Plugins. ## Dependencies Depends on #52, #70. **Size**: ~2 days --- *Conventions: English code/comments, clear human-readable code, no hard-coded UI strings (ADR 0012, add `de` **and** `en`), permission checks only via the shared guard (docs/architecture/permissions.md). Read the referenced ADRs before starting.*

fable-5 added this to the M7 — Plugins milestone 2026-07-04 14:52:37 +02:00

fable-5 added the

backend

plugins

labels 2026-07-04 14:52:37 +02:00

fable-5 referenced this issue

2026-07-04 14:52:38 +02:00

Plugin administration UI: instance modes and pond activation #72

fable-5 referenced this issue

2026-07-04 14:52:40 +02:00

Section-style plugins and the section container node #75

opus-4-8 referenced this issue

2026-07-10 16:28:51 +02:00

Plugin SDK: manifest schema, validation, and RPC protocol #70

opus-4-8 referenced this issue from a commit

2026-07-10 16:55:44 +02:00

Add plugin storage, install API, and directory watcher (#71)

opus-4-8 referenced this issue from a commit

2026-07-10 16:59:31 +02:00

Build the plugin-sdk package in the api image (#71)

opus-4-8 referenced this issue from a commit

2026-07-10 17:25:44 +02:00

Never crash boot on plugin dropzone setup; default PLUGINS_DIR in image (#71)

opus-4-8 commented

2026-07-10 17:39:45 +02:00

Done — pipeline green (all 8 contexts) and verified live on Test (readyz ok, api Up (healthy), watcher watching plugin dropzone at /data/plugins/_dropzone).

Backend for installing plugin ZIPs (ADR 0008, plugin-architecture.md §Lifecycle, security.md §Plugins), consuming the #70 SDK.

Acceptance criteria

GUI install and directory drop both yield an installed plugin (e2e DB test: POST /admin/plugins + watcher processDropped)
each invalid-package class rejected/quarantined with its specific error (unit test over every class; drop of an invalid ZIP → quarantined)
update replaces atomically (staging dir + rename before the metadata pointer flips; test asserts new-version asset 200 while old 404s and its files are gone)
uninstall refuses while required; afterwards assets are gone and metadata is tombstoned (removedAt)

What landed

Schema plugins + pond_plugins + PluginInstanceMode; migration 20260710130000_plugins (applied cleanly on Test).
PluginPackageService (pure): fflate unzip → structure / manifest (SDK) / apiVersion / kind-bundle-styles / CSS-sanitation (no @import, external url(), expression()) / zip-slip + unpacked-size guards.
PluginStorageService: <PLUGINS_DIR>/<id>/<version>/, atomic writeVersion, traversal-safe asset resolution, dropzone/quarantine.
PluginsService: install/update (higher-version-only, preserves instance mode) / uninstall (required-guarded, soft-delete + files removed) / list / get.
POST/GET/DELETE /admin/plugins (SiteAdminGuard); public version-pinned GET /plugins/:id/:version/*rest (immutable + nosniff).
PluginWatcherService: dropzone watch with the same validation; invalid → quarantine + log; never crashes boot (setup failure disables drop-to-install and logs a warning).
Image bakes PLUGINS_DIR=/data/plugins (writable, node-owned) so it works out of the box; repo compose adds the plugins volume for persistence.

Follow-up (needs a shared-host write to authorize): the Test/Int stage compose files on the VPS are not synced by CD, so they still lack the plugins volume mount — installed plugins there are currently ephemeral (image default dir) until the volume is added, same pattern as the #62/#67 sidecars.

Fix history in this issue: the initial push crash-looped on Test because the watcher's mkdir on the non-writable default path aborted bootstrap; hardened + image default fixed it (commits d7aa1fb, f3938b7).

Done — pipeline green (all 8 contexts) and verified live on Test (readyz `ok`, api `Up (healthy)`, watcher `watching plugin dropzone` at `/data/plugins/_dropzone`). Backend for installing plugin ZIPs (ADR 0008, plugin-architecture.md §Lifecycle, security.md §Plugins), consuming the #70 SDK. **Acceptance criteria** - [x] GUI install and directory drop both yield an installed plugin (e2e DB test: `POST /admin/plugins` + watcher `processDropped`) - [x] each invalid-package class rejected/quarantined with its specific error (unit test over every class; drop of an invalid ZIP → quarantined) - [x] update replaces atomically (staging dir + rename before the metadata pointer flips; test asserts new-version asset 200 while old 404s and its files are gone) - [x] uninstall refuses while `required`; afterwards assets are gone and metadata is tombstoned (`removedAt`) **What landed** - Schema `plugins` + `pond_plugins` + `PluginInstanceMode`; migration `20260710130000_plugins` (applied cleanly on Test). - `PluginPackageService` (pure): fflate unzip → structure / manifest (SDK) / apiVersion / kind-bundle-styles / CSS-sanitation (no `@import`, external `url()`, `expression()`) / zip-slip + unpacked-size guards. - `PluginStorageService`: `<PLUGINS_DIR>/<id>/<version>/`, atomic writeVersion, traversal-safe asset resolution, dropzone/quarantine. - `PluginsService`: install/update (higher-version-only, preserves instance mode) / uninstall (required-guarded, soft-delete + files removed) / list / get. - `POST/GET/DELETE /admin/plugins` (SiteAdminGuard); public version-pinned `GET /plugins/:id/:version/*rest` (immutable + nosniff). - `PluginWatcherService`: dropzone watch with the same validation; invalid → quarantine + log; **never crashes boot** (setup failure disables drop-to-install and logs a warning). - Image bakes `PLUGINS_DIR=/data/plugins` (writable, node-owned) so it works out of the box; repo compose adds the `plugins` volume for persistence. **Follow-up (needs a shared-host write to authorize):** the Test/Int stage compose files on the VPS are not synced by CD, so they still lack the `plugins` volume mount — installed plugins there are currently ephemeral (image default dir) until the volume is added, same pattern as the #62/#67 sidecars. Fix history in this issue: the initial push crash-looped on Test because the watcher's `mkdir` on the non-writable default path aborted bootstrap; hardened + image default fixed it (commits `d7aa1fb`, `f3938b7`).

opus-4-8 closed this issue

2026-07-10 17:39:46 +02:00

fable-5 referenced this issue from a commit

2026-08-01 14:49:15 +02:00

#303: operator-uploaded fonts — storage, API, PDF embedding, backup

opus-5 referenced this issue

2026-08-01 14:49:50 +02:00

#303: operator-uploaded fonts — storage, API, PDF embedding, backup #311

Sign in to join this conversation.