Home Explore Help
Sign In
Tilo15
/
Statum
1
0
Fork 0
Files Issues 1 Pull Requests 0 Wiki
Tree: 78c52528b2
Branches Tags
Statum
/
model.md

model.md 4.3 KB
History Raw

Statum Model

Statum Frames

A statum frame consists of a JSON object with three keys:

  • content: a string containing the literal content of the frame.
  • signer: a string containing a signer ID.
  • signature: a base64 encoded signature verifying the content authored by the signer.

Statum Slot

  • key: a server issued ID for the slot.
  • scope: a string value that can be one of:
    • "device": persists between browser sessions.
    • "session": persists within the browser session (e.g. between tabs).
    • "flow": persists only within the current tab, while the tab remains on the site (e.g. persits on between navigation)
    • "page": persists only while the current page is loaded (e.g. clears on navigate).
    • "transient": does not persist, will never get sent back to the server - random or null key each time.
  • type: an application defined type name.

Statum Snapshot

A statum snapshot captures an aspect of the application state at a particular point-in-time. It is usually wrapped in a frame, which must be retained if it is to be sent back to the server after the transmit_after time. It contains:

  • as_at: an ISO 8601 string representing the time the snapshot was authored.
  • slot: a slot object (above)
  • transmit_after: an ISO 8601 string representing the time the slot will no longer be cached by the server and the application will need to send the snapshot. undefined if this is a unidirectional snapshot that never needs to be sent to the server. If it equals as_at, then the snapshot must always be sent.
  • invalid_after: an IOS 8601 string representing the time this snapshot should be considered invalid and not used.
  • private: a base64 encoded string of data only readable by the application server.
  • public: a JSON object with application-defines key/values.

Statum Action

  • uri: The URI to request.
  • method: the HTTP verb to use.
  • private: a base64 encoded string of data only readable by the application server (can be undefined)

Statum Directive

  • type: One of
    • "navigate": Used to redirect the frontend to a new URI.
    • "post": Used to cause the frontend to POST some data to a URI.
    • "set": Used to set a slot to a new snapshot.
    • "clear": Used to clear a slot.

Depending on the type, it will have other properties.

Navigate Directive

  • uri: The URI to navigate to.

Post Directive

  • uri: The URI to perform a form post to.
  • data: Key/value pairs for form data.

Set Directive

  • snapshot_frame: A frame containing a snapshot.

Clear Directive

  • slot_id: The ID of the slot to clear.

Statum HTTP API

Entrypoint Endpoint

GET /_statum/entrypoint: Get initial diretives based on the URL. has query param uri set to the browsers current window.location. Returns a JSON array of Statum Directives.

Slot Post Endpoint

POST /_statum/slots: Send a saved state snapshots frame to the server once it has reached its transmit_after time window. Sent as a JSON array of Statum Frames. Returns a JSON array of Statum Directives.

Action Endpoints

The URLs of action endpoints are entirely defined by the action iteself (in the uri property). An additional X-Statum-Private header should contain the private data of the action if present. Returns a JSON array of Statum Directives.

Request Headers

All HTTP API requests must have a X-Statum-Slot header for each relevant slot snapshot in scope.

There are two variations of this header:

  • For slots that have a snapshot that are within the transmit_after time window, an as_at timestamp is sent, e.g. X-Statum-Slot: key=d3cceb88-c211-41ee-a0b1-6a93f3b6331b; as_at=2026-07-06T07:33:02.332Z.
  • For slots that have a snapshot which has a transmit_after timestamp equal to its as_at timestamp, the frame is sent in base64, e.g. X-Statum-Slot: eyAiY29udGVudCI6ICIuLi4uIiwgInNpZ25lciI6ICJzMSIsICJzaWduYXR1cmUiOiAiZXlBaVkyOXVkR1Z1ZENJNklDSXVMaTR1SWl3Z0luTnBaMjVsY2lJNklDSnpNU0lzSUNKemFXZHVZWFIxY21VaU9pQWlJbjA9In0=

Before an HTTP request is sent, if one or more slot snapshots's transmit_after timestamp is in the past, and it is not equal to its as_at timestamp, a pre-flight request should be made to the slot post endpoint, which will in turn provide updated snapshots and a new as_at timestamp.