@rdlabo/workers-hono-kit 0.6.17 → 0.7.0

package/README.md

@@ -13,6 +13,7 @@ It provides the building blocks a NestJS-style API needs but that don't run on `
 - **Stripe** Workers-native client + async webhook verification.
 - **Payment failure & subscription reconcile**: provider-agnostic `payment_failed` helpers — Stripe decline reasons → Japanese messages, Apple / Google subscription-renewal classification, `iapFailureKey` / receipt (de)serialization, and Stripe reconcile branch decisions.
 - **Testing helpers** (`@rdlabo/workers-hono-kit/testing`): a Drizzle-migration-backed test database, in-memory Firebase fake, configurable test doubles, and Stripe fixtures.
+- **Realtime helpers**: Hibernation WebSocket upgrade/broadcast/close, legacy SSE bridging, and Durable Object retry policy.
 
 ## Install
 
@@ -82,6 +83,10 @@ npm install ai ai-gateway-provider    # createAiGatewayProvider
 | `ErrorReporter` / `ErrorReportContext` | Types for a `reportError`-style unhandled-error reporter (e.g. wired to Sentry), paired with `createHttpErrorHandler`'s `onUnhandledError`. |
 | `createSentryErrorReporter(sentry)` / `SentryExceptionReporterLike` | Build an `ErrorReporter` that forwards to Sentry with an optional `request_id` tag (no hard `@sentry/cloudflare` dependency). |
 | `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. |
 | `createStripeClient(secret, opts?)` / `verifyStripeWebhook(...)` / `CreateStripeClientOptions` | Workers-native Stripe client (fetch transport) + async webhook verification (SubtleCrypto). `apiVersion` optional (pin to a fixed Stripe API version). |
@@ -616,6 +621,40 @@ The package ships three `bin` commands (run via `npx` or an npm script in the co
 | `workers-hono-kit-check-subrequest-fanout [dir…]` | CI gate that greps for per-item external-call fan-outs (`runWithConcurrency(` / `PromisePool` / `.withConcurrency(`) that would eventually exceed the Workers subrequest cap. Annotate a genuinely-safe site with `subrequest-ok`. Scans `src` by default; exits 1 on an un-annotated marker. |
 | `workers-hono-kit-db-baseline [--migrations ./drizzle]` | Brownfield first-deploy helper: record the baseline `0000` migration as *already applied* on an existing MySQL DB without running its DDL (the CLI wrapper around `baselineMigrations` / `readBaselineEntry`). Reads DB credentials from `DB_SECRET` (AWS RDS managed secret) or the individual `DB_*` env vars. |
 
+## Storage-agnostic role policies
+
+`createRolePolicy` builds pure RBAC checks without coupling the policy to a database schema. The
+application can resolve roles from a membership table, a `users.role` column, token claims, or any
+other source.
+
+```ts
+import { createRolePolicy } from '@rdlabo/workers-hono-kit';
+
+type Role = 'owner' | 'admin' | 'member' | 'read';
+type Permission = 'organization.manage' | 'resource.write' | 'resource.read';
+
+const policy = createRolePolicy<Role, Permission>({
+  permissions: {
+    owner: ['organization.manage', 'resource.write', 'resource.read'],
+    admin: ['resource.write', 'resource.read'],
+    member: ['resource.write', 'resource.read'],
+    read: ['resource.read'],
+  },
+  assignableRoles: {
+    owner: ['admin', 'member', 'read'],
+    admin: ['member', 'read'],
+    member: [],
+    read: [],
+  },
+  manageableRoles: {
+    owner: ['admin', 'member', 'read'],
+    admin: ['member', 'read'],
+    member: [],
+    read: [],
+  },
+});
+```
+
 ## Development
 
 ```bash

package/dist/authorization/role-policy.d.ts

@@ -0,0 +1,32 @@
+/** A role-to-permissions lookup used by {@link createRolePolicy}. */
+export type RolePermissionMap<Role extends string, Permission extends string> = Readonly<Record<Role, readonly Permission[]>>;
+/** A role-to-roles lookup used for assignment and management boundaries. */
+export type RoleRelationMap<Role extends string> = Readonly<Record<Role, readonly Role[]>>;
+/** Configuration for a storage-agnostic role policy. */
+export interface RolePolicyConfig<Role extends string, Permission extends string> {
+    /** Permissions granted to each role. */
+    permissions: RolePermissionMap<Role, Permission>;
+    /** Roles that each actor role may assign to another subject. */
+    assignableRoles: RoleRelationMap<Role>;
+    /** Existing subject roles that each actor role may manage. */
+    manageableRoles: RoleRelationMap<Role>;
+}
+/** Pure authorization checks produced from a role policy configuration. */
+export interface RolePolicy<Role extends string, Permission extends string> {
+    /** Returns whether `role` grants `permission`. */
+    hasPermission(role: Role, permission: Permission): boolean;
+    /** Returns whether `actorRole` may assign `nextRole`. */
+    canAssignRole(actorRole: Role, nextRole: Role): boolean;
+    /** Returns whether `actorRole` may manage a subject with `targetRole`. */
+    canManageRole(actorRole: Role, targetRole: Role): boolean;
+    /** Returns whether an actor may change a subject from one role to another. */
+    canChangeRole(actorRole: Role, currentRole: Role, nextRole: Role): boolean;
+}
+/**
+ * Creates pure, schema-independent RBAC checks.
+ *
+ * The caller resolves a role from any persistence model (for example `group_users.role`,
+ * `users.role`, a token claim, or an external identity provider) and passes that role into these
+ * checks. Keeping lookup and policy separate makes the same policy reusable across applications.
+ */
+export declare function createRolePolicy<Role extends string, Permission extends string>(config: RolePolicyConfig<Role, Permission>): RolePolicy<Role, Permission>;

package/dist/authorization/role-policy.js

@@ -0,0 +1,25 @@
+function ownListIncludes(record, key, value) {
+    if (!Object.prototype.hasOwnProperty.call(record, key)) {
+        return false;
+    }
+    return record[key]?.includes(value) ?? false;
+}
+/**
+ * Creates pure, schema-independent RBAC checks.
+ *
+ * The caller resolves a role from any persistence model (for example `group_users.role`,
+ * `users.role`, a token claim, or an external identity provider) and passes that role into these
+ * checks. Keeping lookup and policy separate makes the same policy reusable across applications.
+ */
+export function createRolePolicy(config) {
+    // Keep the public config strongly typed while treating runtime values as untrusted input.
+    const permissions = config.permissions;
+    const assignableRoles = config.assignableRoles;
+    const manageableRoles = config.manageableRoles;
+    return {
+        hasPermission: (role, permission) => ownListIncludes(permissions, role, permission),
+        canAssignRole: (actorRole, nextRole) => ownListIncludes(assignableRoles, actorRole, nextRole),
+        canManageRole: (actorRole, targetRole) => ownListIncludes(manageableRoles, actorRole, targetRole),
+        canChangeRole: (actorRole, currentRole, nextRole) => ownListIncludes(manageableRoles, actorRole, currentRole) && ownListIncludes(assignableRoles, actorRole, nextRole),
+    };
+}

package/dist/index.d.ts

@@ -24,6 +24,8 @@ export { createIsolateMemo } from './container/isolate-memo.js';
 export type { IsolateMemo } from './container/isolate-memo.js';
 export { createContainerRuntime } from './container/middleware.js';
 export type { ContainerBuildContext, ContainerRuntime, ContainerRuntimeOptions } from './container/middleware.js';
+export { createRolePolicy } from './authorization/role-policy.js';
+export type { RolePermissionMap, RolePolicy, RolePolicyConfig, RoleRelationMap } from './authorization/role-policy.js';
 export { getUserProtocol } from './http/user-protocol.js';
 export type { IUserProtocol } from './http/user-protocol.js';
 export { getAppInfo } from './http/app-info.js';
@@ -45,6 +47,12 @@ export { defaultDefer, createWaitUntilDefer } from './http/defer.js';
 export type { DeferExecutor } from './http/defer.js';
 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 { 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

@@ -21,6 +21,8 @@ export { perfLog } from './middleware/perf-log.js';
 export { createMaintenanceMiddleware, createMaintenanceWaitHandler, isMaintenanceEnabled, MAINTENANCE_BODY, MAINTENANCE_CODE, MAINTENANCE_WAIT_PATH, } from './middleware/maintenance.js';
 export { createIsolateMemo } from './container/isolate-memo.js';
 export { createContainerRuntime } from './container/middleware.js';
+// authorization
+export { createRolePolicy } from './authorization/role-policy.js';
 // http
 export { getUserProtocol } from './http/user-protocol.js';
 export { getAppInfo } from './http/app-info.js';
@@ -33,6 +35,10 @@ export { createAppErrorHandler } from './http/app-error-handler.js';
 export { normalizeTrailingSlash } from './http/trailing-slash.js';
 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';
 // cache
 export { KVCache } from './cache/kv-cache.js';
 // stripe

package/dist/realtime/hibernation.d.ts

@@ -0,0 +1,48 @@
+/** Minimal Hibernation WebSocket state used by the shared helpers. */
+export interface HibernationWebSocketStateLike {
+    acceptWebSocket(socket: WebSocket): void;
+    getWebSockets(): WebSocket[];
+    setWebSocketAutoResponse(pair: unknown): void;
+}
+/** A server-side WebSocket that can persist metadata across Durable Object hibernation. */
+export interface HibernationWebSocketLike extends WebSocket {
+    serializeAttachment(value: unknown): void;
+}
+/** Constructor shape of the Workers `WebSocketPair` runtime global. */
+export type WebSocketPairFactory = new () => {
+    0: HibernationWebSocketLike;
+    1: HibernationWebSocketLike;
+};
+/** Constructor shape of the Workers `WebSocketRequestResponsePair` runtime global. */
+export type WebSocketAutoResponsePairFactory = new (request: string, response: string) => unknown;
+/** Options for configuring runtime-handled ping/pong responses. */
+export interface HibernationAutoResponseOptions {
+    state: HibernationWebSocketStateLike;
+    ping: string;
+    pong: string;
+    pairFactory?: WebSocketAutoResponsePairFactory;
+}
+/** Options for upgrading a request to a Hibernation WebSocket. */
+export interface HibernationUpgradeOptions {
+    state: HibernationWebSocketStateLike;
+    request: Request;
+    protocol: string;
+    attachment?: unknown;
+    pairFactory?: WebSocketPairFactory;
+    responseFactory?: (client: WebSocket, protocol: string) => Response;
+}
+/** Configure ping/pong at the runtime layer so application heartbeats do not wake the object. */
+export declare function configureHibernationAutoResponse(options: HibernationAutoResponseOptions): void;
+/**
+ * Upgrade a request and register its server socket with the Hibernation WebSocket API.
+ *
+ * Attachments are serialized before acceptance so connection metadata remains available after
+ * the Durable Object instance is evicted and reconstructed.
+ */
+export declare function upgradeHibernationWebSocket(options: HibernationUpgradeOptions): Response;
+/** Broadcast one JSON message to all sockets restored by `getWebSockets()`. */
+export declare function broadcastHibernationWebSockets(state: Pick<HibernationWebSocketStateLike, 'getWebSockets'>, payload: unknown): void;
+/** Close a Hibernation WebSocket while tolerating already-closed sockets. */
+export declare function closeHibernationWebSocket(socket: WebSocket, code: number, reason: string): void;
+/** Echo a peer close using a legal close-frame code. */
+export declare function acknowledgeHibernationWebSocketClose(socket: WebSocket, code: number, reason: string): void;

package/dist/realtime/hibernation.js

@@ -0,0 +1,57 @@
+/** Configure ping/pong at the runtime layer so application heartbeats do not wake the object. */
+export function configureHibernationAutoResponse(options) {
+    const Pair = options.pairFactory ?? WebSocketRequestResponsePair;
+    options.state.setWebSocketAutoResponse(new Pair(options.ping, options.pong));
+}
+/**
+ * Upgrade a request and register its server socket with the Hibernation WebSocket API.
+ *
+ * Attachments are serialized before acceptance so connection metadata remains available after
+ * the Durable Object instance is evicted and reconstructed.
+ */
+export function upgradeHibernationWebSocket(options) {
+    if (options.request.headers.get('Upgrade')?.toLowerCase() !== 'websocket') {
+        return new Response('Expected Upgrade: websocket', { status: 426 });
+    }
+    const Pair = options.pairFactory ?? WebSocketPair;
+    const pair = new Pair();
+    const client = pair[0];
+    const server = pair[1];
+    if (options.attachment !== undefined) {
+        server.serializeAttachment(options.attachment);
+    }
+    options.state.acceptWebSocket(server);
+    return options.responseFactory
+        ? options.responseFactory(client, options.protocol)
+        : new Response(null, {
+            status: 101,
+            webSocket: client,
+            headers: { 'Sec-WebSocket-Protocol': options.protocol },
+        });
+}
+/** Broadcast one JSON message to all sockets restored by `getWebSockets()`. */
+export function broadcastHibernationWebSockets(state, payload) {
+    const message = JSON.stringify(payload);
+    for (const socket of state.getWebSockets()) {
+        try {
+            socket.send(message);
+        }
+        catch {
+            closeHibernationWebSocket(socket, 1011, 'publish failed');
+        }
+    }
+}
+/** Close a Hibernation WebSocket while tolerating already-closed sockets. */
+export function closeHibernationWebSocket(socket, code, reason) {
+    try {
+        socket.close(code, reason);
+    }
+    catch {
+        // The socket is already closed or cannot send a close frame.
+    }
+}
+/** Echo a peer close using a legal close-frame code. */
+export function acknowledgeHibernationWebSocketClose(socket, code, reason) {
+    const replyCode = code === 1005 || code === 1006 || code === 1015 ? 1000 : code;
+    closeHibernationWebSocket(socket, replyCode, reason);
+}

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

@@ -0,0 +1,25 @@
+/** Minimal Durable Object namespace needed by the legacy SSE bridge. */
+export interface RealtimeDurableObjectNamespaceLike {
+    idFromName(name: string): unknown;
+    get(id: unknown): {
+        fetch(input: string | URL | Request, init?: RequestInit): Promise<Response>;
+    };
+}
+/** Options for bridging legacy SSE clients to Hibernation WebSocket rooms. */
+export interface LegacySseBridgeOptions {
+    namespace: RealtimeDurableObjectNamespaceLike;
+    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(options: LegacySseBridgeOptions): Response;

package/dist/realtime/legacy-sse.js

@@ -0,0 +1,110 @@
+/**
+ * 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',
+        },
+    });
+}

package/dist/realtime/retry.d.ts

@@ -0,0 +1,22 @@
+/** Durable Object error flags documented by the Workers runtime. */
+export interface DurableObjectErrorLike {
+    retryable?: boolean;
+    overloaded?: boolean;
+}
+/** Retry policy for an idempotent Durable Object operation. */
+export interface DurableObjectRetryOptions {
+    maxAttempts?: number;
+    baseDelayMs?: number;
+    maxDelayMs?: number;
+    random?: () => number;
+    wait?: (delayMs: number) => Promise<void>;
+}
+/** Return whether a Durable Object failure may be retried safely by policy. */
+export declare function isRetryableDurableObjectError(error: unknown): boolean;
+/**
+ * Retry an idempotent Durable Object operation with jittered exponential backoff.
+ *
+ * `operation` is invoked again for every attempt. Callers must create a fresh stub inside it,
+ * because a stub that threw may remain in a broken state. Overload errors are never retried.
+ */
+export declare function retryDurableObjectOperation<T>(operation: (attempt: number) => Promise<T>, options?: DurableObjectRetryOptions): Promise<T>;

package/dist/realtime/retry.js

@@ -0,0 +1,42 @@
+function hasFlag(error, flag) {
+    if (typeof error !== 'object' || error === null) {
+        return false;
+    }
+    return error[flag] === true;
+}
+function defaultWait(delayMs) {
+    const runtimeScheduler = globalThis.scheduler;
+    return runtimeScheduler?.wait
+        ? runtimeScheduler.wait(delayMs)
+        : new Promise((resolve) => setTimeout(resolve, delayMs));
+}
+/** Return whether a Durable Object failure may be retried safely by policy. */
+export function isRetryableDurableObjectError(error) {
+    return hasFlag(error, 'retryable') && !hasFlag(error, 'overloaded');
+}
+/**
+ * Retry an idempotent Durable Object operation with jittered exponential backoff.
+ *
+ * `operation` is invoked again for every attempt. Callers must create a fresh stub inside it,
+ * because a stub that threw may remain in a broken state. Overload errors are never retried.
+ */
+export async function retryDurableObjectOperation(operation, options = {}) {
+    const maxAttempts = Math.max(1, options.maxAttempts ?? 3);
+    const baseDelayMs = Math.max(0, options.baseDelayMs ?? 100);
+    const maxDelayMs = Math.max(baseDelayMs, options.maxDelayMs ?? 1000);
+    const random = options.random ?? Math.random;
+    const wait = options.wait ?? defaultWait;
+    for (let attempt = 0; attempt < maxAttempts; attempt += 1) {
+        try {
+            return await operation(attempt);
+        }
+        catch (error) {
+            if (!isRetryableDurableObjectError(error) || attempt + 1 >= maxAttempts) {
+                throw error;
+            }
+            const delayMs = Math.min(maxDelayMs, baseDelayMs * 2 ** attempt * random());
+            await wait(delayMs);
+        }
+    }
+    throw new Error('Durable Object retry exhausted');
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rdlabo/workers-hono-kit",
-  "version": "0.6.17",
+  "version": "0.7.0",
   "private": false,
   "publishConfig": {
     "access": "public"