@rdlabo/workers-hono-kit 0.7.2 → 0.9.0

package/README.md

@@ -85,7 +85,6 @@ npm install ai ai-gateway-provider    # createAiGatewayProvider
 | `DeferExecutor` / `defaultDefer` / `createWaitUntilDefer(ctx)` | Fire-and-forget executor for Workers: `defaultDefer` swallows rejections (tests); `createWaitUntilDefer` registers work via `ctx.waitUntil`. |
 | `configureHibernationAutoResponse` / `upgradeHibernationWebSocket` / `broadcastHibernationWebSockets` | Hibernation WebSocket room primitives: runtime ping/pong without waking JavaScript, attachment-before-accept upgrade, and broadcast through sockets restored by `getWebSockets()`. |
 | `acknowledgeHibernationWebSocketClose` / `closeHibernationWebSocket` | Safe close helpers, including normalization of reserved received-only close codes. |
-| `createLegacySseBridge(options)` | Migration adapter from legacy SSE clients to one or more Hibernation WebSocket rooms. Downstream cancellation aborts pending upgrades and closes late-arriving sockets. |
 | `retryDurableObjectOperation(operation, options?)` / `isRetryableDurableObjectError(error)` | Retry idempotent DO work only for `retryable && !overloaded`, with jittered exponential backoff. `operation` runs per attempt so callers create a fresh stub after an exception. |
 | `createAiGatewayProvider(config)` / `AiGatewayConfig` / `AiGatewayProvider` | Route `@ai-sdk` models through the Cloudflare AI Gateway, via either a Workers `AI` binding or REST credentials (`accountId` / `gateway` / `token`). |
 | `KVCache` / `KVNamespace` / `KVCacheOptions` | Workers-KV cache-aside helper (key `appName+version+table_type_column`, sha256 for string ids, TTL clamped ≥60s). Set `appName` / `version` per application. |

package/dist/index.d.ts

@@ -49,10 +49,12 @@ export { createSentryErrorReporter } from './http/http-error.js';
 export type { SentryExceptionReporterLike } from './http/http-error.js';
 export { acknowledgeHibernationWebSocketClose, broadcastHibernationWebSockets, closeHibernationWebSocket, configureHibernationAutoResponse, upgradeHibernationWebSocket, } from './realtime/hibernation.js';
 export type { HibernationAutoResponseOptions, HibernationUpgradeOptions, HibernationWebSocketLike, HibernationWebSocketStateLike, WebSocketAutoResponsePairFactory, WebSocketPairFactory, } from './realtime/hibernation.js';
-export { createLegacySseBridge } from './realtime/legacy-sse.js';
-export type { LegacySseBridgeOptions, RealtimeDurableObjectNamespaceLike } from './realtime/legacy-sse.js';
 export { isRetryableDurableObjectError, retryDurableObjectOperation } from './realtime/retry.js';
 export type { DurableObjectErrorLike, DurableObjectRetryOptions } from './realtime/retry.js';
+export { DurableObjectResponseError, invokeDurableObjectFetch } from './realtime/invoke.js';
+export type { DurableObjectFetchRequest, DurableObjectFetchStubLike, InvokeDurableObjectFetchOptions, } from './realtime/invoke.js';
+export { parseRealtimeWebSocketProtocolOffer, parseWebSocketProtocols } from './realtime/protocol.js';
+export type { ParseRealtimeWebSocketProtocolOptions, RealtimeWebSocketProtocolOffer } from './realtime/protocol.js';
 export { KVCache } from './cache/kv-cache.js';
 export type { KVNamespace, KVCacheOptions } from './cache/kv-cache.js';
 export { createStripeClient, verifyStripeWebhook } from './stripe/client.js';

package/dist/index.js

@@ -37,8 +37,9 @@ export { defaultDefer, createWaitUntilDefer } from './http/defer.js';
 export { createSentryErrorReporter } from './http/http-error.js';
 // realtime
 export { acknowledgeHibernationWebSocketClose, broadcastHibernationWebSockets, closeHibernationWebSocket, configureHibernationAutoResponse, upgradeHibernationWebSocket, } from './realtime/hibernation.js';
-export { createLegacySseBridge } from './realtime/legacy-sse.js';
 export { isRetryableDurableObjectError, retryDurableObjectOperation } from './realtime/retry.js';
+export { DurableObjectResponseError, invokeDurableObjectFetch } from './realtime/invoke.js';
+export { parseRealtimeWebSocketProtocolOffer, parseWebSocketProtocols } from './realtime/protocol.js';
 // cache
 export { KVCache } from './cache/kv-cache.js';
 // stripe

