dynamodb-reactive 0.4.0 → 0.6.0

package/dist/cloudflare.d.cts

@@ -6,7 +6,8 @@ import { HubSocket, HubPaths } from './hub.cjs';
  * takes the Durable Object's `ctx` instead of extending `DurableObject`, so this
  * entry imports nothing from `cloudflare:workers` and builds like every other
  * entry. Your Durable Object class owns its name and migrations and delegates
- * `fetch`, `webSocketMessage`, `webSocketClose` and `webSocketError` to it.
+ * `fetch`, `webSocketMessage`, `webSocketClose` and `webSocketError` to it, plus
+ * `alarm` when it tracks presence.
  */
 /** Set by the route handler on requests it forwards to the hub; never trusted from clients. */
 declare const HUB_PRINCIPAL_HEADER = "x-reactive-principal";
@@ -19,9 +20,17 @@ interface DurableObjectStateLike {
     acceptWebSocket(socket: DurableObjectWebSocket, tags?: string[]): void;
     getWebSockets(tag?: string): DurableObjectWebSocket[];
     setWebSocketAutoResponse?(pair?: unknown): void;
+    /** When the runtime last answered this socket's `ping` itself; needed for presence. */
+    getWebSocketAutoResponseTimestamp?(socket: DurableObjectWebSocket): Date | null;
     storage: {
         get<T>(key: string): Promise<T | undefined>;
         put<T>(key: string, value: T): Promise<void>;
+        /** Lets presence forget principals that left instead of storing `false`. */
+        delete?(key: string): Promise<boolean>;
+        /** Needed for presence. */
+        getAlarm?(): Promise<number | null>;
+        /** Needed for presence. */
+        setAlarm?(scheduledTime: number): Promise<void>;
     };
 }
 /** Anything with a Durable Object stub's `fetch`. */
@@ -32,6 +41,10 @@ type WebSocketPairConstructor = new () => {
     0: DurableObjectWebSocket;
     1: DurableObjectWebSocket;
 };
