@rdlabo/workers-hono-kit 0.4.0 → 0.4.3

package/dist/middleware/perf-log.js

@@ -0,0 +1,97 @@
+// `t_app` = wall time inside the Hono app (this middleware wrapping `next()`), i.e. everything from
+// the middlewares/auth guards through the route handler. On a DB-round-trip-bound Worker it is
+// dominated by database round trips, so it is the signal that exposes edge↔origin distance (Smart
+// Placement) and serial-await fan-out.
+//
+// SCOPE DEPENDS ON WIRING. Whatever runs *inside* the app is included, whatever runs in `fetch`
+// *before* the app is not. If the app builds its container/secrets/DB connection as an in-app
+// middleware (e.g. secrets fetch + Hyperdrive connect inside `createApp`), those costs land in the
+// cold `t_app`; if the container is built in `fetch` before `createApp(...).fetch(req)`, they do not.
+// So the cold-row `t_app` is NOT directly comparable across repos wired differently — document the
+// wiring per repo, or add a scope label, before comparing cold numbers.
+//
+// Note: on production Workers `Date.now()` only advances at I/O boundaries (Spectre mitigation), so
+// `t_app` ≈ I/O wait, not CPU time — which is what you want for round-trip-bound analysis.
+//
+// Module scope: survives for the isolate's lifetime, so the first request after a cold start reports
+// `cold: true` and later requests `cold: false`. Caveat: requests that arrive concurrently right after
+// a cold start are labelled warm (only the very first flips the flag) even though they pay cold-init
+// waits — a minor warm-side contamination, negligible at the low request rates this targets.
+let isolateWarm = false;
+/**
+ * Create a Hono middleware that records a per-request latency data point and emits it to Workers
+ * Logs (`console`) and/or Workers Analytics Engine (`dataset`).
+ *
+ * Register it first (`app.use('*', perfLog(...))`) so `t_app` covers the whole in-app path. Route
+ * grouping uses the matched route pattern (e.g. `/user/:id`) rather than the raw path so ids do not
+ * explode cardinality; unmatched requests collapse to `(unmatched)`. Colo comes from `request.cf.colo`;
+ * cold/warm from an isolate-scoped flag. See {@link PerfLogOptions} for the two sinks and the note
+ * above for exactly what `t_app` includes (it depends on where secrets/DB-connect are wired).
+ *
+ * Two wiring styles, both A/B-capable (Workers Logs and/or Analytics Engine):
+ *
+ * @example Bare, when the app is served with `app.fetch(req, env, ctx)` — reads `PERF` (Analytics
+ * Engine binding) and `PERF_LOG === '1'` (Workers Logs) straight off `c.env`:
+ * ```ts
+ * app.use('*', perfLog());
+ * ```
+ *
+ * @example Explicit, when the app is built without Hono `env` (e.g. `createApp(container).fetch(req)`)
+ * — thread the bindings in:
+ * ```ts
+ * app.use('*', perfLog({ console: env.PERF_LOG === '1', dataset: env.PERF }));
+ * ```
+ *
+ * @example Query Analytics Engine (SQL API), handler p50/p90 by route and colo:
+ * ```sql
+ * SELECT blob1 AS path, blob2 AS colo,
+ *        quantileWeighted(0.5)(double1, _sample_interval) AS p50,
+ *        quantileWeighted(0.9)(double1, _sample_interval) AS p90,
+ *        sum(_sample_interval) AS n
+ * FROM your_dataset WHERE timestamp > now() - INTERVAL '7' DAY
+ * GROUP BY path, colo ORDER BY n DESC
+ * ```
+ */
+export function perfLog(options = {}) {
+    const { console: toConsole, dataset, sampleRate = 1 } = options;
+    const rate = Math.min(1, Math.max(0, sampleRate)); // clamp so out-of-range values can't invert sampling
+    return async (c, next) => {
+        const cold = !isolateWarm;
+        isolateWarm = true;
+        const start = Date.now();
+        await next();
+        const tApp = Date.now() - start;
+        // Resolve sinks. Both are independently overridable: an explicit option wins, otherwise fall back
+        // to bindings on `c.env` (populated when the app is served with `app.fetch(req, env, ctx)`), so a
+        // bare `perfLog()` still works. `PERF` = Analytics Engine dataset binding; `PERF_LOG === '1'` turns
+        // on Workers Logs. `console: false` explicitly disables Workers Logs even when `PERF_LOG` is set.
+        const envBindings = c.env;
+        const sink = dataset ?? envBindings?.PERF;
+        const emitConsole = toConsole !== undefined ? toConsole : envBindings?.PERF_LOG === '1';
+        if (!sink && !emitConsole) {
+            return;
+        }
+        // Matched route pattern keeps cardinality low (`/user/:id`, not `/user/4821`). Use the deprecated
+        // `c.req.routePath` (not `routePath(c)` from `hono/route`) so the middleware works across the whole
+        // `hono` peer range `^4.6.0` — `hono/route` only exists on newer hono and would break the floor.
+        // Unmatched requests (404 / bot scans) collapse to a single label so they cannot explode cardinality.
+        // eslint-disable-next-line @typescript-eslint/no-deprecated -- routePath(c) needs hono ≥4.8; peer floor is 4.6
+        const matched = c.req.routePath;
+        const path = matched && matched !== '/*' ? matched : '(unmatched)';
+        const colo = c.req.raw.cf?.colo ?? '-';
+        const method = c.req.method;
+        const status = c.res.status;
+        // In-code sampling thins Analytics Engine writes only; Workers Logs volume is controlled separately
+        // by the observability `head_sampling_rate`. Low-traffic Workers should leave `sampleRate` at 1.
+        if (sink && (rate >= 1 || Math.random() < rate)) {
+            sink.writeDataPoint({
+                doubles: [tApp, cold ? 1 : 0, status],
+                blobs: [path, colo, method],
+                indexes: [path],
+            });
+        }
+        if (emitConsole) {
+            console.log(JSON.stringify({ perf: { cold, colo, method, path, status, t_app: tApp } }));
+        }
+    };
+}

