dynamodb-reactive 0.3.0 → 0.5.0

package/README.md

@@ -24,15 +24,17 @@ pnpm add aws-cdk-lib constructs esbuild
 
 Every public entry point supplies ESM (`.js` and `.d.ts`) and CommonJS (`.cjs` and `.d.cts`) conditions, so both `import` and `require()` consumers are supported:
 
-| Import | Contents |
-| --- | --- |
-| `dynamodb-reactive` | Core table and schema exports |
-| `dynamodb-reactive/core` | Same core API, explicitly named |
-| `dynamodb-reactive/server` | Routers, database context, and HTTP/stream handlers |
-| `dynamodb-reactive/client` | React-free client, WebSocket manager, and query-key helpers |
-| `dynamodb-reactive/react` | Provider and React hooks |
-| `dynamodb-reactive/infra` | `ReactiveEngine` and its configuration types |
-| `dynamodb-reactive/cluster` | Cluster-worker connection, signed tickets, and wire-protocol types |
+| Import                         | Contents                                                                    |
+| ------------------------------ | --------------------------------------------------------------------------- |
+| `dynamodb-reactive`            | Core table and schema exports                                               |
+| `dynamodb-reactive/core`       | Same core API, explicitly named                                             |
+| `dynamodb-reactive/server`     | Routers, database context, and HTTP/stream handlers                         |
+| `dynamodb-reactive/client`     | React-free client, WebSocket manager, and query-key helpers                 |
+| `dynamodb-reactive/react`      | Provider and React hooks                                                    |
+| `dynamodb-reactive/infra`      | `ReactiveEngine` and its configuration types                                |
+| `dynamodb-reactive/cluster`    | Cluster-worker connection, signed tickets, and wire-protocol types          |
+| `dynamodb-reactive/hub`        | Runtime-free reactive hub core for backends that hold WebSockets themselves |
+| `dynamodb-reactive/cloudflare` | Durable Object hub shell and ticket, socket, and reactive HTTP routes       |
 
 React code must import the provider and hooks from `dynamodb-reactive/react`. Importing `dynamodb-reactive/client` does not load React.
 
@@ -84,20 +86,18 @@ const t = initReactive<AppContext>();
 
 export const appRouter = t.router({
   todos: {
-    list: t.procedure
-      .input(z.object({ ownerId: z.string() }))
-      .query(({ ctx, input }) => {
-        if (input.ownerId !== ctx.principalId) {
-          throw new Error('Forbidden');
-        }
-        return ctx.db
-          .query(TodoTable)
-          .useIndex('byOwner')
-          .filter((q) => q.eq(TodoTable.field.ownerId, input.ownerId))
-          .sortDescending()
-          .take(100)
-          .execute();
-      }),
+    list: t.procedure.input(z.object({ ownerId: z.string() })).query(({ ctx, input }) => {
+      if (input.ownerId !== ctx.principalId) {
+        throw new Error('Forbidden');
+      }
+      return ctx.db
+        .query(TodoTable)
+        .useIndex('byOwner')
+        .filter((q) => q.eq(TodoTable.field.ownerId, input.ownerId))
+        .sortDescending()
+        .take(100)
+        .execute();
+    }),
 
     create: t.procedure
       .input(z.object({ text: z.string().min(1) }))
@@ -126,15 +126,13 @@ export const appRouter = t.router({
         ),
       ),
 
-    delete: t.procedure
-      .input(z.object({ id: z.string() }))
-      .mutation(async ({ ctx, input }) => {
-        await ctx.db.delete(TodoTable, {
-          pk: `USER#${ctx.principalId}`,
-          sk: `TODO#${input.id}`,
-        });
-        return { id: input.id };
-      }),
+    delete: t.procedure.input(z.object({ id: z.string() })).mutation(async ({ ctx, input }) => {
+      await ctx.db.delete(TodoTable, {
+        pk: `USER#${ctx.principalId}`,
+        sk: `TODO#${input.id}`,
+      });
+      return { id: input.id };
+    }),
   },
 });
 
