statewire 0.13.1 → 0.15.0

package/src/transports/ws.ts

@@ -2,7 +2,12 @@ import { useState } from "react";
 import { flushTapSync, resource } from "@assistant-ui/tap";
 import type { ResourceElement } from "@assistant-ui/tap";
 import { timing } from "../client/timing";
-import { handleEnvelope, useStatewireConn } from "../client/connection";
+import {
+  attachFrame,
+  handleEnvelope,
+  unsupportedVersion,
+  useLink,
+} from "../client/connection";
 import type {
   AttemptOutcome,
   Conn,
@@ -12,6 +17,7 @@ import type { Statewire } from "../types";
 import type { StatewireClient } from "../statewire";
 import { useStatewireRemote } from "./remote";
 import { CLIENT_QUERY_PARAM } from "../host/adapter";
+import { WS_SUBPROTOCOL } from "../wire/version";
 import type {
   RemoteLink,
   StatewireFrame,
@@ -21,12 +27,11 @@ import type {
 
 type WsChannel = {
   socket: WebSocket | null;
-  authStale: boolean;
 };
 
 const OPEN = 1;
 
-export const WS_SUBPROTOCOL = "statewire.v1";
+export { WS_SUBPROTOCOL };
 
 const socketUrl = async (
   options: StatewireClient.WSOptions,
@@ -37,30 +42,15 @@ const socketUrl = async (
     typeof query === "function" ? await query() : query,
   );
   params.set(CLIENT_QUERY_PARAM, clientId);
-  const base = url.replace(/\/$/, "").replace(/^http/, "ws");
-  return `${base}/ws?${params.toString()}`;
-};
-
-const firstFrame = async (
-  options: StatewireClient.WSOptions,
-  stale: boolean,
-  lanes: StatewireFrame | null,
-): Promise<string> => {
-  const { headers } = options;
-  const resolved = new Headers(
-    typeof headers === "function"
-      ? await headers({ staleAuth: stale })
-      : headers,
-  );
-  return JSON.stringify({
-    headers: Object.fromEntries(resolved),
-    ...(lanes ?? {}),
-  });
+  const resolved = new URL(url, globalThis.location?.href);
+  resolved.protocol = resolved.protocol.replace(/^http/, "ws");
+  resolved.pathname = `${resolved.pathname.replace(/\/$/, "")}/ws`;
+  resolved.search = params.toString();
+  return resolved.href;
 };
 
 const runSocket = (
   c: Conn,
-  w: WsChannel,
   ws: WebSocket,
   frame: string,
   abort: AbortController,
@@ -80,7 +70,15 @@ const runSocket = (
     arm();
     abort.signal.addEventListener("abort", () => ws.close());
     ws.onerror = () => {};
-    ws.onopen = () => ws.send(frame);
+    ws.onopen = () => {
+      const negotiated = ws.protocol.trim();
+      if (negotiated !== "" && negotiated !== WS_SUBPROTOCOL) {
+        outcome = unsupportedVersion(c, negotiated);
+        ws.close();
+        return;
+      }
+      ws.send(frame);
+    };
     const stale = () => Boolean(outcome) || closed || abort.signal.aborted;
     const fail = (error: unknown) => {
       clearTimeout(timer);
@@ -94,7 +92,7 @@ const runSocket = (
       try {
         env = JSON.parse(String(event.data)) as StatewireEnvelope;
       } catch {
-        fail(new Error("protocol"));
+        fail(new SyntaxError("invalid JSON packet"));
         return;
       }
       // {} heartbeats live below the packet layer: invisible to handlers.
@@ -108,7 +106,6 @@ const runSocket = (
       try {
         const done = flushTapSync(() => handleEnvelope(c, env));
         if (done) {
-          if (env.fin?.reason === "unauthorized") w.authStale = true;
           outcome = done;
           ws.close();
         }
@@ -133,10 +130,7 @@ const attemptSocket = async (
   let ws: WebSocket | null = null;
   try {
     const url = await socketUrl(options, c.ctx.clientId);
-    const stale = w.authStale;
-    w.authStale = false;
-    const lanes = flushTapSync(() => c.ctx.takeAttachLanes());
-    const frame = await firstFrame(options, stale, lanes);
+    const { body } = await attachFrame(c, options.headers);
     abort.signal.throwIfAborted();
     const { protocols, webSocket } = options;
     const WS = webSocket ?? globalThis.WebSocket;
@@ -149,7 +143,7 @@ const attemptSocket = async (
           : protocols;
     ws = new WS(url, [WS_SUBPROTOCOL, ...extra]);
     w.socket = ws;
-    return await runSocket(c, w, ws, frame, abort);
+    return await runSocket(c, ws, body, abort);
   } finally {
     if (w.socket === ws) w.socket = null;
   }
@@ -175,26 +169,13 @@ const useWsLink = (
   options: StatewireClient.WSOptions,
   ctx: StatewireRemoteProps,
 ): RemoteLink => {
-  const [w] = useState((): WsChannel => ({ socket: null, authStale: false }));
-  const c = useStatewireConn({
-    url: options.url,
-    isNew: options.isNew,
-    onChange: options.onChange,
+  const [w] = useState((): WsChannel => ({ socket: null }));
+  return useLink({
+    ...options,
     ctx,
     attemptOnce: (c, abort) => attemptSocket(c, w, options, abort),
+    send: (_, frame) => sendFrame(w, frame),
   });
-  const [link] = useState(
-    (): RemoteLink => ({
-      get connection() {
-        return c.connection;
-      },
-      get parked() {
-        return c.parked;
-      },
-      send: (frame) => sendFrame(w, frame),
-    }),
-  );
-  return link;
 };
 
 const useStatewireWS = (

package/src/types.ts

@@ -57,6 +57,7 @@ export interface Statewire<
   durableSeq?: number;
   /** Negation of the server's broadcast idle level; absent means always busy. */
   isBusy?: boolean;
+  work?: { readonly isIdle: boolean };
   /** Replace this client's ambient context on the server; it rides the ctx lane (no verdict). */
   setContext?: (value: Record<string, unknown>) => void;
   /** The retained failed-send lane; present on transports with a durable session. */

package/src/wire/documents.ts

@@ -0,0 +1,109 @@
+import { applyOps } from "./ops";
+import { reviveValue } from "./meta";
+import type { StatewirePath } from "./ops";
+
+export namespace StatewireDocuments {
+  export type Document = { key: readonly string[] | null; value: unknown };
+  export type State = {
+    mode: "mounted" | "keyless" | null;
+    documents: ReadonlyMap<number, Document>;
+  };
+}
+
+const invalid: (message: string) => never = (message) => {
+  throw new Error(`statewire: protocol error: ${message}`);
+};
+
+export const applyDocumentOps = (
+  previous: StatewireDocuments.State,
+  ops: readonly unknown[],
+) => {
+  let mode = previous.mode;
+  const documents = new Map(previous.documents);
+  const changedPaths: StatewirePath[] = [];
+  for (const raw of ops) {
+    if (typeof raw !== "object" || raw === null || Array.isArray(raw)) {
+      invalid("operation must be an object");
+    }
+    const op = raw as Record<string, unknown>;
+    const doc = op.doc === undefined ? 0 : op.doc;
+    if (typeof doc !== "number" || !Number.isSafeInteger(doc) || doc < 0) {
+      invalid("doc must be a nonnegative safe integer");
+    }
+    if (
+      !["mount", "unmount", "add", "replace", "remove"].includes(
+        op.op as string,
+      )
+    ) {
+      const { doc: _doc, ...unknown } = op;
+      applyOps(undefined, [unknown]);
+      continue;
+    }
+    if (mode === null) {
+      if (op.op === "mount") mode = "mounted";
+      else if (
+        op.op === "replace" &&
+        doc === 0 &&
+        Array.isArray(op.path) &&
+        op.path.length === 0 &&
+        "value" in op
+      ) {
+        mode = "keyless";
+        documents.set(0, { key: null, value: undefined });
+      } else
+        invalid(
+          "first operation must mount a document or replace document 0 at the root",
+        );
+    }
+    if (
+      mode === "keyless" &&
+      (doc !== 0 || op.op === "mount" || op.op === "unmount")
+    ) {
+      invalid("keyless mode only supports mutations of document 0");
+    }
+    if (op.op === "mount") {
+      if (documents.has(doc)) invalid("document is already mounted");
+      if (
+        !Array.isArray(op.key) ||
+        !op.key.every((key) => typeof key === "string") ||
+        !("value" in op)
+      ) {
+        invalid("mount requires a key array and value");
+      }
+      documents.set(doc, {
+        key: op.key,
+        value:
+          op.meta === undefined ? op.value : reviveValue(op.value, op.meta),
+      });
+      if (doc === 0) changedPaths.push([]);
+    } else if (op.op === "unmount") {
+      if (!documents.delete(doc)) invalid("document is not mounted");
+      if (doc === 0) changedPaths.push([]);
+    } else if (op.op === "add" || op.op === "replace" || op.op === "remove") {
+      const document = documents.get(doc);
+      if (!document) invalid("document is not mounted");
+      if (
+        !Array.isArray(op.path) ||
+        !op.path.every(
+          (part) =>
+            typeof part === "string" ||
+            (typeof part === "number" &&
+              Number.isSafeInteger(part) &&
+              part >= 0),
+        )
+      ) {
+        invalid("operation requires a valid path");
+      }
+      if (op.op !== "remove" && !("value" in op))
+        invalid("operation requires a value");
+      const { doc: _doc, meta, ...mutation } = op;
+      if (meta !== undefined)
+        mutation.value = reviveValue(mutation.value, meta);
+      const applied = applyOps(document.value, [mutation]);
+      documents.set(doc, { ...document, value: applied.state });
+      if (doc === 0) changedPaths.push(...applied.changedPaths);
+    }
+  }
+  if (mode === null) invalid("hello missing snapshot");
+  return { mode, documents, changedPaths };
+};

package/src/wire/limits.ts

@@ -0,0 +1,6 @@
+export const MAX_COMMANDS_PER_FRAME = 256;
+export const MAX_INFLIGHT_COMMANDS_PER_CLIENT = 256;
+export const MAX_FRAME_BODY_BYTES = 8 * 1024 * 1024;
+export const MAX_CONTEXT_VALUE_BYTES = 64 * 1024;
+export const MAX_INFLIGHT_COMMANDS_PER_HOST = 1024;
+export const COMMAND_CAPACITY_RETRY_MS = 1_000;

package/src/wire/meta.ts

@@ -42,7 +42,12 @@ export const reviveValue = (
       return fault(`meta path ${path.join(".")} must name a string`);
     }
     const date = new Date(walked.leaf);
-    if (Number.isNaN(date.getTime())) {
+    if (
+      !/(?:T| )\d{2}:\d{2}(?::\d{2}(?:\.\d+)?)?(?:Z|[+-]\d{2}:?\d{2})$/i.test(
+        walked.leaf,
+      ) ||
+      Number.isNaN(date.getTime())
+    ) {
       return fault(`invalid date at meta path ${path.join(".")}`);
     }
     if (walked.parent === undefined) return date;

package/src/wire/ops.ts

@@ -161,8 +161,7 @@ const applyOpToDraft = (box: { state: unknown }, op: Statewire.Op): void => {
     return;
   }
   if (op.path.length === 0) {
-    if (op.op !== "replace") throw invalid(op);
-    box.state = sanitizeValue(op.value);
+    box.state = op.op === "remove" ? undefined : sanitizeValue(op.value);
     return;
   }
   const walked = walkStatePath(box.state, op.path, "parent");

package/src/wire/version.ts

@@ -0,0 +1,3 @@
+export const PROTOCOL_VERSION = "1";
+export const VERSION_HEADER = "Statewire-Version";
+export const WS_SUBPROTOCOL = "statewire.v1";