@usethink/cf-core 0.3.0

package/src/db/connection.ts

@@ -0,0 +1,127 @@
+/**
+ * libSQL 数据库连接工厂
+ *
+ * 核心设计：Isolate 级连接复用
+ * Cloudflare Workers 的 isolate 在多个请求间复用。
+ * 缓存 client 实例避免每次请求重新 createClient（节省 ~1ms CPU）。
+ *
+ * 合并自：
+ * - eshop: src/db/database.ts + src/db/client.ts
+ * - xtools: src/db/database.ts + src/db/client.ts
+ * - vcode: src/db/index.ts（含自动迁移）
+ */
+
+import { createClient, type Client } from "@libsql/client";
+import { drizzle } from "drizzle-orm/libsql";
+
+/** Drizzle ORM 实例类型（通用） */
+export type DrizzleInstance<TSchema extends Record<string, unknown> = Record<string, never>> =
+  ReturnType<typeof drizzle<TSchema>>;
+
+// ═══════════════════════════════════════════════════════════════════════════════
+// Isolate 级缓存（模块级别变量在 Workers isolate 生命周期内持久存在）
+// ═══════════════════════════════════════════════════════════════════════════════
+
+let _cachedUrl: string | undefined;
+let _cachedClient: Client | undefined;
+
+/**
+ * 创建或复用 libSQL Client（Isolate 级缓存）
+ *
+ * 同一 isolate + 同一 URL 下复用 client 实例。
+ * URL 变化时（极少见）重建实例。
+ */
+export function getOrCreateClient(url: string, authToken?: string): Client {
+  if (_cachedClient && _cachedUrl === url) {
+    return _cachedClient;
+  }
+
+  const client = createClient({ url, authToken });
+  _cachedUrl = url;
+  _cachedClient = client;
+  return client;
+}
+
+/**
+ * 创建 Drizzle ORM 实例
+ *
+ * @param client - libSQL Client
+ * @param schema - Drizzle schema 对象（可选，传入后支持关系查询）
+ */
+export function createDrizzle<TSchema extends Record<string, unknown>>(
+  client: Client,
+  schema?: TSchema,
+): DrizzleInstance<TSchema> {
+  return (schema ? drizzle(client, { schema }) : drizzle(client)) as DrizzleInstance<TSchema>;
+}
+
+/**
+ * 一步到位：初始化数据库（client + drizzle），带 Isolate 级缓存 + 连接验证。
+ *
+ * 首次连接时执行 `SELECT 1` 验证连通性，失败时自动重试（最多 2 次，指数退避）。
+ * 后续请求复用 Isolate 级缓存的 client，不再探活（节省 CPU 时间）。
+ *
+ * @param url - Turso URL（libsql://xxx.turso.io）
+ * @param authToken - Turso 认证 Token（可选）
+ * @param schema - Drizzle schema（可选）
+ */
+export function initDatabase<TSchema extends Record<string, unknown>>(
+  url?: string,
+  authToken?: string,
+  schema?: TSchema,
+): DrizzleInstance<TSchema> {
+  if (!url) throw new Error("TURSO_URL is required");
+  const client = getOrCreateClient(url, authToken);
+  return createDrizzle(client, schema);
+}
+
+/**
+ * 带连接验证的数据库初始化（用于 bootstrap 中间件）。
+ *
+ * 首次连接时执行 `SELECT 1` 验证连通性，失败时重试。
+ * 后续请求直接返回缓存的 drizzle 实例（零额外开销）。
+ */
+export async function initDatabaseWithHealthCheck<TSchema extends Record<string, unknown>>(
+  url?: string,
+  authToken?: string,
+  schema?: TSchema,
+): Promise<DrizzleInstance<TSchema>> {
+  if (!url) throw new Error("TURSO_URL is required");
+
+  // 如果已有缓存的连接，直接返回（Isolate 复用场景）
+  if (_cachedClient && _cachedUrl === url) {
+    return createDrizzle(_cachedClient, schema);
+  }
+
+  // 首次连接：创建 client 并验证连通性
+  const client = getOrCreateClient(url, authToken);
+  const db = createDrizzle(client, schema);
+
+  // 最多重试 2 次（500ms → 1s），避免 Turso 短暂不可达导致部署失败
+  for (let attempt = 0; attempt <= 2; attempt++) {
+    try {
+      await client.execute("SELECT 1");
+      return db;
+    } catch (err) {
+      if (attempt >= 2) throw err;
+      const delay = 500 * Math.pow(2, attempt);
+      console.warn(`[db:health-check] 连接失败，${delay}ms 后重试 (${attempt + 1}/2)`);
+      await new Promise((r) => setTimeout(r, delay));
+      // 重建 client（可能连接状态已损坏）
+      _cachedClient = undefined;
+      _cachedUrl = undefined;
+      const newClient = getOrCreateClient(url, authToken);
+      Object.assign(db, createDrizzle(newClient, schema));
+    }
+  }
+
+  return db;
+}
+
+/**
+ * 重置 Isolate 级缓存（仅用于测试）
+ */
+export function _resetCache(): void {
+  _cachedUrl = undefined;
+  _cachedClient = undefined;
+}

