dynamodb-reactive 0.6.1 → 0.7.0

package/dist/cloudflare.d.ts

@@ -1,5 +1,7 @@
 import { SubscribeRequest, SnapshotResponse, UnsubscribeRequest, JsonPatch } from './cluster.js';
 import { HubSocket, HubPaths } from './hub.js';
+import { ClusterTicket } from './cluster.js';
+import './client-BPAct-Dz.js';
 
 /**
  * Cloudflare Durable Object shell for the reactive hub. It is structural: it
@@ -140,6 +142,8 @@ interface RemoteHubOptions {
     url: string;
     /** The Worker's `notifySecret`. Keep it server-side. */
     secret: string;
+    /** Aborts a notify that takes longer than this. Default 3000 ms. */
+    timeoutMs?: number;
     /** Injectable for tests. */
     fetch?: typeof fetch;
 }
@@ -181,5 +185,136 @@ interface ReactiveRoutesOptions {
 /** Serves the ticket, socket, reactive and notify routes; `undefined` for any other path. */
 declare function handleReactiveRoutes(request: Request, options: ReactiveRoutesOptions): Promise<Response | undefined>;
 
-export { HEARTBEAT_TIMEOUT_CLOSE_CODE, HUB_PRINCIPAL_HEADER, createDurableObjectHub, handleReactiveRoutes, hubClient, remoteHub };
-export type { DurableObjectHub, DurableObjectHubOptions, DurableObjectStateLike, DurableObjectWebSocket, HubClientFrame, HubPresenceOptions, HubStub, ReactiveRoutes, ReactiveRoutesOptions, RemoteHubOptions };
+/** Routes a `defineHub` Worker serves. */
+declare const HUB_ROUTES: {
+    /** `POST` with the notify secret and `?principal=`: a ticket for a machine client. */
+    readonly ticket: "/api/hub/token";
+    /** WebSocket upgrade with a signed ticket in `?token=`. */
+    readonly socket: "/api/hub/socket";
+    /** Reactive HTTP subscribe and unsubscribe, with a signed ticket as the bearer. */
+    readonly reactive: "/api/hub/reactive";
+    /** `POST { path, patches? }` with the notify secret, after the data behind a path changed. */
+    readonly notify: "/api/hub/notify";
+    /** `GET` with the notify secret: `{ principals }`, the tracked principals holding a live socket. */
+    readonly presence: "/api/hub/presence";
+};
+/** Names of the Worker secrets and variables a `defineHub` Worker reads. */
+declare const HUB_ENV: {
+    readonly TICKET_SECRET: "REACTIVE_TICKET_SECRET";
+    readonly NOTIFY_SECRET: "HUB_NOTIFY_SECRET";
+    /** Comma-separated browser origins allowed to call the hub cross-origin. */
+    readonly ALLOWED_ORIGINS: "ALLOWED_ORIGINS";
+};
+/** The Durable Object class name and binding a `defineHub` Worker uses. */
+declare const HUB_DURABLE_OBJECT: {
+    readonly className: "ReactiveHub";
+    readonly binding: "REACTIVE_HUB";
+};
+/** The secrets and variables a `defineHub` Worker reads. */
+interface HubWorkerEnv {
+    REACTIVE_TICKET_SECRET?: string;
+    HUB_NOTIFY_SECRET?: string;
+    ALLOWED_ORIGINS?: string;
+    REACTIVE_HUB: {
+        idFromName(name: string): unknown;
+        get(id: unknown): HubStub;
+    };
+}
+/** What a hub's path rules can read from the Durable Object. */
+interface HubContext {
+    /** Whether `principal` holds a live socket. Needs `presence`. */
+    present(principal: string): boolean;
+    /** Every tracked principal holding a live socket, sorted. Needs `presence`. */
+    presentPrincipals(): string[];
+}
+interface HubConfig {
+    /** Path rules: who may watch each path and its snapshot. */
+    paths: (hub: HubContext) => HubPaths;
+    /**
+     * Principals whose live socket counts as presence, such as machine workers.
+     * They must ping more often than `timeoutMs`; `connectClusterWorker` does.
+     */
+    presence?: {
+        principals: readonly string[] | ((principal: string) => boolean);
+        /** @default 90000 */
+        timeoutMs?: number;
+        /** Paths notified when a principal comes online or goes offline, such as a status page. */
+        notify?: readonly string[];
+    };
+    /**
+     * Machine principals that may get a ticket from `HUB_ROUTES.ticket` by presenting
+     * the notify secret. Browsers get tickets from the app instead (`mintHubTicket`).
+     */
+    machinePrincipal?: (principal: string) => boolean;
+}
+/** The Durable Object a `defineHub` Worker exports as `ReactiveHub`. */
+interface HubDurableObject {
+    fetch(request: Request): Promise<Response>;
+    webSocketMessage(socket: DurableObjectWebSocket, message: string | ArrayBuffer): Promise<void>;
+    webSocketClose(socket: DurableObjectWebSocket, code: number): Promise<void>;
+    webSocketError(socket: DurableObjectWebSocket): Promise<void>;
+    alarm(): Promise<void>;
+}
+/** What `defineHub` returns: export `ReactiveHub` by that name and `worker` as the default. */
+interface DefinedHub {
+    ReactiveHub: new (ctx: DurableObjectStateLike, env: unknown) => HubDurableObject;
+    worker: {
+        fetch(request: Request, env: HubWorkerEnv): Promise<Response>;
+    };
+}
+/**
+ * A complete hub Worker: the Durable Object class and the Worker handler, with
+ * the ticket, socket, reactive, notify and presence routes. The application
+ * supplies only its path rules.
+ *
+ * ```ts
+ * const hub = defineHub({ paths: () => ({ 'status': { authorize: () => true, snapshot: () => ({}) } }) });
+ * export const ReactiveHub = hub.ReactiveHub;
+ * export default hub.worker;
+ * ```
+ *
+ * Deploy it with `dynamodb-reactive-hub deploy`, which writes the matching
+ * Wrangler config and puts the secrets.
+ */
+declare function defineHub(config: HubConfig): DefinedHub;
+/** The hub's two secrets, derived from one root secret the application already holds. */
+interface HubSecrets {
+    /** `REACTIVE_TICKET_SECRET`: signs and verifies tickets. */
+    ticket: string;
+    /** `HUB_NOTIFY_SECRET`: notify, presence and machine ticket routes. */
+    notify: string;
+}
+/**
+ * Derives the hub secrets as HMAC-SHA256 hex of `root` under `<name>-ticket` and
+ * `<name>-notify`, where `name` is the hub Worker's name. Everything that already
+ * holds `root` derives them itself; `dynamodb-reactive-hub deploy` puts the same
+ * values on the Worker, so no hub secret has to be distributed.
+ */
+declare function deriveHubSecrets(root: string, name: string): Promise<HubSecrets>;
+interface MintHubTicketOptions {
+    /** The hub's origin, such as `https://my-hub.example.workers.dev`. */
+    origin: string;
+    /** The hub's ticket secret. */
+    secret: string;
+    principal: string;
+    /** @default 60 */
+    lifetimeSeconds?: number;
+}
+/** A browser ticket for the hub, minted by the app that knows the signed-in user. */
+declare function mintHubTicket(options: MintHubTicketOptions): Promise<ClusterTicket & {
+    httpUrl: string;
+}>;
+/**
+ * The tracked principals holding a live socket, from `HUB_ROUTES.presence`, or
+ * undefined when the hub cannot be reached.
+ */
+declare function fetchHubPresence(options: {
+    origin: string;
+    secret: string;
+    /** @default 3000 */
+    timeoutMs?: number;
+    fetch?: typeof fetch;
+}): Promise<string[] | undefined>;
+
+export { HEARTBEAT_TIMEOUT_CLOSE_CODE, HUB_DURABLE_OBJECT, HUB_ENV, HUB_PRINCIPAL_HEADER, HUB_ROUTES, createDurableObjectHub, defineHub, deriveHubSecrets, fetchHubPresence, handleReactiveRoutes, hubClient, mintHubTicket, remoteHub };
+export type { DefinedHub, DurableObjectHub, DurableObjectHubOptions, DurableObjectStateLike, DurableObjectWebSocket, HubClientFrame, HubConfig, HubContext, HubDurableObject, HubPresenceOptions, HubSecrets, HubStub, HubWorkerEnv, MintHubTicketOptions, ReactiveRoutes, ReactiveRoutesOptions, RemoteHubOptions };

package/dist/cloudflare.js

@@ -1,3 +1,8 @@
+// ../client/src/log.ts
+function error(...values) {
+  console.error(...values);
+}
+
 // ../client/src/cluster.ts
 var DEFAULT_TICKET_LIFETIME_SECONDS = 60;
 function isRecord(value) {
@@ -261,7 +266,7 @@ var HEARTBEAT_TIMEOUT_CLOSE_CODE = 4001;
 function json(value, status = 200) {
   return Response.json(value, { status, headers: { "cache-control": "no-store" } });
 }
-function error(message, status) {
+function error2(message, status) {
   return json({ type: "error", message }, status);
 }
 function workersGlobal(name) {
@@ -333,7 +338,7 @@ function createDurableObjectHub(ctx, options) {
   };
   const accept = async (request) => {
     const principal = request.headers.get(HUB_PRINCIPAL_HEADER);
-    if (!principal) return error("Unauthorized", 401);
+    if (!principal) return error2("Unauthorized", 401);
     const Pair = options.WebSocketPair ?? workersGlobal("WebSocketPair");
     if (!Pair) throw new Error("WebSocketPair is not available in this runtime");
     const pair = new Pair();
@@ -368,10 +373,10 @@ function createDurableObjectHub(ctx, options) {
           await hub.publish(action.path, action.patches);
           return json({ type: "ok" });
         default:
-          return error("Unknown hub action", 400);
+          return error2("Unknown hub action", 400);
       }
     } catch (cause) {
-      if (cause instanceof ReactiveHubError) return error(cause.message, 400);
+      if (cause instanceof ReactiveHubError) return error2(cause.message, 400);
       throw cause;
     }
   };
@@ -453,12 +458,14 @@ function hubClient(stub) {
     publish: async (path, patches) => ok(await post({ action: "publish", path, patches }))
   };
 }
+var DEFAULT_REMOTE_HUB_TIMEOUT_MS = 3e3;
 function remoteHub(options) {
   const send2 = async (body) => {
     const response = await (options.fetch ?? fetch)(options.url, {
       method: "POST",
       headers: { authorization: `Bearer ${options.secret}`, "content-type": "application/json" },
-      body: JSON.stringify(body)
+      body: JSON.stringify(body),
+      signal: AbortSignal.timeout(options.timeoutMs ?? DEFAULT_REMOTE_HUB_TIMEOUT_MS)
     });
     if (!response.ok) throw new Error(`Hub notify failed: HTTP ${response.status}`);
   };
@@ -508,31 +515,31 @@ async function handleReactiveRoutes(request, options) {
     });
   }
   if (url.pathname === routes.notify) {
-    if (request.method !== "POST") return error("Method not allowed", 405);
-    if (!options.notifySecret) return error("Hub notify is not configured", 503);
+    if (request.method !== "POST") return error2("Method not allowed", 405);
+    if (!options.notifySecret) return error2("Hub notify is not configured", 503);
     if (!sameSecret(bearerToken(request), options.notifySecret)) {
-      return error("Unauthorized", 401);
+      return error2("Unauthorized", 401);
     }
     let body2;
     try {
       body2 = await request.json();
     } catch {
-      return error("Invalid JSON", 400);
+      return error2("Invalid JSON", 400);
     }
     const { path, patches } = body2 ?? {};
     if (typeof path !== "string" || patches !== void 0 && !Array.isArray(patches)) {
-      return error("Expected { path, patches? }", 400);
+      return error2("Expected { path, patches? }", 400);
     }
     const client = hubClient(options.hub());
     if (patches) await client.publish(path, patches);
     else await client.notify(path);
     return json({ type: "ok" });
   }
-  if (!secret) return withCors(error("Reactive hub is not configured", 503), corsOrigin);
+  if (!secret) return withCors(error2("Reactive hub is not configured", 503), corsOrigin);
   if (url.pathname === routes.ticket) {
-    if (request.method !== "POST") return withCors(error("Method not allowed", 405), corsOrigin);
+    if (request.method !== "POST") return withCors(error2("Method not allowed", 405), corsOrigin);
     const principal2 = await options.authenticate(request);
-    if (!principal2) return withCors(error("Unauthorized", 401), corsOrigin);
+    if (!principal2) return withCors(error2("Unauthorized", 401), corsOrigin);
     const socketUrl = new URL(routes.socket, url);
     socketUrl.protocol = "wss:";
     return withCors(
@@ -549,7 +556,7 @@ async function handleReactiveRoutes(request, options) {
   }
   if (url.pathname === routes.socket) {
     if (request.headers.get("upgrade") !== "websocket") {
-      return error("Expected a WebSocket upgrade", 426);
+      return error2("Expected a WebSocket upgrade", 426);
     }
     const principal2 = await verifySignedClusterTicket(url.searchParams.get("token") ?? "", secret);
     if (!principal2) return new Response("Unauthorized", { status: 401 });
@@ -557,19 +564,187 @@ async function handleReactiveRoutes(request, options) {
     forwarded.headers.set(HUB_PRINCIPAL_HEADER, principal2);
     return options.hub().fetch(forwarded);
   }
-  if (request.method !== "POST") return withCors(error("Method not allowed", 405), corsOrigin);
+  if (request.method !== "POST") return withCors(error2("Method not allowed", 405), corsOrigin);
   const principal = await verifySignedClusterTicket(bearerToken(request), secret);
-  if (!principal) return withCors(error("Unauthorized", 401), corsOrigin);
+  if (!principal) return withCors(error2("Unauthorized", 401), corsOrigin);
   let body;
   try {
     body = await request.json();
   } catch {
-    return withCors(error("Invalid JSON", 400), corsOrigin);
+    return withCors(error2("Invalid JSON", 400), corsOrigin);
   }
-  if (!isHubRequest(body)) return withCors(error("Unsupported reactive request", 400), corsOrigin);
+  if (!isHubRequest(body)) return withCors(error2("Unsupported reactive request", 400), corsOrigin);
   return withCors(await hubClient(options.hub()).request(body, principal), corsOrigin);
 }
 
-export { HEARTBEAT_TIMEOUT_CLOSE_CODE, HUB_PRINCIPAL_HEADER, createDurableObjectHub, handleReactiveRoutes, hubClient, remoteHub };
+// ../client/src/cloudflare-hub.ts
+var HUB_ROUTES = {
+  /** `POST` with the notify secret and `?principal=`: a ticket for a machine client. */
+  ticket: "/api/hub/token",
+  /** WebSocket upgrade with a signed ticket in `?token=`. */
+  socket: "/api/hub/socket",
+  /** Reactive HTTP subscribe and unsubscribe, with a signed ticket as the bearer. */
+  reactive: "/api/hub/reactive",
+  /** `POST { path, patches? }` with the notify secret, after the data behind a path changed. */
+  notify: "/api/hub/notify",
+  /** `GET` with the notify secret: `{ principals }`, the tracked principals holding a live socket. */
+  presence: "/api/hub/presence"
+};
+var HUB_ENV = {
+  TICKET_SECRET: "REACTIVE_TICKET_SECRET",
+  NOTIFY_SECRET: "HUB_NOTIFY_SECRET",
+  /** Comma-separated browser origins allowed to call the hub cross-origin. */
+  ALLOWED_ORIGINS: "ALLOWED_ORIGINS"
+};
+var HUB_DURABLE_OBJECT = { className: "ReactiveHub", binding: "REACTIVE_HUB" };
+var HUB_INSTANCE = "hub";
+var PRESENCE_ACTION_URL = "https://reactive-hub/presence";
+function sameSecret2(given, expected) {
+  const left = new TextEncoder().encode(given);
+  const right = new TextEncoder().encode(expected);
+  let difference = left.length ^ right.length;
+  for (let index = 0; index < right.length; index++) {
+    difference |= (left[index] ?? 0) ^ right[index];
+  }
+  return difference === 0;
+}
+function parseOrigins(value) {
+  return (value ?? "").split(",").map((origin) => origin.trim().replace(/\/+$/u, "")).filter(Boolean);
+}
+function defineHub(config) {
+  class ReactiveHub {
+    #ctx;
+    #reactive;
+    constructor(ctx, _env) {
+      this.#ctx = ctx;
+      const context = {
+        present: (principal) => this.#reactive.present(principal),
+        presentPrincipals: () => this.#presentPrincipals()
+      };
+      const presence = config.presence;
+      this.#reactive = createDurableObjectHub(ctx, {
+        paths: config.paths(context),
+        ...presence ? {
+          presence: {
+            principals: presence.principals,
+            ...presence.timeoutMs === void 0 ? {} : { timeoutMs: presence.timeoutMs },
+            onChange: async () => {
+              for (const path of presence.notify ?? []) {
+                await this.#reactive.hub.notify(path);
+              }
+            }
+          }
+        } : {}
+      });
+    }
+    #presentPrincipals() {
+      const principals = /* @__PURE__ */ new Set();
+      for (const socket of this.#ctx.getWebSockets()) {
+        const principal = this.#reactive.principalOf(socket);
+        if (this.#reactive.present(principal)) principals.add(principal);
+      }
+      return [...principals].sort();
+    }
+    async fetch(request) {
+      if (request.url === PRESENCE_ACTION_URL) {
+        return Response.json(
+          { principals: this.#presentPrincipals() },
+          { headers: { "cache-control": "no-store" } }
+        );
+      }
+      return this.#reactive.fetch(request);
+    }
+    webSocketMessage(socket, message) {
+      return this.#reactive.webSocketMessage(socket, message);
+    }
+    webSocketClose(socket, code) {
+      return this.#reactive.webSocketClose(socket, code);
+    }
+    webSocketError(socket) {
+      return this.#reactive.webSocketError(socket);
+    }
+    alarm() {
+      return this.#reactive.alarm();
+    }
+  }
+  const worker = {
+    async fetch(request, env) {
+      const stub = () => env.REACTIVE_HUB.get(env.REACTIVE_HUB.idFromName(HUB_INSTANCE));
+      const notifySecret = env.HUB_NOTIFY_SECRET;
+      const authorized = () => Boolean(notifySecret) && sameSecret2(bearerToken(request), notifySecret);
+      try {
+        if (new URL(request.url).pathname === HUB_ROUTES.presence) {
+          if (request.method !== "GET") return new Response(null, { status: 405 });
+          if (!notifySecret) return new Response(null, { status: 503 });
+          if (!authorized()) return new Response(null, { status: 401 });
+          return await stub().fetch(new Request(PRESENCE_ACTION_URL));
+        }
+        const response = await handleReactiveRoutes(request, {
+          routes: HUB_ROUTES,
+          secret: env.REACTIVE_TICKET_SECRET,
+          notifySecret,
+          allowedOrigins: parseOrigins(env.ALLOWED_ORIGINS),
+          hub: stub,
+          authenticate: (incoming) => {
+            const principal = new URL(incoming.url).searchParams.get("principal") ?? "";
+            return authorized() && config.machinePrincipal?.(principal) ? principal : void 0;
+          }
+        });
+        return response ?? new Response("Not found", { status: 404 });
+      } catch (cause) {
+        error("hub request failed", request.method, new URL(request.url).pathname, cause);
+        return Response.json({ error: "Hub error" }, { status: 500 });
+      }
+    }
+  };
+  return { ReactiveHub, worker };
+}
+async function hmacHex(key, label) {
+  const encoder2 = new TextEncoder();
+  const cryptoKey = await crypto.subtle.importKey(
+    "raw",
+    encoder2.encode(key),
+    { name: "HMAC", hash: "SHA-256" },
+    false,
+    ["sign"]
+  );
+  const signature = new Uint8Array(
+    await crypto.subtle.sign("HMAC", cryptoKey, encoder2.encode(label))
+  );
+  return Array.from(signature, (byte) => byte.toString(16).padStart(2, "0")).join("");
+}
+async function deriveHubSecrets(root, name) {
+  const [ticket, notify] = await Promise.all([
+    hmacHex(root, `${name}-ticket`),
+    hmacHex(root, `${name}-notify`)
+  ]);
+  return { ticket, notify };
+}
+async function mintHubTicket(options) {
+  const socketUrl = new URL(HUB_ROUTES.socket, options.origin);
+  socketUrl.protocol = "wss:";
+  const ticket = await createSignedClusterTicket({
+    secret: options.secret,
+    principal: options.principal,
+    url: socketUrl.toString(),
+    ...options.lifetimeSeconds === void 0 ? {} : { lifetimeSeconds: options.lifetimeSeconds }
+  });
+  return { ...ticket, httpUrl: new URL(HUB_ROUTES.reactive, options.origin).toString() };
+}
+async function fetchHubPresence(options) {
+  try {
+    const response = await (options.fetch ?? fetch)(new URL(HUB_ROUTES.presence, options.origin), {
+      headers: { authorization: `Bearer ${options.secret}` },
+      signal: AbortSignal.timeout(options.timeoutMs ?? 3e3)
+    });
+    if (!response.ok) return void 0;
+    const { principals } = await response.json();
+    return Array.isArray(principals) && principals.every((value) => typeof value === "string") ? principals : void 0;
+  } catch {
+    return void 0;
+  }
+}
+
+export { HEARTBEAT_TIMEOUT_CLOSE_CODE, HUB_DURABLE_OBJECT, HUB_ENV, HUB_PRINCIPAL_HEADER, HUB_ROUTES, createDurableObjectHub, defineHub, deriveHubSecrets, fetchHubPresence, handleReactiveRoutes, hubClient, mintHubTicket, remoteHub };
 //# sourceMappingURL=cloudflare.js.map
 //# sourceMappingURL=cloudflare.js.map