@rdlabo/workers-hono-kit 0.6.13 → 0.6.14

package/README.md

@@ -78,6 +78,7 @@ npm install ai ai-gateway-provider    # createAiGatewayProvider
 | `HTTP_ERROR_PHRASES` | `{ 400, 401, 403, 404 }` → standard `error` field phrases. |
 | `createAuthMiddleware(options)` / `AuthMiddlewareOptions` | Factory for a Firebase-token auth middleware: reads the token header, verifies, resolves the DB user id, and stashes the result on the context. Omit `resolveUserId` for a token-only (login) guard. |
 | `perfLog(options?)` / `PerfLogOptions` / `AnalyticsEngineDatasetLike` | Middleware that records one per-request latency data point (`t_app`, colo, cold/warm, route, status) and emits it to **Workers Logs** (`console.log`) and/or **Workers Analytics Engine** (`writeDataPoint`). Lets you measure low-traffic Workers without a live `wrangler tail`. |
+| `createMaintenanceMiddleware(options)` / `createMaintenanceWaitHandler(options)` / `isMaintenanceEnabled(env)` / `MAINTENANCE_CODE` / `MAINTENANCE_WAIT_PATH` | Fleet maintenance short-circuit: when enabled (`MAINTENANCE=1`), every non-allowlisted request returns `503` + `{ statusCode, message, code: 'MAINTENANCE' }` **before** container/DB. Pair with `GET /public/maintenance/wait` SSE (`event: ping` / `event: ended`) so clients can auto-dismiss a lock UI. Mount after `cors`, before `containerMiddleware`. |
 | `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`. |

package/dist/index.d.ts

@@ -18,6 +18,8 @@ export { createAuthMiddleware } from './middleware/auth.js';
 export type { AuthMiddlewareOptions } from './middleware/auth.js';
 export { perfLog } from './middleware/perf-log.js';
 export type { PerfLogOptions, AnalyticsEngineDatasetLike } from './middleware/perf-log.js';
+export { createMaintenanceMiddleware, createMaintenanceWaitHandler, isMaintenanceEnabled, MAINTENANCE_BODY, MAINTENANCE_CODE, MAINTENANCE_WAIT_PATH, } from './middleware/maintenance.js';
+export type { MaintenanceBody, MaintenanceMiddlewareOptions, MaintenanceWaitOptions, } from './middleware/maintenance.js';
 export { createIsolateMemo } from './container/isolate-memo.js';
 export type { IsolateMemo } from './container/isolate-memo.js';
 export { createContainerRuntime } from './container/middleware.js';

package/dist/index.js

@@ -18,6 +18,7 @@ export { createSentryValidate } from './middleware/validation.js';
 export { zNum, zNumNullable, zNumOptional, zNumWithDefault } from './middleware/zod-coerce.js';
 export { createAuthMiddleware } from './middleware/auth.js';
 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';
 // http

package/dist/middleware/maintenance.d.ts

