@rdlabo/workers-hono-kit 0.8.0 → 0.9.0

package/dist/index.d.ts

@@ -51,6 +51,10 @@ export { acknowledgeHibernationWebSocketClose, broadcastHibernationWebSockets, c
 export type { HibernationAutoResponseOptions, HibernationUpgradeOptions, HibernationWebSocketLike, HibernationWebSocketStateLike, WebSocketAutoResponsePairFactory, WebSocketPairFactory, } from './realtime/hibernation.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

@@ -38,6 +38,8 @@ export { createSentryErrorReporter } from './http/http-error.js';
 // realtime
 export { acknowledgeHibernationWebSocketClose, broadcastHibernationWebSockets, closeHibernationWebSocket, configureHibernationAutoResponse, upgradeHibernationWebSocket, } from './realtime/hibernation.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

@@ -2,3 +2,7 @@ export { acknowledgeHibernationWebSocketClose, broadcastHibernationWebSockets, c
 export type { HibernationAutoResponseOptions, HibernationUpgradeOptions, HibernationWebSocketLike, HibernationWebSocketStateLike, WebSocketAutoResponsePairFactory, WebSocketPairFactory, } from './hibernation.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,2 +1,4 @@
 export { acknowledgeHibernationWebSocketClose, broadcastHibernationWebSockets, closeHibernationWebSocket, configureHibernationAutoResponse, upgradeHibernationWebSocket, } from './hibernation.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.8.0",
+  "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": {
     ".": {

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/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));