package/src/db/index.ts

@@ -0,0 +1,6 @@
+/**
+ * @usethink/cf-core/db — 数据库层统一导出
+ */
+
+export { getOrCreateClient, createDrizzle, initDatabase, initDatabaseWithHealthCheck, type DrizzleInstance } from "./connection";
+export * from "./schema";

package/src/db/schema.ts

@@ -0,0 +1,90 @@
+/**
+ * @usethink/cf-core — 公共数据库 Schema
+ *
+ * 所有项目共享的 Drizzle ORM 表定义。
+ * 各项目在此基础上添加自己的业务表。
+ *
+ * 公共表清单：
+ * 1. systemConfig — 系统配置（KV 存储，热生效）
+ * 2. adminAuditLogs — 管理员审计日志
+ * 3. rateLimitWindows — 限流计数窗口（DB 版限流）
+ * 4. idempotencyKeys — 幂等键（防重复提交）
+ * 5. apiKeys — API Key 认证（可选启用）
+ *
+ * 来源：eshop/xtools/vcode 三项目 schema.ts 中公共部分提取
+ */
+
+import { integer, primaryKey, sqliteTable, text } from "drizzle-orm/sqlite-core";
+
+// ═══════════════════════════════════════════════════════════════════════════════
+// 1. 系统配置表（KV 存储，热生效）
+// ═══════════════════════════════════════════════════════════════════════════════
+
+export const systemConfig = sqliteTable("system_config", {
+  key: text("key").primaryKey(),
+  value: text("value").default("").notNull(),
+  updatedAt: text("updated_at").default("").notNull(),
+});
+
+// ═══════════════════════════════════════════════════════════════════════════════
+// 2. 管理员审计日志表
+// ═══════════════════════════════════════════════════════════════════════════════
+
+export const adminAuditLogs = sqliteTable("admin_audit_logs", {
+  id: text("id").primaryKey(),
+  action: text("action").notNull(),
+  targetType: text("target_type").default("").notNull(),
+  targetId: text("target_id").default("").notNull(),
+  metadataJson: text("metadata_json").default("{}").notNull(),
+  ipHash: text("ip_hash").default("").notNull(),
+  createdAt: text("created_at").default("").notNull(),
+});
+
+// ═══════════════════════════════════════════════════════════════════════════════
+// 3. 限流窗口表（DB 版限流 — 原子 upsert）
+// ═══════════════════════════════════════════════════════════════════════════════
+
+export const rateLimitWindows = sqliteTable(
+  "rate_limit_windows",
+  {
+    action: text("action").notNull(),
+    ipHash: text("ip_hash").notNull(),
+    windowStart: integer("window_start").notNull(),
+    requestCount: integer("request_count").default(0).notNull(),
+  },
+  (table) => ({
+    pk: primaryKey({ columns: [table.action, table.ipHash, table.windowStart] }),
+  }),
+);
+
+// ═══════════════════════════════════════════════════════════════════════════════
+// 4. 幂等键表（防重复提交）
+// ═══════════════════════════════════════════════════════════════════════════════
+
+export const idempotencyKeys = sqliteTable("idempotency_keys", {
+  key: text("key").notNull(),
+  action: text("action").notNull(),
+  resourceId: text("resource_id").notNull(),
+  responseJson: text("response_json").notNull(),
+  createdAt: text("created_at").default("").notNull(),
+});
+
+// ═══════════════════════════════════════════════════════════════════════════════
+// 5. API Key 表（可选启用）
+// ═══════════════════════════════════════════════════════════════════════════════
+
+export const apiKeys = sqliteTable("api_keys", {
+  id: text("id").primaryKey(),
+  name: text("name").notNull(),
+  keyHash: text("key_hash").notNull(),
+  userId: text("user_id").default("").notNull(),
+  tier: text("tier").default("free").notNull(),
+  enabled: integer("enabled").default(1).notNull(),
+  monthlyQuota: integer("monthly_quota").default(0).notNull(),
+  monthlyUsage: integer("monthly_usage").default(0).notNull(),
+  monthlyResetAt: text("monthly_reset_at"),
+  lastUsedAt: text("last_used_at"),
+  createdAt: text("created_at").default("").notNull(),
+  updatedAt: text("updated_at").default("").notNull(),
+  expiresAt: text("expires_at"),
+});

