openmaic-custom/packages/@openmaic/storage/docs/runtime-http-contract.md
wyuc 5cef056d17
feat(storage): server-backed documents — HTTP contract, Postgres backend, one reference server for both stores (#979)
* ci: whitelist the document-server-backend integration trunk

* feat(storage): DocumentStore HTTP contract + client + reference-server routes (1B PR1) (#975)

Mirrors the runtime line's server-backed delivery for the document store:
a documented /documents HTTP contract (validation/not-found/FUTURE_VERSION
taxonomy; authorization stays a deployment concern via injected hooks with
an any-authenticated default), an HttpDocumentStore that runs the same
validators and migrate-on-read semantics as the browser backend before and
after the wire, and document routes on the shared reference server — one
server, both stores. The backend-agnostic document contract suite now runs
against HTTP → reference server → browser store.

Co-authored-by: Codex <codex@openai.com>

* ci: whitelist the trunk in the storage PG contract workflow too

* feat(storage): PgDocumentStore — Postgres document backend (1B PR2) (#976)

Implements the full DocumentStore contract over document_stages /
document_scenes / document_outlines, reusing the pure adapter split so
every backend shares one aggregate semantics: saveDocument replaces the
aggregate in one transaction under the stage row's FOR UPDATE lock
(vanished scenes deleted, outline row added/removed — omission means
deletion), incremental putStage/putScene/deleteScene take the same
current-version gate as the browser backend, loads read FOR SHARE and
migrate without writing back, listings never touch content, and deletes
cascade by FK. The document contract suite is PG-gated the same way the
runtime one is; local coverage comes from stubbed-queryable unit tests.

Co-authored-by: Codex <codex@openai.com>

* feat(document-store): sealed bootstrap injection seam for the document backend (1B PR3) (#977)

configureDocumentStorage mirrors the runtime seam: module-level bootstrap
injection sealed after first resolution, a factory that receives the app
validators so a server-backed store cannot silently skip them, and
reset-for-tests wiring. A deployment swaps the browser document backend
for HttpDocumentStore without touching app code. Storage README roadmap
updated — the document HTTP/PG backend items are done.

Co-authored-by: Codex <codex@openai.com>

* fix(storage): 1B final-review hardening — error classification, JSON-safety, body limits, parity coverage (#978)

Unversioned legacy incremental writes classify as 400 instead of leaking a
500; document/scene reads assert JSON safety before serialization so a
structured-clone value fails loud (500 NOT_JSON_SAFE naming the path)
instead of silently converting; a shared streaming body reader bounds
request bodies (default 32 MiB, 413 PAYLOAD_TOO_LARGE, option exposed
through every handler factory); the putStage stale/future guards and
corrupt-stamp listing tolerance move into the shared contract suite so all
four backends prove them; both HTTP store errors retain structured details.

Co-authored-by: Codex <codex@openai.com>

* refactor(storage): typed document version/not-found errors replace prose classification (#980)

DocumentVersionError (future | not-current, storedVersion) and
DocumentNotFoundError now carry the classification the server previously
regex-derived from message prose — instanceof matching mirrors the runtime
sibling's RuntimeAppendConflictError pattern, so a wording change can no
longer silently break status mapping. The prose fallback remains, after
the typed checks, solely for third-party DocumentStore implementations.
The HTTP client rematerializes 409s as DocumentVersionError for symmetry,
and http.ts's private validator fields are renamed to match the public
option names all three backends already share.

Co-authored-by: Codex <codex@openai.com>

---------

Co-authored-by: Codex <codex@openai.com>
2026-07-23 12:56:26 +08:00

9.5 KiB

RuntimeStore HTTP contract

This contract exposes the complete RuntimeStore interface over JSON HTTP. All paths below are relative to a deployment-defined base URL. Path segments and query parameter values are percent-encoded UTF-8 strings. Identifiers used as path segments MUST NOT be exactly . or .., because URL parsers normalize those dot segments before routing. Request and response bodies use application/json; successful operations with no return value respond with 204 No Content.

Endpoints

Method Path Purpose Success
POST /runtime/sessions Create a session from a RuntimeSessionInit. The server stamps runtimeDslVersion; a client-submitted value is ignored. 201 with the full RuntimeSession
GET /runtime/sessions/{sessionId} Get one session. 200 with the RuntimeSession, or 404 if absent
PATCH /runtime/sessions/{sessionId}/status Set status from { "status", "updatedAt", "expectedLastSeq"? }. expectedLastSeq is a non-negative integer or null. 204
DELETE /runtime/sessions/{sessionId} Delete a session and all of its records. 204
GET /runtime/stages/{stageId}/learners/{learnerKey}/sessions List a partition's sessions, ordered by the instant represented by createdAt, then by id for deterministic ties. 200 with RuntimeSession[]
POST /runtime/sessions/{sessionId}/records Append a RuntimeRecordInit plus optional top-level expectedLastSeq and sessionTransition; body sessionId must match the path. 201 with the full RuntimeRecord
GET /runtime/sessions/{sessionId}/records List records ordered by seq. Optional ?sceneId={sceneId} returns only records anchored to that scene and excludes unanchored records. 200 with RuntimeRecord[]
POST /runtime/learners/merge Atomically re-key all sessions across all stages from { "fromLearnerKey", "toLearnerKey" }. 200 with { "moved": number }
DELETE /runtime/stages/{stageId}/learners/{learnerKey} Delete one learner's sessions and records on one stage. 204
DELETE /runtime/stages/{stageId} Cascade-delete every learner's sessions and records on one stage. 204
DELETE /runtime Delete every runtime session and record. Idempotent; an administrative operation — servers MUST gate it behind an operator-level authorization check, never expose it to learner credentials. 204

GET /runtime/sessions/{sessionId}/records returns an empty array when the session has no records, matching RuntimeStore.listRecords. For an absent session a server MAY answer 404 SESSION_NOT_FOUND instead of 200 [] — authorization-aware servers SHOULD, so absent and unowned sessions are indistinguishable — and the client MUST map that 404 back to an empty array, preserving the store contract. Deleting an absent target succeeds.

Server-assigned sequence

seq is server-assigned. The append request body is a RuntimeRecordInit. If it includes seq, that value is ignored; the store's assigned value is authoritative. The server allocates the next per-session monotonic sequence number atomically with the insert, starting at 0, and the response returns the full RuntimeRecord, including the assigned seq.

Likewise, runtimeDslVersion is server-assigned when a session is created. If the request body includes runtimeDslVersion, that value is ignored; the store's assigned value is authoritative.

Compare guards and session transitions

expectedLastSeq is an optional compare-and-swap guard shared by status updates and record appends. A non-negative integer means the caller observed that sequence at the record tail; null means the caller observed no records. Omission means no precondition. The server compares the value with the actual tail inside the same transaction as the write. A mismatch commits neither the status update nor the append and returns 409 RUNTIME_APPEND_CONFLICT with the expected and actual tails in error.details.

An append may also include a top-level sessionTransition object with { "status", "updatedAt" }. The server validates and commits the completed parent session in the same transaction as the record. A tail conflict or validation failure persists neither change. For example:

{
  "id": "record-1",
  "sessionId": "session-1",
  "createdAt": "2026-01-01T00:00:00.000Z",
  "payload": null,
  "expectedLastSeq": null,
  "sessionTransition": {
    "status": "completed",
    "updatedAt": "2026-01-01T00:00:01.000Z"
  }
}

Payload domain

HTTP implementations carry record payloads through JSON and therefore MUST accept only plain JSON values that survive serialization without changing meaning. They MUST fail loud before sending values such as Map, Set, Date, non-finite numbers, negative zero, nested undefined, bigint, sparse arrays, symbol-keyed properties, non-enumerable properties, arrays with non-index own properties, strings containing U+0000, class instances, and circular references. U+2028 and U+2029 are valid JSON string contents and MUST be accepted. This is intentionally narrower than BrowserRuntimeStore, whose structured-clone persistence can preserve values such as Map, Set, and Date that JSON cannot.

The reference handler streams request bodies into a bounded buffer. maxBodyBytes configures the bound on the runtime, composed-storage, and reference-server factories; it defaults to 32 MiB. A body that crosses the bound is rejected immediately with 413 PAYLOAD_TOO_LARGE.

learnerKey security model

learnerKey appears in paths, query parameters, and request bodies, but the server MUST derive or verify learnerKey from the authenticated session and MUST NOT blindly trust the client-submitted value. learnerKey is an opaque partition key, not proof of identity or authorization; trusting it verbatim creates a lateral-authorization vulnerability that lets one learner read, merge, or delete another learner's runtime data. The same rule applies to both keys in mergeLearner; authorization policy must explicitly permit the authenticated principal to migrate the source partition into the destination partition.

The conformance server in this package is test-only and does not implement an authentication or authorization model; deriving learnerKey from authentication is left to the reference server in #939 Part D.

Errors

Every non-2xx response has this machine-readable JSON shape:

{
  "error": {
    "code": "VALIDATION_FAILED",
    "message": "@openmaic/storage: invalid runtime session ...",
    "details": []
  }
}

details is optional. message preserves the semantic wording of the backing store error so an HTTP client can reconstitute the fail-loud exceptions callers receive from BrowserRuntimeStore.

Condition HTTP status Error code Client behavior
Malformed JSON, an invalid envelope or payload, invalid learner keys, a body/path mismatch, or append to a non-active session 400 VALIDATION_FAILED Throw HttpRuntimeStoreError (an Error) with the server message
Request body exceeds maxBodyBytes 413 PAYLOAD_TOO_LARGE Throw HttpRuntimeStoreError
Session does not exist 404 SESSION_NOT_FOUND getSession returns undefined; operations that require the session throw HttpRuntimeStoreError with the browser store's no session semantics
Route does not exist 404 ROUTE_NOT_FOUND Throw HttpRuntimeStoreError
A stored session has a future runtime DSL version 409 FUTURE_VERSION Throw HttpRuntimeStoreError with the browser store's fail-loud newer than this client's semantics
Session id already exists 409 SESSION_ALREADY_EXISTS Throw HttpRuntimeStoreError with the browser store's already exists semantics
expectedLastSeq does not match the current record tail 409 RUNTIME_APPEND_CONFLICT Reconstitute and throw RuntimeAppendConflictError with sessionId, expectedLastSeq, and actualLastSeq from error.details
Unexpected server failure 500 INTERNAL_ERROR Throw HttpRuntimeStoreError

The client MUST use the machine-readable code, not status alone, when an operation has special behavior. In particular, only SESSION_NOT_FOUND is translated to undefined by getSession. Sessions returned by reads MUST be forward-migrated through the client's migrateRuntime before they are returned, because the server may lag the client schema version. Corrupt sessions remain fail-loud on direct reads and are omitted from partition listings, matching BrowserRuntimeStore.

Retry and atomicity guarantees

mergeLearner, DELETE /runtime/sessions/{sessionId}, DELETE /runtime/stages/{stageId}/learners/{learnerKey}, and DELETE /runtime/stages/{stageId} MUST be safely retryable. Repeating a completed merge moves 0; repeating a delete succeeds with 204. A merge is atomic across every matching source session and MUST NOT expose a partial move. Delete endpoints cascade atomically to the target sessions' records.

The test-only conformance server may report a future-stamped-row conflict encountered mid-merge as 500 INTERNAL_ERROR; structured classification of that specific case is deferred to the real Part D server implementation.

POST /runtime/sessions and record append are not implicitly retry-safe: clients must not retry them after an ambiguous transport failure unless a deployment adds a separate idempotency-key policy. Session ids and record ids remain caller-owned uniqueness keys, while record seq remains exclusively server-owned.