@rdlabo/workers-hono-kit 0.1.0

package/dist/testing/stripe-fixtures.js

@@ -0,0 +1,76 @@
+/**
+ * Stripe オブジェクトの test fixture factory。実 SDK 型は巨大なので、テストが参照する範囲だけを
+ * 妥当な既定値で組み、`over` で上書きする（最後に 1 度だけ Stripe 型へキャスト）。fleet 各 repo の
+ * 課金テストで同じダミー PaymentIntent/Event/... を手組みしていた重複を集約する。
+ */
+export function fakeApiList(data, over = {}) {
+    return {
+        object: 'list',
+        data,
+        has_more: false,
+        url: '/v1/_test',
+        ...over,
+    };
+}
+export function fakePaymentIntent(over = {}) {
+    return {
+        id: 'pi_test_1',
+        object: 'payment_intent',
+        amount: 1000,
+        currency: 'jpy',
+        status: 'succeeded',
+        created: 1_700_000_000,
+        ...over,
+    };
+}
+export function fakeStripeEvent(type, dataObject, over = {}) {
+    return {
+        id: 'evt_test_1',
+        object: 'event',
+        api_version: '2024-06-20',
+        created: 1_700_000_000,
+        livemode: false,
+        type,
+        data: { object: dataObject },
+        ...over,
+    };
+}
+export function fakeCheckoutSession(over = {}) {
+    return {
+        id: 'cs_test_1',
+        object: 'checkout.session',
+        url: 'https://checkout.stripe.test/cs_test_1',
+        mode: 'subscription',
+        status: 'open',
+        ...over,
+    };
+}
+export function fakeCustomer(over = {}) {
+    return {
+        id: 'cus_test_1',
+        object: 'customer',
+        created: 1_700_000_000,
+        livemode: false,
+        ...over,
+    };
+}
+export function fakePrice(over = {}) {
+    return {
+        id: 'price_test_1',
+        object: 'price',
+        active: true,
+        currency: 'jpy',
+        unit_amount: 1000,
+        ...over,
+    };
+}
+export function fakeSubscription(over = {}) {
+    return {
+        id: 'sub_test_1',
+        object: 'subscription',
+        status: 'active',
+        customer: 'cus_test_1',
+        created: 1_700_000_000,
+        ...over,
+    };
+}

package/package.json