@@ -297,10 +295,7 @@ The HTTP principal must own the WebSocket connection named in the request. The c
 
 ```ts
 // reactive-api.ts
-import {
-  createReactiveHandler,
-  type ReactiveRequest,
-} from 'dynamodb-reactive/server';
+import { createReactiveHandler, type ReactiveRequest } from 'dynamodb-reactive/server';
 import { z } from 'zod';
 
 import { authenticateBearer } from './auth.js';
@@ -428,9 +423,7 @@ export function Todos({ ownerId }: { ownerId: string }) {
   return (
     <section aria-busy={todos.loading || todos.stale}>
       <p>Connection: {connection}</p>
-      <button onClick={() => void createTodo.mutate({ text: 'New todo' })}>
-        Add
-      </button>
+      <button onClick={() => void createTodo.mutate({ text: 'New todo' })}>Add</button>
       {todos.data?.map((todo) => (
         <div key={todo.id}>
           <button
@@ -444,9 +437,7 @@ export function Todos({ ownerId }: { ownerId: string }) {
             {todo.completed ? 'Undo' : 'Complete'}
           </button>
           <span>{todo.text}</span>
-          <button onClick={() => void deleteTodo.mutate({ id: todo.id })}>
-            Delete
-          </button>
+          <button onClick={() => void deleteTodo.mutate({ id: todo.id })}>Delete</button>
         </div>
       ))}
     </section>
@@ -544,6 +535,93 @@ Applications can mint stateless tickets with `createSignedClusterTicket({ secret
 
 The module also exports the wire-protocol types (`SubscribeRequest`, `SnapshotResponse`, `ResyncEvent`, `WebSocketEvent`, and the rest) for backends that serve the protocol without the AWS engine. A server that only sends `resync` events is correct: the client answers a resync by re-sending `subscribe`, and accepts the new snapshot only when its `version` is higher than the last one.
 
+## Reactive hubs and Cloudflare Durable Objects
+
+`dynamodb-reactive/hub` is the server half of the wire protocol for backends that hold WebSockets themselves. `createReactiveHub({ sockets, versions, paths })` answers `init` and `ping`, stores subscriptions on each socket's attachment so they survive hibernation, checks that an HTTP caller owns the connection it subscribes, and fans out `notify(path)` as `resync` events or `publish(path, patches)` as `patch` events. Each path has its own version. `paths` maps fixed names to handlers, or is a function that resolves parameterised paths such as `drafts.<id>`:
+
+```ts
+const paths = (path: string) =>
+  path.startsWith('drafts.')
+    ? {
+        // Runs before the subscription is stored; every subscriber of a path receives its pushes.
+        authorize: ({ principal }) => ownsDraft(principal, path.slice(7)),
+        snapshot: () => loadDraft(path.slice(7)),
+      }
+    : undefined;
+```
+
+`publish` sends the same patches to every subscriber of a path, so use it only for paths whose subscribers all see the same data. Subscriptions are rejected once a socket's attachment would exceed 2,048 bytes, the hibernation limit.
+
+`dynamodb-reactive/cloudflare` wires the hub to a Durable Object. It takes the object's `ctx` instead of extending `DurableObject`, so it imports nothing from `cloudflare:workers`, and your class keeps its own name and migrations:
+
+```ts
+import { DurableObject } from 'cloudflare:workers';
+import {
+  createDurableObjectHub,
+  handleReactiveRoutes,
+  hubClient,
+} from 'dynamodb-reactive/cloudflare';
+
+export class ReactiveHubObject extends DurableObject<Env> {
+  private readonly hub = createDurableObjectHub(this.ctx, { paths });
+  override fetch(request: Request) {
+    return this.hub.fetch(request);
+  }
+  override webSocketMessage(socket: WebSocket, message: string | ArrayBuffer) {
+    this.hub.webSocketMessage(socket, message);
+  }
+  override webSocketClose(socket: WebSocket, code: number) {
+    return this.hub.webSocketClose(socket, code);
+  }
+  override webSocketError(socket: WebSocket) {
+    return this.hub.webSocketError(socket);
+  }
+}
+
+const hub = (env: Env) => env.HUB.get(env.HUB.idFromName('hub'));
+
+export default {
+  async fetch(request: Request, env: Env) {
+    const response = await handleReactiveRoutes(request, {
+      routes: {
+        ticket: '/api/reactive/token',
+        socket: '/api/reactive/socket',
+        reactive: '/api/reactive',
+      },
+      secret: env.REACTIVE_TICKET_SECRET,
+      hub: () => hub(env),
+      authenticate: (request) => principalFor(request), // undefined answers 401
+    });
+    return response ?? new Response('Not found', { status: 404 });
+  },
+};
+
+// Anywhere in the Worker, after the data behind a path changes:
+await hubClient(hub(env)).notify('drafts.123');
+```
+
+`handleReactiveRoutes` issues signed tickets, verifies them on the WebSocket upgrade and on reactive HTTP requests, and forwards both to the hub with the verified principal. It answers 503 while `secret` is unset. By default the object answers `ping` with `pong` through the runtime's WebSocket auto-response, so heartbeats do not wake a hibernating object. Versions are kept in the object's storage under `version:<path>`; pass `versionKey` to change that. To shard, pick the instance per path with `idFromName`.
+
+### Presence
+
+Pass `presence` to know whether a principal, such as a cluster worker, is online without it polling over HTTP:
+
+```ts
+private readonly hub = createDurableObjectHub(this.ctx, {
+  paths,
+  presence: {
+    principals: ['worker'],
+    timeoutMs: 90_000, // the default; clients must ping more often than this
+    onChange: () => hubClient(stub).notify('cluster.status'),
+  },
+});
+override alarm() {
+  return this.hub.alarm();
+}
+```
+
+`hub.present(principal)` is true while the principal holds a socket that pinged within `timeoutMs`. The runtime records each auto-answered ping without waking the object, so presence costs nothing per heartbeat. An alarm wakes the object when the stalest tracked socket would time out, closes silent sockets with code `4001`, and reschedules while tracked sockets remain. That sweep is what catches a peer that vanished without a close frame, which an open socket alone never reveals. `onChange` runs when a principal gains its first live socket or loses its last one; the last reported state is stored under `presence:<principal>`, so each change is reported once. Presence needs `autoPong` and the object's `alarm` delegated to the hub.
+
 ## Delivery model
 
 1. The client establishes a WebSocket and receives its API Gateway connection ID.
@@ -553,7 +631,7 @@ The module also exports the wire-protocol types (`SubscribeRequest`, `SnapshotRe
 
 Pending delivery is durable until a send completes, so retries are at least once. A send followed by a failed clear can produce a duplicate; clients must keep duplicate handling enabled. Patch messages larger than 30 KiB become a small `resync` instruction rather than a WebSocket payload. Serialized subscription state is limited to 300 KiB.
 
-Connection and subscription records receive three-hour TTLs. Each authorized HTTP operation refreshes the connection lease; registration and re-registration renew the query and dependency records. The browser sends a WebSocket heartbeat every five minutes, but API Gateway can still close idle or maximum-age connections; the client reconnects and re-registers active subscriptions. DynamoDB TTL removes expired records asynchronously and is cleanup, not an authorization or immediate-deletion mechanism. HTTP ownership checks explicitly enforce connection status and lease expiry.
+Connection and subscription records receive three-hour TTLs. Each authorized HTTP operation refreshes the connection lease; registration and re-registration renew the query and dependency records. The browser sends a WebSocket heartbeat every five minutes (`heartbeatInterval`), but API Gateway can still close idle or maximum-age connections; the client reconnects and re-registers active subscriptions. A heartbeat unanswered within `heartbeatTimeout` (15 seconds by default) marks the socket dead, so a server or network that vanished without a close frame is replaced instead of trusted. `connectClusterWorker` pings every 30 seconds. DynamoDB TTL removes expired records asynchronously and is cleanup, not an authorization or immediate-deletion mechanism. HTTP ownership checks explicitly enforce connection status and lease expiry.
 
 ## Security
 

package/dist/{client-Zb67giI5.d.ts → client-wZQ9XC9S.d.ts}

@@ -45,6 +45,17 @@ interface ReactiveClientConfig {
     connectionTimeout?: number;
     /** Maximum time for the init/connected/pong handshake. @default 10000 */
     handshakeTimeout?: number;
+    /**
+     * Interval between `ping` frames once connected. The default suits API Gateway, which bills
+     * every message and closes sockets idle for 10 minutes; Durable Object hubs answer pings
+     * without waking, so cluster workers can ping far more often. @default 300000
+     */
+    heartbeatInterval?: number;
+    /**
+     * Time a `ping` may go unanswered before the socket is treated as dead and replaced. A server
+     * that vanishes without closing the connection is otherwise never noticed. @default 15000
+     */
+    heartbeatTimeout?: number;
     /**
      * Callback when connected
      */

package/dist/client.cjs

@@ -29,9 +29,7 @@ function canonicalize(value, seen, key, arrayItem = false, applyToJSON = true) {
         if (Array.isArray(value)) {
           const items = [];
           for (let index = 0; index < value.length; index++) {
-            items.push(
-              canonicalize(value[index], seen, String(index), true) ?? "null"
-            );
+            items.push(canonicalize(value[index], seen, String(index), true) ?? "null");
           }
           return `[${items.join(",")}]`;
         }
@@ -48,6 +46,9 @@ function canonicalize(value, seen, key, arrayItem = false, applyToJSON = true) {
         seen.delete(value);
       }
     }
+    case "bigint":
+    case "function":
+    case "symbol":
     default:
       throw new TypeError(`Unsupported query input value: ${typeof value}`);
   }
@@ -55,7 +56,6 @@ function canonicalize(value, seen, key, arrayItem = false, applyToJSON = true) {
 function getQueryKey(path, input) {
   return `${JSON.stringify(path)}:${canonicalize(input, /* @__PURE__ */ new Set(), "") ?? "undefined"}`;
 }
-var { applyPatch } = jsonpatch__default.default;
 function applyPatches(document, patches) {
   if (patches.length === 0) {
     return document;
@@ -74,7 +74,7 @@ function applyPatches(document, patches) {
     return op;
   });
   try {
-    const result = applyPatch(
+    const result = jsonpatch__default.default.applyPatch(
       structuredClone(document),
       operations,
       true,
@@ -94,12 +94,13 @@ function error(...values) {
 }
 
 // ../client/src/websocket.ts
-var HEARTBEAT_INTERVAL_MS = 5 * 60 * 1e3;
 function withDefaults(config) {
   return {
     autoReconnect: true,
     connectionTimeout: 1e4,
     handshakeTimeout: 1e4,
+    heartbeatInterval: 5 * 60 * 1e3,
+    heartbeatTimeout: 15e3,
     maxReconnectAttempts: 10,
     reconnectDelay: 1e3,
     ...config
@@ -113,6 +114,7 @@ var WebSocketManager = class {
   reconnectTimer = null;
   handshakeTimer = null;
   heartbeatTimer = null;
+  pongTimer = null;
   messageHandlers = /* @__PURE__ */ new Set();
   stateHandlers = /* @__PURE__ */ new Set();
   handshakeHandlers = /* @__PURE__ */ new Set();
@@ -212,16 +214,7 @@ var WebSocketManager = class {
       };
       nextSocket.onclose = () => {
         if (!this.isCurrent(nextSocket, generation)) return;
-        this.clearConnectionTimers();
-        this.ws = null;
-        this._connectionId = null;
-        this.setState("disconnected");
-        this.invokeLifecycleCallback("onDisconnect", this.config.onDisconnect);
-        if (this.config.autoReconnect && !this.intentionalDisconnect) {
-          this.scheduleReconnect();
-        } else {
-          this.rejectWaiters(new Error("WebSocket disconnected"));
-        }
+        this.handleClose();
       };
       nextSocket.onerror = () => {
         if (!this.isCurrent(nextSocket, generation)) return;
@@ -310,6 +303,7 @@ var WebSocketManager = class {
         return;
       }
       if (message.type === "pong") {
+        this.clearPongTimer();
         if (!this._connectionId || this.state === "connected") return;
         this.clearHandshakeTimer();
         this.lastConnectionError = void 0;
@@ -338,6 +332,18 @@ var WebSocketManager = class {
       socket.close(4e3, "Handshake timeout");
     }, this.config.handshakeTimeout);
   }
+  handleClose() {
+    this.clearConnectionTimers();
+    this.ws = null;
+    this._connectionId = null;
+    this.setState("disconnected");
+    this.invokeLifecycleCallback("onDisconnect", this.config.onDisconnect);
+    if (this.config.autoReconnect && !this.intentionalDisconnect) {
+      this.scheduleReconnect();
+    } else {
+      this.rejectWaiters(new Error("WebSocket disconnected"));
+    }
+  }
   startHeartbeat(socket, generation) {
     this.clearHeartbeatTimer();
     this.heartbeatTimer = setInterval(() => {
@@ -345,7 +351,17 @@ var WebSocketManager = class {
         return;
       }
       socket.send(JSON.stringify({ type: "ping" }));
-    }, HEARTBEAT_INTERVAL_MS);
+      this.pongTimer ??= setTimeout(() => {
+        this.pongTimer = null;
+        if (!this.isCurrent(socket, generation)) return;
+        const failure = new Error("WebSocket heartbeat timed out");
+        this.lastConnectionError = failure;
+        this.invokeLifecycleCallback("onError", this.config.onError, failure);
+        socket.onclose = null;
+        socket.close(4001, "Heartbeat timeout");
+        this.handleClose();
+      }, this.config.heartbeatTimeout);
+    }, this.config.heartbeatInterval);
   }
   isCurrent(socket, generation) {
     return this.ws === socket && this.socketGeneration === generation;
@@ -412,9 +428,15 @@ var WebSocketManager = class {
     clearInterval(this.heartbeatTimer);
     this.heartbeatTimer = null;
   }
+  clearPongTimer() {
+    if (!this.pongTimer) return;
+    clearTimeout(this.pongTimer);
+    this.pongTimer = null;
+  }
   clearConnectionTimers() {
     this.clearHandshakeTimer();
     this.clearHeartbeatTimer();
+    this.clearPongTimer();
   }
   clearTimers() {
     this.clearConnectionTimers();
@@ -514,10 +536,7 @@ var ReactiveClient = class {
       this.subscriptionsByKey.set(key, shared);
       this.subscriptionsById.set(shared.id, shared);
       if (this.connectionState === "connected") {
-        void this.ensureRegistered(
-          shared,
-          this.wsManager.generation
-        ).catch(() => void 0);
+        void this.ensureRegistered(shared, this.wsManager.generation).catch(() => void 0);
       }
     }
     const leaseId = generateId();
@@ -526,9 +545,7 @@ var ReactiveClient = class {
       onError: options.onError
     });
     if (this.connectionState === "connected" && (!shared.hasRegistered || shared.stale) && !shared.registrationPromise) {
-      void this.ensureRegistered(shared, this.wsManager.generation).catch(
-        () => void 0
-      );
+      void this.ensureRegistered(shared, this.wsManager.generation).catch(() => void 0);
     }
     const state = shared;
     let released = false;
@@ -617,9 +634,7 @@ var ReactiveClient = class {
   registerActiveSubscriptions(socketGeneration) {
     for (const state of this.subscriptionsByKey.values()) {
       if (state.active) {
-        void this.ensureRegistered(state, socketGeneration).catch(
-          () => void 0
-        );
+        void this.ensureRegistered(state, socketGeneration).catch(() => void 0);
       }
     }
   }
@@ -672,9 +687,7 @@ var ReactiveClient = class {
           })
         });
         if (!response.ok) {
-          throw new Error(
-            `Subscribe failed: ${response.status} ${response.statusText}`
-          );
+          throw new Error(`Subscribe failed: ${response.status} ${response.statusText}`);
         }
         const result = await response.json();
         if (result.type === "error") {
@@ -693,12 +706,7 @@ var ReactiveClient = class {
         throw cause;
       } finally {
         if ((!state.active || !isCurrent()) && requestIssued) {
-          void this.sendUnsubscribe(
-            registrationConnectionId,
-            state.id,
-            generation,
-            registrationId
-          );
+          void this.sendUnsubscribe(registrationConnectionId, state.id, generation, registrationId);
         }
         if (state.registrationPromise === request) {
           state.registrationPromise = void 0;
@@ -803,15 +811,12 @@ var ReactiveClient = class {
       return;
     }
     this.discardStalePatches(state);
-    while (true) {
-      const next = [...state.patchBuffer.values()].filter((patch) => patch.fromVersion === state.version).sort((left, right) => left.toVersion - right.toVersion)[0];
+    for (; ; ) {
+      const next = [...state.patchBuffer.values()].filter((patch) => patch.fromVersion === state.version).sort((left, right) => left.toVersion - right.toVersion).at(0);
       if (!next) break;
       state.patchBuffer.delete(next.messageId);
       try {
-        state.authoritativeData = applyPatches(
-          state.authoritativeData,
-          next.patches
-        );
+        state.authoritativeData = applyPatches(state.authoritativeData, next.patches);
         state.version = next.toVersion;
         state.appliedMessageIds.add(next.messageId);
         const awaitingReconciliation = this.hasSettledLayers(state);
@@ -849,12 +854,7 @@ var ReactiveClient = class {
     state.stale = true;
     state.loading = true;
     this.notifySubscription(state);
-    let request;
-    request = this.ensureRegistered(
-      state,
-      this.wsManager.generation,
-      true
-    ).finally(() => {
+    const request = this.ensureRegistered(state, this.wsManager.generation, true).finally(() => {
       if (state.resyncPromise === request) {
         state.resyncPromise = void 0;
         state.resyncGeneration = void 0;
@@ -922,7 +922,10 @@ var ReactiveClient = class {
     if (options?.optimisticData === void 0) return void 0;
     return (data) => {
       if (!Array.isArray(data)) return data;
-      const optimistic = settled ? result === void 0 ? typeof options.optimisticData === "function" ? options.optimisticData(input, data) : options.optimisticData : result : typeof options.optimisticData === "function" ? options.optimisticData(input, data) : options.optimisticData;
+      const optimistic = settled ? (
+        // oxlint-disable-next-line typescript/prefer-nullish-coalescing -- null is a valid mutation result.
+        result === void 0 ? typeof options.optimisticData === "function" ? options.optimisticData(input, data) : options.optimisticData : result
+      ) : typeof options.optimisticData === "function" ? options.optimisticData(input, data) : options.optimisticData;
       if (settled && optimistic !== null && typeof optimistic === "object") {
         const optimisticId = optimistic.id;
         if (optimisticId !== void 0 && data.some(
@@ -937,12 +940,7 @@ var ReactiveClient = class {
   settleMutationLayers(mutationId, input, result, options, states) {
     for (const state of states) {
       const layer = state.optimisticLayers.get(mutationId);
-      const updater = this.createOptimisticUpdater(
-        input,
-        options,
-        result,
-        true
-      );
+      const updater = this.createOptimisticUpdater(input, options, result, true);
       if (!layer || !updater) continue;
       layer.updater = updater;
       layer.settledRevision = ++state.settlementRevision;