weifuwu 0.56.0 → 0.56.1

package/README.md

@@ -679,7 +679,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'

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/index.js

@@ -1567,23 +1567,61 @@ function parseMessage(name, sql, paramTypes = []) {
   return encodeMessage("P", concat(body, types));
 }
 function bindMessage(statement, params, paramFormats = []) {
-  const body = [...utf8(""), 0, ...utf8(statement), 0];
-  body.push(0, paramFormats.length);
+  const stmtBytes = utf8(statement);
+  const lens = new Array(params.length);
+  let total = 1 + stmtBytes.length + 1;
+  total += 2 + paramFormats.length * 2;
+  total += 2;
+  for (let i = 0; i < params.length; i++) {
+    const p = params[i];
+    total += 4;
+    if (p !== null) {
+      const len = typeof p === "string" ? utf8Len(p) : p.length;
+      lens[i] = len;
+      total += len;
+    }
+  }
+  total += 2;
+  const body = new Uint8Array(total);
+  let off = 0;
+  body[off++] = 0;
+  body.set(stmtBytes, off);
+  off += stmtBytes.length;
+  body[off++] = 0;
+  body[off] = paramFormats.length >> 8 & 255;
+  body[off + 1] = paramFormats.length & 255;
+  off += 2;
   for (const f of paramFormats) {
-    body.push(f >> 8 & 255, f & 255);
-  }
-  body.push(0, params.length);
-  for (const p of params) {
+    body[off] = f >> 8 & 255;
+    body[off + 1] = f & 255;
+    off += 2;
+  }
+  body[off] = params.length >> 8 & 255;
+  body[off + 1] = params.length & 255;
+  off += 2;
+  for (let i = 0; i < params.length; i++) {
+    const p = params[i];
     if (p === null) {
-      body.push(255, 255, 255, 255);
+      body[off] = body[off + 1] = body[off + 2] = body[off + 3] = 255;
+      off += 4;
     } else {
-      const bytes = typeof p === "string" ? utf8(p) : p;
-      body.push(bytes.length >> 24 & 255, bytes.length >> 16 & 255, bytes.length >> 8 & 255, bytes.length & 255);
-      for (const b of bytes) body.push(b);
+      const len = lens[i];
+      body[off] = len >> 24 & 255;
+      body[off + 1] = len >> 16 & 255;
+      body[off + 2] = len >> 8 & 255;
+      body[off + 3] = len & 255;
+      off += 4;
+      if (typeof p === "string") body.set(utf8(p), off);
+      else body.set(p, off);
+      off += len;
     }
   }
-  body.push(0, 0);
-  return encodeMessage("B", new Uint8Array(body));
+  body[off] = 0;
+  body[off + 1] = 0;
+  return encodeMessage("B", body);
+}
+function utf8Len(s) {
+  return Buffer.byteLength(s);
 }
 function executeMessage(portal = "", maxRows = 0) {
   const body = new Uint8Array(portal.length + 1 + 4);
@@ -1675,7 +1713,7 @@ function parseRowDescription(payload) {
   for (let c = 0; c < count; c++) {
     let j = i;
     while (payload[j] !== 0) j++;
-    const name = new TextDecoder().decode(payload.subarray(i, j));
+    const name = _decoder.decode(payload.subarray(i, j));
     i = j + 1;
     i += 6;
     const typeOid = payload[i] << 24 | payload[i + 1] << 16 | payload[i + 2] << 8 | payload[i + 3];
@@ -1697,7 +1735,7 @@ function parseDataRow(payload) {
     if (len === -1) {
       values.push(null);
     } else {
-      values.push(new TextDecoder().decode(payload.subarray(i, i + len)));
+      values.push(_decoder.decode(payload.subarray(i, i + len)));
       i += len;
     }
   }
@@ -1710,7 +1748,7 @@ function parseErrorFields(payload) {
     const type = String.fromCharCode(payload[i]);
     let j = i + 1;
     while (j < payload.length && payload[j] !== 0) j++;
-    const value = new TextDecoder().decode(payload.subarray(i + 1, j));
+    const value = _decoder.decode(payload.subarray(i + 1, j));
     switch (type) {
       case "S":
         out.severity = value;
@@ -1735,8 +1773,10 @@ function parseErrorFields(payload) {
   }
   return out;
 }
+var _decoder = new TextDecoder();
+var _encoder = new TextEncoder();
 function utf8(s) {
-  return new TextEncoder().encode(s);
+  return _encoder.encode(s);
 }
 function concat(...parts) {
   let total = 0;
@@ -1789,7 +1829,7 @@ var ValidationError = class extends DbError {
 };
 
 // src/db/postgres/connection.ts
-var PgConnection = class {
+var PgConnection = class _PgConnection {
   opts;
   timeoutSet = false;
   awaitingReady = false;
@@ -1823,11 +1863,7 @@ var PgConnection = class {
       }, this.opts.connectTimeoutMs);
       sock.once("connect", () => {
         sock.setNoDelay(true);
-        sock.write(
-          Buffer.from(
-            startupMessage({ user: this.opts.user, database: this.opts.database })
-          )
-        );
+        sock.write(startupMessage({ user: this.opts.user, database: this.opts.database }));
       });
       sock.on("data", (chunk) => this.onData(chunk));
       sock.on("error", (err) => {
@@ -1860,10 +1896,10 @@ var PgConnection = class {
   onReady = null;
   onAuthFail = null;
   expectingAuth = true;
-  authStage = "start";
   authCtx = null;
   prepared = /* @__PURE__ */ new Map();
-  // sig → stmt + 列缓存
+  // sig → stmt + 列缓存（LRU）
+  static PREPARED_MAX = 128;
   stmtSeq = 0;
   currentQuery = null;
   onData(chunk) {
@@ -1885,7 +1921,6 @@ var PgConnection = class {
           const outer = crypto2.createHash("md5").update(inner + Buffer.from(salt).toString("latin1")).digest("hex");
           this.send(passwordMessage(`md5${outer}`));
         } else if (code === 10) {
-          this.authStage = "sasl-initial";
           const nonce = crypto2.randomBytes(18).toString("base64url");
           const clientFirstBare = `n=,r=${nonce}`;
           this.authCtx = { clientNonce: nonce, clientFirstBare, serverFirst: "" };
@@ -1907,7 +1942,6 @@ var PgConnection = class {
           }
           this.authCtx.serverFirst = serverFirst;
           const clientFinal = this.scramFinal(this.authCtx);
-          this.authStage = "sasl-final";
           this.send(encodeP(utf82(clientFinal)));
         } else if (code === 12) {
           const serverFinal = new TextDecoder().decode(msg.payload.subarray(4));
@@ -1934,9 +1968,7 @@ var PgConnection = class {
         if (this.opts.statementTimeoutMs > 0 && !this.timeoutSet) {
           this.timeoutSet = true;
           this.awaitingReady = true;
-          this.socket?.write(
-            Buffer.from(queryMessage(`SET statement_timeout = ${this.opts.statementTimeoutMs}`))
-          );
+          this.socket?.write(queryMessage(`SET statement_timeout = ${this.opts.statementTimeoutMs}`));
           return;
         }
         this.onReady?.();
@@ -1948,9 +1980,8 @@ var PgConnection = class {
       case "T": {
         if (this.currentQuery) {
           this.currentQuery.columns = parseRowDescription(msg.payload);
-          const entry = this.prepared.get(
-            `${this.currentQuery.sql}|${this.currentQuery.params?.length ?? 0}`
-          );
+          const sig = `${this.currentQuery.sql}|${this.currentQuery.params?.length ?? 0}`;
+          const entry = this.getPrepared(sig);
           if (entry) entry.columns = this.currentQuery.columns;
         }
         break;
@@ -1973,7 +2004,7 @@ var PgConnection = class {
         if (this.currentQuery?.awaitingDescribe && this.currentQuery.sql !== void 0) {
           this.currentQuery.awaitingDescribe = false;
           if (this.currentQuery.prepKey && this.currentQuery.prepName) {
-            this.prepared.set(this.currentQuery.prepKey, {
+            this.setPrepared(this.currentQuery.prepKey, {
               name: this.currentQuery.prepName,
               columns: this.currentQuery.columns
             });
@@ -2057,6 +2088,24 @@ var PgConnection = class {
     const authMessage = `${ctx.clientFirstBare},${ctx.serverFirst},${clientFinalWithoutProof}`;
     return Buffer.from(hmac(serverKey, authMessage)).toString("base64");
   }
+  /** LRU 读取：命中移到尾部（最近使用），超限删最旧 */
+  getPrepared(sig) {
+    const entry = this.prepared.get(sig);
+    if (entry) {
+      this.prepared.delete(sig);
+      this.prepared.set(sig, entry);
+    }
+    return entry;
+  }
+  /** LRU 写入：刷新位置；超上限淘汰最旧（长运行服务防无限累积） */
+  setPrepared(sig, entry) {
+    this.prepared.delete(sig);
+    this.prepared.set(sig, entry);
+    if (this.prepared.size > _PgConnection.PREPARED_MAX) {
+      const oldest = this.prepared.keys().next().value;
+      if (oldest !== void 0) this.prepared.delete(oldest);
+    }
+  }
   /** 事务：BEGIN → fn(tx) → COMMIT；fn 抛错 → ROLLBACK（回滚失败吞掉，保留原始错误） */
   async transaction(fn) {
     await this.query("BEGIN");
@@ -2088,10 +2137,10 @@ var PgConnection = class {
           resolve: resolve3,
           reject
         };
-        this.socket.write(Buffer.from(queryMessage(sql)));
+        this.socket.write(queryMessage(sql));
       } else {
         const sig = `${sql}|${params.length}`;
-        let stmtEntry = this.prepared.get(sig);
+        let stmtEntry = this.getPrepared(sig);
         const encoded = encodeParams(params);
         if (!stmtEntry) {
           const name = `wf_s${++this.stmtSeq}`;
@@ -2106,9 +2155,9 @@ var PgConnection = class {
             prepKey: sig,
             prepName: name
           };
-          this.socket.write(Buffer.from(parseMessage(name, sql, params.map(() => 0))));
-          this.socket.write(Buffer.from(describeMessage("S", name)));
-          this.socket.write(Buffer.from(flushMessage()));
+          this.socket.write(parseMessage(name, sql, params.map(() => 0)));
+          this.socket.write(describeMessage("S", name));
+          this.socket.write(flushMessage());
         } else {
           this.currentQuery = {
             columns: [...stmtEntry.columns],
@@ -2119,15 +2168,15 @@ var PgConnection = class {
             params: encoded,
             awaitingDescribe: false
           };
-          this.socket.write(Buffer.from(bindMessage(stmtEntry.name, encoded)));
-          this.socket.write(Buffer.from(executeMessage()));
-          this.socket.write(Buffer.from(syncMessage()));
+          this.socket.write(bindMessage(stmtEntry.name, encoded));
+          this.socket.write(executeMessage());
+          this.socket.write(syncMessage());
         }
       }
     });
   }
   send(data) {
-    this.socket?.write(Buffer.from(data));
+    this.socket?.write(data);
   }
   notifyIdle() {
     const ws = this.waiters;
@@ -2143,7 +2192,7 @@ var PgConnection = class {
   async close() {
     const sock = this.socket;
     if (this.status === "ready" && sock) {
-      sock.write(Buffer.from(terminateMessage()));
+      sock.write(terminateMessage());
     }
     this.status = "closed";
     if (sock) sock.destroy();
@@ -2615,19 +2664,56 @@ var IncompleteError = class extends Error {
     this.name = "IncompleteError";
   }
 };
+function decodeValue(v, decodeBytes) {
+  if (v instanceof Uint8Array) return decodeBytes ? _decoder2.decode(v) : v;
+  if (Array.isArray(v)) return v.map((x) => decodeValue(x, decodeBytes));
+  return v;
+}
 function encodeCommand(args) {
-  const parts = [`*${args.length}\r
-`];
-  for (const arg of args) {
-    const s = typeof arg === "string" ? arg : arg instanceof Buffer ? arg.toString() : String(arg);
-    parts.push(`$${Buffer.byteLength(s)}\r
-${s}\r
-`);
+  const lens = new Array(args.length);
+  let total = headerLen(args.length);
+  for (let i = 0; i < args.length; i++) {
+    const arg = args[i];
+    const len = typeof arg === "string" ? Buffer.byteLength(arg) : arg instanceof Buffer ? arg.length : String(arg).length;
+    lens[i] = len;
+    total += headerLen(len) + len + 2;
+  }
+  const out = new Uint8Array(total);
+  let off = 0;
+  const head = `*${args.length}\r
+`;
+  out.set(_encoder2.encode(head), 0);
+  off = head.length;
+  for (let i = 0; i < args.length; i++) {
+    const arg = args[i];
+    const len = lens[i];
+    const lh = `$${len}\r
+`;
+    out.set(_encoder2.encode(lh), off);
+    off += lh.length;
+    if (typeof arg === "string") {
+      out.set(_encoder2.encode(arg), off);
+    } else if (arg instanceof Buffer) {
+      out.set(arg, off);
+    } else {
+      out.set(_encoder2.encode(String(arg)), off);
+    }
+    off += len;
+    out[off] = 13;
+    out[off + 1] = 10;
+    off += 2;
   }
-  return _encoder.encode(parts.join(""));
+  return out;
 }
-var _decoder = new TextDecoder();
-var _encoder = new TextEncoder();
+function headerLen(n) {
+  if (n < 10) return 4;
+  if (n < 100) return 5;
+  if (n < 1e3) return 6;
+  if (n < 1e4) return 7;
+  return 8;
+}
+var _decoder2 = new TextDecoder();
+var _encoder2 = new TextEncoder();
 var RespParser = class {
   buf = new Uint8Array(0);
   off = 0;
@@ -2701,16 +2787,15 @@ var RespParser = class {
         return new RespError(line);
       }
       case ":": {
-        const line = this.readLine();
-        return parseInt(line, 10);
+        return this.readInt();
       }
       case "$": {
-        const len = parseInt(this.readLine(), 10);
+        const len = this.readInt();
         if (len === -1) return null;
-        return this.readBulk(len);
+        return this.readBulkBytes(len);
       }
       case "*": {
-        const count = parseInt(this.readLine(), 10);
+        const count = this.readInt();
         if (count === -1) return null;
         const items = [];
         for (let i = 0; i < count; i++) items.push(this.parseValue());
@@ -2720,25 +2805,50 @@ var RespParser = class {
         throw new DbError("protocol", `unknown RESP type byte: ${type}`, { code: "RESP" });
     }
   }
+  /**
+   * 读整数（: 或 $ 长度）：扫描数字字符边算值，直到 \r\n（手动解析，免 parseInt + 字符串）。
+   * 支持负号（-1）。未读到终止符抛 IncompleteError（push 回滚）。
+   */
+  readInt() {
+    const buf = this.buf;
+    let i = this.off;
+    let neg = false;
+    if (i < buf.length && buf[i] === 45) {
+      neg = true;
+      i++;
+    }
+    let n = 0;
+    while (i < buf.length && buf[i] >= 48 && buf[i] <= 57) {
+      n = n * 10 + (buf[i] - 48);
+      i++;
+    }
+    if (i + 1 < buf.length && buf[i] === 13 && buf[i + 1] === 10) {
+      this.off = i + 2;
+      return neg ? -n : n;
+    }
+    throw new IncompleteError();
+  }
   /** 读一行（到 \r\n），返回行内容（不含 type 字节与 \r\n），并推进 off */
   readLine() {
     const idx = indexOfCRLF(this.buf, this.off);
     if (idx === -1) throw new IncompleteError();
-    const line = _decoder.decode(this.buf.subarray(this.off, idx));
+    const line = _decoder2.decode(this.buf.subarray(this.off, idx));
     this.off = idx + 2;
     return line;
   }
-  /** 读 len 字节的 bulk 内容 + \r\n */
-  readBulk(len) {
+  /** 读 len 字节的 bulk 内容 + \r\n（字节中立——不 decode，由调用方决定 string/Buffer） */
+  readBulkBytes(len) {
     if (this.buf.length - this.off < len + 2) throw new IncompleteError();
-    const value = _decoder.decode(this.buf.subarray(this.off, this.off + len));
+    const value = this.buf.subarray(this.off, this.off + len);
     this.off += len + 2;
     return value;
   }
 };
 function indexOfCRLF(buf, from = 0) {
-  for (let i = from; i < buf.length - 1; i++) {
-    if (buf[i] === 13 && buf[i + 1] === 10) return i;
+  let i = buf.indexOf(13, from);
+  while (i !== -1) {
+    if (i + 1 < buf.length && buf[i + 1] === 10) return i;
+    i = buf.indexOf(13, i + 1);
   }
   return -1;
 }
@@ -2751,6 +2861,8 @@ var RedisConnection = class {
   socket = null;
   parser = new RespParser();
   pending = [];
+  /** pending 头指针（避免 shift() O(n)——消费后定期 compact） */
+  pendingHead = 0;
   offlineQueue = [];
   subs = /* @__PURE__ */ new Map();
   psubs = /* @__PURE__ */ new Map();
@@ -2766,7 +2878,8 @@ var RedisConnection = class {
       port: options.port ?? 6379,
       retryDelayMs: options.retryDelayMs ?? 100,
       maxRetries: options.maxRetries ?? 10,
-      enableOfflineQueue: options.enableOfflineQueue ?? true
+      enableOfflineQueue: options.enableOfflineQueue ?? true,
+      maxOfflineQueue: options.maxOfflineQueue ?? 5e3
     };
   }
   /** 建立连接并等待 ready。重连失败（超过 maxRetries）抛 ConnectionError。 */
@@ -2816,10 +2929,10 @@ var RedisConnection = class {
     });
   }
   handleDisconnect(err) {
-    const queue = this.pending;
+    const queue = this.pending.slice(this.pendingHead);
     this.pending = [];
-    const retryErr = err instanceof ConnectionError ? err : err;
-    for (const p of queue) p.reject(retryErr);
+    this.pendingHead = 0;
+    for (const p of queue) p.reject(err);
     if (this.closed || this.status === "closed") return;
     this.retries++;
     if (this.opts.maxRetries > 0 && this.retries > this.opts.maxRetries) {
@@ -2837,38 +2950,52 @@ var RedisConnection = class {
   onData(chunk) {
     try {
       const values = this.parser.pushAll(chunk);
-      for (const value of values) {
-        if (Array.isArray(value) && typeof value[0] === "string" && PUSH_TYPES.has(value[0])) {
-          this.dispatchSubscribe(value);
+      for (const raw of values) {
+        const first = Array.isArray(raw) && raw.length > 0 ? decodeValue(raw[0], true) : void 0;
+        if (typeof first === "string" && PUSH_TYPES.has(first)) {
+          this.dispatchSubscribe(decodeValue(raw, true));
           continue;
         }
-        const p = this.pending.shift();
+        const p = this.pending[this.pendingHead++];
         if (!p) break;
-        if (value instanceof RespError) p.reject(value);
-        else p.resolve(value);
+        if (raw instanceof RespError) p.reject(raw);
+        else p.resolve(decodeValue(raw, !p.asBuffer));
+      }
+      if (this.pendingHead > 64 && this.pendingHead * 2 > this.pending.length) {
+        this.pending = this.pending.slice(this.pendingHead);
+        this.pendingHead = 0;
       }
     } catch (e) {
-      const queue = this.pending;
+      const queue = this.pending.slice(this.pendingHead);
       this.pending = [];
+      this.pendingHead = 0;
       for (const q of queue) q.reject(e);
       this.socket?.destroy();
     }
   }
-  /** 发送命令并等待响应（单连接严格有序）。未 ready 时入离线队列（enableOfflineQueue）或拒绝。 */
+  /**
+   * 发送命令并等待响应（单连接严格有序）。未 ready 时入离线队列（enableOfflineQueue）或拒绝。
+   * opts.asBuffer=true：响应保留原始字节（Uint8Array）——getBuffer 等二进制场景。
+   */
   command(name, ...args) {
+    const last = args[args.length - 1];
+    const opts = typeof last === "object" && last !== null && !(last instanceof Uint8Array) ? args.pop() : void 0;
     if (this.status === "ready" && this.socket) {
-      return this.sendNow(name, args);
+      return this.sendNow(name, args, opts?.asBuffer);
     }
     if (this.closed || this.status === "closed" || !this.opts.enableOfflineQueue) {
       return Promise.reject(new ConnectionError("redis: not connected"));
     }
+    if (this.offlineQueue.length >= this.opts.maxOfflineQueue) {
+      return Promise.reject(new ConnectionError(`redis: offline queue full (${this.opts.maxOfflineQueue})`));
+    }
     return new Promise((resolve3, reject) => {
-      this.offlineQueue.push({ name, args, resolve: resolve3, reject });
+      this.offlineQueue.push({ name, args, resolve: resolve3, reject, asBuffer: opts?.asBuffer });
     });
   }
-  sendNow(name, args) {
+  sendNow(name, args, asBuffer) {
     return new Promise((resolve3, reject) => {
-      this.pending.push({ resolve: resolve3, reject });
+      this.pending.push({ resolve: resolve3, reject, asBuffer });
       this.socket.write(encodeCommand([name, ...args]));
     });
   }
@@ -2876,7 +3003,7 @@ var RedisConnection = class {
     const queue = this.offlineQueue;
     this.offlineQueue = [];
     for (const q of queue) {
-      this.sendNow(q.name, q.args).then(q.resolve, q.reject);
+      this.sendNow(q.name, q.args, q.asBuffer).then(q.resolve, q.reject);
     }
   }
   /** 批量执行：一次 write 发送所有命令字节，响应按序路由（管道） */
@@ -2934,15 +3061,16 @@ var RedisConnection = class {
       clearTimeout(this.reconnectTimer);
       this.reconnectTimer = null;
     }
-    const queue = this.pending;
+    const queue = this.pending.slice(this.pendingHead);
     this.pending = [];
+    this.pendingHead = 0;
     for (const p of queue) p.reject(new ConnectionError("redis: connection closed"));
+    const oq = this.offlineQueue;
+    this.offlineQueue = [];
+    for (const q of oq) q.reject(new ConnectionError("redis: connection closed"));
     const sock = this.socket;
     this.socket = null;
-    if (sock) {
-      sock.destroy();
-      await new Promise((r) => setTimeout(r, 0));
-    }
+    sock?.destroy();
   }
   get connected() {
     return this.status === "ready";
@@ -2961,7 +3089,7 @@ var RedisClient = class _RedisClient {
     await conn.connect();
     return new _RedisClient(conn);
   }
-  /** 底层命令透传（RESP 值） */
+  /** 底层命令透传（RESP 值）；Buffer 参数字节原样发送 */
   command(name, ...args) {
     return this.conn.command(name, ...args);
   }
@@ -2970,6 +3098,15 @@ var RedisClient = class _RedisClient {
     const v = await this.conn.command("GET", key);
     return v === null ? null : String(v);
   }
+  /**
+   * 二进制安全读取：返回原始字节（Uint8Array），不经过字符串解码。
+   * 用于缓存二进制 payload（序列化字节、图片等）。key 不存在返回 null。
+   */
+  async getBuffer(key) {
+    const v = await this.conn.command("GET", key, { asBuffer: true });
+    if (v === null) return null;
+    return v instanceof Uint8Array ? v : new TextEncoder().encode(String(v));
+  }
   /**
    * SET。ttl 秒可省略；传入即安全生效（内部转 SET key val EX ttl）。
    */
@@ -3106,6 +3243,11 @@ var RedisPool = class _RedisPool {
     await this.ensure();
     return this.next().get(this.k(key));
   }
+  /** 二进制安全读取（原始字节，不解码） */
+  async getBuffer(key) {
+    await this.ensure();
+    return this.next().getBuffer(this.k(key));
+  }
   async set(key, value, ttl) {
     await this.ensure();
     return this.next().set(this.k(key), value, ttl);

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "weifuwu",
   "type": "module",
-  "version": "0.56.0",
+  "version": "0.56.1",
   "description": "AI SaaS framework — (req, ctx) => Response",
   "exports": {
     ".": {