+/** A frame from the client that is not part of the protocol, such as `{ type: 'listening' }`. */
+type HubClientFrame = Record<string, unknown> & {
+    type: string;
+};
 interface DurableObjectHubOptions {
     paths: HubPaths;
     /** Storage key for a path's version. Defaults to `version:<path>`. */
@@ -42,15 +55,50 @@ interface DurableObjectHubOptions {
      * Defaults to true.
      */
     autoPong?: boolean;
+    /**
+     * Tracks whether principals hold a live socket, so the hub can report a
+     * worker or listener as online without it polling over HTTP. Requires `autoPong`.
+     */
+    presence?: HubPresenceOptions;
+    /** Runs after a socket is accepted. */
+    onOpen?: (socket: DurableObjectWebSocket, principal: string) => void | Promise<void>;
+    /**
+     * Runs when a socket closes or errors. The socket may still be listed by
+     * `sockets()` during this call, so exclude it when counting.
+     */
+    onClose?: (socket: DurableObjectWebSocket, principal: string) => void | Promise<void>;
+    /** Handles frames the protocol does not, such as application presence updates. */
+    onMessage?: (socket: DurableObjectWebSocket, principal: string, frame: HubClientFrame) => void | Promise<void>;
     /** Workers' `WebSocketPair`; injectable for tests. */
     WebSocketPair?: WebSocketPairConstructor;
     /** Creates a connection id; injectable for tests. */
     randomId?: () => string;
 }
+interface HubPresenceOptions {
+    /** The principals to track, or a predicate for open-ended ones such as anonymous listeners. */
+    principals: readonly string[] | ((principal: string) => boolean);
+    /**
+     * A socket whose last `ping` is older than this is closed as dead, which is how
+     * a peer that vanished without a close frame is noticed. Clients must ping more
+     * often than this. @default 90000
+     */
+    timeoutMs?: number;
+    /**
+     * Called when a principal gains its first live socket or loses its last one,
+     * for example to `notify` a status path. The last reported state is kept in
+     * storage under `presence:<principal>`, so each change is reported once.
+     */
+    onChange?: (principal: string, present: boolean) => void | Promise<void>;
+}
 /** Wires the hub core to a Durable Object's hibernatable WebSockets and storage. */
 declare function createDurableObjectHub(ctx: DurableObjectStateLike, options: DurableObjectHubOptions): {
     hub: {
-        message(socket: HubSocket, raw: string): void;
+        message(socket: HubSocket, raw: string): (Record<string, unknown> & {
+            type: string;
+        }) | undefined;
+        socketData<T = unknown>(socket: HubSocket): T | undefined;
+        setSocketData(socket: HubSocket, data: unknown): void;
+        principalOf(socket: HubSocket): string;
         subscribe(request: SubscribeRequest, principal: string): Promise<SnapshotResponse>;
         unsubscribe(request: UnsubscribeRequest, principal: string): void;
         notify(path: string): Promise<void>;
@@ -58,9 +106,24 @@ declare function createDurableObjectHub(ctx: DurableObjectStateLike, options: Du
     };
     /** The Durable Object's `fetch`: WebSocket upgrades and actions from `hubClient`. */
     fetch(request: Request): Promise<Response>;
-    webSocketMessage(socket: DurableObjectWebSocket, message: string | ArrayBuffer): void;
-    webSocketClose(socket: DurableObjectWebSocket, code: number): void;
-    webSocketError(socket: DurableObjectWebSocket): void;
+    webSocketMessage(socket: DurableObjectWebSocket, message: string | ArrayBuffer): Promise<void>;
+    webSocketClose(socket: DurableObjectWebSocket, code: number): Promise<void>;
+    webSocketError(socket: DurableObjectWebSocket): Promise<void>;
+    /** Every accepted socket, including one whose close is being handled. */
+    sockets(): DurableObjectWebSocket[];
+    /** The principal a socket authenticated as. */
+    principalOf: (socket: DurableObjectWebSocket) => string;
+    /** Application data stored with a socket by `setSocketData`. */
+    socketData: <T = unknown>(socket: DurableObjectWebSocket) => T | undefined;
+    /** Stores application data with a socket; it survives hibernation and shares the 2 KB limit. */
+    setSocketData: (socket: DurableObjectWebSocket, data: unknown) => void;
+    /** Whether `principal` holds a socket that has pinged within the presence timeout. */
+    present(principal: string): boolean;
+    /**
+     * The Durable Object's `alarm` when presence is tracked: closes silent
+     * sockets, reports principals that lost their last one, and reschedules.
+     */
+    alarm(): Promise<void>;
 };
 type DurableObjectHub = ReturnType<typeof createDurableObjectHub>;
 /** Calls a hub Durable Object from the Worker. */
@@ -77,18 +140,27 @@ interface ReactiveRoutes {
     socket: string;
     /** Reactive HTTP subscribe and unsubscribe, authenticated by the ticket as a bearer token. */
     reactive: string;
+    /** `POST { path, patches? }` from other backends, authenticated by `notifySecret`. */
+    notify?: string;
 }
 interface ReactiveRoutesOptions {
     routes: ReactiveRoutes;
     /** Ticket signing secret. Requests get 503 when it is not configured. */
     secret: string | undefined;
+    /** Bearer secret for `routes.notify`; the route answers 503 while it is unset. */
+    notifySecret?: string | undefined;
+    /**
+     * Browser origins allowed to call the ticket and reactive routes cross-origin,
+     * for a hub on a different host from the app.
+     */
+    allowedOrigins?: readonly string[];
     /** The hub Durable Object stub that serves these routes. */
     hub: () => HubStub;
     /** Returns the principal for a ticket request, or undefined to answer 401. */
     authenticate(request: Request): string | undefined | Promise<string | undefined>;
     ticketLifetimeSeconds?: number;
 }
-/** Serves the ticket, socket and reactive HTTP routes; `undefined` for any other path. */
+/** Serves the ticket, socket, reactive and notify routes; `undefined` for any other path. */
 declare function handleReactiveRoutes(request: Request, options: ReactiveRoutesOptions): Promise<Response | undefined>;
 
 export { HUB_PRINCIPAL_HEADER, createDurableObjectHub, handleReactiveRoutes, hubClient };

package/dist/cloudflare.d.ts

@@ -6,7 +6,8 @@ import { HubSocket, HubPaths } from './hub.js';
  * takes the Durable Object's `ctx` instead of extending `DurableObject`, so this
  * entry imports nothing from `cloudflare:workers` and builds like every other
  * entry. Your Durable Object class owns its name and migrations and delegates
- * `fetch`, `webSocketMessage`, `webSocketClose` and `webSocketError` to it.
+ * `fetch`, `webSocketMessage`, `webSocketClose` and `webSocketError` to it, plus
+ * `alarm` when it tracks presence.
  */
 /** Set by the route handler on requests it forwards to the hub; never trusted from clients. */
 declare const HUB_PRINCIPAL_HEADER = "x-reactive-principal";
@@ -19,9 +20,17 @@ interface DurableObjectStateLike {
     acceptWebSocket(socket: DurableObjectWebSocket, tags?: string[]): void;
     getWebSockets(tag?: string): DurableObjectWebSocket[];
     setWebSocketAutoResponse?(pair?: unknown): void;
+    /** When the runtime last answered this socket's `ping` itself; needed for presence. */
+    getWebSocketAutoResponseTimestamp?(socket: DurableObjectWebSocket): Date | null;
     storage: {
         get<T>(key: string): Promise<T | undefined>;
         put<T>(key: string, value: T): Promise<void>;
+        /** Lets presence forget principals that left instead of storing `false`. */
+        delete?(key: string): Promise<boolean>;
+        /** Needed for presence. */
+        getAlarm?(): Promise<number | null>;
+        /** Needed for presence. */
+        setAlarm?(scheduledTime: number): Promise<void>;
     };
 }
 /** Anything with a Durable Object stub's `fetch`. */
@@ -32,6 +41,10 @@ type WebSocketPairConstructor = new () => {
     0: DurableObjectWebSocket;
     1: DurableObjectWebSocket;
 };
+/** A frame from the client that is not part of the protocol, such as `{ type: 'listening' }`. */
+type HubClientFrame = Record<string, unknown> & {
+    type: string;
+};
 interface DurableObjectHubOptions {
     paths: HubPaths;
     /** Storage key for a path's version. Defaults to `version:<path>`. */
@@ -42,15 +55,50 @@ interface DurableObjectHubOptions {
      * Defaults to true.
      */
     autoPong?: boolean;
+    /**
+     * Tracks whether principals hold a live socket, so the hub can report a
+     * worker or listener as online without it polling over HTTP. Requires `autoPong`.
+     */
+    presence?: HubPresenceOptions;
+    /** Runs after a socket is accepted. */
+    onOpen?: (socket: DurableObjectWebSocket, principal: string) => void | Promise<void>;
+    /**
+     * Runs when a socket closes or errors. The socket may still be listed by
+     * `sockets()` during this call, so exclude it when counting.
+     */
+    onClose?: (socket: DurableObjectWebSocket, principal: string) => void | Promise<void>;
+    /** Handles frames the protocol does not, such as application presence updates. */
+    onMessage?: (socket: DurableObjectWebSocket, principal: string, frame: HubClientFrame) => void | Promise<void>;
     /** Workers' `WebSocketPair`; injectable for tests. */
     WebSocketPair?: WebSocketPairConstructor;
     /** Creates a connection id; injectable for tests. */
     randomId?: () => string;
 }
+interface HubPresenceOptions {
+    /** The principals to track, or a predicate for open-ended ones such as anonymous listeners. */
+    principals: readonly string[] | ((principal: string) => boolean);
+    /**
+     * A socket whose last `ping` is older than this is closed as dead, which is how
+     * a peer that vanished without a close frame is noticed. Clients must ping more
+     * often than this. @default 90000
+     */
+    timeoutMs?: number;
+    /**
+     * Called when a principal gains its first live socket or loses its last one,
+     * for example to `notify` a status path. The last reported state is kept in
+     * storage under `presence:<principal>`, so each change is reported once.
+     */
+    onChange?: (principal: string, present: boolean) => void | Promise<void>;
+}
 /** Wires the hub core to a Durable Object's hibernatable WebSockets and storage. */
 declare function createDurableObjectHub(ctx: DurableObjectStateLike, options: DurableObjectHubOptions): {
     hub: {
-        message(socket: HubSocket, raw: string): void;
+        message(socket: HubSocket, raw: string): (Record<string, unknown> & {
+            type: string;
+        }) | undefined;
+        socketData<T = unknown>(socket: HubSocket): T | undefined;
+        setSocketData(socket: HubSocket, data: unknown): void;
+        principalOf(socket: HubSocket): string;
         subscribe(request: SubscribeRequest, principal: string): Promise<SnapshotResponse>;
         unsubscribe(request: UnsubscribeRequest, principal: string): void;
         notify(path: string): Promise<void>;
@@ -58,9 +106,24 @@ declare function createDurableObjectHub(ctx: DurableObjectStateLike, options: Du
     };
     /** The Durable Object's `fetch`: WebSocket upgrades and actions from `hubClient`. */
     fetch(request: Request): Promise<Response>;
-    webSocketMessage(socket: DurableObjectWebSocket, message: string | ArrayBuffer): void;
-    webSocketClose(socket: DurableObjectWebSocket, code: number): void;
-    webSocketError(socket: DurableObjectWebSocket): void;
+    webSocketMessage(socket: DurableObjectWebSocket, message: string | ArrayBuffer): Promise<void>;
+    webSocketClose(socket: DurableObjectWebSocket, code: number): Promise<void>;
+    webSocketError(socket: DurableObjectWebSocket): Promise<void>;
+    /** Every accepted socket, including one whose close is being handled. */
+    sockets(): DurableObjectWebSocket[];
+    /** The principal a socket authenticated as. */
+    principalOf: (socket: DurableObjectWebSocket) => string;
+    /** Application data stored with a socket by `setSocketData`. */
+    socketData: <T = unknown>(socket: DurableObjectWebSocket) => T | undefined;
+    /** Stores application data with a socket; it survives hibernation and shares the 2 KB limit. */
+    setSocketData: (socket: DurableObjectWebSocket, data: unknown) => void;
+    /** Whether `principal` holds a socket that has pinged within the presence timeout. */
+    present(principal: string): boolean;
+    /**
+     * The Durable Object's `alarm` when presence is tracked: closes silent
+     * sockets, reports principals that lost their last one, and reschedules.
+     */
+    alarm(): Promise<void>;
 };
 type DurableObjectHub = ReturnType<typeof createDurableObjectHub>;
 /** Calls a hub Durable Object from the Worker. */
@@ -77,18 +140,27 @@ interface ReactiveRoutes {
     socket: string;
     /** Reactive HTTP subscribe and unsubscribe, authenticated by the ticket as a bearer token. */
     reactive: string;
+    /** `POST { path, patches? }` from other backends, authenticated by `notifySecret`. */
+    notify?: string;
 }
 interface ReactiveRoutesOptions {
     routes: ReactiveRoutes;
     /** Ticket signing secret. Requests get 503 when it is not configured. */
     secret: string | undefined;
+    /** Bearer secret for `routes.notify`; the route answers 503 while it is unset. */
+    notifySecret?: string | undefined;
+    /**
+     * Browser origins allowed to call the ticket and reactive routes cross-origin,
+     * for a hub on a different host from the app.
+     */
+    allowedOrigins?: readonly string[];
     /** The hub Durable Object stub that serves these routes. */
     hub: () => HubStub;
     /** Returns the principal for a ticket request, or undefined to answer 401. */
     authenticate(request: Request): string | undefined | Promise<string | undefined>;
     ticketLifetimeSeconds?: number;
 }
-/** Serves the ticket, socket and reactive HTTP routes; `undefined` for any other path. */
+/** Serves the ticket, socket, reactive and notify routes; `undefined` for any other path. */
 declare function handleReactiveRoutes(request: Request, options: ReactiveRoutesOptions): Promise<Response | undefined>;
 
 export { HUB_PRINCIPAL_HEADER, createDurableObjectHub, handleReactiveRoutes, hubClient };

package/dist/cloudflare.js

@@ -39,7 +39,11 @@ async function createSignedClusterTicket(options) {
     encoder.encode(JSON.stringify({ p: options.principal, exp: expiresAt }))
   );
   const signature = new Uint8Array(
-    await crypto.subtle.sign("HMAC", await hmacKey(options.secret, "sign"), encoder.encode(payload))
+    await crypto.subtle.sign(
+      "HMAC",
+      await hmacKey(options.secret, "sign"),
+      encoder.encode(payload)
+    )
   );
   return parseClusterTicket({
     token: `${payload}.${base64UrlEncode(signature)}`,
@@ -48,8 +52,10 @@ async function createSignedClusterTicket(options) {
   });
 }
 async function verifySignedClusterTicket(token, secret, now = Date.now()) {
-  const [payload, signature, extra] = token.split(".");
-  if (!payload || !signature || extra !== void 0) return void 0;
+  const parts = token.split(".");
+  if (parts.length !== 2) return void 0;
+  const [payload, signature] = parts;
+  if (!payload || !signature) return void 0;
   try {
     const valid = await crypto.subtle.verify(
       "HMAC",
@@ -87,8 +93,13 @@ function bearerToken(request) {
   const match = /^Bearer ([^\s]+)$/u.exec(request.headers.get("authorization") ?? "");
   return match?.[1] ?? "";
 }
-function createHubSocketState(connectionId, principal) {
-  return { connectionId, principal, subscriptions: [] };
+function createHubSocketState(connectionId, principal, connectedAt) {
+  return {
+    connectionId,
+    principal,
+    subscriptions: [],
+    ...connectedAt === void 0 ? {} : { connectedAt }
+  };
 }
 function socketState(socket) {
   const state = socket.deserializeAttachment();
@@ -118,20 +129,42 @@ function createReactiveHub(options) {
     return { fromVersion, toVersion };
   };
   return {
-    /** Answers the client's `init` and `ping` frames. */
+    /**
+     * Answers the client's `init` and `ping` frames. Any other frame with a
+     * string `type` is returned for the application to handle.
+     */
     message(socket, raw) {
       let frame;
       try {
         frame = JSON.parse(raw);
       } catch {
-        return;
+        return void 0;
       }
-      const type = isRecord2(frame) ? frame.type : void 0;
-      if (type === "init") {
+      if (!isRecord2(frame) || typeof frame.type !== "string") return void 0;
+      if (frame.type === "init") {
         send(socket, { type: "connected", connectionId: socketState(socket).connectionId });
-      } else if (type === "ping") {
+      } else if (frame.type === "ping") {
         send(socket, { type: "pong" });
+      } else {
+        return frame;
+      }
+      return void 0;
+    },
+    /** The application data stored with a socket. */
+    socketData(socket) {
+      return socketState(socket).data;
+    },
+    /** Stores application data with a socket; it shares the attachment size limit. */
+    setSocketData(socket, data) {
+      const next = { ...socketState(socket), data };
+      if (new TextEncoder().encode(JSON.stringify(next)).length > maxAttachmentBytes) {
+        throw new ReactiveHubError("Socket data is too large");
       }
+      socket.serializeAttachment(next);
+    },
+    /** The principal a socket authenticated as. */
+    principalOf(socket) {
+      return socketState(socket).principal;
     },
     async subscribe(request, principal) {
       const handler = resolve(request.path);
@@ -149,9 +182,7 @@ function createReactiveHub(options) {
       const next = {
         ...state,
         subscriptions: [
-          ...state.subscriptions.filter(
-            (entry) => entry.subscriptionId !== request.subscriptionId
-          ),
+          ...state.subscriptions.filter((entry) => entry.subscriptionId !== request.subscriptionId),
           {
             subscriptionId: request.subscriptionId,
             generation: request.generation,
@@ -222,6 +253,11 @@ function createReactiveHub(options) {
 // ../client/src/cloudflare.ts
 var HUB_PRINCIPAL_HEADER = "x-reactive-principal";
 var HUB_ACTION_URL = "https://reactive-hub/";
+var PRESENCE_TAG = "presence";
+var PRESENCE_TAG_PREFIX = "presence:";
+var PRESENCE_KEY_PREFIX = "presence:";
+var DEFAULT_PRESENCE_TIMEOUT_MS = 9e4;
+var HEARTBEAT_TIMEOUT_CLOSE_CODE = 4001;
 function json(value, status = 200) {
   return Response.json(value, { status, headers: { "cache-control": "no-store" } });
 }
@@ -255,15 +291,66 @@ function createDurableObjectHub(ctx, options) {
       );
     }
   }
-  const accept = (request) => {
+  const presence = options.presence;
+  const timeoutMs = presence?.timeoutMs ?? DEFAULT_PRESENCE_TIMEOUT_MS;
+  const isTracked = (principal) => {
+    if (!presence) return false;
+    const { principals } = presence;
+    return typeof principals === "function" ? principals(principal) : principals.includes(principal);
+  };
+  const principalOf = (socket) => socket.deserializeAttachment().principal;
+  const lastSeen = (socket) => Math.max(
+    ctx.getWebSocketAutoResponseTimestamp?.(socket)?.getTime() ?? 0,
+    socket.deserializeAttachment().connectedAt ?? 0
+  );
+  const liveSockets = (principal, closing) => {
+    const now = Date.now();
+    return ctx.getWebSockets(PRESENCE_TAG_PREFIX + principal).filter((socket) => socket !== closing && now - lastSeen(socket) <= timeoutMs);
+  };
+  const reconcile = async (principal, closing) => {
+    const present = liveSockets(principal, closing).length > 0;
+    const key = PRESENCE_KEY_PREFIX + principal;
+    if ((await ctx.storage.get(key) ?? false) === present) return;
+    if (present || !ctx.storage.delete) await ctx.storage.put(key, present);
+    else await ctx.storage.delete(key);
+    await presence?.onChange?.(principal, present);
+  };
+  const scheduleSweep = async () => {
+    const { storage } = ctx;
+    if (!storage.getAlarm || !storage.setAlarm) {
+      throw new Error("Hub presence needs Durable Object alarms");
+    }
+    const seen = ctx.getWebSockets(PRESENCE_TAG).map((socket) => lastSeen(socket));
+    if (seen.length === 0) return;
+    const due = Math.min(...seen) + timeoutMs + 1;
+    const current = await storage.getAlarm();
+    if (current === null || current > due) await storage.setAlarm(due);
+  };
+  const closed = async (socket) => {
+    const principal = principalOf(socket);
+    if (isTracked(principal)) await reconcile(principal, socket);
+    await options.onClose?.(socket, principal);
+  };
+  const accept = async (request) => {
     const principal = request.headers.get(HUB_PRINCIPAL_HEADER);
     if (!principal) return error("Unauthorized", 401);
     const Pair = options.WebSocketPair ?? workersGlobal("WebSocketPair");
     if (!Pair) throw new Error("WebSocketPair is not available in this runtime");
     const pair = new Pair();
     const connectionId = randomId();
-    ctx.acceptWebSocket(pair[1], [connectionId]);
-    pair[1].serializeAttachment(createHubSocketState(connectionId, principal));
+    const tracked = isTracked(principal);
+    ctx.acceptWebSocket(
+      pair[1],
+      tracked ? [connectionId, PRESENCE_TAG, PRESENCE_TAG_PREFIX + principal] : [connectionId]
+    );
+    pair[1].serializeAttachment(
+      createHubSocketState(connectionId, principal, tracked ? Date.now() : void 0)
+    );
+    if (tracked) {
+      await reconcile(principal);
+      await scheduleSweep();
+    }
+    await options.onOpen?.(pair[1], principal);
     return new Response(null, { status: 101, webSocket: pair[0] });
   };
   const act = async (action) => {
@@ -295,20 +382,60 @@ function createDurableObjectHub(ctx, options) {
       if (request.headers.get("upgrade") === "websocket") return accept(request);
       return act(await request.json());
     },
-    webSocketMessage(socket, message) {
-      if (typeof message === "string") hub.message(socket, message);
+    async webSocketMessage(socket, message) {
+      if (typeof message !== "string") return;
+      const frame = hub.message(socket, message);
+      if (frame && options.onMessage) await options.onMessage(socket, principalOf(socket), frame);
     },
-    webSocketClose(socket, code) {
+    async webSocketClose(socket, code) {
       try {
         socket.close(code === 1005 ? 1e3 : code, "closed");
       } catch {
       }
+      await closed(socket);
     },
-    webSocketError(socket) {
+    async webSocketError(socket) {
       try {
         socket.close(1011, "error");
       } catch {
       }
+      await closed(socket);
+    },
+    /** Every accepted socket, including one whose close is being handled. */
+    sockets() {
+      return ctx.getWebSockets();
+    },
+    /** The principal a socket authenticated as. */
+    principalOf,
+    /** Application data stored with a socket by `setSocketData`. */
+    socketData: (socket) => hub.socketData(socket),
+    /** Stores application data with a socket; it survives hibernation and shares the 2 KB limit. */
+    setSocketData: (socket, data) => hub.setSocketData(socket, data),
+    /** Whether `principal` holds a socket that has pinged within the presence timeout. */
+    present(principal) {
+      return liveSockets(principal).length > 0;
+    },
+    /**
+     * The Durable Object's `alarm` when presence is tracked: closes silent
+     * sockets, reports principals that lost their last one, and reschedules.
+     */
+    async alarm() {
+      const now = Date.now();
+      const principals = /* @__PURE__ */ new Set();
+      for (const socket of ctx.getWebSockets(PRESENCE_TAG)) {
+        const principal = principalOf(socket);
+        principals.add(principal);
+        if (now - lastSeen(socket) <= timeoutMs) continue;
+        try {
+          socket.close(HEARTBEAT_TIMEOUT_CLOSE_CODE, "Heartbeat timeout");
+        } catch {
+        }
+        await options.onClose?.(socket, principal);
+      }
+      for (const principal of principals) {
+        await reconcile(principal);
+      }
+      await scheduleSweep();
     }
   };
 }
@@ -326,24 +453,84 @@ function hubClient(stub) {
     publish: async (path, patches) => ok(await post({ action: "publish", path, patches }))
   };
 }
+function sameSecret(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 withCors(response, origin) {
+  if (!origin) return response;
+  const headers = new Headers(response.headers);
+  headers.set("access-control-allow-origin", origin);
+  headers.append("vary", "origin");
+  return new Response(response.body, {
+    status: response.status,
+    statusText: response.statusText,
+    headers
+  });
+}
 async function handleReactiveRoutes(request, options) {
   const url = new URL(request.url);
   const { routes, secret } = options;
-  if (![routes.ticket, routes.socket, routes.reactive].includes(url.pathname)) return void 0;
-  if (!secret) return error("Reactive hub is not configured", 503);
-  if (url.pathname === routes.ticket) {
+  const known = [routes.ticket, routes.socket, routes.reactive, routes.notify];
+  if (!known.includes(url.pathname)) return void 0;
+  const requestOrigin = request.headers.get("origin");
+  const corsOrigin = requestOrigin && options.allowedOrigins?.includes(requestOrigin) ? requestOrigin : null;
+  if (request.method === "OPTIONS" && url.pathname !== routes.socket) {
+    if (!corsOrigin) return new Response(null, { status: 403 });
+    return new Response(null, {
+      status: 204,
+      headers: {
+        "access-control-allow-origin": corsOrigin,
+        "access-control-allow-methods": "POST, OPTIONS",
+        "access-control-allow-headers": "authorization, content-type",
+        "access-control-max-age": "86400",
+        vary: "origin"
+      }
+    });
+  }
+  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 (!sameSecret(bearerToken(request), options.notifySecret)) {
+      return error("Unauthorized", 401);
+    }
+    let body2;
+    try {
+      body2 = await request.json();
+    } catch {
+      return error("Invalid JSON", 400);
+    }
+    const { path, patches } = body2 ?? {};
+    if (typeof path !== "string" || patches !== void 0 && !Array.isArray(patches)) {
+      return error("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 (url.pathname === routes.ticket) {
+    if (request.method !== "POST") return withCors(error("Method not allowed", 405), corsOrigin);
     const principal2 = await options.authenticate(request);
-    if (!principal2) return error("Unauthorized", 401);
+    if (!principal2) return withCors(error("Unauthorized", 401), corsOrigin);
     const socketUrl = new URL(routes.socket, url);
     socketUrl.protocol = "wss:";
-    return json(
-      await createSignedClusterTicket({
-        secret,
-        principal: principal2,
-        url: socketUrl.toString(),
-        ...options.ticketLifetimeSeconds === void 0 ? {} : { lifetimeSeconds: options.ticketLifetimeSeconds }
-      })
+    return withCors(
+      json(
+        await createSignedClusterTicket({
+          secret,
+          principal: principal2,
+          url: socketUrl.toString(),
+          ...options.ticketLifetimeSeconds === void 0 ? {} : { lifetimeSeconds: options.ticketLifetimeSeconds }
+        })
+      ),
+      corsOrigin
     );
   }
   if (url.pathname === routes.socket) {
@@ -356,17 +543,17 @@ async function handleReactiveRoutes(request, options) {
     forwarded.headers.set(HUB_PRINCIPAL_HEADER, principal2);
     return options.hub().fetch(forwarded);
   }
-  if (request.method !== "POST") return error("Method not allowed", 405);
+  if (request.method !== "POST") return withCors(error("Method not allowed", 405), corsOrigin);
   const principal = await verifySignedClusterTicket(bearerToken(request), secret);
-  if (!principal) return error("Unauthorized", 401);
+  if (!principal) return withCors(error("Unauthorized", 401), corsOrigin);
   let body;
   try {
     body = await request.json();
   } catch {
-    return error("Invalid JSON", 400);
+    return withCors(error("Invalid JSON", 400), corsOrigin);
   }
-  if (!isHubRequest(body)) return error("Unsupported reactive request", 400);
-  return hubClient(options.hub()).request(body, principal);
+  if (!isHubRequest(body)) return withCors(error("Unsupported reactive request", 400), corsOrigin);
+  return withCors(await hubClient(options.hub()).request(body, principal), corsOrigin);
 }
 
 export { HUB_PRINCIPAL_HEADER, createDurableObjectHub, handleReactiveRoutes, hubClient };