statewire 0.16.0 → 0.17.1

package/src/document.ts

@@ -0,0 +1,185 @@
+import { isUnsafeKey, walkStatePath } from "./util/statePath";
+
+export namespace StatewireDocument {
+  export type Value =
+    | null
+    | boolean
+    | number
+    | string
+    | Value[]
+    | { [key: string]: Value };
+  export type MetaEntry = { path: (string | number)[]; type: "date" };
+  export type Encoded = { value: Value; meta?: MetaEntry[] };
+}
+
+const invalid = (message: string): never => {
+  throw new Error(`statewire: protocol error: invalid document: ${message}`);
+};
+
+const isObject = (value: unknown): value is Record<string, unknown> =>
+  typeof value === "object" &&
+  value !== null &&
+  (Object.getPrototypeOf(value) === Object.prototype ||
+    Object.getPrototypeOf(value) === null);
+
+const copyValue = (
+  value: unknown,
+  dates: boolean,
+  meta: StatewireDocument.MetaEntry[],
+  path: (string | number)[] = [],
+  ancestors = new Set<object>(),
+): StatewireDocument.Value => {
+  if (value === null || typeof value === "boolean" || typeof value === "string")
+    return value;
+  if (typeof value === "number") {
+    if (
+      !Number.isFinite(value) ||
+      (Number.isInteger(value) && !Number.isSafeInteger(value))
+    )
+      invalid(
+        `number at ${JSON.stringify(path)} must be finite and within the safe integer range`,
+      );
+    return value;
+  }
+  if (dates && value instanceof Date) {
+    if (
+      !Number.isFinite(value.getTime()) ||
+      value.getUTCFullYear() < 1 ||
+      value.getUTCFullYear() > 9999
+    )
+      invalid(
+        `date at ${JSON.stringify(path)} must have a year from 0001 to 9999`,
+      );
+    meta.push({ path, type: "date" });
+    return value.toISOString();
+  }
+  if (!Array.isArray(value) && !isObject(value))
+    return invalid(`unsupported value at ${JSON.stringify(path)}`);
+  if (ancestors.has(value)) invalid(`cycle at ${JSON.stringify(path)}`);
+  ancestors.add(value);
+  const descriptors = Object.getOwnPropertyDescriptors(value);
+  for (const key of Reflect.ownKeys(descriptors)) {
+    if (Array.isArray(value) && key === "length") continue;
+    if (typeof key !== "string")
+      invalid(`symbol key at ${JSON.stringify(path)}`);
+    const descriptor = descriptors[key as string]!;
+    if (!("value" in descriptor) || !descriptor.enumerable)
+      invalid(
+        `property at ${JSON.stringify([...path, key])} must be enumerable data`,
+      );
+    if (isUnsafeKey(key as string, path.at(-1)))
+      invalid(`unsafe key at ${JSON.stringify([...path, key])}`);
+    if (
+      Array.isArray(value) &&
+      (!/^(0|[1-9]\d*)$/.test(key as string) || Number(key) >= value.length)
+    )
+      invalid(
+        `unsupported array property at ${JSON.stringify([...path, key])}`,
+      );
+  }
+  let result: StatewireDocument.Value;
+  if (Array.isArray(value)) {
+    result = Array.from({ length: value.length }, (_, index) => {
+      if (!Object.hasOwn(value, index))
+        invalid(`sparse array at ${JSON.stringify(path)}`);
+      return copyValue(
+        descriptors[index]!.value,
+        dates,
+        meta,
+        [...path, index],
+        ancestors,
+      );
+    });
+  } else {
+    result = Object.fromEntries(
+      Object.keys(descriptors).map((key) => [
+        key,
+        copyValue(
+          descriptors[key]!.value,
+          dates,
+          meta,
+          [...path, key],
+          ancestors,
+        ),
+      ]),
+    );
+  }
+  ancestors.delete(value);
+  return result;
+};
+
+/** Encode a document value as detached JSON data with date metadata. */
+export const encodeDocument = (value: unknown): StatewireDocument.Encoded => {
+  const meta: StatewireDocument.MetaEntry[] = [];
+  const encoded = copyValue(value, true, meta);
+  return meta.length ? { value: encoded, meta } : { value: encoded };
+};
+
+/** Validate and decode a document into detached values with native dates. */
+export const decodeDocument = (encoded: unknown): unknown => {
+  const document = copyValue(encoded, false, []);
+  if (
+    !isObject(document) ||
+    !Object.hasOwn(document, "value") ||
+    Object.keys(document).some((key) => key !== "value" && key !== "meta")
+  )
+    return invalid("expected an object with value and optional meta");
+  const value: unknown = document.value;
+  if (!Object.hasOwn(document, "meta")) return value;
+  if (!Array.isArray(document.meta)) return invalid("meta must be an array");
+  return reviveDocumentValue(value, document.meta, {
+    rejectUnknown: true,
+    canonical: true,
+  });
+};
+
+export const reviveDocumentValue = (
+  value: unknown,
+  meta: unknown,
+  { rejectUnknown = false, canonical = false } = {},
+): unknown => {
+  if (!Array.isArray(meta)) return invalid("meta must be an array");
+  const seen = new Set<string>();
+  for (const entry of meta) {
+    if (
+      !isObject(entry) ||
+      !Array.isArray(entry.path) ||
+      (canonical &&
+        Object.keys(entry).some((key) => key !== "path" && key !== "type")) ||
+      !entry.path.every(
+        (segment) =>
+          typeof segment === "string" ||
+          (typeof segment === "number" &&
+            Number.isSafeInteger(segment) &&
+            segment >= 0),
+      )
+    )
+      return invalid("meta entry requires a path array and type date");
+    if (entry.type !== "date") {
+      if (rejectUnknown) invalid(`unknown meta type: ${String(entry.type)}`);
+      continue;
+    }
+    const path = entry.path as (string | number)[];
+    const identity = JSON.stringify(path);
+    if (seen.has(identity)) invalid(`duplicate meta path ${identity}`);
+    seen.add(identity);
+    const walked = walkStatePath(value, path, "resolve");
+    if (!walked || typeof walked.leaf !== "string")
+      return invalid(`meta path ${identity} must resolve to a string`);
+    const date = new Date(walked.leaf);
+    if (
+      canonical
+        ? !/^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}\.\d{3}Z$/.test(walked.leaf) ||
+          !Number.isFinite(date.getTime()) ||
+          date.getUTCFullYear() < 1 ||
+          date.toISOString() !== walked.leaf
+        : !/(?:T| )\d{2}:\d{2}(?::\d{2}(?:\.\d+)?)?(?:Z|[+-]\d{2}:?\d{2})$/i.test(
+            walked.leaf,
+          ) || !Number.isFinite(date.getTime())
+    )
+      return invalid(`invalid date at meta path ${identity}`);
+    if (walked.parent === undefined) value = date;
+    else (walked.parent as Record<string | number, unknown>)[walked.key] = date;
+  }
+  return value;
+};

