weifuwu 0.56.0 → 0.57.0

package/README.md

@@ -230,6 +230,10 @@ createApp().use(router({ routes })).mount('#root', RouteView, { hydrate: true })
 | `weifuwu` | **redis** | Redis 客户端（自研 RESP2 协议）→ `ctx.redis` | Router, REDIS_URL |
 | `weifuwu` | **ui** | SSR 渲染 + esbuild JS/CSS 动态编译 → `ctx.ui` | Router |
 | `weifuwu` | **uiSsr** | 路由级 SSR：匹配 routes → 自动完整 HTML + `__DATA__` + bundle | Router, ui |
+| `weifuwu` | **rateLimit** | 限流中间件（fixed/sliding，redis 多实例原子）→ `ctx.limit` | Router, redis |
+| `weifuwu` | **email** | 邮件发送（Resend/SMTP 自研/自定义适配器）→ `ctx.email` | Router |
+| `weifuwu` | **userSystem** | 用户系统（scrypt 密码哈希 + 混合会话）→ `ctx.user` / `ctx.auth` + `/api/auth/*` | Router, postgres |
+| `weifuwu` | **queue** | 可靠任务队列（Redis Streams，at-least-once + DLQ）→ `ctx.queue` | Router, redis |
 | `weifuwu/dev` | **dev loader** | Node loader：服务端直接跑 `.ts/.tsx`（`--import weifuwu/dev`） | esbuild |
 | `weifuwu` | **graphql** | GraphQL 端点（支持 GraphiQL） | Router |
 | `weifuwu` | **createMiddleware** | 类型安全中间件工厂 | — |
@@ -679,7 +683,7 @@ app.use(db)
 
 ## redis — Redis 客户端（自研）
 
-> **自研 RESP2 协议**（零第三方依赖）——连接/重连（断线 pending 拒绝、指数退避）/离线队列/管道/Pub-Sub（订阅断线自动重放）+ 消除 ioredis 高频痛点（TTL 参数顺序、JSON 手动序列化、缓存样板）。
+> **自研 RESP2 协议**（零第三方依赖）——连接/重连（断线 pending 拒绝、指数退避）/离线队列/管道/Pub-Sub（订阅断线自动重放）+ 消除 ioredis 高频痛点（TTL 参数顺序、JSON 手动序列化、缓存样板）。**二进制安全**：`getBuffer(key)` 原样返回字节（缓存序列化 payload 不损坏）。
 
 ```ts
 import { redis } from 'weifuwu'
@@ -1019,6 +1023,8 @@ app.get('/secure', () => {
 
 ## 响应辅助函数
 
+> 以下为完整 API 参考，按需查阅。四个 SaaS 地基模块（rateLimit / email / userSystem / queue）见文末「SaaS 地基模块」章节。
+
 消除 `Response.json(...)` 重复模式：
 
 ```ts
