Permission-filtered metadata delivery¶
Issue #116 adds the ui-metadata-delivery crate and two authenticated runtime
endpoints:
GET /api/v1/workspaces/{workspace}/ui/pages/{page}GET /api/v1/workspaces/{workspace}/ui/resources/{resource}
The delivery service is injected with a UiSnapshotSource and requires a
membership-derived UiCaller. The API's source is UiSnapshotProvider
(apps/api/src/ui_snapshots.rs), built from durable state on every request:
- Linked UI, not loose files. A native plugin's artifact digest covers its
linked code, so its UI documents are compiled in (
NativeUiPlugin). At startupplugin_runtime_native::verify_ui_pluginrequires every declared document to be linked exactly once, nothing undeclared, the declared ids and owner, and a valid bundle. The bundle must also install on a catalogue with the host component registry. A failure stops the API from starting. - Per-workspace catalogue. Only plugins active in the workspace, per the activation projection, contribute. The linked version and declared document set must also match the active, digest-verified manifest exactly. A skewed plugin's pages stay unavailable rather than being served from mismatched metadata. Catalogues are cached per distinct set of active packages.
- Published customisations. The workspace's published page patches and
publication generations come from
ui_metadata_page_state. - Priming. Delivery is synchronous, so each page, resource, preview, and
publication request first builds the snapshot asynchronously. A store
failure answers 503 (
temporarily-unavailable), never stale or partial metadata.
HOST_COMPONENTS mirrors the web host registry
(apps/web/src/plugin-ui/renderer/hostComponents.tsx), and a unit test fails
when they drift. It does not fall back to the demo user or an in-memory plugin
set.
Security filtering¶
Resolution happens first against the workspace's enabled catalogue and published tenant patches. Before serialization, the service:
- removes resources without an allowed operation for the current host;
- removes fields, relationships, operations, data sources, and actions whose permissions are absent;
- removes nodes bound to forbidden fields, data sources, or actions;
- evaluates and removes permission predicates, applying their resulting visible, enabled, read-only, or required state without returning permission names; and
- strips all remaining permission annotations.
Caller-safe resource DTOs deliberately have no permission property. Missing, disabled, non-member, and denied pages all return the same 404 code and detail. Incompatible, conflicted, and temporarily unavailable outcomes use stable, redacted categories without workspace, plugin, page, field, or action names.
Cache and conditional requests¶
The private cache key includes:
- workspace and target;
- a SHA-256 fingerprint of user, membership version, roles, and permissions;
- locale, host, mode, form factor, audience, subtype, and record context; and
- catalogue and publication generations.
Consequently, users and permission sets cannot reuse one another's entries.
ETags include the filtered response, the security fingerprint, and both
generations. A 304 is returned only when If-None-Match equals the current
caller's current authorized ETag. Responses use
private, max-age=0, must-revalidate.
Generation changes naturally miss stale entries. Lifecycle and publication
adapters should also call invalidate_workspace after a committed state change
to bound memory and remove superseded entries immediately.
Operations and observability¶
Readiness exposes only a boolean provider state and cache entry count. Delivery observations contain kind, outcome category, cache result, definition version, and elapsed time; their type has no tenant, caller, permission, record, field, or page value. HTTP request tracing may correlate the observation through the existing request ID without logging metadata values.
The TypeScript mirror in plugin-ui/contracts.ts checks the Rust response shape.
Integration tests cover permission separation, ETag isolation, 304 behavior,
locale, form factor, role, host, membership denial, lifecycle disablement,
publication/catalogue generations, resource filtering, readiness, and stable
failure categories.