statewire 0.16.0 → 0.17.0

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";