statewire 0.0.2 → 0.0.4

package/src/host/socket.ts

@@ -40,6 +40,7 @@ type Admission = {
 type ClientRec = {
   id: string;
   lastSeq: number;
+  context: Record<string, unknown> | null;
   results: Map<number, { ts: number; res: StatewireResponse }>;
   inflight: Map<number, Admission>;
 };
@@ -51,7 +52,12 @@ type Conn = {
   lastSentAt: number;
 };
 
-type Frame = { method: string; seq: number; params: unknown[] };
+type Frame = {
+  method?: string;
+  seq: number;
+  params: unknown[];
+  context?: unknown;
+};
 
 const parseFrame = (raw: string): Frame | null => {
   let frame: unknown;
@@ -63,9 +69,16 @@ const parseFrame = (raw: string): Frame | null => {
   if (typeof frame !== "object" || frame === null || Array.isArray(frame)) {
     return null;
   }
-  const { method, seq, params, meta } = frame as Record<string, unknown>;
-  if (typeof method !== "string") return null;
+  const { method, seq, params, meta, context } = frame as Record<
+    string,
+    unknown
+  >;
+  if (method === undefined && context === undefined) return null;
   if (typeof seq !== "number" || !Number.isInteger(seq) || seq < 1) return null;
+  if (method === undefined) {
+    return { seq, params: [], ...(context !== undefined && { context }) };
+  }
+  if (typeof method !== "string") return null;
   if (!Array.isArray(params)) return null;
   if (meta !== undefined) {
     try {
@@ -74,7 +87,29 @@ const parseFrame = (raw: string): Frame | null => {
       return null;
     }
   }
-  return { method, seq, params };
+  return { method, seq, params, ...(context !== undefined && { context }) };
+};
+
+/** v1 context submissions are exactly one root replace with an object value. */
+const contextValue = (context: unknown): Record<string, unknown> => {
+  if (!Array.isArray(context) || context.length !== 1) {
+    throw new Error("context must be a single-op array");
+  }
+  const op = context[0] as Record<string, unknown> | null;
+  if (
+    typeof op !== "object" ||
+    op === null ||
+    op["op"] !== "replace" ||
+    !Array.isArray(op["path"]) ||
+    op["path"].length !== 0
+  ) {
+    throw new Error("context op must be a root replace");
+  }
+  const value = op["value"];
+  if (typeof value !== "object" || value === null || Array.isArray(value)) {
+    throw new Error("context value must be an object");
+  }
+  return value as Record<string, unknown>;
 };
 
 const encodePayload = (
@@ -321,15 +356,14 @@ const createSocketHost = (
     return { seq, type: "result-unavailable" };
   };
 
-  const settleWire = (
+  const settleResponse = (
     rec: ClientRec,
     adm: Admission,
-    outcome: CommandsOutcome,
+    response: StatewireResponse,
   ) => {
     if (adm.settled) return;
     adm.settled = true;
     rec.inflight.delete(adm.seq);
-    const response = responseOf(adm, outcome);
     retain(rec, response);
     if (!adm.acked) {
       adm.acked = true;
@@ -346,6 +380,25 @@ const createSocketHost = (
     adm.release();
   };
 
+  const settleWire = (
+    rec: ClientRec,
+    adm: Admission,
+    outcome: CommandsOutcome,
+  ) => settleResponse(rec, adm, responseOf(adm, outcome));
+
+  const callerOf = (rec: ClientRec): StatewireHost.Caller => ({
+    get context() {
+      return rec.context;
+    },
+    get isConnected() {
+      if (clients.get(rec.id) !== rec) return false;
+      for (const conn of conns) {
+        if (conn.clientId === rec.id && conn.open) return true;
+      }
+      return false;
+    },
+  });
+
   const admit = (conn: Conn, frame: Frame): Promise<void> | void => {
     if (!conn.open || disposed || finished !== null) return;
     const rec = clients.get(conn.clientId)!;
@@ -364,20 +417,42 @@ const createSocketHost = (
     }
     const adm: Admission = {
       seq: frame.seq,
-      method: frame.method,
+      method: frame.method ?? "",
       acked: false,
       pendingSent: false,
       settled: false,
       release: () => {},
     };
+    if (frame.context !== undefined) {
+      let value: Record<string, unknown>;
+      try {
+        value = contextValue(frame.context);
+      } catch (error) {
+        rec.inflight.set(frame.seq, adm);
+        settleResponse(rec, adm, {
+          seq: frame.seq,
+          type: "rejected",
+          code: "invalid-context",
+          message: `invalid context: ${(error as Error).message}`,
+        });
+        return;
+      }
+      rec.context = value;
+      if (frame.method === undefined) {
+        rec.inflight.set(frame.seq, adm);
+        settleResponse(rec, adm, { seq: frame.seq, type: "accepted" });
+        return;
+      }
+    }
     const released = new Promise<void>((resolve) => {
       adm.release = resolve;
     });
     rec.inflight.set(frame.seq, adm);
     commandsHost!.submit!({
-      method: frame.method,
+      method: frame.method!,
       params: frame.params,
       clientId: rec.id,
+      caller: callerOf(rec),
       onAck: () => {
         if (adm.settled || adm.acked) return;
         adm.acked = true;
@@ -437,6 +512,7 @@ const createSocketHost = (
           const created: ClientRec = {
             id: clientId,
             lastSeq: 0,
+            context: null,
             results: new Map(),
             inflight: new Map(),
           };

package/src/host.ts

@@ -46,6 +46,17 @@ export namespace StatewireHost {
     reject: (error: unknown) => void;
   };
 
+  /**
+   * The submitting client, bound as `this` of a command handler. Holdable
+   * across a long run: `context` reads the client's current ambient context
+   * live (null until the client sends one), `isConnected` reports whether the
+   * client has an active stream attachment.
+   */
+  export type Caller = {
+    readonly context: Record<string, unknown> | null;
+    readonly isConnected: boolean;
+  };
+
   export type HandledCommands<THandlers extends Statewire.Commands> = {
     [K in keyof THandlers]: (
       ...args: Parameters<THandlers[K]>

package/src/statewire.ts

@@ -8,7 +8,6 @@ import {
 import type { ResourceElement } from "@assistant-ui/tap";
 import { LIVE_CONNECTION, useStatewireCore } from "./client/core";
 import type { Statewire } from "./types";
-import type { ConnectionState } from "./transports/sse";
 import type { StatewireSessionStoreOptions } from "./client/sessionStore";
 
 export const useStatewire = <
@@ -41,8 +40,16 @@ export const useStatewire = <
       getState: core.getState as () => TState,
       connection,
       commands: core.commands as Statewire.CommandsProxy<TCommands>,
+      setContext: (contextValue: Record<string, unknown>) => {
+        if (!value.setContext) {
+          throw new Error(
+            "statewire: this transport has no client context channel",
+          );
+        }
+        return value.setContext(contextValue);
+      },
     }),
-    [state, connection, core],
+    [state, connection, core, value],
   );
 };
 
@@ -80,6 +87,10 @@ export class StatewireClient<
     return this.root.getValue().commands;
   }
 
+  setContext(value: Record<string, unknown>): Promise<unknown> {
+    return this.root.getValue().setContext(value);
+  }
+
   subscribe(listener: () => void): () => void {
     return this.root.subscribe(listener);
   }
@@ -120,8 +131,22 @@ export namespace StatewireClient {
     getState: () => TState;
     connection: Connection;
     commands: Statewire.CommandsProxy<TCommands>;
+    /** Replace this client's ambient context on the server; throws on transports without a client context channel. */
+    setContext: (value: Record<string, unknown>) => Promise<unknown>;
   };
 
+  export type ConnectionState =
+    | { status: "connecting" }
+    | { status: "live" }
+    | {
+        status: "reconnecting";
+        cause: "dropped" | "evicted" | "error";
+        attempt: number;
+        nextRetryAt: number;
+        lastError?: string;
+        message?: string;
+      }
+    | { status: "gone"; message?: string; payload?: unknown };
   export type Connection = ConnectionState & { reconnect: () => void };
   export type ConnectionStatus = Connection["status"];
 

package/src/transports/remote.ts

@@ -1,7 +1,11 @@
 import { useEffect } from "react";
 import { useStatewireEmit } from "../host/host";
 import type { Statewire } from "../types";
-import { setTransport, useStatewireSession } from "../client/session";
+import {
+  setContext,
+  setTransport,
+  useStatewireSession,
+} from "../client/session";
 import type { StatewireSessionStoreOptions } from "../client/sessionStore";
 import type { StatewireClient } from "../statewire";
 import type { RemoteLink, StatewireRemoteProps } from "./sse";
@@ -26,5 +30,6 @@ export const useStatewireRemote = <
     emit,
     connection: conn.connection,
     source: s.source,
+    setContext: (value) => setContext(s, value),
   };
 };

package/src/transports/sse.ts

@@ -32,10 +32,24 @@ export type StatewireRemoteProps = {
   onFinish: (args: StatewireHost.Fin) => void;
 };
 
-export type StatewireWireCommand = {
-  method: string;
-  params: readonly unknown[];
-};
+export type StatewireWireCommand =
+  | { method: string; params: readonly unknown[]; context?: never }
+  | { method?: never; params?: never; context: Record<string, unknown> };
+
+/** The wire shape of a client context submission: one root replace op. */
+export const contextOps = (value: Record<string, unknown>) => [
+  { op: "replace", path: [], value },
+];
+
+export const encodeWireCommand = (command: StatewireWireCommand) => ({
+  ...(command.method !== undefined && {
+    method: command.method,
+    ...encodeParams(command.params),
+  }),
+  ...(command.context !== undefined && {
+    context: contextOps(command.context),
+  }),
+});
 
 export type StatewireSubmitResult =
   | { type: "receipt"; response?: StatewireResponse }
@@ -44,18 +58,7 @@ export type StatewireSubmitResult =
   | { type: "unknown-client" }
   | { type: "stale-lease" };
 
-export type ConnectionState =
-  | { status: "connecting" }
-  | { status: "live" }
-  | {
-      status: "reconnecting";
-      cause: "dropped" | "evicted" | "error";
-      attempt: number;
-      nextRetryAt: number;
-      lastError?: string;
-      message?: string;
-    }
-  | { status: "gone"; message?: string; payload?: unknown };
+export type ConnectionState = StatewireClient.ConnectionState;
 
 /** The live wire a remote session drives: connection status plus command POST. */
 export type RemoteLink = {
@@ -184,10 +187,7 @@ const sendCommand = async (
         "Statewire-Command-Seq": String(seq),
         ...(c.lease !== null && { "Statewire-Lease": c.lease }),
       }),
-      body: JSON.stringify({
-        method: command.method,
-        ...encodeParams(command.params),
-      }),
+      body: JSON.stringify(encodeWireCommand(command)),
       signal: AbortSignal.any([
         c.lifetime?.signal ?? AbortSignal.abort(),
         timeout,

package/src/transports/testing.ts

@@ -20,8 +20,8 @@ export const applyOptimistic = <TState>(
 export type MockTransport<TState> = {
   /** Pass as the `transport:` option of useStatewire / Harness. */
   transport: ResourceElement<Statewire<TState | undefined, any, any>>;
-  /** Captured `{ method, params }` command bodies, in POST order. */
-  commands: { method: string; params: unknown[] }[];
+  /** Captured `/commands` POST bodies, in POST order. */
+  commands: { method?: string; params?: unknown[]; context?: unknown }[];
   /** Replace the replicated state and broadcast it as a root snapshot op. */
   setState: (state: TState) => Promise<void>;
   /** Deliver an ack watermark on the stream. */
@@ -49,7 +49,7 @@ export const createMockTransport = <TState>(
   let finished = false;
   const clients = new Map<string, number>();
   const streams = new Set<FakeStreamHandle>();
-  const commands: { method: string; params: unknown[] }[] = [];
+  const commands: MockTransport<unknown>["commands"] = [];
 
   const sendEnvelope = (envelope: StatewireEnvelope) => {
     for (const stream of streams) stream.send(sseFrame(envelope));
@@ -86,7 +86,9 @@ export const createMockTransport = <TState>(
       const seq = Number(headers.get("Statewire-Command-Seq"));
       clients.set(id, Math.max(clients.get(id) ?? 0, seq));
       commands.push(
-        JSON.parse(String(init?.body)) as { method: string; params: unknown[] },
+        JSON.parse(
+          String(init?.body),
+        ) as MockTransport<unknown>["commands"][number],
       );
       return Response.json({});
     }

package/src/transports/ws.ts

@@ -1,7 +1,6 @@
 import { useState } from "react";
 import { flushTapSync, resource } from "@assistant-ui/tap";
 import type { ResourceElement } from "@assistant-ui/tap";
-import { encodeParams } from "../wire/meta";
 import { timing } from "../client/timing";
 import {
   handleEnvelope,
@@ -13,6 +12,7 @@ import type { Statewire } from "../types";
 import type { StatewireClient } from "../statewire";
 import { useStatewireRemote } from "./remote";
 import { CLIENT_QUERY_PARAM } from "../host/adapter";
+import { encodeWireCommand } from "./sse";
 import type {
   RemoteLink,
   StatewireSubmitResult,
@@ -206,13 +206,7 @@ const sendCommand = (
     }, timing.heartbeatTimeoutMs);
     w.pending.push(entry);
     try {
-      ws.send(
-        JSON.stringify({
-          method: command.method,
-          ...encodeParams(command.params),
-          seq,
-        }),
-      );
+      ws.send(JSON.stringify({ ...encodeWireCommand(command), seq }));
     } catch {
       clearTimeout(timer);
       w.pending = w.pending.filter((p) => p !== entry);

package/src/types.ts

@@ -56,6 +56,8 @@ export interface Statewire<
   emit?: (event: TEvent) => void;
   connection?: StatewireClient.Connection;
   source?: Statewire.StateSource;
+  /** Replace this client's ambient context on the server; absent on transports without a client context channel. */
+  setContext?: (value: Record<string, unknown>) => Promise<unknown>;
 }
 
 const describe = (failure: StatewireClient.SendFailure): string => {