@rdlabo/workers-hono-kit 0.4.2 → 0.5.0

package/dist/http/query-failed-error.d.ts

@@ -0,0 +1,29 @@
+import type { Context, Env } from 'hono';
+import type { ErrorReporter, NestErrorHandlerOptions } from './nest-error.js';
+/** Nest QueryFailedExceptionFilter が返す `{ statusCode, message }` 形（error フィールド無し）。 */
+export interface ClassifiedDbError {
+    statusCode: 400 | 500;
+    message: string;
+}
+/** mysql2 / Drizzle 由来の DB エラーを HTTP 応答用に分類する。非 DB エラーは null。 */
+export type QueryFailedClassifier = (err: unknown) => ClassifiedDbError | null;
+/**
+ * 分類済み DB エラーをログし、500 のみ {@link ErrorReporter} へ通報する。
+ * 400 はビジネスエラー扱い（warn ログのみ、Sentry 不要）。
+ */
+export declare function reportClassifiedDbError(err: unknown, classified: ClassifiedDbError, reportError?: ErrorReporter, requestId?: string): void;
+export interface QueryFailedNestErrorHandlerOptions<E extends Env = Env> extends NestErrorHandlerOptions<E> {
+    /** アプリ固有の分類（parity-critical な日本語メッセージ等は consumer 側で定義）。 */
+    classify: QueryFailedClassifier;
+}
+/**
+ * QueryFailedExceptionFilter → Nest 既定 exception filter の合成 onError。
+ *
+ * @remarks
+ * classify が non-null のときは parity 用 body を返しつつログ（+ 500 は onUnhandledError）を残す。
+ * 非 DB エラーは {@link createNestErrorHandler} に委譲する。
+ *
+ * `Sentry.withSentry` だけでは onError 握りエラーは capture されないため、
+ * `onUnhandledError: (err, c) => container.reportError?.(err, { requestId: c.get('requestId') })` を必ず配線する。
+ */
+export declare function createQueryFailedNestErrorHandler<E extends Env = Env>(options: QueryFailedNestErrorHandlerOptions<E>): (err: Error, c: Context<E>) => Response;

package/dist/http/query-failed-error.js

@@ -0,0 +1,43 @@
+import { logMysqlDriverError } from './mysql-driver-error.js';
+import { createNestErrorHandler } from './nest-error.js';
+/**
+ * 分類済み DB エラーをログし、500 のみ {@link ErrorReporter} へ通報する。
+ * 400 はビジネスエラー扱い（warn ログのみ、Sentry 不要）。
+ */
+export function reportClassifiedDbError(err, classified, reportError, requestId) {
+    logMysqlDriverError(err, classified.statusCode);
+    if (classified.statusCode === 500) {
+        reportError?.(err, { requestId });
+    }
+}
+/**
+ * QueryFailedExceptionFilter → Nest 既定 exception filter の合成 onError。
+ *
+ * @remarks
+ * classify が non-null のときは parity 用 body を返しつつログ（+ 500 は onUnhandledError）を残す。
+ * 非 DB エラーは {@link createNestErrorHandler} に委譲する。
+ *
+ * `Sentry.withSentry` だけでは onError 握りエラーは capture されないため、
+ * `onUnhandledError: (err, c) => container.reportError?.(err, { requestId: c.get('requestId') })` を必ず配線する。
+ */
+export function createQueryFailedNestErrorHandler(options) {
+    const { classify, ...nestOptions } = options;
+    const nestErrorHandler = createNestErrorHandler(nestOptions);
+    const { onUnhandledError } = nestOptions;
+    return (err, c) => {
+        const classified = classify(err);
+        if (classified) {
+            logMysqlDriverError(err, classified.statusCode);
+            if (classified.statusCode === 500) {
+                try {
+                    onUnhandledError?.(err, c);
+                }
+                catch {
+                    // Reporting must never change the error response.
+                }
+            }
+            return c.json({ statusCode: classified.statusCode, message: classified.message }, classified.statusCode);
+        }
+        return nestErrorHandler(err, c);
+    };
+}

package/dist/index.d.ts