package/src/error.ts

@@ -0,0 +1,125 @@
+/**
+ * 错误分类与指数退避重试
+ *
+ * 区分可重试 / 不可重试 / 需延迟重试的错误类型，
+ * 配合指数退避（exponential backoff + jitter）减少无效重试。
+ *
+ * 来源：xtools src/lib/error-classifier.ts
+ */
+
+export enum ErrorType {
+  /** 网络超时、5xx 服务器错误 → 可重试 */
+  TRANSIENT = "transient",
+  /** 4xx 认证失败、invalid_grant → 不可重试 */
+  PERMANENT = "permanent",
+  /** 429 Too Many Requests → 延迟重试 */
+  RATE_LIMIT = "rate_limit",
+}
+
+const PERMANENT_KEYWORDS = [
+  "invalid_grant",
+  "invalid_client",
+  "unauthorized",
+  "interaction_required",
+  "access_denied",
+  "invalid_token",
+  "401",
+  "403",
+  "account_disabled",
+  "consent_required",
+];
+
+const RATE_LIMIT_KEYWORDS = [
+  "429",
+  "too many requests",
+  "rate limit",
+  "throttl",
+];
+
+/**
+ * 分类错误类型
+ */
+export function classifyError(error: unknown): ErrorType {
+  const message = (error instanceof Error ? error.message : String(error)).toLowerCase();
+
+  if (RATE_LIMIT_KEYWORDS.some((kw) => message.includes(kw))) {
+    return ErrorType.RATE_LIMIT;
+  }
+  if (PERMANENT_KEYWORDS.some((kw) => message.includes(kw))) {
+    return ErrorType.PERMANENT;
+  }
+  return ErrorType.TRANSIENT;
+}
+
+export interface RetryOptions {
+  /** 最大重试次数（默认 3） */
+  maxRetries?: number;
+  /** 基础延迟毫秒（默认 1000） */
+  baseDelayMs?: number;
+  /** 限流延迟倍数（默认 5） */
+  rateLimitMultiplier?: number;
+  /** 最大延迟毫秒（默认 30000） */
+  maxDelayMs?: number;
+  /** 重试回调（用于日志） */
+  onRetry?: (attempt: number, error: Error, delayMs: number) => void;
+}
+
+/**
+ * 带指数退避的重试执行器
+ *
+ * - TRANSIENT: 指数退避（1s → 2s → 4s）
+ * - RATE_LIMIT: 更长延迟（5s → 10s → 20s）
+ * - PERMANENT: 立即抛出，不重试
+ *
+ * @example
+ * const result = await retryWithBackoff(
+ *   () => fetchExternalApi(),
+ *   { maxRetries: 3, onRetry: (n, err, ms) => console.warn(`重试 #${n}: ${err.message} (${ms}ms)`) }
+ * );
+ */
+export async function retryWithBackoff<T>(
+  fn: () => Promise<T>,
+  options: RetryOptions = {},
+): Promise<T> {
+  const {
+    maxRetries = 3,
+    baseDelayMs = 1000,
+    rateLimitMultiplier = 5,
+    maxDelayMs = 30_000,
+    onRetry,
+  } = options;
+
+  let lastError: unknown;
+
+  for (let attempt = 0; attempt <= maxRetries; attempt++) {
+    try {
+      return await fn();
+    } catch (error) {
+      lastError = error;
+      const errorType = classifyError(error);
+
+      if (errorType === ErrorType.PERMANENT) {
+        throw error;
+      }
+      if (attempt >= maxRetries) {
+        break;
+      }
+
+      let delayMs: number;
+      if (errorType === ErrorType.RATE_LIMIT) {
+        delayMs = Math.min(baseDelayMs * rateLimitMultiplier * Math.pow(2, attempt), maxDelayMs);
+      } else {
+        delayMs = Math.min(baseDelayMs * Math.pow(2, attempt), maxDelayMs);
+      }
+
+      // 随机抖动（±20%），避免雷群效应
+      const jitter = delayMs * 0.2 * (Math.random() * 2 - 1);
+      delayMs = Math.round(delayMs + jitter);
+
+      onRetry?.(attempt + 1, error as Error, delayMs);
+      await new Promise((resolve) => setTimeout(resolve, delayMs));
+    }
+  }
+
+  throw lastError;
+}