package/dist/realtime/index.d.ts

@@ -1,6 +1,8 @@
 export { acknowledgeHibernationWebSocketClose, broadcastHibernationWebSockets, closeHibernationWebSocket, configureHibernationAutoResponse, upgradeHibernationWebSocket, } from './hibernation.js';
 export type { HibernationAutoResponseOptions, HibernationUpgradeOptions, HibernationWebSocketLike, HibernationWebSocketStateLike, WebSocketAutoResponsePairFactory, WebSocketPairFactory, } from './hibernation.js';
-export { createLegacySseBridge } from './legacy-sse.js';
-export type { LegacySseBridgeOptions, RealtimeDurableObjectNamespaceLike } from './legacy-sse.js';
 export { isRetryableDurableObjectError, retryDurableObjectOperation } from './retry.js';
 export type { DurableObjectErrorLike, DurableObjectRetryOptions } from './retry.js';
+export { DurableObjectResponseError, invokeDurableObjectFetch } from './invoke.js';
+export type { DurableObjectFetchRequest, DurableObjectFetchStubLike, InvokeDurableObjectFetchOptions, } from './invoke.js';
+export { parseRealtimeWebSocketProtocolOffer, parseWebSocketProtocols } from './protocol.js';
+export type { ParseRealtimeWebSocketProtocolOptions, RealtimeWebSocketProtocolOffer } from './protocol.js';

package/dist/realtime/index.js

@@ -1,3 +1,4 @@
 export { acknowledgeHibernationWebSocketClose, broadcastHibernationWebSockets, closeHibernationWebSocket, configureHibernationAutoResponse, upgradeHibernationWebSocket, } from './hibernation.js';
-export { createLegacySseBridge } from './legacy-sse.js';
 export { isRetryableDurableObjectError, retryDurableObjectOperation } from './retry.js';
+export { DurableObjectResponseError, invokeDurableObjectFetch } from './invoke.js';
+export { parseRealtimeWebSocketProtocolOffer, parseWebSocketProtocols } from './protocol.js';

package/dist/realtime/invoke.d.ts

@@ -0,0 +1,30 @@
+import type { DurableObjectRetryOptions } from './retry.js';
+/** Minimal fetch surface implemented by a Durable Object stub. */
+export interface DurableObjectFetchStubLike {
+    fetch(input: Request | string | URL, init?: RequestInit): Promise<Response>;
+}
+/** A freshly-created request for one Durable Object invocation attempt. */
+export interface DurableObjectFetchRequest {
+    input: Request | string | URL;
+    init?: RequestInit;
+}
+/** Options for invoking a Durable Object fetch endpoint safely. */
+export interface InvokeDurableObjectFetchOptions {
+    getStub: () => DurableObjectFetchStubLike;
+    createRequest: () => DurableObjectFetchRequest;
+    retry?: boolean;
+    retryOptions?: DurableObjectRetryOptions;
+    errorMessage?: string;
+}
+/** HTTP response failure returned explicitly by a Durable Object fetch handler. */
+export declare class DurableObjectResponseError extends Error {
+    readonly response: Response;
+    constructor(message: string, response: Response);
+}
+/**
+ * Invoke a Durable Object fetch endpoint with a fresh stub and request for every attempt.
+ *
+ * Non-2xx responses always throw. Runtime retryable exceptions are retried only when `retry` is
+ * explicitly enabled, allowing callers to keep non-idempotent operations at-most-once.
+ */
+export declare function invokeDurableObjectFetch(options: InvokeDurableObjectFetchOptions): Promise<Response>;

package/dist/realtime/invoke.js

@@ -0,0 +1,27 @@
+import { retryDurableObjectOperation } from './retry.js';
+/** HTTP response failure returned explicitly by a Durable Object fetch handler. */
+export class DurableObjectResponseError extends Error {
+    response;
+    constructor(message, response) {
+        super(message);
+        this.response = response;
+        this.name = 'DurableObjectResponseError';
+    }
+}
+/**
+ * Invoke a Durable Object fetch endpoint with a fresh stub and request for every attempt.
+ *
+ * Non-2xx responses always throw. Runtime retryable exceptions are retried only when `retry` is
+ * explicitly enabled, allowing callers to keep non-idempotent operations at-most-once.
+ */
+export async function invokeDurableObjectFetch(options) {
+    const invoke = async () => {
+        const request = options.createRequest();
+        const response = await options.getStub().fetch(request.input, request.init);
+        if (!response.ok) {
+            throw new DurableObjectResponseError(`${options.errorMessage ?? 'Durable Object request failed'}: ${response.status}`, response);
+        }
+        return response;
+    };
+    return options.retry ? retryDurableObjectOperation(invoke, options.retryOptions) : invoke();
+}