@@ -15,6 +15,8 @@ export type { ValidateOptions, ValidationTarget, ZodErrorLike, SentryLike, Sentr
 export { zNum, zNumNullable, zNumOptional, zNumWithDefault } from './middleware/zod-coerce.js';
 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 { getUserProtocol } from './http/user-protocol.js';
 export type { IUserProtocol } from './http/user-protocol.js';
 export { getAppInfo } from './http/app-info.js';
@@ -24,6 +26,10 @@ export type { AppEnv } from './http/app-env.js';
 export { HttpStatus } from './http/http-status.js';
 export { createNestErrorHandler, nestNotFoundHandler, NEST_REASON_PHRASES } from './http/nest-error.js';
 export type { NestErrorHandlerOptions, ErrorReportContext, ErrorReporter } from './http/nest-error.js';
+export { findMysqlDriverError, logMysqlDriverError } from './http/mysql-driver-error.js';
+export type { MysqlDriverErrorLike } from './http/mysql-driver-error.js';
+export { createQueryFailedNestErrorHandler, reportClassifiedDbError, } from './http/query-failed-error.js';
+export type { ClassifiedDbError, QueryFailedClassifier, QueryFailedNestErrorHandlerOptions, } from './http/query-failed-error.js';
 export { normalizeTrailingSlash } from './http/trailing-slash.js';
 export type { ExecutionContextLike } from './http/execution-context.js';
 export { KVCache } from './cache/kv-cache.js';

package/dist/index.js

@@ -14,12 +14,15 @@ export { finalizeResponse } from './middleware/finalize-response.js';
 export { validate, 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';
 // http
 export { getUserProtocol } from './http/user-protocol.js';
 export { getAppInfo } from './http/app-info.js';
 export { resolveAppEnv, isProductionEnv } from './http/app-env.js';
 export { HttpStatus } from './http/http-status.js';
 export { createNestErrorHandler, nestNotFoundHandler, NEST_REASON_PHRASES } from './http/nest-error.js';
+export { findMysqlDriverError, logMysqlDriverError } from './http/mysql-driver-error.js';
+export { createQueryFailedNestErrorHandler, reportClassifiedDbError, } from './http/query-failed-error.js';
 export { normalizeTrailingSlash } from './http/trailing-slash.js';
 // cache
 export { KVCache } from './cache/kv-cache.js';

package/dist/middleware/perf-log.d.ts

@@ -0,0 +1,77 @@
+import type { MiddlewareHandler } from 'hono';
+/**
+ * Minimal shape of a Workers Analytics Engine dataset binding.
+ *
+ * Declared locally so consumers are not forced to depend on `@cloudflare/workers-types`. Only the
+ * single write operation the emitter needs is modeled. A real `AnalyticsEngineDataset` binding is
+ * assignable. Writes are non-blocking and add no latency to the request.
+ *
+ * @see https://developers.cloudflare.com/analytics/analytics-engine/
+ */
+export interface AnalyticsEngineDatasetLike {
+    writeDataPoint(event: {
+        doubles?: number[];
+        blobs?: (string | null)[];
+        indexes?: string[];
+    }): void;
+}
+/** Options for {@link perfLog}. Both sinks are optional; enable either or both. */
+export interface PerfLogOptions {
+    /**
+     * When `true`, emit one `console.log(JSON.stringify({ perf }))` per request. With
+     * `[observability] enabled = true` these lines are captured by **Workers Logs** (retained up to
+     * 7 days, queryable via the dashboard Query Builder or the Observability REST API) — no live
+     * `wrangler tail` needed, which is what makes this practical for low-traffic Workers.
+     *
+     * Explicit wins over the `PERF_LOG` env fallback in both directions: `true` forces on, `false` forces
+     * off (even when `PERF_LOG === '1'`), `undefined` (default) defers to `PERF_LOG`.
+     */
+    console?: boolean;
+    /**
+     * When provided, write one data point per request to a **Workers Analytics Engine** dataset. Query
+     * percentiles by route/colo with the SQL API (≈90-day retention). Non-blocking. Layout:
+     * `doubles = [t_app_ms, cold(0|1), status]`, `blobs = [path, colo, method]`, `indexes = [path]`.
+     */
+    dataset?: AnalyticsEngineDatasetLike;
+    /**
+     * In-code sampling in `[0, 1]` (default `1` = every request; values are clamped to the range).
+     * Thins **Analytics Engine writes only** — Workers Logs volume is controlled separately by the
+     * observability `head_sampling_rate`. Low-traffic Workers should leave it at `1`.
+     */
+    sampleRate?: number;
+}
+/**
+ * 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 declare function perfLog(options?: PerfLogOptions): MiddlewareHandler;

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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rdlabo/workers-hono-kit",
-  "version": "0.4.2",
+  "version": "0.5.0",
   "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
   ? {