package/src/http.ts

@@ -0,0 +1,150 @@
+/**
+ * HTTP 响应工具模块
+ *
+ * 提供统一的 ok/fail 响应格式，以及常用的请求解析工具。
+ * 泛型设计：兼容任意 Hono AppEnv 类型，无需绑定特定项目。
+ *
+ * 来源：eshop/xtools/vcode 三项目 lib/http.ts 合并
+ */
+
+import type { Context } from "hono";
+import type { ContentfulStatusCode } from "hono/utils/http-status";
+import type { RateLimitResult } from "./types";
+
+/**
+ * 成功响应 — 统一格式 { ok: true, ...data }
+ */
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+export function ok(
+  c: Context<any>,
+  data: Record<string, unknown>,
+  status: ContentfulStatusCode = 200,
+) {
+  return c.json({ ok: true, ...data } as Record<string, unknown>, status);
+}
+
+/**
+ * 失败响应 — 统一格式 { ok: false, error: message }
+ */
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+export function fail(
+  c: Context<any>,
+  message: string,
+  status: number = 400,
+  details?: unknown,
+) {
+  return c.json(
+    { ok: false, error: message, ...(details ? { details } : {}) } as Record<string, unknown>,
+    status as ContentfulStatusCode,
+  );
+}
+
+/**
+ * 限流失败响应 — 429 + 标准 RateLimit 头
+ *
+ * 返回标准 HTTP 429 响应，包含以下头信息：
+ * - Retry-After: 秒数（建议客户端等待时间）
+ * - X-RateLimit-Limit: 窗口内允许的最大请求数
+ * - X-RateLimit-Remaining: 窗口内剩余请求数（0）
+ * - X-RateLimit-Reset: 窗口重置的 Unix 时间戳
+ *
+ * @example
+ * ```ts
+ * const result = await rateLimiter.check(key, limit, windowMs);
+ * if (!result.ok) {
+ *   return failRateLimit(c, result, limit);
+ * }
+ * ```
+ */
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+export function failRateLimit(
+  c: Context<any>,
+  result: RateLimitResult,
+  limit: number,
+) {
+  const retryAfterSeconds = Math.ceil((result.resetMs || 0) / 1000);
+  const resetTimestamp = Math.ceil((Date.now() + (result.resetMs || 0)) / 1000);
+
+  return c.json(
+    { ok: false, error: result.message || "请求过于频繁，请稍后再试" },
+    429,
+    {
+      "Retry-After": String(retryAfterSeconds),
+      "X-RateLimit-Limit": String(limit),
+      "X-RateLimit-Remaining": "0",
+      "X-RateLimit-Reset": String(resetTimestamp),
+    },
+  );
+}
+
+/**
+ * 获取站点域名 — 优先使用环境变量 APP_ORIGIN，降级使用请求 URL
+ */
+export function getOrigin<E extends { Bindings: { APP_ORIGIN?: string } }>(c: Context<E>): string {
+  return c.env.APP_ORIGIN || new URL(c.req.url).origin;
+}
+
+/**
+ * 安全读取 JSON body — 解析失败返回 undefined（避免非 JSON 请求体导致 400）
+ *
+ * 支持泛型，让调用方可以明确 JSON 形状，避免下游 zod safeParse 的 unknown 类型报错。
+ * 默认类型为 unknown，保持向后兼容。
+ */
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+export async function safeJsonBody<T = unknown>(c: Context<any>): Promise<T> {
+  return c.req.json().catch(() => undefined) as Promise<T>;
+}
+
+/**
+ * 联系方式脱敏 — 用于管理端展示
+ *
+ * - 邮箱：ab***@example.com
+ * - 手机/其他：ab***cd
+ * - 长度 ≤ 4：***
+ */
+export function maskContact(value: string): string {
+  const text = value.trim();
+  if (text.length <= 4) return "***";
+  if (text.includes("@") && !text.startsWith("@")) {
+    const [name, domain] = text.split("@");
+    return `${name.slice(0, 2)}***@${domain}`;
+  }
+  return `${text.slice(0, 2)}***${text.slice(-2)}`;
+}
+
+/**
+ * 标准化编码 — trim + lowercase（用于优惠码/折扣码等）
+ */
+export function normalizeCode(value?: string): string {
+  return (value || "").trim().toLowerCase();
+}
+
+/**
+ * CSV 注入防护 — 对导出值做安全转义
+ *
+ * 如果值以 = + - @ \t \n 开头，前置制表符阻止公式注入。
+ * 来源：eshop admin 订单导出
+ */
+export function csvEscape(value: unknown): string {
+  const str = String(value ?? "");
+  if (/^[=+\-@\t\n]/.test(str)) {
+    return `\t${str}`;
+  }
+  return str;
+}
+
+/**
+ * 将对象数组导出为 CSV 字符串
+ */
+export function toCsv(rows: Record<string, unknown>[], columns: string[]): string {
+  const header = columns.join(",");
+  const body = rows.map((row) =>
+    columns.map((col) => {
+      const val = csvEscape(row[col]);
+      return val.includes(",") || val.includes('"') || val.includes("\n")
+        ? `"${val.replace(/"/g, '""')}"`
+        : val;
+    }).join(","),
+  ).join("\n");
+  return `${header}\n${body}`;
+}