package/dist/testing/index.d.ts

@@ -13,3 +13,5 @@ export type { Database, DisposableDatabase, QueryRunner, TxOf } from '../db/data
 export { authHeaders, registerFirebaseToken, provisionUser } from './auth.js';
 export { configurableFake } from './configurable-fake.js';
 export { fakeApiList, fakePaymentIntent, fakeStripeEvent, fakeCheckoutSession, fakeCustomer, fakePrice, fakeSubscription, } from './stripe-fixtures.js';
+export { fakeKv, fakeQueue } from './workers-bindings.js';
+export type { FakeQueue } from './workers-bindings.js';

package/dist/testing/index.js

@@ -13,3 +13,5 @@ export { authHeaders, registerFirebaseToken, provisionUser } from './auth.js';
 export { configurableFake } from './configurable-fake.js';
 // Test fixture factories for Stripe objects.
 export { fakeApiList, fakePaymentIntent, fakeStripeEvent, fakeCheckoutSession, fakeCustomer, fakePrice, fakeSubscription, } from './stripe-fixtures.js';
+// In-memory Workers binding fakes (KV / Queues producer).
+export { fakeKv, fakeQueue } from './workers-bindings.js';

package/dist/testing/workers-bindings.d.ts

@@ -0,0 +1,49 @@
+import type { KVNamespace } from '../cache/kv-cache.js';
+import type { QueueLike } from '../queue/send.js';
+/**
+ * In-memory {@link QueueLike} test double that records every enqueued message.
+ *
+ * @remarks
+ * `sent` collects all message bodies (from both {@link FakeQueue.send} and
+ * {@link FakeQueue.sendBatch}). `batchCount` increments once per `sendBatch` call so tests can
+ * assert producers bound subrequests to `ceil(N / chunkSize)` rather than `N`.
+ *
+ * @typeParam Body - Message body type.
+ */
+export interface FakeQueue<Body = unknown> extends QueueLike<Body> {
+    /** Every body passed to `send` or `sendBatch`, in enqueue order. */
+    readonly sent: Body[];
+    /** Number of `sendBatch` calls issued. */
+    readonly batchCount: number;
+    /**
+     * Enqueue a single message (one subrequest in production).
+     *
+     * @param body - Message payload.
+     */
+    send(body: Body): Promise<void>;
+}
+/**
+ * Create an in-memory {@link FakeQueue} for offline producer tests.
+ *
+ * @typeParam Body - Message body type.
+ * @returns A queue double assignable to `QueueLike` / Workers `Queue` bindings in tests.
+ * @example
+ * ```ts
+ * const queue = fakeQueue<{ userId: number }>();
+ * await sendInChunks(queue, [1, 2, 3]);
+ * expect(queue.batchCount).toBe(1);
+ * expect(queue.sent).toEqual([1, 2, 3]);
+ * ```
+ */
+export declare function fakeQueue<Body = unknown>(): FakeQueue<Body>;
+/**
+ * Create a minimal in-memory {@link KVNamespace} for offline tests (`KVCache`, env fixtures, etc.).
+ *
+ * @remarks
+ * Only `get` / `put` / `delete` are fully implemented (the subset {@link KVCache} uses). `list` and
+ * `getWithMetadata` return empty/null stubs so the object is structurally assignable to Workers
+ * `KVNamespace` when tests need a binding-shaped fake env.
+ *
+ * @returns An in-memory KV double.
+ */
+export declare function fakeKv(): KVNamespace;

package/dist/testing/workers-bindings.js

