@ultimat3/http 29.4.0 → 30.0.0

package/src/webhook-verify.ts

@@ -3,11 +3,10 @@
 // a pipeline stage because a receiver is an ordinary `api/` route — the secret is per sender, and
 // only the route knows which one applies.
 //
-// THE FORMAT IS `@ultimat3/core`'s (`webhook-signature.ts`) and is not re-declared here. That
-// module is at the tier both halves can reach: `@ultimat3/jobs` (tier 3) signs a delivery and its
-// boundary forbids this package, and this package (tier 2) may not reach tier 3. What stays here
-// is the POLICY — what counts as fresh, how large a body may be, and which refusal a receiver
-// answers with.
+// THE FORMAT IS `@ultimat3/core`'s (`webhook-signature.ts`) and is not re-declared here: this
+// package (tier 2) may not reach `@ultimat3/jobs` (tier 3), which signs, so the format sits below
+// both. What stays here is the POLICY — what counts as fresh, how large a body may be, and which
+// refusal a receiver answers with.
 
 import type { Clock } from '@ultimat3/core';
 import {
@@ -22,6 +21,7 @@ import {
   WEBHOOK_TOPIC_HEADER,
   webhookMac,
 } from '@ultimat3/core';
+import type { WebhookVerifier } from './errors';
 import {
   bodyInvalid,
   httpCountInvalid,
@@ -93,6 +93,27 @@ const assertWebhookSecret = (secret: unknown): string => {
   );
 };
 
+/**
+ * The same screen over a rotation list (`verifyBodyHmac`): one entry or several, every one
+ * non-empty, and at least one. One empty entry refuses the list — `[current, process.env.OLD]`
+ * with `OLD` unset would otherwise verify anything under the empty key.
+ */
+export const assertWebhookSecrets = (
+  secret: unknown,
+  via: WebhookVerifier = 'verifyWebhookSignature',
+): readonly string[] => {
+  const list: readonly unknown[] = Array.isArray(secret) ? secret : [secret];
+  if (list.length === 0) throw webhookSecretMissing('an empty list', via);
+  for (const entry of list) {
+    if (typeof entry === 'string' && entry.length > 0) continue;
+    throw webhookSecretMissing(
+      entry === '' ? 'an empty string' : `a value of type ${typeof entry}`,
+      via,
+    );
+  }
+  return list as readonly string[];
+};
+
 export interface WebhookVerifyOptions {
   /** The shared secret for THIS sender. Never logged, never rendered into a refusal. */
   readonly secret: string;

package/src/websocket-mounts.ts

@@ -0,0 +1,104 @@
+// Several websocket mounts on ONE listener. `Bun.serve` takes one `websocket` handler set for every
+// socket it opens, so the mounts are joined here: an upgrade is routed by path, and each socket's
+// events go back to the mount that upgraded it — keyed by the `data` object that mount handed
+// `server.upgrade`, which Bun returns as `ws.data`. No mount's socket is wrapped or proxied.
+
+import { assert } from '@ultimat3/core';
+import type { UpgradeTarget, WebSocketMount } from './server';
+
+/**
+ * A mount's handler set with Bun's optional `drain`: the sync node answers it with its
+ * backpressure gap repair, and a join that dropped it left a refused frame's socket gapped.
+ */
+export type MountHandlers<TSocket> = WebSocketMount<TSocket>['websocket'] & {
+  drain?(ws: TSocket): void;
+};
+
+/** What `httpServer` dispatches: every path the mounts own, one fetch, one handler set. */
+export interface JoinedWebSocketMounts {
+  readonly paths: ReadonlySet<string>;
+  fetch(
+    request: Request,
+    server: UpgradeTarget,
+  ): Promise<Response | undefined> | Response | undefined;
+  readonly websocket: MountHandlers<{ readonly data: unknown }>;
+}
+
+/** Bun's per-listener knobs, joined so no mount gets less than it declared. */
+function joinedLimits(mounts: readonly WebSocketMount<never>[]) {
+  const max = (pick: (mount: WebSocketMount<never>) => number | undefined): number | undefined => {
+    const values = mounts.map(pick).filter((value): value is number => value !== undefined);
+    return values.length === 0 ? undefined : Math.max(...values);
+  };
+  const idleTimeout = max((mount) => mount.websocket.idleTimeout);
+  const backpressureLimit = max((mount) => mount.websocket.backpressureLimit);
+  const maxPayloadLength = max((mount) => mount.websocket.maxPayloadLength);
+  const sendPings = mounts.some((mount) => mount.websocket.sendPings === true);
+  return {
+    ...(idleTimeout === undefined ? {} : { idleTimeout }),
+    ...(backpressureLimit === undefined ? {} : { backpressureLimit }),
+    ...(maxPayloadLength === undefined ? {} : { maxPayloadLength }),
+    ...(sendPings ? { sendPings } : {}),
+  };
+}
+
+/**
+ * The mounts, joined. Two at one path is `X_INVARIANT` here — the same fact `httpServer` refuses
+ * between a mount and a route. The listener's limits are the widest any mount declared, so Bun
+ * enforces only those: a mount whose own bound is tighter (the sync node's `maxFrameBytes`, the
+ * device socket's frame cap) refuses past it in its own `message`, never through Bun alone.
+ */
+export function joinWebSocketMounts(
+  mounts: readonly WebSocketMount<never>[],
+): JoinedWebSocketMounts {
+  const byPath = new Map<string, WebSocketMount<never>>();
+  for (const mount of mounts) {
+    assert(
+      !byPath.has(mount.path),
+      `two websocket mounts claim ${mount.path}, and a path is answered by one of them`,
+      'x routes --json   # then move one mount to a path of its own',
+    );
+    byPath.set(mount.path, mount);
+  }
+  // A socket's owner, by the identity of the data its mount upgraded it with.
+  const owners = new WeakMap<object, WebSocketMount<never>>();
+  const ownerOf = (ws: { readonly data: unknown }): WebSocketMount<never> | undefined =>
+    typeof ws.data === 'object' && ws.data !== null ? owners.get(ws.data) : undefined;
+  // `never` is each mount's own socket type, unknown to this file: the socket handed back is the
+  // one that mount's upgrade produced, so the widening below is the only way to return it.
+  const hand = (ws: { readonly data: unknown }): never => ws as never;
+  // Read through the wider type: `drain` is optional, so every mount's handler set is one.
+  const handlersOf = (mount?: WebSocketMount<never>): MountHandlers<never> | undefined =>
+    mount?.websocket;
+  return {
+    paths: new Set(byPath.keys()),
+    fetch(request, server) {
+      const mount = byPath.get(new URL(request.url).pathname);
+      if (mount === undefined) return new Response('not found', { status: 404 });
+      const recording: UpgradeTarget = {
+        upgrade(upgraded, options) {
+          const { data } = options;
+          assert(
+            typeof data === 'object' && data !== null,
+            `the websocket mount at ${mount.path} upgraded with data that is not an object, so its socket cannot be routed back to it`,
+            'server.upgrade(request, { data: { socketId } })   # an object, in the mount at that path',
+          );
+          owners.set(data, mount);
+          return server.upgrade(upgraded, options);
+        },
+        requestIP: (asked) => server.requestIP(asked),
+      };
+      return mount.fetch(request, recording);
+    },
+    websocket: {
+      open: (ws) => ownerOf(ws)?.websocket.open(hand(ws)),
+      message: (ws, message) => ownerOf(ws)?.websocket.message(hand(ws), message),
+      close: (ws) => ownerOf(ws)?.websocket.close(hand(ws)),
+      // Present only when a mount answers it: Bun calls it once a socket's buffer can take frames.
+      ...(mounts.some((mount) => handlersOf(mount)?.drain !== undefined)
+        ? { drain: (ws) => handlersOf(ownerOf(ws))?.drain?.(hand(ws)) }
+        : {}),
+      ...joinedLimits(mounts),
+    },
+  };
+}