@@ -2722,3 +2728,124 @@ node scripts/release.mjs <version>   # 发布
 # 测试前启动依赖服务
 docker compose up -d
 ```
+
+---
+
+# SaaS 地基模块（rateLimit / email / userSystem / queue）
+
+四个内建模块组成一个"基本 SaaS 底座"：认证、异步任务、限流、邮件——零新增依赖
+（只依赖已自研的 redis / postgres 客户端与 node 标准库）。
+
+## rateLimit — 限流
+
+```ts
+import { rateLimit } from 'weifuwu'
+
+app.use(redis())                                        // 依赖 ctx.redis
+app.use(rateLimit({ windowMs: 60_000, max: 100 }))      // 全局限流（默认固定窗口）
+
+app.get('/api/search', async (req, ctx) => {
+  await ctx.limit('search', { max: 30, windowMs: 60_000 })  // 手动限流，超限抛 429
+})
+
+// 登录防爆破（配合 userSystem）：组合键 ip:email
+app.use(rateLimit({ key: (req) => `login:${req.ip}:${req.email}`, max: 5, windowMs: 15 * 60_000 }))
+```
+
+| 选项 | 默认 | 说明 |
+|------|------|------|
+| `windowMs` | `60000` | 时间窗口 |
+| `max` | `100` | 窗口内最大请求 |
+| `key` | X-Forwarded-For | 限流键（生产环境配置反向代理注入） |
+| `algorithm` | `fixed` | `fixed`（INCR+EXPIRE，原子）\| `sliding`（ZSET，仅 redis） |
+| `store` | `redis` | `redis`（多实例一致）\| `memory`（仅单实例/开发） |
+
+- 响应自动带 `RateLimit-Limit` / `RateLimit-Remaining` / `RateLimit-Reset` / `Retry-After`
+- 多实例共享计数：计数在 redis，水平扩展天然一致
+
+## email — 邮件发送
+
+```ts
+import { email } from 'weifuwu'
+
+app.use(email({ from: 'no-reply@your.app', adapter: 'resend', resend: { apiKey: process.env.RESEND_API_KEY } }))
+// 或 adapter: 'smtp' + smtp: { host, port, user, pass }（自研 SMTP 客户端，零依赖）
+
+app.post('/api/notify', async (req, ctx) => {
+  await ctx.email.send({ to: 'user@x.com', subject: '通知', html: '<h1>hi</h1>' })
+})
+```
+
+- 适配器：`resend`（默认，一个 POST）/ `smtp`（自研 node:net + node:tls：EHLO/STARTTLS/AUTH PLAIN/DATA/dot-stuffing，非 ASCII subject 自动 RFC2047 编码）/ 自定义函数
+- 裁剪：附件、退信/送达率（服务商职责）、批量营销不支持
+
+## userSystem — 用户系统
+
+```ts
+import { userSystem } from 'weifuwu'
+
+const db = postgres()
+await db.migrate()
+const users = userSystem({ sql: db.sql, secret: process.env.AUTH_SECRET })
+await users.migrate()          // 幂等建表（users + sessions）
+app.use(db)
+app.use(users)                 // 注入 ctx.user / ctx.auth
+users.routes(app)              // POST /api/auth/register|login|logout|refresh + GET /api/auth/me
+
+app.get('/me', (req, ctx) => ok(ctx.user))        // 已注入
+app.post('/secure', (req, ctx) => { ctx.auth.requireAuth(); ... })
+```
+
+- **安全基线**：scrypt 密码哈希（per-user salt + timing-safe，异步不阻塞）；access token = HMAC-SHA256 JWT（与 `weifuwu/client` 的 `auth()` 天然配对）；refresh token = 不透明随机串，DB 只存哈希，logout/轮换即撤销
+- **防枚举**：登录失败统一 401（不泄露邮箱是否存在）
+- **`ctx.auth` 方法面**：`register` / `login` / `logout` / `requireAuth` / `setPassword(userId, newPwd)` / `createToken(type, payload, { ttlSeconds })`（邮箱验证/密码重置自接）
+- **裁剪**：OAuth、邮箱验证邮件（给底层 API 自接）、多因素、RBAC 权限引擎（只留 `role` 字段）、多租户语义（tenant-ready：`tenant` 字段 + token claim 已预留）
+
+## queue — 可靠任务队列
+
+```ts
+import { queue } from 'weifuwu'
+
+const q = queue()              // 默认 REDIS_URL
+app.use(q)                     // 注入 ctx.queue
+
+app.post('/api/generate', async (req, ctx) => {
+  await ctx.queue.add('llm.batch', { prompt: '...' }, { attempts: 3 })
+  return new Response(null, { status: 202 })  // 立即 202，任务后台执行
+})
+
+// 消费者（独立进程或同进程均可，多开安全）
+const worker = q.worker('llm.batch', async (job) => {
+  await runLLM(job.data)       // 失败自动重试 → 用尽进 DLQ（q:llm.batch:dead）
+}, { concurrency: 5, visibilityTimeout: 30_000 })
+await worker.start()
+await worker.stop()            // 优雅停止
+```
+
+- **语义**：at-least-once（handler 可能重复执行——幂等由业务保证）；Redis Streams 消费组，多 worker 实例不重复消费
+- **可靠性**：失败 → 延迟重试（间隔 = `visibilityTimeout`，ZSET 延迟队列）→ attempts 用尽 → DLQ；worker 崩溃 → pending 由其他实例 `XAUTOCLAIM` 接管
+- 裁剪：延迟调度（除重试外）、cron、优先级、指数退避、速率限制不支持
+
+## 组合示例：注册 → 验证邮件 → 欢迎任务 → 登录防爆破
+
+```ts
+app.use(redis())
+app.use(rateLimit({ key: (req) => `login:${req.ip}`, max: 5, windowMs: 60_000 }))  // 防爆破
+app.use(email({ from: 'no-reply@x.com', adapter: 'resend', resend: { apiKey } }))
+app.use(db)
+app.use(users)
+users.routes(app)
+
+// 注册：限流守卫 → 用户系统 → 验证邮件 → 欢迎任务入队
+app.post('/api/auth/register', async (req, ctx) => {
+  await ctx.limit(`register:${req.ip}`, { max: 10, windowMs: 60_000 })
+  const result = await ctx.auth.register(await req.json())
+  const token = ctx.auth.createToken('verify', { sub: result.user.id }, { ttlSeconds: 86400 })
+  await ctx.email.send({ to: result.user.email, subject: '验证邮箱', html: `...?token=${token}` })
+  await ctx.queue.add('welcome.flow', { userId: result.user.id })
+  return created(result)
+})
+
+const worker = q.worker('welcome.flow', async (job) => { /* 欢迎流程 */ })
+await worker.start()
+```

package/dist/core/router.d.ts

@@ -1,4 +1,4 @@
-import type { Context, Handler, Middleware, ErrorHandler, Closeable } from '../types.ts';
+import { type Context, type Handler, type Middleware, type ErrorHandler, type Closeable } from '../types.ts';
 import { type WebSocketHandler, type WsUpgradeHandler } from './ws.ts';
 import type { GraphQLHandler } from '../graphql.ts';
 /**

package/dist/db/postgres/connection.d.ts

@@ -39,9 +39,9 @@ export declare class PgConnection {
     private onReady;
     private onAuthFail;
     private expectingAuth;
-    private authStage;
     private authCtx;
     private prepared;
+    private static readonly PREPARED_MAX;
     private stmtSeq;
     private currentQuery;
     private onData;
@@ -49,6 +49,10 @@ export declare class PgConnection {
     /** SCRAM client-final 消息 */
     private scramFinal;
     private scramServerSignature;
+    /** LRU 读取：命中移到尾部（最近使用），超限删最旧 */
+    private getPrepared;
+    /** LRU 写入：刷新位置；超上限淘汰最旧（长运行服务防无限累积） */
+    private setPrepared;
     /** 事务：BEGIN → fn(tx) → COMMIT；fn 抛错 → ROLLBACK（回滚失败吞掉，保留原始错误） */
     transaction<T>(fn: (tx: {
         query: (sql: string, params?: (string | number | boolean | object | null)[]) => Promise<Row[]>;

package/dist/db/postgres/protocol.d.ts

@@ -21,7 +21,10 @@ export declare function startupMessage(params: Record<string, string>): Uint8Arr
 export declare function queryMessage(sql: string): Uint8Array;
 /** Parse: P + statementName\0 + query\0 + paramTypeCount(2) + OIDs */
 export declare function parseMessage(name: string, sql: string, paramTypes?: number[]): Uint8Array;
-/** Bind: B + portal\0 + statement\0 + fmtCount + formats + paramCount + params + resultFmtCount */
+/**
+ * Bind: B + portal\0 + statement\0 + fmtCount + formats + paramCount + params + resultFmtCount
+ * 两遍法：先算 payload 总长 → 预分配一次写入（buffer + offset 指针，避免 number[] 累积 O(n²)）。
+ */
 export declare function bindMessage(statement: string, params: (string | Uint8Array | null)[], paramFormats?: number[]): Uint8Array;
 /** Execute: E + portal\0 + maxRows(4) */
 export declare function executeMessage(portal?: string, maxRows?: number): Uint8Array;

package/dist/db/redis/client.d.ts

@@ -15,9 +15,14 @@ export declare class RedisClient {
     private constructor();
     /** 建立连接并返回就绪的客户端 */
     static connect(options?: RedisClientOptions): Promise<RedisClient>;
-    /** 底层命令透传（RESP 值） */
-    command(name: string, ...args: (string | number)[]): Promise<RespValue>;
+    /** 底层命令透传（RESP 值）；Buffer 参数字节原样发送 */
+    command(name: string, ...args: (string | number | Buffer)[]): Promise<RespValue>;
     get(key: string): Promise<string | null>;
+    /**
+     * 二进制安全读取：返回原始字节（Uint8Array），不经过字符串解码。
+     * 用于缓存二进制 payload（序列化字节、图片等）。key 不存在返回 null。
+     */
+    getBuffer(key: string): Promise<Uint8Array | null>;
     /**
      * SET。ttl 秒可省略；传入即安全生效（内部转 SET key val EX ttl）。
      */

package/dist/db/redis/connection.d.ts

@@ -18,6 +18,8 @@ export interface RedisConnectionOptions {
     maxRetries?: number;
     /** 未连接时命令是否入队等待（ioredis enableOfflineQueue 语义）。默认 true。 */
     enableOfflineQueue?: boolean;
+    /** 离线队列上限。默认 5000。超限命令立即 reject（防断线期间无限累积）。 */
+    maxOfflineQueue?: number;
 }
 export declare class RedisConnection {
     readonly ready = false;
@@ -25,6 +27,8 @@ export declare class RedisConnection {
     private socket;
     private parser;
     private pending;
+    /** pending 头指针（避免 shift() O(n)——消费后定期 compact） */
+    private pendingHead;
     private offlineQueue;
     private subs;
     private psubs;
@@ -42,8 +46,13 @@ export declare class RedisConnection {
     private openSocket;
     private handleDisconnect;
     private onData;
-    /** 发送命令并等待响应（单连接严格有序）。未 ready 时入离线队列（enableOfflineQueue）或拒绝。 */
-    command(name: string, ...args: (string | number)[]): Promise<RespValue>;
+    /**
+     * 发送命令并等待响应（单连接严格有序）。未 ready 时入离线队列（enableOfflineQueue）或拒绝。
+     * opts.asBuffer=true：响应保留原始字节（Uint8Array）——getBuffer 等二进制场景。
+     */
+    command(name: string, ...args: (string | number | Buffer | {
+        asBuffer?: boolean;
+    })[]): Promise<RespValue>;
     private sendNow;
     private flushOffline;
     /** 批量执行：一次 write 发送所有命令字节，响应按序路由（管道） */

package/dist/db/redis/pool.d.ts

@@ -34,6 +34,8 @@ export declare class RedisPool {
     private next;
     command(name: string, ...args: (string | number)[]): Promise<RespValue>;
     get(key: string): Promise<string | null>;
+    /** 二进制安全读取（原始字节，不解码） */
+    getBuffer(key: string): Promise<Uint8Array | null>;
     set(key: string, value: string | number, ttl?: number): Promise<'OK'>;
     del(...keys: string[]): Promise<number>;
     incr(key: string): Promise<number>;

package/dist/db/redis/resp.d.ts

@@ -7,7 +7,7 @@
  * 解码为增量式：连接层可喂入任意分片，累积到完整消息后取回。
  */
 import { DbError } from '../errors.ts';
-export type RespValue = string | number | null | RespError | RespValue[];
+export type RespValue = string | number | null | RespError | RespValue[] | Uint8Array;
 /** 服务器错误响应（-ERR ...） */
 export declare class RespError extends DbError {
     constructor(message: string);
@@ -16,9 +16,11 @@ export declare class RespError extends DbError {
 export declare class IncompleteError extends Error {
     constructor();
 }
-/** 编码命令为 RESP 数组字节 */
+/** 递归解码字节值（bulk → string）。decodeBytes=false 时字节原样保留（二进制安全）。 */
+export declare function decodeValue(v: RespValue, decodeBytes: boolean): RespValue;
+/** 编码命令为 RESP 数组字节。Buffer 参数字节原样写入（二进制安全，零损坏）。 */
 export declare function encodeCommand(args: (string | number | Buffer)[]): Uint8Array;
-/** 从完整 buffer 解析单个 RESP 值（非增量——单消息场景） */
+/** 从完整 buffer 解析单个 RESP 值（非增量——单消息场景，解码为 string 语义） */
 export declare function parseReply(data: Uint8Array): RespValue;
 export declare class RespParser {
     private buf;
@@ -35,8 +37,13 @@ export declare class RespParser {
     /** 全部消费后压缩（释放底层） */
     private compact;
     private parseValue;
+    /**
+     * 读整数（: 或 $ 长度）：扫描数字字符边算值，直到 \r\n（手动解析，免 parseInt + 字符串）。
+     * 支持负号（-1）。未读到终止符抛 IncompleteError（push 回滚）。
+     */
+    private readInt;
     /** 读一行（到 \r\n），返回行内容（不含 type 字节与 \r\n），并推进 off */
     private readLine;
-    /** 读 len 字节的 bulk 内容 + \r\n */
-    private readBulk;
+    /** 读 len 字节的 bulk 内容 + \r\n（字节中立——不 decode，由调用方决定 string/Buffer） */
+    private readBulkBytes;
 }

package/dist/email/index.d.ts

@@ -0,0 +1,72 @@
+/**
+ * weifuwu/email — 邮件发送中间件
+ *
+ * 注入 ctx.email.send —— 统一发送接口，适配器抽象底层服务商。
+ *
+ * 适配器：
+ *   - 'resend'（默认推荐）：一个 POST，独立开发者首选
+ *   - 'smtp'：自研 SMTP 客户端（node:net + node:tls，零依赖），任意服务商/自建 Postfix
+ *   - 自定义函数：`adapter: async (msg) => ...` 一行接入任意服务商
+ *
+ * 裁剪声明：
+ *   ✅ 统一 send 接口 / text + html / 多收件人 / 自定义适配器
+ *   ❌ 附件（SMTP MIME multipart 未实现）、退信/送达率（服务商职责）、
+ *      批量营销、隐式入队（文档给"发邮件 = ctx.queue.add"示例）
+ *
+ * ```ts
+ * import { email } from 'weifuwu'
+ *
+ * app.use(email({
+ *   from: 'no-reply@your.app',
+ *   adapter: 'resend',            // 或 'smtp'
+ *   resend: { apiKey: process.env.RESEND_API_KEY },
+ * }))
+ *
+ * app.post('/api/notify', async (req, ctx) => {
+ *   await ctx.email.send({ to: 'user@x.com', subject: '通知', html: '<h1>hi</h1>' })
+ *   return ok()
+ * })
+ * ```
+ */
+import type { Context, Middleware } from '../types.ts';
+import { type SmtpConfig } from './smtp.ts';
+export interface EmailMessage {
+    /** 收件人（可多个） */
+    to: string | string[];
+    subject: string;
+    text?: string;
+    html?: string;
+    /** 覆盖全局 from（可选） */
+    from?: string;
+}
+export interface EmailResult {
+    /** 服务商返回的邮件 ID（有则给） */
+    id?: string;
+    accepted: boolean;
+}
+/** 适配器：输入已标准化的邮件消息，输出结果。 */
+export type EmailAdapter = (msg: EmailMessage) => Promise<EmailResult>;
+export interface EmailOptions {
+    /** 默认发件人 */
+    from: string;
+    adapter?: 'resend' | 'smtp' | EmailAdapter;
+    resend?: {
+        apiKey?: string;
+        /** 测试可注入 mock 地址 */
+        baseUrl?: string;
+    };
+    smtp?: SmtpConfig;
+}
+export interface EmailInjected {
+    email: {
+        send: (msg: EmailMessage) => Promise<EmailResult>;
+    };
+}
+declare module '../types.ts' {
+    interface Context {
+        email?: EmailInjected['email'];
+    }
+}
+export interface EmailClient extends Middleware<Context, Context & EmailInjected> {
+}
+export declare function email(options: EmailOptions): EmailClient;

package/dist/email/smtp.d.ts

@@ -0,0 +1,34 @@
+/**
+ * 自研 SMTP 客户端（零依赖，node:net + node:tls）
+ *
+ * 覆盖流程：连接 → 220 → EHLO（特性协商）→ STARTTLS（可选）→ AUTH PLAIN
+ * → MAIL FROM → RCPT TO → DATA（dot-stuffing）→ QUIT。
+ *
+ * 诚实裁剪：
+ *   - 无连接池/批处理（每次发送新建连接）
+ *   - 无附件（MIME multipart 未实现，v1 只 text/html）
+ *   - Subject 非 ASCII 自动 RFC2047 encoded-word（UTF-8）
+ *   - AUTH 仅 PLAIN（LOGIN/CRAM-MD5 不支持——明确报错而非静默）
+ */
+export interface SmtpConfig {
+    host: string;
+    /** 默认 465（secure=true）/ 587（secure=false） */
+    port?: number;
+    user?: string;
+    pass?: string;
+    /** true = 直连 TLS（465）；false = 明文 + STARTTLS（587）。默认 false。 */
+    secure?: boolean;
+    /** secure=false 时 STARTTLS 失败是否中止。默认 false（继续明文，测试/内网场景）。 */
+    requireTls?: boolean;
+    timeoutMs?: number;
+    /** 自签证书/测试环境放行。默认 false。 */
+    rejectUnauthorized?: boolean;
+}
+export interface SmtpMessage {
+    from: string;
+    to: string[];
+    subject: string;
+    text?: string;
+    html?: string;
+}
+export declare function sendSmtp(cfg: SmtpConfig, msg: SmtpMessage): Promise<void>;

package/dist/index.d.ts

@@ -11,6 +11,16 @@ export { cors } from './middleware/cors.ts';
 export type { CORSOptions } from './middleware/cors.ts';
 export { serveStatic } from './middleware/static.ts';
 export type { ServeStaticOptions } from './middleware/static.ts';
+export { rateLimit } from './middleware/rate-limit.ts';
+export type { RateLimitOptions, RateLimitInjected, RateLimitAlgorithm, RateLimitStore } from './middleware/rate-limit.ts';
+export { email } from './email/index.ts';
+export type { EmailOptions, EmailMessage, EmailResult, EmailAdapter, EmailInjected } from './email/index.ts';
+export { sendSmtp } from './email/smtp.ts';
+export type { SmtpConfig } from './email/smtp.ts';
+export { userSystem } from './user/index.ts';
+export type { UserSystemOptions, UserInjected, AuthApi, RegisterInput } from './user/index.ts';
+export { queue } from './queue/index.ts';
+export type { QueueOptions, QueueClient, QueueInjected, QueueWorker, WorkerOptions, AddOptions, Job } from './queue/index.ts';
 export { ui } from './ui/index.ts';
 export { uiSsr } from './ui/ssr-page.ts';
 export type { UiSsrOptions } from './ui/ssr-page.ts';