@@ -0,0 +1,62 @@
+/**
+ * Create an in-memory {@link FakeQueue} for offline producer tests.
+ *
+ * @typeParam Body - Message body type.
+ * @returns A queue double assignable to `QueueLike` / Workers `Queue` bindings in tests.
+ * @example
+ * ```ts
+ * const queue = fakeQueue<{ userId: number }>();
+ * await sendInChunks(queue, [1, 2, 3]);
+ * expect(queue.batchCount).toBe(1);
+ * expect(queue.sent).toEqual([1, 2, 3]);
+ * ```
+ */
+export function fakeQueue() {
+    const sent = [];
+    let batchCount = 0;
+    return {
+        get sent() {
+            return sent;
+        },
+        get batchCount() {
+            return batchCount;
+        },
+        send(body) {
+            sent.push(body);
+            return Promise.resolve();
+        },
+        sendBatch(messages) {
+            batchCount++;
+            for (const m of messages) {
+                sent.push(m.body);
+            }
+            return Promise.resolve();
+        },
+    };
+}
+/**
+ * Create a minimal in-memory {@link KVNamespace} for offline tests (`KVCache`, env fixtures, etc.).
+ *
+ * @remarks
+ * Only `get` / `put` / `delete` are fully implemented (the subset {@link KVCache} uses). `list` and
+ * `getWithMetadata` return empty/null stubs so the object is structurally assignable to Workers
+ * `KVNamespace` when tests need a binding-shaped fake env.
+ *
+ * @returns An in-memory KV double.
+ */
+export function fakeKv() {
+    const store = new Map();
+    return {
+        get: (key) => Promise.resolve(store.get(key) ?? null),
+        put: (key, value) => {
+            store.set(key, value);
+            return Promise.resolve();
+        },
+        delete: (key) => {
+            store.delete(key);
+            return Promise.resolve();
+        },
+        list: () => Promise.resolve({ keys: [], list_complete: true, cacheStatus: null }),
+        getWithMetadata: () => Promise.resolve({ value: null, metadata: null, cacheStatus: null }),
+    };
+}

package/package.json

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

package/scripts/db-baseline.mjs

@@ -2,14 +2,15 @@
 // Record the Drizzle baseline (0000) as *already applied* on an existing (brownfield) MySQL DB,
 // without executing its CREATE TABLE statements. One-time per environment.
 //
-// なぜ: 現行サービスの DB は先にスキーマが在るため、introspect 由来の baseline 0000 を `db:migrate`
-// で流すと衝突する。代わりに `__drizzle_migrations` に marker を 1 行入れ、以後 `db:migrate` が when の
-// 大きい 0001+ だけを適用するようにする（新規/テスト DB は marker 無しでフルチェーン＝挙動不変）。
+// Why: an in-production DB already has its schema, so running the introspect-derived baseline 0000 via
+// `db:migrate` collides. Instead we insert a single marker row into `__drizzle_migrations` so that
+// subsequent `db:migrate` runs apply only the later 0001+ (larger `when`). A fresh / test DB has no
+// marker, so the full chain runs (behavior unchanged).
 //
-// 実行基盤: VPC 内（AWS CodeBuild 等）から RDS へ直 TCP。Hyperdrive は Workers 専用で使えない。
-// creds は env（CodeBuild では Secrets Manager → env に注入）:
+// Where it runs: direct TCP from inside a VPC (e.g. AWS CodeBuild) to RDS. Hyperdrive is Workers-only
+// and cannot be used here. Credentials come from env (on CodeBuild, Secrets Manager → injected into env):
 //   DB_HOST / DB_PORT / DB_USER / DB_PASSWORD / DB_NAME
-// migrations フォルダ: 既定 ./drizzle（--migrations <dir> または MIGRATIONS_DIR で上書き）。
+// Migrations folder: defaults to ./drizzle (override with --migrations <dir> or MIGRATIONS_DIR).
 //
 // usage:
 //   npx workers-hono-kit-db-baseline [--migrations ./drizzle]
@@ -23,9 +24,9 @@ function arg(name) {
 }
 
 const migrationsFolder = arg('migrations') ?? process.env.MIGRATIONS_DIR ?? './drizzle';
-// db:migrate（honoDrizzleConfig）と同じ DB_SECRET 解釈を共有する。CI/本番は AWS Secrets Manager の
-// RDS マネージド secret を DB_SECRET に渡す運用（不正/欠損は resolveDbSecret が throw）。未設定時は
-// 従来の個別 DB_* env にフォールバック。
+// Shares the same DB_SECRET handling as db:migrate (honoDrizzleConfig). CI/production passes an AWS
+// Secrets Manager RDS managed secret via DB_SECRET (invalid/missing → resolveDbSecret throws). When
+// unset, it falls back to the individual DB_* env vars.
 const secret = resolveDbSecret();
 const conn = secret
   ? {