@@ -0,0 +1,113 @@
+{
+  "name": "@rdlabo/workers-hono-kit",
+  "version": "0.1.0",
+  "private": false,
+  "publishConfig": {
+    "access": "public"
+  },
+  "type": "module",
+  "description": "Infrastructure toolkit for building APIs on Hono + Cloudflare Workers: Firebase ID-token verification (jose), AWS Secrets Manager (aws4fetch), ETag/validation/zod-coerce middleware, deadlock retry, and shared HTTP helpers.",
+  "author": "Masahiko Sakakibara<sakakibara@rdlabo.jp>",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/rdlabo-team/workers-hono-kit.git"
+  },
+  "bugs": {
+    "url": "https://github.com/rdlabo-team/workers-hono-kit/issues"
+  },
+  "homepage": "https://github.com/rdlabo-team/workers-hono-kit#readme",
+  "keywords": [
+    "hono",
+    "cloudflare-workers",
+    "workers",
+    "edge",
+    "firebase",
+    "jose",
+    "aws-secrets-manager",
+    "middleware",
+    "etag",
+    "zod",
+    "nestjs"
+  ],
+  "engines": {
+    "node": ">=20.0.0"
+  },
+  "files": [
+    "dist",
+    "src",
+    "scripts",
+    "!src/**/*.spec.ts"
+  ],
+  "bin": {
+    "workers-hono-kit-sync-dev-aws": "./scripts/sync-dev-aws.mjs"
+  },
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "default": "./dist/index.js"
+    },
+    "./db": {
+      "types": "./dist/db/index.d.ts",
+      "import": "./dist/db/index.js",
+      "default": "./dist/db/index.js"
+    },
+    "./testing": {
+      "types": "./dist/testing/index.d.ts",
+      "import": "./dist/testing/index.js",
+      "default": "./dist/testing/index.js"
+    }
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.build.json",
+    "prepare": "npm run build",
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "lint": "eslint \"src/**/*.ts\"",
+    "lint:fix": "eslint \"src/**/*.ts\" --fix",
+    "format": "prettier --write \"src/**/*.ts\"",
+    "format:check": "prettier --check \"src/**/*.ts\""
+  },
+  "peerDependencies": {
+    "@hono/zod-validator": "^0.8.0",
+    "ai": "^6.0.0",
+    "ai-gateway-provider": "^3.1.0",
+    "aws4fetch": "^1.0.20",
+    "drizzle-orm": "^0.45.2",
+    "hono": "^4.6.0",
+    "jose": "^6.2.0",
+    "mysql2": "^3.14.0",
+    "stripe": ">=15",
+    "zod": "^4.4.0"
+  },
+  "peerDependenciesMeta": {
+    "ai": { "optional": true },
+    "ai-gateway-provider": { "optional": true },
+    "stripe": { "optional": true },
+    "drizzle-orm": { "optional": true },
+    "mysql2": { "optional": true }
+  },
+  "devDependencies": {
+    "@ai-sdk/anthropic": "^3.0.84",
+    "@ai-sdk/openai": "^3.0.71",
+    "@hono/eslint-config": "^2.1.0",
+    "@hono/zod-validator": "^0.8.0",
+    "@types/node": "^22.19.21",
+    "ai": "^6.0.204",
+    "ai-gateway-provider": "^3.1.3",
+    "aws4fetch": "^1.0.20",
+    "drizzle-orm": "0.45.2",
+    "eslint": "^9.39.4",
+    "hono": "^4.6.0",
+    "jose": "^6.2.3",
+    "mysql2": "3.22.5",
+    "prettier": "^3.8.4",
+    "stripe": "^20.4.1",
+    "typescript": "~5.6.2",
+    "typescript-eslint": "^8.61.1",
+    "vitest": "^2.1.0",
+    "zod": "^4.4.3"
+  }
+}

package/scripts/sync-dev-aws.mjs

@@ -0,0 +1,59 @@
+#!/usr/bin/env node
+// Launch `wrangler` with AWS credentials injected as --var, resolved from the active
+// AWS profile. Nothing is written to disk (no .dev.vars).
+//
+// Cloudflare Workers has no AWS SDK default-credential chain, so the Worker reads
+// env.AWS_* at runtime. This resolves them via `aws configure export-credentials`
+// (which honors AWS_PROFILE) and passes them as `--var KEY:VALUE` bindings on the
+// wrangler argv — in-memory only, supporting short-lived SSO/temporary creds
+// (incl. AWS_SESSION_TOKEN). Re-resolved on every launch, so creds stay fresh.
+//
+// All args after the script are forwarded to `wrangler` verbatim; the AWS --var flags
+// are appended. Wire it as the `dev` npm script (it spawns wrangler itself, so it
+// replaces both the old `predev` file-sync and the `wrangler dev` invocation):
+//   AWS_PROFILE=<profile> node node_modules/@rdlabo/workers-hono-kit/scripts/sync-dev-aws.mjs dev --var APP_ENV:development
+//
+// Trade-off vs .dev.vars: creds appear in the wrangler process args (visible to other
+// users via `ps` on a shared host). Fine for a personal dev machine; nothing on disk.
+// Exits non-zero if the profile can't be resolved, so the dev server never starts blind.
+import { spawnSync } from 'node:child_process';
+
+const CRED_KEYS = ['AWS_ACCESS_KEY_ID', 'AWS_SECRET_ACCESS_KEY', 'AWS_SESSION_TOKEN'];
+const profile = process.env.AWS_PROFILE ?? '(default)';
+
+const forwarded = process.argv.slice(2);
+if (forwarded.length === 0) {
+  console.error('[dev-aws] usage: node sync-dev-aws.mjs <wrangler-args...>  (e.g. dev --var APP_ENV:development)');
+  process.exit(1);
+}
+
+const cred = spawnSync('aws', ['configure', 'export-credentials', '--format', 'env-no-export'], { encoding: 'utf8' });
+if (cred.status !== 0) {
+  console.error(`[dev-aws] could not export credentials for AWS_PROFILE=${profile}.`);
+  console.error('[dev-aws] check the AWS CLI is installed and the profile is valid (e.g. aws sso login).');
+  process.exit(1);
+}
+
+// "KEY=VALUE" -> ["--var", "KEY:VALUE"]. AWS values are base64 (A-Za-z0-9+/=) and contain
+// no ':', so wrangler's split-on-first-':' is safe. Split each line on its first '=' only.
+const credVars = (cred.stdout ?? '')
+  .split('\n')
+  .filter((line) => CRED_KEYS.some((k) => line.startsWith(`${k}=`)))
+  .flatMap((line) => {
+    const eq = line.indexOf('=');
+    return ['--var', `${line.slice(0, eq)}:${line.slice(eq + 1)}`];
+  });
+
+if (credVars.length === 0) {
+  console.error('[dev-aws] no AWS credentials were returned; aborting.');
+  process.exit(1);
+}
+
+// Run the repo-local wrangler regardless of how this script was invoked.
+const binDir = `${process.cwd()}/node_modules/.bin`;
+console.log(`[dev-aws] wrangler ${forwarded.join(' ')} (+${credVars.length / 2} AWS --var, AWS_PROFILE=${profile})`);
+const run = spawnSync('wrangler', [...forwarded, ...credVars], {
+  stdio: 'inherit',
+  env: { ...process.env, PATH: `${binDir}:${process.env.PATH ?? ''}` },
+});
+process.exit(run.status ?? 1);

