statewire 0.15.0 → 0.17.0

package/src/wire/documents.ts

@@ -1,9 +1,31 @@
 import { applyOps } from "./ops";
 import { reviveValue } from "./meta";
+import { protocolToken } from "./protocol";
 import type { StatewirePath } from "./ops";
 
 export namespace StatewireDocuments {
-  export type Document = { key: readonly string[] | null; value: unknown };
+  export type CacheEntry = { version: string; value: unknown };
+  export type Storage = {
+    namespace?: string;
+    load: (identity: readonly string[]) => CacheEntry | undefined;
+    save: (identity: readonly string[], entry: CacheEntry) => void;
+    subscribe?: (listener: () => void) => () => void;
+  };
+  export type Source = {
+    get: (
+      protocol: string,
+      key?: readonly string[],
+      prefix?: readonly string[],
+    ) => unknown;
+    list: () => ReadonlyMap<number, Document>;
+    subscribe: (listener: () => void) => () => void;
+  };
+  export type Document = {
+    key: readonly string[] | null;
+    protocol?: string;
+    main?: boolean;
+    value: unknown;
+  };
   export type State = {
     mode: "mounted" | "keyless" | null;
     documents: ReadonlyMap<number, Document>;
@@ -17,8 +39,12 @@ const invalid: (message: string) => never = (message) => {
 export const applyDocumentOps = (
   previous: StatewireDocuments.State,
   ops: readonly unknown[],
+  protocols?: readonly { name: string; version: string }[],
+  strict = false,
 ) => {
-  let mode = previous.mode;
+  let mode =
+    previous.mode ??
+    (protocols !== undefined && ops.length === 0 ? "mounted" : null);
   const documents = new Map(previous.documents);
   const changedPaths: StatewirePath[] = [];
   for (const raw of ops) {
@@ -35,10 +61,13 @@ export const applyDocumentOps = (
         op.op as string,
       )
     ) {
+      if (strict) invalid("unknown context operation");
       const { doc: _doc, ...unknown } = op;
       applyOps(undefined, [unknown]);
       continue;
     }
+    if (protocols !== undefined && mode === null && op.op !== "mount")
+      invalid("negotiated state must start with mounts");
     if (mode === null) {
       if (op.op === "mount") mode = "mounted";
       else if (
@@ -64,23 +93,73 @@ export const applyDocumentOps = (
     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") ||
+        (op.key !== undefined &&
+          (!Array.isArray(op.key) ||
+            !op.key.every((key) => typeof key === "string"))) ||
         !("value" in op)
       ) {
-        invalid("mount requires a key array and value");
+        invalid("mount requires value and an optional key array");
       }
+      if (
+        op.protocol !== undefined &&
+        (typeof op.protocol !== "string" ||
+          !protocolToken.test(op.protocol) ||
+          op.protocol === "*")
+      )
+        invalid("invalid mount protocol");
+      if (
+        protocols !== undefined &&
+        !protocols.some((p) => p.name === op.protocol)
+      )
+        invalid("mount protocol was not negotiated");
+      if (op.main !== undefined && typeof op.main !== "boolean")
+        invalid("main must be boolean");
+      if (
+        op.main === true &&
+        [...documents.values()].some(
+          (d) => d.protocol === op.protocol && d.main,
+        )
+      )
+        invalid("protocol already has a main document");
+      if (
+        op.key !== undefined &&
+        [...documents.values()].some(
+          (d) =>
+            d.protocol === op.protocol &&
+            JSON.stringify(d.key) === JSON.stringify(op.key),
+        )
+      )
+        invalid("protocol document key is already mounted");
       documents.set(doc, {
-        key: op.key,
+        key: op.key === undefined ? null : (op.key as string[]),
+        ...(op.protocol === undefined
+          ? {}
+          : { protocol: op.protocol as string }),
+        ...(op.main === undefined ? {} : { main: op.main as boolean }),
         value:
-          op.meta === undefined ? op.value : reviveValue(op.value, op.meta),
+          op.meta === undefined
+            ? op.value
+            : reviveValue(op.value, op.meta, { rejectUnknown: strict }),
       });
       if (doc === 0) changedPaths.push([]);
     } else if (op.op === "unmount") {
+      const document = documents.get(doc);
+      if (
+        protocols !== undefined &&
+        document !== undefined &&
+        !protocols.some((p) => p.name === document.protocol)
+      )
+        invalid("document protocol was not negotiated");
       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 (
+        protocols !== undefined &&
+        document !== undefined &&
+        !protocols.some((p) => p.name === document.protocol)
+      )
+        invalid("document protocol was not negotiated");
       if (!document) invalid("document is not mounted");
       if (
         !Array.isArray(op.path) ||
@@ -98,7 +177,9 @@ export const applyDocumentOps = (
         invalid("operation requires a value");
       const { doc: _doc, meta, ...mutation } = op;
       if (meta !== undefined)
-        mutation.value = reviveValue(mutation.value, meta);
+        mutation.value = reviveValue(mutation.value, meta, {
+          rejectUnknown: strict,
+        });
       const applied = applyOps(document.value, [mutation]);
       documents.set(doc, { ...document, value: applied.state });
       if (doc === 0) changedPaths.push(...applied.changedPaths);
@@ -107,3 +188,40 @@ export const applyDocumentOps = (
   if (mode === null) invalid("hello missing snapshot");
   return { mode, documents, changedPaths };
 };
+
+export const mainDocument = (
+  state: StatewireDocuments.State,
+  protocol: string,
+) =>
+  [...state.documents.values()].find(
+    (document) => document.protocol === protocol && document.main,
+  );
+
+export const resolveDocumentKey = (
+  key: readonly string[],
+  prefix?: readonly string[],
+) =>
+  key[0] === "."
+    ? prefix === undefined
+      ? undefined
+      : [...prefix, ...key.slice(1)]
+    : key;
+
+export const findDocument = (
+  state: StatewireDocuments.State,
+  protocol: string,
+  key?: readonly string[],
+  prefix?: readonly string[],
+) => {
+  if (key === undefined) return mainDocument(state, protocol);
+  const resolved = resolveDocumentKey(key, prefix);
+  return [...state.documents.values()].find(
+    (document) =>
+      document.protocol === protocol &&
+      document.key !== null &&
+      (JSON.stringify(document.key) === JSON.stringify(key) ||
+        (resolved !== undefined &&
+          JSON.stringify(resolveDocumentKey(document.key, prefix)) ===
+            JSON.stringify(resolved))),
+  );
+};

package/src/wire/protocol.ts

@@ -0,0 +1,327 @@
+export namespace StatewireProtocol {
+  export type Range = { version: string; minVersion?: string };
+  export type Offer = Range & { name: string; optional?: boolean };
+  export type Selection = {
+    version: string;
+    protocols: { name: string; version: string }[];
+  };
+  export type Options = {
+    wireVersion?: Range;
+    applicationProtocols?: readonly Offer[] | "*";
+    protocol?: string;
+    keyPrefixes?: Readonly<Record<string, readonly string[]>>;
+  };
+  export type Definition = Range & {
+    name: string;
+    requires?: Readonly<Record<string, Range>>;
+  };
+}
+
+export const WIRE_VERSION = "2026-09-07";
+export const DEFAULT_PROTOCOL = "default";
+export const PROTOCOL_HEADER = "Statewire-Protocol";
+export const VERSION_HEADER = "Statewire-Version";
+export const protocolToken = /^[A-Za-z*][A-Za-z0-9!#$%&'*+.^_`|~:/-]*$/;
+
+const invalid = (message: string): never => {
+  throw new Error(`statewire: protocol error: ${message}`);
+};
+
+export const validateVersion = (value: unknown): string => {
+  if (typeof value !== "string" || !/^\d{4}-\d{2}-\d{2}$/.test(value))
+    return invalid("version must be a YYYY-MM-DD date");
+  const parsed = new Date(`${value}T00:00:00.000Z`);
+  if (
+    !Number.isFinite(parsed.getTime()) ||
+    parsed.toISOString().slice(0, 10) !== value ||
+    value.startsWith("0000")
+  )
+    return invalid("invalid version date");
+  return value;
+};
+
+export const validateRange = (range: StatewireProtocol.Range) => {
+  const version = validateVersion(range.version);
+  const minVersion =
+    range.minVersion === undefined
+      ? version
+      : validateVersion(range.minVersion);
+  if (minVersion > version) invalid("min-version exceeds version");
+  return { version, minVersion };
+};
+
+export const inRange = (value: string, range: StatewireProtocol.Range) => {
+  const checked = validateRange(range);
+  return value >= checked.minVersion && value <= checked.version;
+};
+
+export const protocolOffers = (options: StatewireProtocol.Options) =>
+  options.applicationProtocols ?? [
+    { name: options.protocol ?? DEFAULT_PROTOCOL, version: WIRE_VERSION },
+  ];
+
+export const negotiationHeaders = (
+  options: StatewireProtocol.Options,
+): Record<string, string> => {
+  const suffix = (range: StatewireProtocol.Range) => {
+    const { version, minVersion } = validateRange(range);
+    return `"${version}"${minVersion === version ? "" : `; min-version="${minVersion}"`}`;
+  };
+  const offers = protocolOffers(options);
+  const seen = new Set<string>();
+  if (offers !== "*" && !offers.length)
+    invalid("protocol list must not be empty");
+  return {
+    [VERSION_HEADER]: suffix(options.wireVersion ?? { version: WIRE_VERSION }),
+    [PROTOCOL_HEADER]:
+      offers === "*"
+        ? "*"
+        : offers
+            .map((offer) => {
+              if (
+                !protocolToken.test(offer.name) ||
+                offer.name === "*" ||
+                seen.has(offer.name)
+              )
+                invalid("invalid or duplicate protocol name");
+              if (
+                offer.optional !== undefined &&
+                typeof offer.optional !== "boolean"
+              )
+                invalid("optional must be boolean");
+              seen.add(offer.name);
+              return `${offer.name}; version=${suffix(offer)}${offer.optional ? "; optional" : ""}`;
+            })
+            .join(", "),
+  };
+};
+
+const parseItem = (input: string) => {
+  const atom = String.raw`"(?:[\x20-\x21\x23-\x5b\x5d-\x7e]|\\["\\])*"|[A-Za-z*][A-Za-z0-9!#$%&'*+.^_\x60|~:/-]*|\?[01]`;
+  const text = input.trim();
+  const match = new RegExp(`^(?:${atom})`).exec(text);
+  if (!match) return invalid("invalid structured item");
+  const quoted = match[0].startsWith('"');
+  const decode = (raw: string) => raw.slice(1, -1).replace(/\\(["\\])/g, "$1");
+  const value = quoted ? decode(match[0]) : match[0];
+  const params = new Map<string, string | boolean>();
+  let rest = text.slice(match[0].length);
+  while (rest) {
+    const parameter = new RegExp(
+      `^; *([a-z*][a-z0-9_.*-]*)(?:=(${atom}))?`,
+    ).exec(rest);
+    if (!parameter) return invalid("invalid structured parameters");
+    const key = parameter[1]!;
+    const raw = parameter[2];
+    if (params.has(key)) invalid("duplicate parameter");
+    if (raw === undefined || raw === "?1") params.set(key, true);
+    else if (raw === "?0") params.set(key, false);
+    else if (raw.startsWith('"')) params.set(key, decode(raw));
+    else invalid("parameter must be string or boolean");
+    rest = rest.slice(parameter[0].length);
+  }
+  return { value, quoted, params };
+};
+
+export const parseNegotiation = (
+  headers: Headers,
+): Required<
+  Pick<StatewireProtocol.Options, "wireVersion" | "applicationProtocols">
+> => {
+  const wire = headers.get(VERSION_HEADER);
+  const application = headers.get(PROTOCOL_HEADER);
+  if (wire === null || application === null)
+    return invalid("negotiation fields are required");
+  const item = parseItem(wire);
+  if (!item.quoted || [...item.params.keys()].some((k) => k !== "min-version"))
+    invalid("invalid Statewire-Version");
+  const minVersion = item.params.get("min-version");
+  if (minVersion !== undefined && typeof minVersion !== "string")
+    return invalid("min-version must be a string");
+  const wireVersion = validateRange({
+    version: item.value,
+    ...(minVersion === undefined ? {} : { minVersion }),
+  });
+  if (application.trim() === "*")
+    return { wireVersion, applicationProtocols: "*" };
+  const names = new Set<string>();
+  const applicationProtocols = application
+    .split(",")
+    .map((text): StatewireProtocol.Offer => {
+      const { value: name, quoted, params } = parseItem(text);
+      if (
+        quoted ||
+        !protocolToken.test(name) ||
+        name === "*" ||
+        names.has(name)
+      )
+        invalid("invalid or duplicate protocol name");
+      names.add(name);
+      if (
+        [...params.keys()].some(
+          (k) => !["version", "min-version", "optional"].includes(k),
+        )
+      )
+        invalid("unsupported parameter");
+      const version = params.get("version");
+      const minVersion = params.get("min-version");
+      const optional = params.get("optional") ?? false;
+      if (
+        typeof version !== "string" ||
+        (minVersion !== undefined && typeof minVersion !== "string") ||
+        typeof optional !== "boolean"
+      )
+        return invalid("invalid protocol parameters");
+      return {
+        name,
+        ...validateRange({
+          version,
+          ...(minVersion === undefined ? {} : { minVersion }),
+        }),
+        optional,
+      };
+    });
+  return { wireVersion, applicationProtocols };
+};
+
+export const validateSelection = (
+  value: unknown,
+  options: StatewireProtocol.Options,
+): StatewireProtocol.Selection => {
+  if (typeof value !== "object" || value === null)
+    return invalid("missing negotiation selection");
+  const syn = value as Record<string, unknown>;
+  const version = validateVersion(syn.version);
+  if (!inRange(version, options.wireVersion ?? { version: WIRE_VERSION }))
+    invalid("selected wire version is outside offer");
+  if (!Array.isArray(syn.protocols))
+    return invalid("syn.protocols must be an array");
+  const offers = protocolOffers(options);
+  const seen = new Set<string>();
+  const protocols = syn.protocols.map((entry: unknown) => {
+    if (typeof entry !== "object" || entry === null)
+      return invalid("invalid selected protocol");
+    const item = entry as Record<string, unknown>;
+    const name = item.name;
+    if (
+      typeof name !== "string" ||
+      !protocolToken.test(name) ||
+      name === "*" ||
+      seen.has(name)
+    )
+      return invalid("invalid selected protocol name");
+    const version = validateVersion(item.version);
+    seen.add(name);
+    if (offers !== "*") {
+      const offer = offers.find((o) => o.name === name);
+      if (!offer || !inRange(version, offer))
+        invalid("selected protocol is outside offer");
+    }
+    return { name, version };
+  });
+  if (offers !== "*" && offers.some((o) => !o.optional && !seen.has(o.name)))
+    invalid("required protocol missing from selection");
+  return { version, protocols };
+};
+
+export const negotiateProtocols = (
+  headers: Headers,
+  wire: StatewireProtocol.Range,
+  definitions: readonly StatewireProtocol.Definition[],
+):
+  | StatewireProtocol.Selection
+  | {
+      fin: {
+        reason: "protocol-error";
+        code: string;
+        status: number;
+        message: string;
+        payload?: unknown;
+      };
+    } => {
+  const supported = {
+    ...validateRange(wire),
+    protocols: definitions.map((d) => ({ name: d.name, ...validateRange(d) })),
+  };
+  const failure = (code: string, message: string) => ({
+    fin: {
+      reason: "protocol-error" as const,
+      code,
+      message,
+      status: code === "invalid-negotiation" ? 400 : 406,
+      ...(code === "invalid-negotiation" ? {} : { payload: supported }),
+    },
+  });
+  let request: ReturnType<typeof parseNegotiation>;
+  try {
+    request = parseNegotiation(headers);
+  } catch (error) {
+    return failure(
+      "invalid-negotiation",
+      error instanceof Error ? error.message : "invalid negotiation",
+    );
+  }
+  const version = [wire.version, request.wireVersion.version].sort()[0]!;
+  if (!inRange(version, wire) || !inRange(version, request.wireVersion))
+    return failure("unsupported-version", "Statewire versions do not overlap");
+  const offers =
+    request.applicationProtocols === "*"
+      ? definitions.map((d) => ({
+          name: d.name,
+          version: d.version,
+          optional: false,
+        }))
+      : request.applicationProtocols;
+  const registry = new Map(definitions.map((d) => [d.name, d]));
+  if (registry.size !== definitions.length)
+    throw new Error("statewire: duplicate registered protocol");
+  const offered = new Map(offers.map((o) => [o.name, o]));
+  const solve = (names: Set<string>) => {
+    const active = new Set(names);
+    for (const name of active) {
+      const definition = registry.get(name);
+      if (!definition || !offered.has(name)) return undefined;
+      for (const dependency of Object.keys(definition.requires ?? {}))
+        active.add(dependency);
+    }
+    const result = new Map<string, string>();
+    for (const name of active) {
+      const ranges = [
+        registry.get(name)!,
+        offered.get(name)!,
+        ...[...active].flatMap((parent) => {
+          const dependency = registry.get(parent)!.requires?.[name];
+          return dependency ? [dependency] : [];
+        }),
+      ].map(validateRange);
+      const lower = ranges
+        .map((r) => r.minVersion)
+        .sort()
+        .at(-1)!;
+      const upper = ranges.map((r) => r.version).sort()[0]!;
+      if (lower > upper) return undefined;
+      result.set(name, upper);
+    }
+    return result;
+  };
+  let selected = solve(
+    new Set(offers.filter((o) => !o.optional).map((o) => o.name)),
+  );
+  if (!selected)
+    return failure(
+      "unsupported-protocol",
+      "required protocol combination is unsupported",
+    );
+  for (const offer of offers) {
+    if (offer.optional)
+      selected = solve(new Set([...selected.keys(), offer.name])) ?? selected;
+  }
+  return {
+    version,
+    protocols: offers.flatMap((o) =>
+      selected!.has(o.name)
+        ? [{ name: o.name, version: selected!.get(o.name)! }]
+        : [],
+    ),
+  };
+};

package/src/wire/version.ts

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