package/src/host/host.ts

@@ -102,6 +102,7 @@ type Settled =
   | { type: "rejected"; error: unknown };
 
 export type CommandsInvocation = {
+  readonly protocol?: string;
   readonly method: string;
   readonly params: readonly unknown[];
   readonly ts: number;

package/src/host/http.ts

@@ -15,7 +15,8 @@ import {
 } from "./socket";
 import type { ParsedFrame, Registration, SocketHostState } from "./socket";
 import { MAX_FRAME_BODY_BYTES } from "../wire/limits";
-import { PROTOCOL_VERSION, VERSION_HEADER } from "../wire/version";
+import { negotiateProtocols } from "../wire/protocol";
+import type { StatewireProtocol } from "../wire/protocol";
 
 export { MAX_FRAME_BODY_BYTES } from "../wire/limits";
 
@@ -139,6 +140,7 @@ const attachSse = (
   h: SocketHostState,
   clientId: string,
   auth: unknown,
+  selection: StatewireProtocol.Selection,
 ): SseAttachment => {
   let controller: ReadableStreamDefaultController<Uint8Array>;
   let connection: Registration["connection"] | null = null;
@@ -192,7 +194,7 @@ const attachSse = (
       }
     },
   };
-  const registration = register(h, clientId, socket, false, auth);
+  const registration = register(h, clientId, socket, false, auth, selection);
   connection = registration?.connection ?? null;
   if (!open) connection?.close();
   return {
@@ -213,7 +215,6 @@ const streamResponse = (
     status: 200,
     headers: {
       "Content-Type": "text/event-stream",
-      [VERSION_HEADER]: PROTOCOL_VERSION,
       ...(lease !== null && { [LEASE_HEADER]: lease }),
     },
   });
