dynamodb-reactive 0.6.2 → 0.7.0

package/README.md

@@ -628,18 +628,73 @@ override alarm() {
 
 ### Hubs for apps hosted elsewhere
 
-An app on Vercel or AWS can still use a Cloudflare hub. Add `routes.notify` with a `notifySecret`, and call it after writes from any backend:
+An app on Vercel or AWS cannot hold WebSockets cheaply, so it runs a packaged hub on Cloudflare: the Cloudflare counterpart of `ReactiveEngine`. `defineHub` is the whole Worker; the app supplies only its path rules.
 
 ```ts
-import { remoteHub } from 'dynamodb-reactive/cloudflare';
+// hub/index.ts
+import { defineHub } from 'dynamodb-reactive/cloudflare';
 
-const hub = remoteHub({ url: 'https://hub.example.com/api/reactive/notify', secret });
-await hub.notify('scraper.status');
+const isWorker = (principal: string) => principal.startsWith('worker:');
+
+const hub = defineHub({
+  paths: (context) => ({
+    'workers.status': {
+      authorize: ({ principal }) => principal.startsWith('admin:'),
+      snapshot: () => ({ online: context.presentPrincipals() }),
+    },
+    'jobs.queued': {
+      authorize: ({ principal }) => isWorker(principal),
+      snapshot: () => ({ ready: true }),
+    },
+  }),
+  // Machine workers that hold a socket count as online; their status path is notified on change.
+  presence: { principals: isWorker, notify: ['workers.status'] },
+  // Machine workers get tickets from the hub with the notify secret.
+  machinePrincipal: isWorker,
+});
+
+export const ReactiveHub = hub.ReactiveHub;
+export default hub.worker;
 ```
 
-Each call aborts after `timeoutMs` (default 3000 ms) and throws on a timeout or non-2xx answer, so wrap it where a lost notify must not fail the write.
+Deploy it with the bundled command, which writes the Wrangler config (Durable Object binding and migration, `workers_dev`, allowed origins), deploys, and puts the secrets. It needs `wrangler` installed and `CLOUDFLARE_API_TOKEN`:
+
+```sh
+dynamodb-reactive-hub deploy --name my-hub --entry hub/index.ts   --account <account-id> --allowed-origins https://my.app --secret-root-env APP_SECRET
+```
+
+The hub is served at `https://my-hub.<account subdomain>.workers.dev`; keep that URL as a constant in the app. Its routes are `HUB_ROUTES`:
+
+| Route                            | Auth          | Purpose                                                   |
+| -------------------------------- | ------------- | --------------------------------------------------------- |
+| `POST /api/hub/token?principal=` | notify secret | ticket for a `machinePrincipal`                           |
+| `GET /api/hub/socket?token=`     | signed ticket | WebSocket upgrade                                         |
+| `POST /api/hub/reactive`         | signed ticket | subscribe and unsubscribe                                 |
+| `POST /api/hub/notify`           | notify secret | `{ path, patches? }` after the data behind a path changed |
+| `GET /api/hub/presence`          | notify secret | `{ principals }` holding a live socket                    |
+
+No hub secret has to be distributed. Both are HMAC digests of a secret the app already holds (`--secret-root-env`), and every backend derives them with `deriveHubSecrets(root, name)`:
+
+```ts
+import { deriveHubSecrets, mintHubTicket, remoteHub } from 'dynamodb-reactive/cloudflare';
+
+const HUB_ORIGIN = 'https://my-hub.example.workers.dev';
+const secrets = await deriveHubSecrets(process.env.APP_SECRET!, 'my-hub');
+
+// After a write, from Vercel, a Lambda or a worker:
+await remoteHub({ url: `${HUB_ORIGIN}/api/hub/notify`, secret: secrets.notify }).notify(
+  'jobs.queued',
+);
+
+// In the app's ticket route, for the signed-in user:
+const ticket = await mintHubTicket({
+  origin: HUB_ORIGIN,
+  secret: secrets.ticket,
+  principal: 'admin:me',
+});
+```
 
-The app can mint browser tickets itself with `createSignedClusterTicket` and the hub's ticket secret, pointing `url` at the hub's socket route. Pass `allowedOrigins` so browsers on the app's origin may call the ticket and reactive routes cross-origin. When the data lives outside Cloudflare, a path's snapshot can be a small marker such as `{ version }`, and the page re-fetches from its own API whenever the marker changes.
+`remoteHub` calls abort after `timeoutMs` (default 3000 ms) and throw on a timeout or non-2xx answer, so wrap them where a lost notify must not fail the write. `fetchHubPresence` reads the presence route. When the data lives outside Cloudflare, a path's snapshot can be a small marker such as `{ ready: true }`, and the page re-fetches from its own API whenever it is pushed.
 
 ## Delivery model
 

package/dist/cloudflare.cjs

@@ -1,5 +1,10 @@
 'use strict';
 
+// ../client/src/log.ts
+function error(...values) {
+  console.error(...values);
+}
+
 // ../client/src/cluster.ts
 var DEFAULT_TICKET_LIFETIME_SECONDS = 60;
 function isRecord(value) {
@@ -263,7 +268,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) {
@@ -335,7 +340,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();
@@ -370,10 +375,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;
     }
   };
@@ -512,31 +517,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(
@@ -553,7 +558,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 });
@@ -561,24 +566,199 @@ 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);
 }
 
+// ../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;
+  }
+}
+
 exports.HEARTBEAT_TIMEOUT_CLOSE_CODE = HEARTBEAT_TIMEOUT_CLOSE_CODE;
+exports.HUB_DURABLE_OBJECT = HUB_DURABLE_OBJECT;
+exports.HUB_ENV = HUB_ENV;
 exports.HUB_PRINCIPAL_HEADER = HUB_PRINCIPAL_HEADER;
+exports.HUB_ROUTES = HUB_ROUTES;
 exports.createDurableObjectHub = createDurableObjectHub;
+exports.defineHub = defineHub;
+exports.deriveHubSecrets = deriveHubSecrets;
+exports.fetchHubPresence = fetchHubPresence;
 exports.handleReactiveRoutes = handleReactiveRoutes;
 exports.hubClient = hubClient;
+exports.mintHubTicket = mintHubTicket;
 exports.remoteHub = remoteHub;
 //# sourceMappingURL=cloudflare.cjs.map
 //# sourceMappingURL=cloudflare.cjs.map