@@ -0,0 +1,113 @@
+import type { Context, Env, MiddlewareHandler } from 'hono';
+/** Canonical API error `code` for fleet-wide maintenance short-circuit. */
+export declare const MAINTENANCE_CODE: "MAINTENANCE";
+/** Default allowlisted SSE path that stays open while the rest of the API returns 503. */
+export declare const MAINTENANCE_WAIT_PATH = "/public/maintenance/wait";
+/** JSON body returned for every blocked request during maintenance. */
+export interface MaintenanceBody {
+    statusCode: 503;
+    message: string;
+    code: typeof MAINTENANCE_CODE;
+}
+/** Default 503 body (no phrase `error` field — would collide with `code` shape on the client). */
+export declare const MAINTENANCE_BODY: MaintenanceBody;
+/**
+ * True when the Workers binding / wrangler var `MAINTENANCE` is the string `'1'`.
+ *
+ * @param env - Bindings object that may carry `MAINTENANCE`
+ */
+export declare function isMaintenanceEnabled(env: {
+    MAINTENANCE?: string;
+} | null | undefined): boolean;
+/**
+ * Options for {@link createMaintenanceMiddleware}.
+ *
+ * @typeParam E - The Hono `Env` of the application.
+ */
+export interface MaintenanceMiddlewareOptions<E extends Env = Env> {
+    /**
+     * Whether maintenance mode is currently on for this request.
+     *
+     * @remarks
+     * Typical wiring: `(c) => isMaintenanceEnabled(c.env)`. Injected so tests and non-env sources
+     * (future KV) can supply their own predicate without forking the middleware.
+     */
+    isEnabled: (c: Context<E>) => boolean;
+    /**
+     * Paths that stay reachable during maintenance (default: {@link MAINTENANCE_WAIT_PATH}).
+     *
+     * @remarks
+     * Compared against `pathname` with and without a trailing slash. {@link MAINTENANCE_WAIT_PATH}
+     * is handled inside this middleware (SSE) so it never reaches container/DB. Other allowlisted
+     * paths call `next()`.
+     */
+    allowPaths?: readonly string[];
+    /** Override the default {@link MAINTENANCE_BODY.message}. */
+    message?: string;
+    /** Optional `Retry-After` header (seconds). */
+    retryAfterSeconds?: number;
+    /**
+     * Ping interval for the in-middleware wait SSE (ms). Defaults to `5_000`.
+     *
+     * @see {@link MaintenanceWaitOptions.pingIntervalMs}
+     */
+    pingIntervalMs?: number;
+}
+/**
+ * Options for {@link createMaintenanceWaitHandler}.
+ *
+ * @typeParam E - The Hono `Env` of the application.
+ */
+export interface MaintenanceWaitOptions<E extends Env = Env> {
+    /**
+     * Whether maintenance mode is still on. Re-evaluated on each ping tick.
+     *
+     * @remarks
+     * Wrangler `vars` do not change inside a long-lived isolate; after a deploy that clears
+     * `MAINTENANCE`, new connections (and clients that reconnect) see `false` and get `ended`.
+     */
+    isEnabled: (c: Context<E>) => boolean;
+    /**
+     * Interval between SSE `ping` events and `isEnabled` re-checks (ms). Defaults to `5_000`.
+     */
+    pingIntervalMs?: number;
+}
+/**
+ * Short-circuit middleware: when enabled, every non-allowlisted request returns
+ * `503` + `{ statusCode, message, code: 'MAINTENANCE' }` without running downstream
+ * (so container / Hyperdrive / secrets stay cold).
+ *
+ * @remarks
+ * Mount **after** `cors` / `finalizeResponse` and **before** `containerMiddleware`.
+ * {@link MAINTENANCE_WAIT_PATH} is served **inside this middleware** (both when
+ * maintenance is on and off) so the wait SSE never reaches container / DB. Other
+ * `allowPaths` still call `next()`.
+ *
+ * @typeParam E - The Hono `Env` of the application.
+ * @param options - Enable predicate, allowlist, and optional body/header overrides.
+ * @returns A {@link MiddlewareHandler} that either returns 503 / SSE or calls `next()`.
+ *
+ * @example
+ * ```ts
+ * app.use('*', createMaintenanceMiddleware({
+ *   isEnabled: (c) => isMaintenanceEnabled(c.env),
+ * }));
+ * // Optional: also register createMaintenanceWaitHandler as a route — redundant when
+ * // this middleware is mounted, because MAINTENANCE_WAIT_PATH is handled here.
+ * ```
+ */
+export declare function createMaintenanceMiddleware<E extends Env = Env>(options: MaintenanceMiddlewareOptions<E>): MiddlewareHandler<E>;
+/**
+ * SSE handler for {@link MAINTENANCE_WAIT_PATH}.
+ *
+ * @remarks
+ * - Already off → emit `event: ended` once and close.
+ * - Still on → emit `event: ping` on an interval; when `isEnabled` becomes false, emit
+ *   `event: ended` and close. Clients should close the EventSource on `ended` and dismiss UI.
+ *
+ * @typeParam E - The Hono `Env` of the application.
+ * @param options - Enable predicate and ping interval.
+ * @returns A handler `(c) => Response` suitable for `app.get(MAINTENANCE_WAIT_PATH, …)`
+ *   or for embedding inside {@link createMaintenanceMiddleware}.
+ */
+export declare function createMaintenanceWaitHandler<E extends Env = Env>(options: MaintenanceWaitOptions<E>): (c: Context<E>) => Response;

package/dist/middleware/maintenance.js

