statewire 0.19.4 → 0.21.0

package/src/transports/testing.ts

@@ -5,7 +5,7 @@ import type { StatewireFrame } from "./sse";
 import type { Statewire } from "../types";
 import { openSSEStream, sseFrame } from "./fake-sse";
 import type { FakeStreamHandle } from "./fake-sse";
-import { WIRE_VERSION } from "../wire/protocol";
+import { WIRE_VERSION, parseNegotiation } from "../wire/protocol";
 
 export * from "./fixtures";
 
@@ -19,6 +19,7 @@ export type MockTransport<TState> = {
   transport: ResourceElement<Statewire<TState | undefined, any>>;
   /** Captured statements in arrival order. */
   commands: { protocol: string; method: string; params: unknown[] }[];
+  contexts: NonNullable<StatewireFrame["ctx"]>;
   /** Replace the replicated state and broadcast it as a root snapshot op. */
   setState: (state: TState) => Promise<void>;
   /** Deliver a bare ack cmd packet on the stream. */
@@ -54,6 +55,7 @@ export const createMockTransport = <TState>(
   const clients = new Map<string, Record<string, number>>();
   const streams = new Set<FakeStreamHandle>();
   const commands: MockTransport<unknown>["commands"] = [];
+  const contexts: MockTransport<unknown>["contexts"] = [];
 
   const sendEnvelope = (envelope: StatewireEnvelope) => {
     for (const stream of streams) stream.send(sseFrame(envelope));
@@ -62,6 +64,7 @@ export const createMockTransport = <TState>(
 
   const admit = (id: string, frame: StatewireFrame) => {
     const rec = clients.get(id)!;
+    contexts.push(...(frame.ctx ?? []));
     for (const statement of frame.cmd ?? []) {
       if (statement.seq <= (rec[statement.protocol] ?? 0)) continue;
       rec[statement.protocol] = statement.seq;
@@ -86,6 +89,13 @@ export const createMockTransport = <TState>(
       if (!clients.has(id)) clients.set(id, {});
       const rec = clients.get(id)!;
       const ephemeral = ephemeralLanes();
+      const offers = parseNegotiation(headers).applicationProtocols;
+      const applicationVersion =
+        offers === "*"
+          ? WIRE_VERSION
+          : offers.find((offer) => offer.name === protocol)?.version;
+      if (applicationVersion === undefined)
+        throw new Error("mock protocol was not offered");
       for (const lane of ephemeral) delete rec[lane];
       const frame = JSON.parse(String(init?.body ?? "{}")) as StatewireFrame;
       admit(id, frame);
@@ -101,12 +111,12 @@ export const createMockTransport = <TState>(
                 protocols: [
                   {
                     name: protocol,
-                    version: WIRE_VERSION,
+                    version: applicationVersion,
                     seq: rec[protocol] ?? 0,
                   },
                   ...ephemeral.map((name) => ({
                     name,
-                    version: WIRE_VERSION,
+                    version: applicationVersion,
                     record: "ephemeral" as const,
                     seq: 0,
                   })),
@@ -132,6 +142,7 @@ export const createMockTransport = <TState>(
       fetch: fakeFetch,
     }),
     commands,
+    contexts,
     setState: (next) => {
       state = next;
       return sendEnvelope({ ops: [{ op: "replace", path: [], value: next }] });

package/src/types.ts

@@ -5,6 +5,7 @@ import type { StatewireClient } from "./statewire";
 import type { StatewirePath } from "./wire/ops";
 
 export namespace Statewire {
+  export type Context = Readonly<Record<string, unknown>>;
   export type Commands = Record<string, (...args: never[]) => unknown>;
 
   export type Command<TCommands extends Commands = Commands> = {
@@ -56,6 +57,17 @@ export interface Statewire<
   state: TState;
   documents?: StatewireDocuments.Source;
   selection?: StatewireProtocol.Selection | undefined;
+  setContext?: (protocol: string, value: Statewire.Context) => void;
+  validateContext?: (
+    protocol: string,
+    value: Statewire.Context,
+    attach: StatewireHost.Attach,
+  ) => void;
+  contextChanged?: (
+    protocol: string,
+    value: Statewire.Context,
+    attach: StatewireHost.Attach,
+  ) => void;
   invoke?: (
     protocol: string,
     method: string,

package/src/wire/context.ts

@@ -0,0 +1,40 @@
+import { decodeDocument, encodeDocument } from "../document";
+import type { Statewire } from "../types";
+import { MAX_CONTEXT_BYTES } from "./limits";
+import { protocolToken } from "./protocol";
+
+const freeze = (value: unknown): void => {
+  if (typeof value !== "object" || value === null) return;
+  for (const child of Object.values(value)) freeze(child);
+  Object.freeze(value);
+};
+
+export const contextValue = (encoded: unknown): Statewire.Context => {
+  const value = decodeDocument(encoded);
+  if (
+    typeof value !== "object" ||
+    value === null ||
+    Array.isArray(value) ||
+    value instanceof Date
+  )
+    throw new TypeError("statewire: context root must be an object");
+  freeze(value);
+  return value as Statewire.Context;
+};
+
+export const encodeContext = (protocol: string, value: Statewire.Context) => {
+  if (!protocolToken.test(protocol))
+    throw new TypeError("statewire: invalid context protocol");
+  const encoded = encodeDocument(value);
+  contextValue(encoded);
+  const entry = { protocol, ...encoded };
+  if (
+    new TextEncoder().encode(JSON.stringify(entry)).byteLength >
+    MAX_CONTEXT_BYTES
+  )
+    throw new TypeError("statewire: context entry too large");
+  return entry;
+};
+
+export const captureContext = (value: Statewire.Context): Statewire.Context =>
+  contextValue(encodeDocument(value));

package/src/wire/limits.ts

@@ -4,3 +4,5 @@ export const MAX_FRAME_BODY_BYTES = 8 * 1024 * 1024;
 export const MAX_EPHEMERAL_DOCUMENT_BYTES = 64 * 1024;
 export const MAX_INFLIGHT_COMMANDS_PER_HOST = 1024;
 export const COMMAND_CAPACITY_RETRY_MS = 1_000;
+
+export const MAX_CONTEXT_BYTES = 64 * 1024;

package/src/wire/protocol.ts

@@ -18,7 +18,7 @@ export namespace StatewireProtocol {
   };
 }
 
-export const WIRE_VERSION = "2026-09-13";
+export const WIRE_VERSION = "2026-09-30";
 export const DEFAULT_PROTOCOL = "default";
 export const PROTOCOL_HEADER = "Statewire-Protocol";
 export const VERSION_HEADER = "Statewire-Version";