package/dist/realtime/protocol.d.ts

@@ -0,0 +1,22 @@
+/** Parsed WebSocket subprotocol offer used by authenticated realtime endpoints. */
+export interface RealtimeWebSocketProtocolOffer {
+    protocols: string[];
+    authToken?: string;
+    clientId?: string;
+}
+/** Options for validating an application/auth/client WebSocket subprotocol offer. */
+export interface ParseRealtimeWebSocketProtocolOptions {
+    protocol: string;
+    authPrefix?: string;
+    clientPrefix: string;
+    requireAuth?: boolean;
+    clientIdPattern?: RegExp;
+}
+/** Split a `Sec-WebSocket-Protocol` header into trimmed, non-empty protocol tokens. */
+export declare function parseWebSocketProtocols(header: string | undefined): string[];
+/**
+ * Validate the standard application/auth/client WebSocket subprotocol offer.
+ *
+ * Returns `null` when the application protocol, required auth token, or client ID is invalid.
+ */
+export declare function parseRealtimeWebSocketProtocolOffer(header: string | undefined, options: ParseRealtimeWebSocketProtocolOptions): RealtimeWebSocketProtocolOffer | null;

package/dist/realtime/protocol.js

@@ -0,0 +1,33 @@
+/** Split a `Sec-WebSocket-Protocol` header into trimmed, non-empty protocol tokens. */
+export function parseWebSocketProtocols(header) {
+    return (header ?? '')
+        .split(',')
+        .map((value) => value.trim())
+        .filter(Boolean);
+}
+/**
+ * Validate the standard application/auth/client WebSocket subprotocol offer.
+ *
+ * Returns `null` when the application protocol, required auth token, or client ID is invalid.
+ */
+export function parseRealtimeWebSocketProtocolOffer(header, options) {
+    const protocols = parseWebSocketProtocols(header);
+    if (!protocols.includes(options.protocol)) {
+        return null;
+    }
+    const authPrefix = options.authPrefix;
+    const authToken = authPrefix
+        ? protocols.find((value) => value.startsWith(authPrefix))?.slice(authPrefix.length)
+        : undefined;
+    if ((options.requireAuth ?? true) && !authToken) {
+        return null;
+    }
+    const clientId = protocols
+        .find((value) => value.startsWith(options.clientPrefix))
+        ?.slice(options.clientPrefix.length);
+    const clientIdPattern = options.clientIdPattern ?? /^[A-Za-z0-9_-]{1,64}$/;
+    if (clientId !== undefined && !clientIdPattern.test(clientId)) {
+        return null;
+    }
+    return { protocols, authToken, clientId };
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rdlabo/workers-hono-kit",
-  "version": "0.7.2",
+  "version": "0.9.0",
   "private": false,
   "publishConfig": {
     "access": "public"
@@ -41,7 +41,9 @@
   "bin": {
     "workers-hono-kit-sync-dev-aws": "./scripts/sync-dev-aws.mjs",
     "workers-hono-kit-check-subrequest-fanout": "./scripts/check-subrequest-fanout.mjs",
-    "workers-hono-kit-db-baseline": "./scripts/db-baseline.mjs"
+    "workers-hono-kit-db-baseline": "./scripts/db-baseline.mjs",
+    "workers-hono-kit-check-realtime-bundle": "./scripts/check-realtime-bundle.mjs",
+    "workers-hono-kit-query-realtime-do-metrics": "./scripts/query-realtime-do-metrics.mjs"
   },
   "exports": {
     ".": {
@@ -71,7 +73,7 @@
     }
   },
   "scripts": {
-    "build": "tsc -p tsconfig.build.json",
+    "build": "node scripts/clean-dist.mjs && tsc -p tsconfig.build.json",
     "prepare": "npm run build",
     "typecheck": "tsc --noEmit",
     "test": "vitest run",

package/scripts/check-realtime-bundle.mjs

@@ -0,0 +1,14 @@
+#!/usr/bin/env node
+import { stat } from 'node:fs/promises';
+
+const bundlePath = process.argv[2] ?? 'dist-realtime/realtime-worker.js';
+const maxBytes = Number(process.argv[3] ?? 32 * 1024);
+if (!Number.isFinite(maxBytes) || maxBytes <= 0) {
+  throw new Error(`Invalid realtime bundle byte limit: ${process.argv[3]}`);
+}
+
+const { size } = await stat(bundlePath);
+if (size > maxBytes) {
+  throw new Error(`Realtime Worker bundle is ${size} bytes; expected at most ${maxBytes}`);
+}
+console.log(`[realtime-bundle] ${size} bytes (limit ${maxBytes})`);

package/scripts/clean-dist.mjs

@@ -0,0 +1,3 @@
+import { rmSync } from 'node:fs';
+
+rmSync(new URL('../dist', import.meta.url), { recursive: true, force: true });

package/scripts/query-realtime-do-metrics.mjs

@@ -0,0 +1,68 @@
+#!/usr/bin/env node
+const token = process.env.CLOUDFLARE_API_TOKEN;
+if (!token) {
+  throw new Error('CLOUDFLARE_API_TOKEN (Account Analytics:Read) is required');
+}
+
+const namespace = process.argv[2] ?? process.env.REALTIME_DO_CLASS;
+if (!namespace) {
+  throw new Error('Durable Object class name is required as argv[2] or REALTIME_DO_CLASS');
+}
+const accountTag = process.env.CLOUDFLARE_ACCOUNT_ID;
+if (!accountTag) {
+  throw new Error('CLOUDFLARE_ACCOUNT_ID is required');
+}
+const since = process.env.REALTIME_METRICS_SINCE ?? new Date(Date.now() - 24 * 60 * 60 * 1000).toISOString();
+const query = `query RealtimeMetrics($accountTag: string!, $since: Time!, $namespace: string!) {
+  viewer {
+    accounts(filter: { accountTag: $accountTag }) {
+      invocations: durableObjectsInvocationsAdaptiveGroups(
+        filter: { datetime_geq: $since, name: $namespace }
+        limit: 10000
+      ) {
+        dimensions { datetimeHour type status }
+        sum { requests errors wallTime }
+      }
+      periodic: durableObjectsPeriodicGroups(
+        filter: { datetime_geq: $since, name: $namespace }
+        limit: 10000
+      ) {
+        dimensions { datetimeHour }
+        sum {
+          duration activeTime cpuTime rowsRead rowsWritten storageDeletes storageReadUnits storageWriteUnits
+          inboundWebsocketMsgCount outboundWebsocketMsgCount
+        }
+      }
+    }
+  }
+}`;
+
+const response = await fetch('https://api.cloudflare.com/client/v4/graphql', {
+  method: 'POST',
+  headers: { Authorization: `Bearer ${token}`, 'Content-Type': 'application/json' },
+  body: JSON.stringify({ query, variables: { accountTag, since, namespace } }),
+});
+const payload = await response.json();
+if (!response.ok || payload.errors?.length) {
+  throw new Error(JSON.stringify(payload.errors ?? payload));
+}
+
+const metrics = payload.data?.viewer?.accounts?.[0] ?? { invocations: [], periodic: [] };
+const sum = (groups, field) => groups.reduce((total, group) => total + Number(group.sum?.[field] ?? 0), 0);
+const summary = {
+  requests: sum(metrics.invocations, 'requests'),
+  errors: sum(metrics.invocations, 'errors'),
+  wallTime: sum(metrics.invocations, 'wallTime'),
+  duration: sum(metrics.periodic, 'duration'),
+  activeTime: sum(metrics.periodic, 'activeTime'),
+  cpuTime: sum(metrics.periodic, 'cpuTime'),
+  rowsRead: sum(metrics.periodic, 'rowsRead'),
+  rowsWritten: sum(metrics.periodic, 'rowsWritten'),
+  storageDeletes: sum(metrics.periodic, 'storageDeletes'),
+  storageReadUnits: sum(metrics.periodic, 'storageReadUnits'),
+  storageWriteUnits: sum(metrics.periodic, 'storageWriteUnits'),
+  inboundWebsocketMsgCount: sum(metrics.periodic, 'inboundWebsocketMsgCount'),
+  outboundWebsocketMsgCount: sum(metrics.periodic, 'outboundWebsocketMsgCount'),
+};
+
+console.log(JSON.stringify({ since, namespace, summary, ...metrics }, null, 2));

package/dist/realtime/legacy-sse.d.ts

@@ -1,25 +0,0 @@
-/** Minimal Durable Object namespace needed by the legacy SSE bridge. */
-export interface RealtimeDurableObjectNamespaceLike<TId = unknown> {
-    idFromName(name: string): TId;
-    get(id: TId): {
-        fetch(input: string | URL | Request, init?: RequestInit): Promise<Response>;
-    };
-}
-/** Options for bridging legacy SSE clients to Hibernation WebSocket rooms. */
-export interface LegacySseBridgeOptions<TId = unknown> {
-    namespace: RealtimeDurableObjectNamespaceLike<TId>;
-    roomNames: readonly string[];
-    signal: AbortSignal;
-    protocol: string;
-    clientId?: string;
-    heartbeatMs?: number;
-    pong?: string;
-    connectUrl?: string;
-}
-/**
- * Bridge legacy SSE clients to one or more Hibernation WebSocket rooms.
- *
- * The heartbeat lives in the outer Worker only; Durable Objects remain hibernatable. Aborting the
- * downstream request also aborts pending upgrades, including the late-upgrade race during teardown.
- */
-export declare function createLegacySseBridge<TId>(options: LegacySseBridgeOptions<TId>): Response;

package/dist/realtime/legacy-sse.js

@@ -1,110 +0,0 @@
-/**
- * Bridge legacy SSE clients to one or more Hibernation WebSocket rooms.
- *
- * The heartbeat lives in the outer Worker only; Durable Objects remain hibernatable. Aborting the
- * downstream request also aborts pending upgrades, including the late-upgrade race during teardown.
- */
-export function createLegacySseBridge(options) {
-    const encoder = new TextEncoder();
-    const sockets = new Set();
-    const heartbeatMs = options.heartbeatMs ?? 25_000;
-    const pong = options.pong ?? 'pong';
-    const connectUrl = options.connectUrl ?? 'https://do/connect';
-    let heartbeat;
-    let closeStream;
-    const stream = new ReadableStream({
-        start(controller) {
-            let closed = false;
-            const upstreamAbort = new AbortController();
-            const close = () => {
-                if (closed) {
-                    return;
-                }
-                closed = true;
-                upstreamAbort.abort();
-                if (heartbeat) {
-                    clearInterval(heartbeat);
-                }
-                for (const socket of sockets) {
-                    try {
-                        socket.close(1000, 'legacy SSE closed');
-                    }
-                    catch {
-                        // already closed
-                    }
-                }
-                sockets.clear();
-                try {
-                    controller.close();
-                }
-                catch {
-                    // already closed
-                }
-            };
-            closeStream = close;
-            if (options.signal.aborted) {
-                close();
-                return;
-            }
-            options.signal.addEventListener('abort', close, { once: true });
-            heartbeat = setInterval(() => {
-                try {
-                    controller.enqueue(encoder.encode('event: ping\ndata: ping\n\n'));
-                }
-                catch {
-                    close();
-                }
-            }, heartbeatMs);
-            const connect = async (roomName) => {
-                const id = options.namespace.idFromName(roomName);
-                const response = (await options.namespace.get(id).fetch(connectUrl, {
-                    signal: upstreamAbort.signal,
-                    headers: {
-                        Upgrade: 'websocket',
-                        'Sec-WebSocket-Protocol': options.protocol,
-                        ...(options.clientId ? { 'x-client-id': options.clientId } : {}),
-                    },
-                }));
-                const socket = response.webSocket;
-                if (response.status !== 101 || !socket) {
-                    socket?.close(1011, 'legacy SSE upgrade failed');
-                    throw new Error('Legacy realtime WebSocket upgrade failed');
-                }
-                if (closed) {
-                    socket.close(1000, 'legacy SSE already closed');
-                    return;
-                }
-                sockets.add(socket);
-                socket.accept();
-                socket.addEventListener('message', ({ data }) => {
-                    if (typeof data !== 'string' || data === pong) {
-                        return;
-                    }
-                    try {
-                        const parsed = JSON.parse(data);
-                        for (const event of Array.isArray(parsed) ? parsed : [parsed]) {
-                            controller.enqueue(encoder.encode(`data: ${JSON.stringify(event)}\n\n`));
-                        }
-                    }
-                    catch {
-                        // Ignore malformed upstream messages.
-                    }
-                });
-                socket.addEventListener('close', close, { once: true });
-                socket.addEventListener('error', close, { once: true });
-            };
-            void Promise.all(options.roomNames.map((roomName) => connect(roomName))).catch(close);
-        },
-        cancel() {
-            closeStream?.();
-        },
-    });
-    return new Response(stream, {
-        headers: {
-            'Content-Type': 'text/event-stream',
-            'Cache-Control': 'no-cache',
-            Connection: 'keep-alive',
-            'X-Accel-Buffering': 'no',
-        },
-    });
-}