@@ -0,0 +1,171 @@
+/** Canonical API error `code` for fleet-wide maintenance short-circuit. */
+export const MAINTENANCE_CODE = 'MAINTENANCE';
+/** Default allowlisted SSE path that stays open while the rest of the API returns 503. */
+export const MAINTENANCE_WAIT_PATH = '/public/maintenance/wait';
+/** Default 503 body (no phrase `error` field — would collide with `code` shape on the client). */
+export const MAINTENANCE_BODY = {
+    statusCode: 503,
+    message: 'Service temporarily unavailable',
+    code: MAINTENANCE_CODE,
+};
+/**
+ * True when the Workers binding / wrangler var `MAINTENANCE` is the string `'1'`.
+ *
+ * @param env - Bindings object that may carry `MAINTENANCE`
+ */
+export function isMaintenanceEnabled(env) {
+    return env?.MAINTENANCE === '1';
+}
+const SSE_HEADERS = {
+    'Content-Type': 'text/event-stream',
+    'Cache-Control': 'no-cache',
+    Connection: 'keep-alive',
+    'X-Accel-Buffering': 'no',
+};
+function normalizePath(pathname) {
+    if (pathname.length > 1 && pathname.endsWith('/')) {
+        return pathname.slice(0, -1);
+    }
+    return pathname;
+}
+function isAllowlisted(pathname, allowPaths) {
+    const normalized = normalizePath(pathname);
+    return allowPaths.has(normalized) || allowPaths.has(pathname);
+}
+/**
+ * Short-circuit middleware: when enabled, every non-allowlisted request returns
+ * `503` + `{ statusCode, message, code: 'MAINTENANCE' }` without running downstream
+ * (so container / Hyperdrive / secrets stay cold).
+ *
+ * @remarks
+ * Mount **after** `cors` / `finalizeResponse` and **before** `containerMiddleware`.
+ * {@link MAINTENANCE_WAIT_PATH} is served **inside this middleware** (both when
+ * maintenance is on and off) so the wait SSE never reaches container / DB. Other
+ * `allowPaths` still call `next()`.
+ *
+ * @typeParam E - The Hono `Env` of the application.
+ * @param options - Enable predicate, allowlist, and optional body/header overrides.
+ * @returns A {@link MiddlewareHandler} that either returns 503 / SSE or calls `next()`.
+ *
+ * @example
+ * ```ts
+ * app.use('*', createMaintenanceMiddleware({
+ *   isEnabled: (c) => isMaintenanceEnabled(c.env),
+ * }));
+ * // Optional: also register createMaintenanceWaitHandler as a route — redundant when
+ * // this middleware is mounted, because MAINTENANCE_WAIT_PATH is handled here.
+ * ```
+ */
+export function createMaintenanceMiddleware(options) {
+    const allowPaths = new Set((options.allowPaths ?? [MAINTENANCE_WAIT_PATH]).map((p) => normalizePath(p)));
+    const message = options.message ?? MAINTENANCE_BODY.message;
+    const waitHandler = createMaintenanceWaitHandler({
+        isEnabled: options.isEnabled,
+        pingIntervalMs: options.pingIntervalMs,
+    });
+    const waitPath = normalizePath(MAINTENANCE_WAIT_PATH);
+    return async (c, next) => {
+        const pathname = normalizePath(new URL(c.req.url).pathname);
+        // Wait SSE must never hit container/DB — handle it here whether maintenance is on or off.
+        if (pathname === waitPath) {
+            return waitHandler(c);
+        }
+        if (!options.isEnabled(c)) {
+            return next();
+        }
+        if (isAllowlisted(pathname, allowPaths)) {
+            return next();
+        }
+        if (options.retryAfterSeconds != null) {
+            c.header('Retry-After', String(options.retryAfterSeconds));
+        }
+        const body = {
+            statusCode: 503,
+            message,
+            code: MAINTENANCE_CODE,
+        };
+        return c.json(body, 503);
+    };
+}
+/**
+ * SSE handler for {@link MAINTENANCE_WAIT_PATH}.
+ *
+ * @remarks
+ * - Already off → emit `event: ended` once and close.
+ * - Still on → emit `event: ping` on an interval; when `isEnabled` becomes false, emit
+ *   `event: ended` and close. Clients should close the EventSource on `ended` and dismiss UI.
+ *
+ * @typeParam E - The Hono `Env` of the application.
+ * @param options - Enable predicate and ping interval.
+ * @returns A handler `(c) => Response` suitable for `app.get(MAINTENANCE_WAIT_PATH, …)`
+ *   or for embedding inside {@link createMaintenanceMiddleware}.
+ */
+export function createMaintenanceWaitHandler(options) {
+    const pingIntervalMs = options.pingIntervalMs ?? 5_000;
+    const encoder = new TextEncoder();
+    return (c) => {
+        const clientSignal = c.req.raw.signal;
+        if (!options.isEnabled(c)) {
+            const stream = new ReadableStream({
+                start(controller) {
+                    controller.enqueue(encoder.encode('event: ended\ndata: ended\n\n'));
+                    controller.close();
+                },
+            });
+            return new Response(stream, { headers: SSE_HEADERS });
+        }
+        let heartbeat;
+        const stream = new ReadableStream({
+            start(controller) {
+                let closed = false;
+                const close = () => {
+                    if (closed) {
+                        return;
+                    }
+                    closed = true;
+                    if (heartbeat) {
+                        clearInterval(heartbeat);
+                        heartbeat = undefined;
+                    }
+                    try {
+                        controller.close();
+                    }
+                    catch {
+                        /* already closed */
+                    }
+                };
+                const enqueue = (chunk) => {
+                    try {
+                        controller.enqueue(encoder.encode(chunk));
+                    }
+                    catch {
+                        close();
+                    }
+                };
+                const end = () => {
+                    enqueue('event: ended\ndata: ended\n\n');
+                    close();
+                };
+                if (clientSignal.aborted) {
+                    close();
+                    return;
+                }
+                clientSignal.addEventListener('abort', close, { once: true });
+                heartbeat = setInterval(() => {
+                    if (!options.isEnabled(c)) {
+                        end();
+                        return;
+                    }
+                    enqueue('event: ping\ndata: ping\n\n');
+                }, pingIntervalMs);
+            },
+            cancel() {
+                if (heartbeat) {
+                    clearInterval(heartbeat);
+                    heartbeat = undefined;
+                }
+            },
+        });
+        return new Response(stream, { headers: SSE_HEADERS });
+    };
+}

package/package.json

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