@@ -230,6 +231,7 @@ const admitAttachFrame = (
     registration.rec,
     frame,
     registration.conn.auth,
+    registration.conn.selection,
   );
   if (admission.type === "refused") {
     sendTo(h, registration.conn, JSON.stringify(admission.syn));
@@ -251,7 +253,12 @@ const getStream = async (
   );
   if (mismatch !== null) return mismatch;
   if (atSubscriberLimit(h)) return subscriberLimitResponse();
-  const attachment = attachSse(h, client.clientId, authorized.auth);
+  const selection = negotiateProtocols(request.headers, h.wireVersion, [
+    h.protocol,
+  ]);
+  if ("fin" in selection)
+    return Response.json(selection, { status: selection.fin.status });
+  const attachment = attachSse(h, client.clientId, authorized.auth, selection);
   const lease = attachment.registration === null ? null : mintLease();
   if (attachment.registration !== null)
     attachment.registration.conn.lease = lease;
@@ -295,11 +302,26 @@ const postStream = async (
   );
   if (mismatch !== null) return mismatch;
   if (atSubscriberLimit(h)) return subscriberLimitResponse();
-  const attachment = attachSse(h, client.clientId, authorized.auth);
+  const selection = negotiateProtocols(request.headers, h.wireVersion, [
+    h.protocol,
+  ]);
+  if ("fin" in selection)
+    return Response.json(selection, { status: selection.fin.status });
+  const attachment = attachSse(h, client.clientId, authorized.auth, selection);
   if (attachment.registration === null) return streamResponse(attachment, null);
   const lease = mintLease();
   attachment.registration.conn.lease = lease;
-  admitAttachFrame(h, attachment.registration, frame);
+  try {
+    admitAttachFrame(h, attachment.registration, frame);
+  } catch (error) {
+    closeConn(h, attachment.registration.conn, 1008, "invalid-context");
+    if (!(error instanceof Error) || error.name !== "StatewireViolation")
+      throw error;
+    return Response.json(
+      { fin: { reason: "protocol-error", message: error.message } },
+      { status: 400 },
+    );
+  }
   return streamResponse(attachment, lease);
 };
 
@@ -371,7 +393,14 @@ export const frames = async (
   if (!leased.open || h.disposed || h.finished !== null) {
     return Response.json({ error: "stale-lease" }, { status: 423 });
   }
-  const admission = admitFrame(h, rec, frame, leased.auth);
+  let admission: ReturnType<typeof admitFrame>;
+  try {
+    admission = admitFrame(h, rec, frame, leased.auth, leased.selection);
+  } catch (error) {
+    if (!(error instanceof Error) || error.name !== "StatewireViolation")
+      throw error;
+    return violationResponse(h, clientId, error.message);
+  }
   if (admission.type === "refused") {
     const retry = admission.syn.syn.retry;
     return Response.json(admission.syn, {