package/src/idempotency.ts

@@ -0,0 +1,127 @@
+/**
+ * 幂等性模块 — 防止同一请求被重复处理
+ *
+ * 使用 (key, action) 复合键作为幂等标识。
+ * 核心设计：原子 UPSERT + 非空哨兵值，消除 TOCTOU 竞态。
+ *
+ * 流程：
+ * 1. checkIdempotency() — 原子 UPSERT，返回 shouldProceed
+ * 2. shouldProceed === false → 返回缓存响应
+ * 3. shouldProceed === true → 执行业务逻辑 → saveIdempotentResponse()
+ *
+ * 来源：eshop src/lib/idempotency.ts（三项目中唯一实现）
+ */
+
+import { idempotencyKeys } from "./db/schema";
+import { eq, and, sql } from "drizzle-orm";
+
+const PENDING_SENTINEL = "__pending__";
+
+/**
+ * 通用 Drizzle 数据库接口（仅约束幂等模块需要的方法）
+ */
+interface DbLike {
+  insert: (table: typeof idempotencyKeys) => {
+    values: (data: { key: string; action: string; resourceId: string; responseJson: string; createdAt: string }) => {
+      onConflictDoUpdate: (opts: {
+        target: [typeof idempotencyKeys.key, typeof idempotencyKeys.action];
+        set: Record<string, unknown>;
+      }) => {
+        returning: (cols: { responseJson: typeof idempotencyKeys.responseJson }) => Promise<{ responseJson: string }[]>;
+      };
+    };
+  };
+  select: (cols: { responseJson: typeof idempotencyKeys.responseJson }) => {
+    from: (table: typeof idempotencyKeys) => {
+      where: (cond: unknown) => {
+        limit: (n: number) => Promise<{ responseJson: string }[]>;
+      };
+    };
+  };
+}
+
+/**
+ * 原子检查幂等性
+ *
+ * INSERT ON CONFLICT UPDATE RETURNING 是 SQLite 原子操作。
+ * 并发请求中只有一个获得 shouldProceed=true。
+ *
+ * @returns shouldProceed=true 时应执行业务逻辑；false 时 cachedResponse 含之前缓存的响应
+ */
+export async function checkIdempotency(
+  db: DbLike,
+  key: string,
+  action: string,
+): Promise<{ shouldProceed: boolean; cachedResponse: string | null }> {
+  const [row] = await db
+    .insert(idempotencyKeys)
+    .values({
+      key,
+      action,
+      resourceId: "",
+      responseJson: PENDING_SENTINEL,
+      createdAt: new Date().toISOString(),
+    })
+    .onConflictDoUpdate({
+      target: [idempotencyKeys.key, idempotencyKeys.action],
+      set: { responseJson: sql`idempotency_keys.response_json` },
+    })
+    .returning({ responseJson: idempotencyKeys.responseJson });
+
+  const shouldProceed = row?.responseJson === PENDING_SENTINEL;
+  const cachedResponse = shouldProceed
+    ? null
+    : row?.responseJson === PENDING_SENTINEL
+      ? null
+      : row?.responseJson ?? null;
+
+  return { shouldProceed, cachedResponse };
+}
+
+/**
+ * 保存幂等响应
+ *
+ * 在 checkIdempotency 返回 shouldProceed=true 并执行业务逻辑后调用。
+ */
+export async function saveIdempotentResponse(
+  db: DbLike,
+  key: string,
+  action: string,
+  resourceId: string,
+  response: unknown,
+): Promise<void> {
+  await db
+    .insert(idempotencyKeys)
+    .values({
+      key,
+      action,
+      resourceId,
+      responseJson: JSON.stringify(response),
+      createdAt: new Date().toISOString(),
+    })
+    .onConflictDoUpdate({
+      target: [idempotencyKeys.key, idempotencyKeys.action],
+      set: {
+        responseJson: JSON.stringify(response),
+        resourceId,
+      },
+    });
+}
+
+/**
+ * 查询已缓存的幂等响应（只读，不创建记录）
+ *
+ * @deprecated 使用 checkIdempotency() 替代
+ */
+export async function getIdempotentResponse(
+  db: DbLike,
+  key: string,
+  action: string,
+): Promise<{ responseJson: string } | null> {
+  const [row] = await db
+    .select({ responseJson: idempotencyKeys.responseJson })
+    .from(idempotencyKeys)
+    .where(and(eq(idempotencyKeys.key, key), eq(idempotencyKeys.action, action)))
+    .limit(1);
+  return row || null;
+}