dynamodb-reactive 0.3.0 → 0.5.0

package/dist/cloudflare.d.cts

@@ -0,0 +1,129 @@
+import { SubscribeRequest, SnapshotResponse, UnsubscribeRequest, JsonPatch } from './cluster.cjs';
+import { HubSocket, HubPaths } from './hub.cjs';
+
+/**
+ * Cloudflare Durable Object shell for the reactive hub. It is structural: it
+ * 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, 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";
+/** A hibernatable Workers WebSocket, as far as the hub needs it. */
+interface DurableObjectWebSocket extends HubSocket {
+    close(code?: number, reason?: string): void;
+}
+/** The parts of `DurableObjectState` the hub uses. */
+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>;
+        /** Needed for presence. */
+        getAlarm?(): Promise<number | null>;
+        /** Needed for presence. */
+        setAlarm?(scheduledTime: number): Promise<void>;
+    };
+}
+/** Anything with a Durable Object stub's `fetch`. */
+interface HubStub {
+    fetch(request: Request): Promise<Response>;
+}
+type WebSocketPairConstructor = new () => {
+    0: DurableObjectWebSocket;
+    1: DurableObjectWebSocket;
+};
+interface DurableObjectHubOptions {
+    paths: HubPaths;
+    /** Storage key for a path's version. Defaults to `version:<path>`. */
+    versionKey?: (path: string) => string;
+    maxAttachmentBytes?: number;
+    /**
+     * Answers the client's `ping` with `pong` without waking the Durable Object.
+     * Defaults to true.
+     */
+    autoPong?: boolean;
+    /**
+     * Tracks whether these principals hold a live socket, so the hub can report a
+     * worker as online without the worker polling over HTTP. Requires `autoPong`.
+     */
+    presence?: HubPresenceOptions;
+    /** Workers' `WebSocketPair`; injectable for tests. */
+    WebSocketPair?: WebSocketPairConstructor;
+    /** Creates a connection id; injectable for tests. */
+    randomId?: () => string;
+}
+interface HubPresenceOptions {
+    principals: readonly string[];
+    /**
+     * 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;
+        subscribe(request: SubscribeRequest, principal: string): Promise<SnapshotResponse>;
+        unsubscribe(request: UnsubscribeRequest, principal: string): void;
+        notify(path: string): Promise<void>;
+        publish(path: string, patches: JsonPatch[]): Promise<void>;
+    };
+    /** 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): Promise<void>;
+    webSocketError(socket: DurableObjectWebSocket): Promise<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. */
+declare function hubClient(stub: HubStub): {
+    /** Forwards a reactive HTTP request and returns the hub's response unchanged. */
+    request: (body: SubscribeRequest | UnsubscribeRequest, principal: string) => Promise<Response>;
+    notify: (path: string) => Promise<void>;
+    publish: (path: string, patches: JsonPatch[]) => Promise<void>;
+};
+interface ReactiveRoutes {
+    /** `POST` exchanges a credential for a signed ticket. */
+    ticket: string;
+    /** WebSocket upgrade, authenticated by the ticket in the `token` query parameter. */
+    socket: string;
+    /** Reactive HTTP subscribe and unsubscribe, authenticated by the ticket as a bearer token. */
+    reactive: string;
+}
+interface ReactiveRoutesOptions {
+    routes: ReactiveRoutes;
+    /** Ticket signing secret. Requests get 503 when it is not configured. */
+    secret: string | undefined;
+    /** 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. */
+declare function handleReactiveRoutes(request: Request, options: ReactiveRoutesOptions): Promise<Response | undefined>;
+
+export { HUB_PRINCIPAL_HEADER, createDurableObjectHub, handleReactiveRoutes, hubClient };
+export type { DurableObjectHub, DurableObjectHubOptions, DurableObjectStateLike, DurableObjectWebSocket, HubStub, ReactiveRoutes, ReactiveRoutesOptions };

package/dist/cloudflare.d.ts

@@ -0,0 +1,129 @@
+import { SubscribeRequest, SnapshotResponse, UnsubscribeRequest, JsonPatch } from './cluster.js';
+import { HubSocket, HubPaths } from './hub.js';
+
+/**
+ * Cloudflare Durable Object shell for the reactive hub. It is structural: it
+ * 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, 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";
+/** A hibernatable Workers WebSocket, as far as the hub needs it. */
+interface DurableObjectWebSocket extends HubSocket {
+    close(code?: number, reason?: string): void;
+}
+/** The parts of `DurableObjectState` the hub uses. */
+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>;
+        /** Needed for presence. */
+        getAlarm?(): Promise<number | null>;
+        /** Needed for presence. */
+        setAlarm?(scheduledTime: number): Promise<void>;
+    };
+}
+/** Anything with a Durable Object stub's `fetch`. */
+interface HubStub {
+    fetch(request: Request): Promise<Response>;
+}
+type WebSocketPairConstructor = new () => {
+    0: DurableObjectWebSocket;
+    1: DurableObjectWebSocket;
+};
+interface DurableObjectHubOptions {
+    paths: HubPaths;
+    /** Storage key for a path's version. Defaults to `version:<path>`. */
+    versionKey?: (path: string) => string;
+    maxAttachmentBytes?: number;
+    /**
+     * Answers the client's `ping` with `pong` without waking the Durable Object.
+     * Defaults to true.
+     */
+    autoPong?: boolean;
+    /**
+     * Tracks whether these principals hold a live socket, so the hub can report a
+     * worker as online without the worker polling over HTTP. Requires `autoPong`.
+     */
+    presence?: HubPresenceOptions;
+    /** Workers' `WebSocketPair`; injectable for tests. */
+    WebSocketPair?: WebSocketPairConstructor;
+    /** Creates a connection id; injectable for tests. */
+    randomId?: () => string;
+}
+interface HubPresenceOptions {
+    principals: readonly string[];
+    /**
+     * 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;
+        subscribe(request: SubscribeRequest, principal: string): Promise<SnapshotResponse>;
+        unsubscribe(request: UnsubscribeRequest, principal: string): void;
+        notify(path: string): Promise<void>;
+        publish(path: string, patches: JsonPatch[]): Promise<void>;
+    };
+    /** 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): Promise<void>;
+    webSocketError(socket: DurableObjectWebSocket): Promise<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. */
+declare function hubClient(stub: HubStub): {
+    /** Forwards a reactive HTTP request and returns the hub's response unchanged. */
+    request: (body: SubscribeRequest | UnsubscribeRequest, principal: string) => Promise<Response>;
+    notify: (path: string) => Promise<void>;
+    publish: (path: string, patches: JsonPatch[]) => Promise<void>;
+};
+interface ReactiveRoutes {
+    /** `POST` exchanges a credential for a signed ticket. */
+    ticket: string;
+    /** WebSocket upgrade, authenticated by the ticket in the `token` query parameter. */
+    socket: string;
+    /** Reactive HTTP subscribe and unsubscribe, authenticated by the ticket as a bearer token. */
+    reactive: string;
+}
+interface ReactiveRoutesOptions {
+    routes: ReactiveRoutes;
+    /** Ticket signing secret. Requests get 503 when it is not configured. */
+    secret: string | undefined;
+    /** 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. */
+declare function handleReactiveRoutes(request: Request, options: ReactiveRoutesOptions): Promise<Response | undefined>;
+
+export { HUB_PRINCIPAL_HEADER, createDurableObjectHub, handleReactiveRoutes, hubClient };
+export type { DurableObjectHub, DurableObjectHubOptions, DurableObjectStateLike, DurableObjectWebSocket, HubStub, ReactiveRoutes, ReactiveRoutesOptions };