package/src/ai/gateway.ts

@@ -0,0 +1,81 @@
+/**
+ * Cloudflare AI Gateway のプロバイダ生成（`ai` SDK + `ai-gateway-provider`）。
+ * フリート共通 = foodlabel / winecode / receptray hono の AI 呼び出しを必ず Gateway 経由にする。
+ *
+ * `createAiGateway` が返す wrapper で `@ai-sdk/*` のモデルを包むと、SDK が組み立てた
+ * プロバイダ宛リクエスト（api.openai.com / api.anthropic.com / *-aiplatform.googleapis.com 等）を
+ * AI Gateway の Universal Endpoint 経由に差し替える。OpenAI / Anthropic / Google Vertex(SA) の
+ * いずれも同じ `aigateway(model)` で透過的にルーティングされる（Vertex も対応）。
+ *
+ * ここはインフラ層（Gateway 識別子と認証トークンの注入だけ）。プロバイダの API キーや
+ * Vertex の SA 認証情報は各 repo 側でモデル生成時に渡す（pass-through）。
+ */
+import { createAiGateway } from 'ai-gateway-provider';
+import type { AiGateway, AiGatewayBindingSettings, AiGatewayOptions } from 'ai-gateway-provider';
+
+export type { AiGateway, AiGatewayOptions } from 'ai-gateway-provider';
+
+/** Workers の AI binding（`env.AI.gateway(name)`）の最小形。Cloudflare の `AiGateway` が構造的に適合する。 */
+export type AiGatewayBinding = AiGatewayBindingSettings['binding'];
+
+/**
+ * AI Gateway 設定。2 系統:
+ *  - binding 形: Workers ランタイム（本番 / `wrangler dev`）。`env.AI.gateway(name)` を渡す。
+ *    binding 経由は同一アカウント内で事前認証されるため Gateway トークン不要。
+ *  - REST 形: Workers 外（Node の eval ハーネス等、binding 不可）。accountId + gateway + token で REST。
+ */
+export type AiGatewayConfig =
+  | {
+      /** `env.AI.gateway(name)` 等の AI Gateway binding。 */
+      binding: AiGatewayBinding;
+      /** キャッシュ / リトライ / メタデータ等の Gateway オプション（任意）。 */
+      options?: AiGatewayOptions;
+    }
+  | {
+      /** Cloudflare アカウント ID。 */
+      accountId: string;
+      /** AI Gateway 名。 */
+      gateway: string;
+      /**
+       * `cf-aig-authorization` に載せる Gateway 認証トークン。Authenticated Gateway のときだけ必要。
+       * unauthenticated Gateway では省略可（プロバイダの API キーではなく Gateway 自体への認証）。
+       */
+      token?: string;
+      /** キャッシュ / リトライ / メタデータ等の Gateway オプション（任意）。 */
+      options?: AiGatewayOptions;
+    };
+
+export interface AiGatewayProvider {
+  /**
+   * `@ai-sdk/*` のモデルを包んで AI Gateway 経由にする。
+   * 例: `aigateway(createAnthropic({ apiKey }).('claude-...'))`。
+   * 配列を渡すとフォールバック（先頭から順に試行）になる。
+   */
+  aigateway: AiGateway;
+}
+
+/**
+ * AI Gateway 用のプロバイダを生成する。binding 形 / REST 形のどちらでも可（欠落時は fail-fast）。
+ */
+export function createAiGatewayProvider(config: AiGatewayConfig): AiGatewayProvider {
+  if ('binding' in config) {
+    return { aigateway: createAiGateway({ binding: config.binding, options: config.options }) };
+  }
+
+  if (!config.accountId) {
+    throw new Error('AI Gateway: accountId が未設定です');
+  }
+  if (!config.gateway) {
+    throw new Error('AI Gateway: gateway 名が未設定です');
+  }
+
+  // token は Authenticated Gateway のときだけ apiKey として送る。unauthenticated では undefined で可。
+  return {
+    aigateway: createAiGateway({
+      accountId: config.accountId,
+      gateway: config.gateway,
+      apiKey: config.token,
+      options: config.options,
+    }),
+  };
+}

