page-specs Specification
Purpose
Pages as data: a JSON envelope over a catalog of safe components, fed only by declared data sources, validated alike by every client; built-in, user and per-context shared pages. Rationale: app#11.
Requirements
Requirement: Page Envelope
A page SHALL be a JSON document {version, name, title, sources, spec}: version the envelope version (an integer, 1 for this spec), name a stable identifier (lower-case letters, digits and _, at most 32, with a letter: the naming library's identifier once upper-cased), title what the client shows, sources the page's data sources (Data Sources), and spec a json-render spec, a flat map of elements (root, elements with type, props, children, visible, on, repeat, watch, and an optional initial state) whose values bind to page state by JSON Pointer. A client SHALL refuse a page of an envelope version it does not know and say so. The envelope SHALL be the only page format clients exchange, so a renderer can change without changing pages.
Scenario: Unknown envelope version
- WHEN a client loads a page with
version2 and knows only version 1 - THEN it SHALL not render the page and SHALL say that the page needs a newer client
Requirement: Catalog Contract
The components a page may use SHALL form a catalog: each component has a name and a JSON Schema of its props, and the catalog SHALL be published as JSON Schema so every client validates pages alike. A component SHALL never render markup taken from a page. A client SHALL render the components it supports; a component it does not support SHALL show a placeholder naming it, and the rest of the page SHALL work.
Scenario: A component the client lacks
- WHEN a page uses a catalog component the client cannot draw
- THEN the client SHALL show a placeholder with the component's name in its place and render the other elements
Requirement: Data Sources
A page SHALL get its data only from the sources it declares, by id, of three kinds:
- invoke: a backend read through the gateway (operator-clients, Backend Access through the Gateway): a service and a method whose name starts with List or Get, a request, and refreshOn, the events after which it is read again;
- state: a state key;
- topic: a subscription keeping the latest value (keep: latest) or the last N values (keep: {last: N}).
Topic and key names SHALL be given as a naming-library reference, never as literal strings: {entity, event, params} for a topic (an entity of a naming fragment, one of its events, and the identity parameters, e.g. {"entity": "virtufin.service.workmanager/worker", "event": "lifecycle"}) and {entity, params} for a state key. refreshOn lists such topic references. A client SHALL put each source's current result into page state at /sources/<id> as {status, data, error, since} (status one of loading, ready, stale, failed), keep it current from events, not by reading on a timer (operator-clients, Pushed Data, Not Polling), and drop and resolve every source again on a context switch. A page SHALL open at most a configured number of subscriptions; a page asking for more SHALL be refused by validation.
Scenario: A backend list
- WHEN a page declares
{"workers": {"invoke": {"service": "workmanager", "method": "ListWorkers", "refreshOn": [{"entity": "virtufin.service.workmanager/worker", "event": "lifecycle"}]}}} - THEN
/sources/workers/dataSHALL hold the workers, read again after each listing change on the lifecycle topic
Scenario: A write method as a source
- WHEN a page declares an
invokesource with methodStopWorker - THEN validation SHALL refuse the page, naming the source
Scenario: A read fails
- WHEN reading a source fails after it had data
- THEN its
statusSHALL bestalewith the reason inerror, anddataSHALL keep the last good result (operator-clients, Error Reporting)
Requirement: Page Actions
A page SHALL trigger only actions of the catalog: json-render's state actions (setState, pushState, removeState) and named actions the client maps to existing operations (start, stop and delete workers, set a tag). Every action that writes SHALL pass the client's write gate (operator-clients, Contexts) and the server's authorization; a page SHALL NOT widen what its user may do. A page SHALL carry no code: computed values SHALL only call functions the client registers, and a page SHALL contain no HTML and no URL outside the client.
Scenario: A reader's page stops a worker
- WHEN a signed-in user who is no admin presses a page's button bound to the stop action
- THEN the write SHALL be refused as any other write of that user is, and nothing SHALL be sent
Requirement: Page Validation
A client SHALL validate a page against the envelope, the catalog and the source rules when it loads it and before it saves it, and report each error with the path of the element or source it concerns. An invalid page SHALL NOT be rendered; its errors SHALL be shown instead.
Scenario: An unknown component
- WHEN a page uses the type
Iframe, which is not in the catalog - THEN validation SHALL fail with an error naming
/spec/elements/<id>/type, and the page SHALL not render
Requirement: Built-in and User Pages
A client's views SHALL be page specs it ships. A user page SHALL be the same kind of document; it SHALL NOT replace a built-in page, and a built-in page MAY be copied as the start of a user page. User pages SHALL be kept per client (per browser in the web app). Shared pages SHALL be kept in the state store under the virtufin.pages/page_registry names (domain-devkit): the envelope under cfg.page.<NAME> (the page name upper-cased) and the shared names in the index cfg.page.index, updated by compare-and-swap on its etag so concurrent shares do not lose one another. Sharing, updating and unsharing a page SHALL be writes (admin only), saved with publish_change, and a client SHALL follow the state-change events (virtufin.service.api/state saved, deleted) to keep the shared pages current, not read them on a timer.
Scenario: Share a page
- WHEN an admin shares the user page
stopped_workers - THEN the client SHALL save its envelope at
cfg.page.STOPPED_WORKERSand addstopped_workerstocfg.page.index, both announcing the change, and every client following the context SHALL list the page
Scenario: A reader cannot share
- WHEN a signed-in user who is no admin tries to share a page
- THEN the write SHALL be refused and nothing saved
Scenario: Copy a built-in page
- WHEN the user copies the built-in Workers page
- THEN a user page with the same envelope and a new name SHALL be created, and the built-in page SHALL stay as it was
Requirement: Page Conformance
The page format SHALL have shared conformance vectors (valid and invalid envelopes, sources and elements with the expected errors) and the catalog's JSON Schema, which every client that renders pages SHALL run and pass.
Scenario: Same verdicts
- WHEN two clients validate the conformance vectors
- THEN both SHALL accept and refuse the same pages with errors at the same paths