strata_client

strata_client is a sans-IO state machine. It encodes outbound Strata frames and decodes inbound frames. The caller owns the WebSocket transport. The package targets JavaScript and Erlang.

Correlated mutations

strata_client/operation adds opt-in request tracking without changing legacy Command and Event types. Construct a request with strata_protocol/operation.request(id, mutation), submit it through an operation session, and feed responses to that session's inbound. It returns either a normal connection event or an operation outcome.

Keep the session across reconnects. resume marks pending requests unknown and returns only join frames. After joins, call retry for an unknown delta or delete. It reuses the exact request ID and payload. Create retries return UnsafeCreateRetry. timed_out marks a local response deadline without claiming rejection; a later receipt can resolve it.

The session holds at most 1024 records. forget releases terminal records, but refuses pending or unknown ones. Do not reuse forgotten IDs. Records are session-local and do not survive browser termination. The server keeps no request-ID deduplication cache.

A rejected retry leaves an earlier ambiguous submission unknown. A known terminal result does not regress when a duplicate or late response arrives. See Protocol for retry, acceptance, and persistence semantics.

State machine

Drive the state machine with a Connection value.

1. Create state with strata_client.new().
2. Pass the current state and a Command to strata_client.outbound().
3. Keep the returned Connection.
4. Send the returned JSON text through your WebSocket.
5. Pass received text to strata_client.inbound().
6. Keep its returned Connection and handle its typed Event.
7. Call strata_client.frames_for_resume() after a reconnect.

Connection functions

• new() -> Connection: Creates a new, empty connection state.
• protocol_version() -> Int: Returns 0.
• is_welcomed(Connection) -> Bool: Reports whether welcome arrived.
• session_id(Connection) -> Option(String): Returns the current socket id.
• server_id(Connection) -> Option(String): Returns the server id.
• joined_documents(Connection) -> List(String): Returns ids joined through this state value.
• outbound(Connection, Command) -> #(Connection, String): Creates an outbound frame. Command includes Join, Leave, SendDelta, SendPresence, Create, Delete, and SendPing.
• inbound(Connection, String) -> Result<#(Connection, Event), StepError>: Processes an inbound frame. Event includes Welcomed, Snapshot, RemoteDelta, Deleted, presence events, ServerError, and Pong.
• frames_for_resume(Connection) -> #(Connection, List<String>): Generates frames to rejoin documents after a reconnect.

outbound updates local join state before a transport sends the returned text. If the send fails, the application must retry or correct its connection state. frames_for_resume keeps joined ids and clears welcome data.

inbound returns ProtocolError(DecodeError) for invalid server text. A server error frame is a successful decode and becomes ServerError(code, message).

Typed multi-document apps: strata_client/page_store

strata_client/page_store gives apps that hold several open documents a typed store, PageStore(page), keyed by document id over the app's own page sum type. The app supplies merge and to_json; page_store.open/close track which ids are open, page_store.update applies a local edit, and page_store.apply_document_event merges an incoming document Event into the right page and closes it on Deleted. See Composing Documents.

page_store.update returns None when the id is not open. apply_document_event returns Result(PageStore(page), ApplyError). ApplyError has three variants:

• NotOpen(document_id) means that the event targets a closed id.
• MergeFailed(document_id, error) preserves the DocumentError.
• NotDocumentEvent means that the event has no document state.

Use apply_event only when you need compatibility with the old no-op behavior. It calls apply_document_event and intentionally returns the unchanged store for every error.