package/src/aws/cloudfront.ts

@@ -0,0 +1,65 @@
+/**
+ * CloudFront 署名付き URL 生成（`@aws-sdk/cloudfront-signer` の getSignedUrl を Web Crypto で再実装）。
+ * Cloudflare Workers ネイティブ（aws-sdk 不要）。フリート共通 = tipsys/winecode hono。
+ *
+ * canned policy を RSASSA-PKCS1-v1_5 + SHA-1 で署名し、AWS の URL-safe base64 変換
+ *   '+' -> '-' , '/' -> '~' , '=' -> '_'
+ * を施して `Expires` / `Key-Pair-Id` / `Signature` の順でクエリを付与する（aws-sdk の出力とバイト一致）。
+ */
+export async function getCloudFrontSignedUrl(
+  url: string,
+  privateKeyPem: string,
+  keyPairId: string,
+  dateLessThan: string | number | Date,
+): Promise<string> {
+  const epochSeconds = Math.round(new Date(dateLessThan).getTime() / 1000);
+
+  const policy = JSON.stringify({
+    Statement: [{ Resource: url, Condition: { DateLessThan: { 'AWS:EpochTime': epochSeconds } } }],
+  });
+
+  const key = await crypto.subtle.importKey(
+    'pkcs8',
+    pemToDer(privateKeyPem),
+    { name: 'RSASSA-PKCS1-v1_5', hash: 'SHA-1' },
+    false,
+    ['sign'],
+  );
+  const signatureBuffer = await crypto.subtle.sign(
+    { name: 'RSASSA-PKCS1-v1_5' },
+    key,
+    new TextEncoder().encode(policy),
+  );
+
+  const signature = toUrlSafeBase64(arrayBufferToBase64(signatureBuffer));
+  const separator = url.includes('?') ? '&' : '?';
+
+  // @aws-sdk/cloudfront-signer のクエリ順: Expires -> Key-Pair-Id -> Signature
+  return `${url}${separator}Expires=${epochSeconds}&Key-Pair-Id=${keyPairId}&Signature=${signature}`;
+}
+
+function toUrlSafeBase64(value: string): string {
+  return value.replace(/\+/g, '-').replace(/=/g, '_').replace(/\//g, '~');
+}
+
+function arrayBufferToBase64(buffer: ArrayBuffer): string {
+  const bytes = new Uint8Array(buffer);
+  let binary = '';
+  for (const b of bytes) {
+    binary += String.fromCharCode(b);
+  }
+  return btoa(binary);
+}
+
+function pemToDer(pem: string): ArrayBuffer {
+  const base64 = pem
+    .replace(/-----BEGIN [^-]+-----/, '')
+    .replace(/-----END [^-]+-----/, '')
+    .replace(/\s+/g, '');
+  const binary = atob(base64);
+  const bytes = new Uint8Array(binary.length);
+  for (let i = 0; i < binary.length; i++) {
+    bytes[i] = binary.charCodeAt(i);
+  }
+  return bytes.buffer;
+}

package/src/aws/secrets-manager.ts

@@ -0,0 +1,63 @@
+import { AwsClient } from 'aws4fetch';
+
+/**
+ * AWS Secrets Manager の GetSecretValue を aws4fetch（SigV4 署名 fetch）で叩く汎用ヘルパ。
+ * Cloudflare Workers には AWS SDK も IAM ロールも無いため、AWS の静的キーを Workers secrets として
+ * 渡して署名する（移植元 `api/src/secrets-manager.ts` 相当）。DB 認証情報は Hyperdrive 側に持つので対象外。
+ *
+ * Secret の中身（スキーマ）と secretId は repo ごとに異なるため、`<T>` と `secretId` を呼び出し側が渡す。
+ */
+export interface AwsSecretsOptions {
+  accessKeyId: string;
+  secretAccessKey: string;
+  sessionToken?: string;
+  region: string;
+}
+
+/**
+ * Per-isolate cache: Secrets Manager は isolate ごと 1 回だけ叩く。region+accessKeyId+secretId を
+ * キーにし、資格情報ローテーション時は再取得する。promise をキャッシュして同時初回リクエストが 1 回の
+ * 呼び出しを共有する。reject 時はキャッシュをクリアして retry を許す。
+ */
+let cache: { key: string; value: Promise<unknown> } | null = null;
+
+export function getAuthenticationSecret<T>(options: AwsSecretsOptions, secretId: string): Promise<T> {
+  const key = `${options.region}:${options.accessKeyId}:${secretId}`;
+  if (cache?.key !== key) {
+    const value = fetchSecret(options, secretId).catch((error: unknown) => {
+      cache = null;
+      throw error;
+    });
+    cache = { key, value };
+  }
+  return cache.value as Promise<T>;
+}
+
+async function fetchSecret(options: AwsSecretsOptions, secretId: string): Promise<unknown> {
+  const aws = new AwsClient({
+    accessKeyId: options.accessKeyId,
+    secretAccessKey: options.secretAccessKey,
+    sessionToken: options.sessionToken,
+    service: 'secretsmanager',
+    region: options.region,
+  });
+
+  const response = await aws.fetch(`https://secretsmanager.${options.region}.amazonaws.com/`, {
+    method: 'POST',
+    headers: {
+      'Content-Type': 'application/x-amz-json-1.1',
+      'X-Amz-Target': 'secretsmanager.GetSecretValue',
+    },
+    body: JSON.stringify({ SecretId: secretId, VersionStage: 'AWSCURRENT' }),
+  });
+
+  if (!response.ok) {
+    throw new Error(`Secrets Manager GetSecretValue failed: ${response.status} ${await response.text()}`);
+  }
+
+  const body = (await response.json()) as { SecretString?: string };
+  if (!body.SecretString) {
+    throw new Error('Secrets Manager GetSecretValue returned no SecretString');
+  }
+  return JSON.parse(body.SecretString);
+}

package/src/cache/kv-cache.ts

@@ -0,0 +1,134 @@
+/**
+ * Workers KV を使った cache-aside キャッシュ（フリート共通 = winecode/tipsys hono の CacheService）。
+ * 同一 DB を参照する透過キャッシュなので `/api` とレスポンスは一致する（perf 層であり parity に影響しない）。
+ *
+ * キー構成は各 repo の `/api`（旧 Valkey）と一致させる:
+ *   `${appName}${version}${table}_${type}_${column}`  （column: id が string なら sha256hex、number はそのまま）
+ * KV の expirationTtl は 60s 下限のため lifetime を 60 でクランプする。
+ */
+
+/** @cloudflare/workers-types の KVNamespace 最小サブセット（get/put/delete のみ使用）。 */
+export interface KVNamespace {
+  get(key: string): Promise<string | null>;
+  put(key: string, value: string, options?: { expirationTtl?: number }): Promise<void>;
+  delete(key: string): Promise<void>;
+}
+
+export interface KVCacheOptions {
+  /** キー前置（repo 名）。例 `'winecode'` / `'tipsys'`。 */
+  appName: string;
+  /** バージョン前置。既定 `'v8_'`。 */
+  version?: string;
+  /** lifetime の下限秒（KV の最小 TTL）。既定 `60`。 */
+  minTtlSeconds?: number;
+  /** lifetime 未指定時の既定秒。既定 `600`。 */
+  defaultLifetime?: number;
+}
+
+interface CacheSetItem {
+  table: string;
+  type: string | number;
+  id: string | number;
+  data: unknown;
+  lifetime?: number;
+}
+
+interface CacheKeyItem {
+  table: string;
+  type: string | number;
+  id: string | number;
+}
+
+const encoder = new TextEncoder();
+
+async function sha256Hex(input: string): Promise<string> {
+  const digest = await crypto.subtle.digest('SHA-256', encoder.encode(input));
+  return [...new Uint8Array(digest)].map((b) => b.toString(16).padStart(2, '0')).join('');
+}
+
+export class KVCache {
+  readonly #kv: KVNamespace;
+  readonly #appName: string;
+  readonly #version: string;
+  readonly #minTtl: number;
+  readonly #defaultLifetime: number;
+
+  constructor(kv: KVNamespace, options: KVCacheOptions) {
+    this.#kv = kv;
+    this.#appName = options.appName;
+    this.#version = options.version ?? 'v8_';
+    this.#minTtl = options.minTtlSeconds ?? 60;
+    this.#defaultLifetime = options.defaultLifetime ?? 600;
+  }
+
+  async #buildKey(table: string, type: string | number, id: string | number): Promise<string | undefined> {
+    const column = typeof id === 'string' ? await sha256Hex(id) : id;
+    const key = `${this.#appName}${this.#version}${table}_${type}_${column}`;
+    // KV のキーは 512〜1024 バイト上限。超えるものはキャッシュ対象外（cache-aside なので DB 直読みに落ちる）。
+    if (encoder.encode(key).byteLength > 1024) {
+      return undefined;
+    }
+    return key;
+  }
+
+  async get<T>(table: string, type: string | number, id: string | number): Promise<T | undefined> {
+    const key = await this.#buildKey(table, type, id);
+    if (!key) {
+      return undefined;
+    }
+    try {
+      const data = await this.#kv.get(key);
+      if (!data) {
+        return undefined;
+      }
+      return JSON.parse(data) as T;
+    } catch {
+      return undefined;
+    }
+  }
+
+  async set(
+    table: string,
+    type: string | number,
+    id: string | number,
+    data: unknown,
+    lifetime?: number,
+  ): Promise<void> {
+    if (!data) {
+      return;
+    }
+    const key = await this.#buildKey(table, type, id);
+    if (!key) {
+      return;
+    }
+    let payload: string;
+    try {
+      payload = JSON.stringify(data);
+    } catch {
+      return;
+    }
+    const ttl = Math.max(this.#minTtl, lifetime ?? this.#defaultLifetime);
+    await this.#kv.put(key, payload, { expirationTtl: ttl }).catch(() => undefined);
+  }
+
+  async setMany(items: CacheSetItem[]): Promise<void> {
+    if (items.length === 0) {
+      return;
+    }
+    await Promise.all(items.map((i) => this.set(i.table, i.type, i.id, i.data, i.lifetime)));
+  }
+
+  // T は呼び出し側が指定する戻り値型（get<T> と同じく ergonomics 目的）。
+  // eslint-disable-next-line @typescript-eslint/no-unnecessary-type-parameters
+  async getMany<T>(items: CacheKeyItem[]): Promise<{ id: string | number; value: T | undefined }[]> {
+    return Promise.all(items.map(async (i) => ({ id: i.id, value: await this.get<T>(i.table, i.type, i.id) })));
+  }
+
+  async delete(table: string, type: string | number, id: string | number): Promise<void> {
+    const key = await this.#buildKey(table, type, id);
+    if (!key) {
+      return;
+    }
+    await this.#kv.delete(key).catch(() => undefined);
+  }
+}

package/src/db/connection.ts

@@ -0,0 +1,73 @@
+import { createConnection } from 'mysql2/promise';
+import type { Connection } from 'mysql2/promise';
+
+/**
+ * Hyperdrive バインディングの最小形（@cloudflare/workers-types への依存を避けるための構造型）。
+ */
+export interface HyperdriveLike {
+  host: string;
+  user: string;
+  password: string;
+  database: string;
+  port: number;
+}
+
+/**
+ * Hyperdrive バインディングから mysql2 の createConnection 用オプションを作る。
+ * `disableEval: true`（Workers で eval 不可）は既定で付与。`extra` で timezone 等を上書き/追加。
+ *
+ * `decimalNumbers: true`: DECIMAL/NEWDECIMAL を文字列でなく JS number で返す。Drizzle の
+ * `$inferSelect`（decimal→string）と生 SQL reads の戻り値を、各 repo の数値ドメイン型
+ * （nutrition の number 等）に揃えるため既定で有効化。precision/scale が JS の安全整数域
+ * （decimal(15,2) 程度まで）を超える列が無いことが前提。
+ *
+ * `timezone: '+09:00'`: フリートの接続先 RDB は session time_zone=Asia/Tokyo。mysql2 の driver
+ * `timezone` 既定は `'local'`＝Workers では UTC で、揃わないと `datetime/timestamp` の生 Date 読みが
+ * +9h・生 Date 書きが −9h ズレる（NestJS は JST 実行で一致＝移植で顕在化する潜在バグ）。driver を
+ * 固定すれば round-trip の観測値は DB の session tz に非依存（内部格納 UTC 値だけ変わるが app 不可視）。
+ * 非 JST repo は `extra: { timezone: '...' }` で上書き可。
+ */
+export function hyperdriveConnectionOptions(
+  hyperdrive: HyperdriveLike,
+  extra?: Record<string, unknown>,
+): Record<string, unknown> {
+  return {
+    host: hyperdrive.host,
+    user: hyperdrive.user,
+    password: hyperdrive.password,
+    database: hyperdrive.database,
+    port: hyperdrive.port,
+    disableEval: true,
+    decimalNumbers: true,
+    timezone: '+09:00',
+    ...extra,
+  };
+}
+
+export interface ExecutionContextLike {
+  waitUntil(promise: Promise<unknown>): void;
+}
+
+/**
+ * primary/replica の接続を開いて `fn` を実行し、finally で `ctx.waitUntil` 越しに閉じる
+ * （receptray/tipsys の worker entry の接続ライフサイクル相当）。
+ */
+export async function withMysqlConnections<T>(
+  hyperdrives: { primary: HyperdriveLike; replica: HyperdriveLike },
+  ctx: ExecutionContextLike,
+  fn: (connections: { primary: Connection; replica: Connection }) => Promise<T>,
+  connectionOptions?: Record<string, unknown>,
+): Promise<T> {
+  let primary: Connection | undefined;
+  let replica: Connection | undefined;
+  try {
+    primary = await createConnection(hyperdriveConnectionOptions(hyperdrives.primary, connectionOptions));
+    replica = await createConnection(hyperdriveConnectionOptions(hyperdrives.replica, connectionOptions));
+    return await fn({ primary, replica });
+  } finally {
+    const closing = [primary, replica].filter((c): c is Connection => c !== undefined).map((c) => c.end());
+    if (closing.length > 0) {
+      ctx.waitUntil(Promise.allSettled(closing));
+    }
+  }
+}