@lakutata/nats 2.0.1 → 2.1.0

package/CHANGELOG.md

@@ -3,6 +3,17 @@
 All notable changes to this project will be documented in this file.
 See [Conventional Commits](https://conventionalcommits.org) for commit guidelines.
 
+# [2.1.0](https://github.com/lakutata/lakutata-packages/compare/@lakutata/nats@2.0.1...@lakutata/nats@2.1.0) (2026-06-21)
+
+
+### Features
+
+* **nats:** add bulk data transfer and service proxy retry ([107ad48](https://github.com/lakutata/lakutata-packages/commit/107ad48219857f7f7e13dcfd728d1f92438f10a9)), closes [#2](https://github.com/lakutata/lakutata-packages/issues/2) [#3](https://github.com/lakutata/lakutata-packages/issues/3) [#7](https://github.com/lakutata/lakutata-packages/issues/7)
+
+
+
+
+
 ## [2.0.1](https://github.com/lakutata/lakutata-packages/compare/@lakutata/nats@2.0.0...@lakutata/nats@2.0.1) (2026-03-02)
 
 **Note:** Version bump only for package @lakutata/nats

package/dist/CommonExports.d.ts

@@ -14,4 +14,6 @@ export { NatsInternalServerException } from './exceptions/NatsInternalServerExce
 export { NatsNoRespondersAvailableException } from './exceptions/NatsNoRespondersAvailableException';
 export { NatsNotFoundException } from './exceptions/NatsNotFoundException';
 export { NatsRequestTimeoutException } from './exceptions/NatsRequestTimeoutException';
+export { ServiceInvokeException } from './exceptions/ServiceInvokeException';
+export { NatsBulkException } from './exceptions/NatsBulkException';
 //# sourceMappingURL=CommonExports.d.ts.map

package/dist/CommonExports.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"CommonExports.d.ts","sourceRoot":"","sources":["../src/CommonExports.ts"],"names":[],"mappings":"AAAA,OAAO,EAAC,0BAA0B,EAAC,MAAM,0CAA0C,CAAA;AACnF,OAAO,EAAC,YAAY,EAAE,iBAAiB,EAAE,KAAK,wBAAwB,EAAC,MAAM,0BAA0B,CAAA;AACvG,OAAO,EAAC,eAAe,EAAC,MAAM,MAAM,CAAA;AACpC,OAAO,EAAC,IAAI,EAAE,sBAAsB,EAAC,MAAM,mBAAmB,CAAA;AAC9D,OAAO,EAAC,SAAS,EAAC,MAAM,oBAAoB,CAAA;AAC5C,OAAO,EAAC,gBAAgB,EAAC,MAAM,2BAA2B,CAAA;AAC1D,OAAO,EAAC,WAAW,EAAC,MAAM,MAAM,CAAA;AAChC,YAAY,EAAC,gBAAgB,EAAC,MAAM,0BAA0B,CAAA;AAC9D,YAAY,EAAC,YAAY,EAAE,KAAK,EAAC,MAAM,MAAM,CAAA;AAC7C,YAAY,EAAC,iBAAiB,EAAC,MAAM,gCAAgC,CAAA;AACrE,OAAO,EAAC,uBAAuB,EAAC,MAAM,sCAAsC,CAAA;AAC5E,OAAO,EAAC,sBAAsB,EAAC,MAAM,qCAAqC,CAAA;AAC1E,OAAO,EAAC,2BAA2B,EAAC,MAAM,0CAA0C,CAAA;AACpF,OAAO,EAAC,kCAAkC,EAAC,MAAM,iDAAiD,CAAA;AAClG,OAAO,EAAC,qBAAqB,EAAC,MAAM,oCAAoC,CAAA;AACxE,OAAO,EAAC,2BAA2B,EAAC,MAAM,0CAA0C,CAAA"}
+{"version":3,"file":"CommonExports.d.ts","sourceRoot":"","sources":["../src/CommonExports.ts"],"names":[],"mappings":"AAAA,OAAO,EAAC,0BAA0B,EAAC,MAAM,0CAA0C,CAAA;AACnF,OAAO,EAAC,YAAY,EAAE,iBAAiB,EAAE,KAAK,wBAAwB,EAAC,MAAM,0BAA0B,CAAA;AACvG,OAAO,EAAC,eAAe,EAAC,MAAM,MAAM,CAAA;AACpC,OAAO,EAAC,IAAI,EAAE,sBAAsB,EAAC,MAAM,mBAAmB,CAAA;AAC9D,OAAO,EAAC,SAAS,EAAC,MAAM,oBAAoB,CAAA;AAC5C,OAAO,EAAC,gBAAgB,EAAC,MAAM,2BAA2B,CAAA;AAC1D,OAAO,EAAC,WAAW,EAAC,MAAM,MAAM,CAAA;AAChC,YAAY,EAAC,gBAAgB,EAAC,MAAM,0BAA0B,CAAA;AAC9D,YAAY,EAAC,YAAY,EAAE,KAAK,EAAC,MAAM,MAAM,CAAA;AAC7C,YAAY,EAAC,iBAAiB,EAAC,MAAM,gCAAgC,CAAA;AACrE,OAAO,EAAC,uBAAuB,EAAC,MAAM,sCAAsC,CAAA;AAC5E,OAAO,EAAC,sBAAsB,EAAC,MAAM,qCAAqC,CAAA;AAC1E,OAAO,EAAC,2BAA2B,EAAC,MAAM,0CAA0C,CAAA;AACpF,OAAO,EAAC,kCAAkC,EAAC,MAAM,iDAAiD,CAAA;AAClG,OAAO,EAAC,qBAAqB,EAAC,MAAM,oCAAoC,CAAA;AACxE,OAAO,EAAC,2BAA2B,EAAC,MAAM,0CAA0C,CAAA;AACpF,OAAO,EAAC,sBAAsB,EAAC,MAAM,qCAAqC,CAAA;AAC1E,OAAO,EAAC,iBAAiB,EAAC,MAAM,gCAAgC,CAAA"}

package/dist/CommonExports.js

@@ -1,6 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.NatsRequestTimeoutException = exports.NatsNotFoundException = exports.NatsNoRespondersAvailableException = exports.NatsInternalServerException = exports.NatsForbiddenException = exports.NatsBadRequestException = exports.StringCodec = exports.MessagePackCodec = exports.JSONCodec = exports.buildNatsClientOptions = exports.NATS = exports.RetentionPolicy = exports.BuildServiceProxy = exports.ServiceProxy = exports.SetupNatsServiceEntrypoint = void 0;
+exports.NatsBulkException = exports.ServiceInvokeException = exports.NatsRequestTimeoutException = exports.NatsNotFoundException = exports.NatsNoRespondersAvailableException = exports.NatsInternalServerException = exports.NatsForbiddenException = exports.NatsBadRequestException = exports.StringCodec = exports.MessagePackCodec = exports.JSONCodec = exports.buildNatsClientOptions = exports.NATS = exports.RetentionPolicy = exports.BuildServiceProxy = exports.ServiceProxy = exports.SetupNatsServiceEntrypoint = void 0;
 var SetupNatsServiceEntrypoint_1 = require("./entrypoints/SetupNatsServiceEntrypoint");
 Object.defineProperty(exports, "SetupNatsServiceEntrypoint", { enumerable: true, get: function () { return SetupNatsServiceEntrypoint_1.SetupNatsServiceEntrypoint; } });
 var ServiceProxy_1 = require("./providers/ServiceProxy");
@@ -29,3 +29,7 @@ var NatsNotFoundException_1 = require("./exceptions/NatsNotFoundException");
 Object.defineProperty(exports, "NatsNotFoundException", { enumerable: true, get: function () { return NatsNotFoundException_1.NatsNotFoundException; } });
 var NatsRequestTimeoutException_1 = require("./exceptions/NatsRequestTimeoutException");
 Object.defineProperty(exports, "NatsRequestTimeoutException", { enumerable: true, get: function () { return NatsRequestTimeoutException_1.NatsRequestTimeoutException; } });
+var ServiceInvokeException_1 = require("./exceptions/ServiceInvokeException");
+Object.defineProperty(exports, "ServiceInvokeException", { enumerable: true, get: function () { return ServiceInvokeException_1.ServiceInvokeException; } });
+var NatsBulkException_1 = require("./exceptions/NatsBulkException");
+Object.defineProperty(exports, "NatsBulkException", { enumerable: true, get: function () { return NatsBulkException_1.NatsBulkException; } });

package/dist/components/NATS.d.ts

@@ -1,5 +1,5 @@
 import { Application, Component, ComponentOptionsBuilder } from 'lakutata';
-import { type Codec, Subscription } from 'nats';
+import { type Codec, Subscription, type ObjectStoreStatus } from 'nats';
 import { SubscribeOptions } from '../types/SubscribeOptions';
 import { NatsClientOptions } from '../interfaces/NatsClientOptions';
 export declare const buildNatsClientOptions: ComponentOptionsBuilder<NatsClientOptions>;
@@ -94,6 +94,27 @@ export declare class NATS extends Component {
      * @protected
      */
     protected readonly reconnect?: boolean;
+    /**
+     * 是否启用 bulk 大数据旁路:启用后启动时建第二条独立连接 + 准备 Object Store。
+     * @default true
+     * @protected
+     */
+    protected readonly bulk?: boolean;
+    /**
+     * bulk Object Store bucket 名,默认 lkt-bulk-${name}。
+     * @protected
+     */
+    protected readonly bulkBucket?: string;
+    /**
+     * bulk 对象 TTL(毫秒),默认 5 分钟。
+     * @protected
+     */
+    protected readonly bulkTTL?: number;
+    /**
+     * bulk bucket 副本数,默认 1(中转数据用完即弃,不需要高可用副本)。
+     * @protected
+     */
+    protected readonly bulkReplicas?: number;
     /**
      * Service event subscription map
      * @protected
@@ -109,6 +130,13 @@ export declare class NATS extends Component {
      * @protected
      */
     protected destroy(): Promise<void>;
+    /**
+     * 优雅停机:drain 停止接收新消息、把 in-flight 处理完、flush 出站后再关闭,
+     * 这样 K8s 滚动升级/缩容时正在处理的请求不被硬切断;drain 失败兜底强制关闭。
+     * @param conn
+     * @private
+     */
+    private drainConnection;
     /**
      * Publishes the specified data to the specified subject.
      * @param subject
@@ -135,6 +163,59 @@ export declare class NATS extends Component {
      * @param subscribeOptions
      */
     subscribe(subject: string, callback: (data: any) => any | Promise<any>, subscribeOptions?: SubscribeOptions): Subscription;
+    /**
+     * 安全地发出 error 事件:仅在存在监听器时发出。
+     * Node EventEmitter 在没有 'error' 监听器时 emit('error') 会抛出,
+     * 在异步回调里那会变成 unhandled rejection,所以这里加监听器守卫。
+     * @param error
+     * @protected
+     */
+    protected emitError(error: any): void;
+    /**
+     * 是否启用了 bulk 旁路(连接 + Object Store 均就绪)
+     */
+    get bulkEnabled(): boolean;
+    /**
+     * 走 bulk 的字节阈值 = server max_payload × 0.9(从连接 info 自动读,跟随集群配置)
+     */
+    get bulkThreshold(): number;
+    /**
+     * server 是否支持消息 header(从连接 info)
+     */
+    get headersSupported(): boolean;
+    /**
+     * 把一块字节存入 Object Store,返回 objId(供引用中转)。
+     * @param bytes
+     */
+    putBulk(bytes: Uint8Array): Promise<string>;
+    /**
+     * 从 Object Store 取回一块字节。
+     * @param objId
+     */
+    getBulk(objId: string): Promise<Uint8Array>;
+    /**
+     * 删除 Object Store 中的对象(用完即清,失败由 TTL 兜底)。
+     * @param objId
+     */
+    deleteBulk(objId: string): Promise<void>;
+    /**
+     * 返回 bulk Object Store 的运行时状态(bucket/ttl/replicas/storage/size 等);未启用 bulk 返回 undefined。
+     */
+    bulkStatus(): Promise<ObjectStoreStatus | undefined>;
+    /**
+     * 打包待发送 payload:编码后若对端支持中转且超阈值,存入 Object Store 改发小引用。
+     * @param payload
+     * @param peerSupportsBulk 对端是否支持引用中转(不支持只能直传)
+     * @private
+     */
+    private packPayload;
+    /**
+     * 解包收到的字节:若是引用,从 Object Store 取回真实字节再解码(取回后即删,失败靠 TTL 兜底)。
+     * @param bytes
+     * @param isRef
+     * @private
+     */
+    private unpackPayload;
     /**
      * Emit service event
      * @param eventName

package/dist/components/NATS.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"NATS.d.ts","sourceRoot":"","sources":["../../src/components/NATS.ts"],"names":[],"mappings":"AAAA,OAAO,EACH,WAAW,EACX,SAAS,EAET,uBAAuB,EAE1B,MAAM,UAAU,CAAA;AAEjB,OAAO,EAAC,KAAK,KAAK,EAAgC,YAAY,EAAC,MAAM,MAAM,CAAA;AAC3E,OAAO,EAAC,gBAAgB,EAAC,MAAM,2BAA2B,CAAA;AAO1D,OAAO,EAAC,iBAAiB,EAAC,MAAM,iCAAiC,CAAA;AAIjE,eAAO,MAAM,sBAAsB,EAAE,uBAAuB,CAAC,iBAAiB,CAkB7E,CAAA;AAED,qBAAa,IAAK,SAAQ,SAAS;;IAC/B;;;OAGG;IAEH,SAAS,CAAC,QAAQ,CAAC,GAAG,EAAE,WAAW,CAAA;IAEnC;;;OAGG;IAEH,SAAS,CAAC,QAAQ,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,EAAE,CAAA;IAE7C;;;OAGG;IAKH,SAAS,CAAC,QAAQ,CAAC,KAAK,EAAE,KAAK,CAAC,OAAO,CAAC,CAAA;IAExC;;;;OAIG;IAEH,SAAS,CAAC,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,CAAA;IAEnC;;;;OAIG;IAEH,SAAS,CAAC,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,CAAA;IAEjC;;;OAGG;IAEH,SAAS,CAAC,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,CAAA;IAEhC;;;OAGG;IAEH,SAAS,CAAC,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,CAAA;IAEhC;;;;OAIG;IAEH,SAAS,CAAC,QAAQ,CAAC,KAAK,CAAC,EAAE,OAAO,CAAA;IAElC;;;;OAIG;IAEH,SAAS,CAAC,QAAQ,CAAC,UAAU,CAAC,EAAE,MAAM,CAAA;IAEtC;;;;;;OAMG;IAEH,SAAS,CAAC,QAAQ,CAAC,oBAAoB,CAAC,EAAE,MAAM,CAAA;IAEhD;;;;OAIG;IAEH,SAAS,CAAC,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,CAAA;IAEhC;;;;;OAKG;IAEH,SAAS,CAAC,QAAQ,CAAC,MAAM,CAAC,EAAE,OAAO,CAAA;IAEnC;;;OAGG;IAEH,SAAS,CAAC,QAAQ,CAAC,WAAW,CAAC,EAAE,OAAO,CAAA;IAExC;;;;;OAKG;IAEH,SAAS,CAAC,QAAQ,CAAC,YAAY,CAAC,EAAE,MAAM,CAAA;IAExC;;;;;OAKG;IAEH,SAAS,CAAC,QAAQ,CAAC,SAAS,CAAC,EAAE,OAAO,CAAA;IAEtC;;;OAGG;IACH,SAAS,CAAC,QAAQ,CAAC,2BAA2B,EAAE,GAAG,CAAC,MAAM,EAAE,GAAG,CAAC,CAAC,GAAG,IAAI,EAAE,GAAG,EAAE,KAAK,IAAI,EAAE,YAAY,CAAC,CAAC,CAAY;IAQpH;;;OAGG;cACa,IAAI,IAAI,OAAO,CAAC,IAAI,CAAC;IAkBrC;;;OAGG;cACa,OAAO,IAAI,OAAO,CAAC,IAAI,CAAC;IAIxC;;;;OAIG;IACI,OAAO,CAAC,OAAO,EAAE,MAAM,EAAE,OAAO,EAAE,GAAG,GAAG,IAAI;IAInD;;;;;;;;;OASG;IACU,OAAO,CAAC,OAAO,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,GAAG,EAAE,OAAO,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,GAAG,CAAC;IA4BpF;;;;;;;OAOG;IACI,SAAS,CAAC,OAAO,EAAE,MAAM,EAAE,QAAQ,EAAE,CAAC,IAAI,EAAE,GAAG,KAAK,GAAG,GAAG,OAAO,CAAC,GAAG,CAAC,EAAE,gBAAgB,CAAC,EAAE,gBAAgB,GAAG,YAAY;IAwBjI;;;;OAIG;IACI,gBAAgB,CAAC,SAAS,EAAE,MAAM,EAAE,GAAG,IAAI,EAAE,GAAG,EAAE,GAAG,IAAI;IAMhE;;;;;;OAMG;IACI,cAAc,CAAC,SAAS,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,EAAE,QAAQ,EAAE,CAAC,GAAG,IAAI,EAAE,GAAG,EAAE,KAAK,IAAI,EAAE,wBAAwB,GAAE,OAAe,GAAG,IAAI;IAYhJ;;;;;OAKG;IACI,gBAAgB,CAAC,SAAS,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,EAAE,QAAQ,EAAE,CAAC,GAAG,IAAI,EAAE,GAAG,EAAE,KAAK,IAAI,GAAG,IAAI;IAavG;;;;;OAKG;IACI,eAAe,CAAC,SAAS,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,EAAE,QAAQ,CAAC,EAAE,CAAC,GAAG,IAAI,EAAE,GAAG,EAAE,KAAK,IAAI,GAAG,IAAI;CAW1G"}
+{"version":3,"file":"NATS.d.ts","sourceRoot":"","sources":["../../src/components/NATS.ts"],"names":[],"mappings":"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"}

package/dist/components/NATS.js

@@ -19,8 +19,13 @@ const NatsNotFoundException_1 = require("../exceptions/NatsNotFoundException");
 const NatsRequestTimeoutException_1 = require("../exceptions/NatsRequestTimeoutException");
 const NatsNoRespondersAvailableException_1 = require("../exceptions/NatsNoRespondersAvailableException");
 const NatsInternalServerException_1 = require("../exceptions/NatsInternalServerException");
+const NatsBulkException_1 = require("../exceptions/NatsBulkException");
 const ServiceEventCodec_1 = require("../lib/ServiceEventCodec");
 const MessagePackCodec_1 = require("../codecs/MessagePackCodec");
+const node_crypto_1 = require("node:crypto");
+// bulk 中转协议头(放 header,不污染 payload)
+const HDR_BULK = 'X-Lkt-Bulk'; // 能力声明:本端支持 bulk 引用中转
+const HDR_REF = 'X-Lkt-Ref'; // 标记:payload 是 Object Store 引用 {__ref}
 const buildNatsClientOptions = (options) => {
     return {
         class: NATS,
@@ -37,7 +42,11 @@ const buildNatsClientOptions = (options) => {
         noEcho: options.noEcho,
         noRandomize: options.noRandomize,
         pingInterval: options.pingInterval,
-        reconnect: options.reconnect
+        reconnect: options.reconnect,
+        bulk: options.bulk,
+        bulkBucket: options.bulkBucket,
+        bulkTTL: options.bulkTTL,
+        bulkReplicas: options.bulkReplicas
     };
 };
 exports.buildNatsClientOptions = buildNatsClientOptions;
@@ -49,18 +58,36 @@ class NATS extends lakutata_1.Component {
          * @protected
          */
         this.serviceEventSubscriptionMap = new Map();
+        /**
+         * 缓存对端(按 subject)是否支持 bulk 中转,从对方响应/请求的能力声明 header 学到。
+         * 用于请求侧判断对端:已知支持才发引用,未知/不支持则直传(向后兼容)。
+         * @private
+         */
+        this.#peerCapabilityCache = new Map();
     }
     /**
      * NATS client instance
      * @private
      */
     #conn;
+    /**
+     * bulk 连接与 Object Store(仅 bulk 启用时存在)
+     * @private
+     */
+    #bulkConn;
+    #objectStore;
+    /**
+     * 缓存对端(按 subject)是否支持 bulk 中转,从对方响应/请求的能力声明 header 学到。
+     * 用于请求侧判断对端:已知支持才发引用,未知/不支持则直传(向后兼容)。
+     * @private
+     */
+    #peerCapabilityCache;
     /**
      * Initializer
      * @protected
      */
     async init() {
-        this.#conn = await (0, nats_1.connect)({
+        const connectOptions = {
             servers: this.servers,
             user: this.user,
             pass: this.pass,
@@ -74,14 +101,50 @@ class NATS extends lakutata_1.Component {
             noRandomize: this.noRandomize,
             pingInterval: this.pingInterval,
             reconnect: this.reconnect
-        });
+        };
+        this.#conn = await (0, nats_1.connect)(connectOptions);
+        if (this.bulk) {
+            // 用同一套配置再开一条【独立】连接专供大数据,避免大对象传输堵塞 core RPC 连接;
+            // 并 get-or-create 一个 Object Store bucket 做大对象中转(短 TTL 自动清理)。
+            this.#bulkConn = await (0, nats_1.connect)({
+                ...connectOptions,
+                name: this.name ? `${this.name}-bulk` : undefined
+            });
+            const bucket = this.bulkBucket ?? `lkt-bulk-${this.name ?? 'default'}`;
+            this.#objectStore = await this.#bulkConn.jetstream().views.os(bucket, {
+                storage: nats_1.StorageType.File,
+                replicas: this.bulkReplicas ?? 1,
+                ttl: (0, nats_1.nanos)(this.bulkTTL ?? 5 * 60 * 1000)
+            });
+        }
     }
     /**
      * Destroyer
      * @protected
      */
     async destroy() {
-        await this.#conn.close();
+        await this.drainConnection(this.#conn);
+        if (this.#bulkConn)
+            await this.drainConnection(this.#bulkConn);
+    }
+    /**
+     * 优雅停机:drain 停止接收新消息、把 in-flight 处理完、flush 出站后再关闭,
+     * 这样 K8s 滚动升级/缩容时正在处理的请求不被硬切断;drain 失败兜底强制关闭。
+     * @param conn
+     * @private
+     */
+    async drainConnection(conn) {
+        try {
+            await conn.drain();
+        }
+        catch {
+            try {
+                await conn.close();
+            }
+            catch {
+                // 连接已不可用,忽略
+            }
+        }
     }
     /**
      * Publishes the specified data to the specified subject.
@@ -102,9 +165,19 @@ class NATS extends lakutata_1.Component {
      * @param timeout
      */
     async request(subject, payload, timeout) {
+        const reqHeaders = (0, nats_1.headers)();
+        if (this.bulkEnabled)
+            reqHeaders.set(HDR_BULK, '1'); // 仅本端启用 bulk 时声明能力
+        const peerSupports = this.#peerCapabilityCache.get(subject) === true;
+        const packed = await this.packPayload(payload, peerSupports);
+        if (packed.isRef)
+            reqHeaders.set(HDR_REF, '1');
         try {
-            const response = await this.#conn.request(subject, this.codec.encode(payload), { timeout: timeout ? timeout : 0 });
-            return this.codec.decode(response.data);
+            const response = await this.#conn.request(subject, packed.bytes, { timeout: timeout ? timeout : 0, headers: reqHeaders });
+            // 双向协商:从响应学习对端是否支持中转
+            this.#peerCapabilityCache.set(subject, response.headers?.get(HDR_BULK) === '1');
+            // 还原响应(可能是 Object Store 引用)
+            return await this.unpackPayload(response.data, response.headers?.get(HDR_REF) === '1');
         }
         catch (e) {
             if (e.code) {
@@ -116,6 +189,7 @@ class NATS extends lakutata_1.Component {
                     case '404':
                         throw new NatsNotFoundException_1.NatsNotFoundException();
                     case '408':
+                    case 'TIMEOUT':
                         throw new NatsRequestTimeoutException_1.NatsRequestTimeoutException();
                     case '503':
                         throw new NatsNoRespondersAvailableException_1.NatsNoRespondersAvailableException();
@@ -129,6 +203,11 @@ class NATS extends lakutata_1.Component {
                 throw e;
             }
         }
+        finally {
+            // 请求引用对象:服务端已取回(响应已返回),删除;失败靠 TTL 兜底
+            if (packed.objId)
+                this.deleteBulk(packed.objId).catch(() => undefined);
+        }
     }
     /**
      * Subscribe expresses interest in the specified subject. The subject may
@@ -143,26 +222,169 @@ class NATS extends lakutata_1.Component {
             queue: subscribeOptions?.queue,
             max: subscribeOptions?.max
         });
+        const handleMessage = async (msg) => {
+            try {
+                // 入站:若标记为引用,从 Object Store 取回真实 payload(对小消息/event 透明)
+                const data = await this.unpackPayload(msg.data, msg.headers?.get(HDR_REF) === '1');
+                const result = await callback(data);
+                // 仅当消息是请求(带 reply)时才回响应;publish/event 无 reply,跳过。
+                if (msg.reply) {
+                    const respHeaders = (0, nats_1.headers)();
+                    if (this.bulkEnabled)
+                        respHeaders.set(HDR_BULK, '1'); // 仅本端启用 bulk 时声明能力
+                    // 请求方是否支持中转 → 决定大响应能否走引用
+                    const clientSupports = msg.headers?.get(HDR_BULK) === '1';
+                    const packed = await this.packPayload(result, clientSupports);
+                    if (packed.isRef)
+                        respHeaders.set(HDR_REF, '1');
+                    msg.respond(packed.bytes, { headers: respHeaders });
+                }
+            }
+            catch (e) {
+                this.emitError(e);
+                // 若是请求且上层提供了错误响应工厂,回标准失败响应(直传 + 能力声明),避免请求方挂到超时。
+                if (msg.reply && subscribeOptions?.errorResponse) {
+                    try {
+                        const errHeaders = (0, nats_1.headers)();
+                        if (this.bulkEnabled)
+                            errHeaders.set(HDR_BULK, '1');
+                        const errorPayload = subscribeOptions.errorResponse(e);
+                        if (errorPayload !== undefined)
+                            msg.respond(this.codec.encode(errorPayload), { headers: errHeaders });
+                    }
+                    catch (encodeError) {
+                        this.emitError(encodeError);
+                    }
+                }
+            }
+        };
         if (subscribeOptions?.iterator) {
             setImmediate(async () => {
                 for await (const msg of subscription) {
-                    const data = this.codec.decode(msg.data);
-                    const result = await callback(data);
-                    msg.respond(this.codec.encode(result));
+                    await handleMessage(msg);
                 }
             });
         }
         else {
             subscription.callback = async (err, msg) => {
-                if (err)
-                    this.emit('error', err);
-                const data = this.codec.decode(msg.data);
-                const result = await callback(data);
-                msg.respond(this.codec.encode(result));
+                // nats.js 在订阅级错误时以 (err, {}) 回调,此时 msg 为空对象无法处理,上报后返回。
+                if (err) {
+                    this.emitError(err);
+                    return;
+                }
+                await handleMessage(msg);
             };
         }
         return subscription;
     }
+    /**
+     * 安全地发出 error 事件:仅在存在监听器时发出。
+     * Node EventEmitter 在没有 'error' 监听器时 emit('error') 会抛出,
+     * 在异步回调里那会变成 unhandled rejection,所以这里加监听器守卫。
+     * @param error
+     * @protected
+     */
+    emitError(error) {
+        if (this.listenerCount('error') > 0)
+            this.emit('error', error);
+    }
+    /**
+     * 是否启用了 bulk 旁路(连接 + Object Store 均就绪)
+     */
+    get bulkEnabled() {
+        return !!this.bulk && !!this.#objectStore;
+    }
+    /**
+     * 走 bulk 的字节阈值 = server max_payload × 0.9(从连接 info 自动读,跟随集群配置)
+     */
+    get bulkThreshold() {
+        const maxPayload = this.#conn.info?.max_payload ?? 1024 * 1024;
+        return Math.floor(maxPayload * 0.9);
+    }
+    /**
+     * server 是否支持消息 header(从连接 info)
+     */
+    get headersSupported() {
+        return this.#conn.info?.headers === true;
+    }
+    /**
+     * 把一块字节存入 Object Store,返回 objId(供引用中转)。
+     * @param bytes
+     */
+    async putBulk(bytes) {
+        if (!this.#objectStore)
+            throw new NatsBulkException_1.NatsBulkException('bulk channel is not enabled');
+        const objId = (0, node_crypto_1.randomUUID)();
+        try {
+            await this.#objectStore.putBlob({ name: objId }, bytes);
+        }
+        catch (e) {
+            throw new NatsBulkException_1.NatsBulkException(`bulk put failed: ${e?.message ?? e}`);
+        }
+        return objId;
+    }
+    /**
+     * 从 Object Store 取回一块字节。
+     * @param objId
+     */
+    async getBulk(objId) {
+        if (!this.#objectStore)
+            throw new NatsBulkException_1.NatsBulkException('bulk channel is not enabled');
+        let data;
+        try {
+            data = await this.#objectStore.getBlob(objId);
+        }
+        catch (e) {
+            throw new NatsBulkException_1.NatsBulkException(`bulk get failed: ${e?.message ?? e}`);
+        }
+        if (data === null)
+            throw new NatsBulkException_1.NatsBulkException(`bulk object not found: ${objId}`);
+        return data;
+    }
+    /**
+     * 删除 Object Store 中的对象(用完即清,失败由 TTL 兜底)。
+     * @param objId
+     */
+    async deleteBulk(objId) {
+        if (!this.#objectStore)
+            return;
+        await this.#objectStore.delete(objId);
+    }
+    /**
+     * 返回 bulk Object Store 的运行时状态(bucket/ttl/replicas/storage/size 等);未启用 bulk 返回 undefined。
+     */
+    async bulkStatus() {
+        return this.#objectStore?.status();
+    }
+    /**
+     * 打包待发送 payload:编码后若对端支持中转且超阈值,存入 Object Store 改发小引用。
+     * @param payload
+     * @param peerSupportsBulk 对端是否支持引用中转(不支持只能直传)
+     * @private
+     */
+    async packPayload(payload, peerSupportsBulk) {
+        const bytes = this.codec.encode(payload);
+        if (peerSupportsBulk && this.bulkEnabled && bytes.length >= this.bulkThreshold) {
+            const objId = await this.putBulk(bytes);
+            return { bytes: this.codec.encode({ __ref: objId }), isRef: true, objId };
+        }
+        return { bytes, isRef: false };
+    }
+    /**
+     * 解包收到的字节:若是引用,从 Object Store 取回真实字节再解码(取回后即删,失败靠 TTL 兜底)。
+     * @param bytes
+     * @param isRef
+     * @private
+     */
+    async unpackPayload(bytes, isRef) {
+        if (isRef) {
+            const ref = this.codec.decode(bytes);
+            const realBytes = await this.getBulk(ref.__ref);
+            this.deleteBulk(ref.__ref).catch(() => undefined);
+            return this.codec.decode(realBytes);
+        }
+        return this.codec.decode(bytes);
+    }
     /**
      * Emit service event
      * @param eventName
@@ -299,3 +521,19 @@ __decorate([
     (0, di_1.Configurable)(lakutata_1.DTO.Boolean().optional().default(true)),
     __metadata("design:type", Boolean)
 ], NATS.prototype, "reconnect", void 0);
+__decorate([
+    (0, di_1.Configurable)(lakutata_1.DTO.Boolean().optional().default(true)),
+    __metadata("design:type", Boolean)
+], NATS.prototype, "bulk", void 0);
+__decorate([
+    (0, di_1.Configurable)(lakutata_1.DTO.String().optional()),
+    __metadata("design:type", String)
+], NATS.prototype, "bulkBucket", void 0);
+__decorate([
+    (0, di_1.Configurable)(lakutata_1.DTO.Number().integer().optional().default(5 * 60 * 1000)),
+    __metadata("design:type", Number)
+], NATS.prototype, "bulkTTL", void 0);
+__decorate([
+    (0, di_1.Configurable)(lakutata_1.DTO.Number().integer().optional().default(1)),
+    __metadata("design:type", Number)
+], NATS.prototype, "bulkReplicas", void 0);

package/dist/entrypoints/SetupNatsServiceEntrypoint.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"SetupNatsServiceEntrypoint.d.ts","sourceRoot":"","sources":["../../src/entrypoints/SetupNatsServiceEntrypoint.ts"],"names":[],"mappings":"AAAA,OAAO,EAGH,iBAAiB,EAEpB,MAAM,yBAAyB,CAAA;AAKhC;;;;GAIG;AACH,wBAAgB,0BAA0B,CAAC,iBAAiB,EAAE,MAAM,GAAG,iBAAiB,CAevF"}
+{"version":3,"file":"SetupNatsServiceEntrypoint.d.ts","sourceRoot":"","sources":["../../src/entrypoints/SetupNatsServiceEntrypoint.ts"],"names":[],"mappings":"AAAA,OAAO,EAGH,iBAAiB,EAEpB,MAAM,yBAAyB,CAAA;AAehC;;;;GAIG;AACH,wBAAgB,0BAA0B,CAAC,iBAAiB,EAAE,MAAM,GAAG,iBAAiB,CAmBvF"}

package/dist/entrypoints/SetupNatsServiceEntrypoint.js

@@ -3,6 +3,15 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.SetupNatsServiceEntrypoint = void 0;
 const entrypoint_1 = require("lakutata/com/entrypoint");
 const ServiceResponseCodec_1 = require("../lib/ServiceResponseCodec");
+/**
+ * 把异常拷成可序列化的普通对象(保留 message/errno/statusCode 等自有属性)。
+ * @param error
+ */
+function toErrorObject(error) {
+    const errorObject = {};
+    Object.getOwnPropertyNames(error).forEach((prop) => errorObject[prop] = error[prop]);
+    return errorObject;
+}
 /**
  * Setup service based on NATS
  * @param natsComponentName
@@ -11,18 +20,22 @@ const ServiceResponseCodec_1 = require("../lib/ServiceResponseCodec");
 function SetupNatsServiceEntrypoint(natsComponentName) {
     return (0, entrypoint_1.BuildServiceEntrypoint)(async (module, handler) => {
         const nats = await module.getObject(natsComponentName);
-        nats.subscribe(module.appId, async (incomeRequestPayload) => {
+        const appId = module.appId;
+        nats.subscribe(appId, async (incomeRequestPayload) => {
             try {
                 return ServiceResponseCodec_1.ServiceResponseCodec.encode(await handler(new entrypoint_1.ServiceContext({
                     data: incomeRequestPayload
                 })), false);
             }
             catch (e) {
-                const errorObject = {};
-                Object.getOwnPropertyNames(e).forEach((prop) => errorObject[prop] = e[prop]);
-                return ServiceResponseCodec_1.ServiceResponseCodec.encode(errorObject, true);
+                return ServiceResponseCodec_1.ServiceResponseCodec.encode(toErrorObject(e), true);
             }
-        }, { queue: `${module.appId}.serviceQueue` });
+        }, {
+            queue: `${appId}.serviceQueue`,
+            // 入站 decode 失败 / 出站 encode 失败等发生在 handler 之外(subscribe 层)的错误,
+            // 由此工厂统一回成标准失败响应,避免请求方挂到超时。
+            errorResponse: (e) => ServiceResponseCodec_1.ServiceResponseCodec.encode(toErrorObject(e), true)
+        });
     });
 }
 exports.SetupNatsServiceEntrypoint = SetupNatsServiceEntrypoint;

package/dist/exceptions/NatsBulkException.d.ts

@@ -0,0 +1,11 @@
+import { Exception } from 'lakutata';
+/**
+ * bulk 中转层故障(Object Store put/get 失败、引用过期取不到、bulk 未启用等)。
+ * 表示"大数据通道出问题",区别于业务错误;不应自动重试(响应取不到时对侧可能已处理)。
+ * message 由抛出处给出具体原因(不设默认值,以保留原因)。
+ */
+export declare class NatsBulkException extends Exception {
+    errno: string | number;
+    statusCode: number;
+}
+//# sourceMappingURL=NatsBulkException.d.ts.map

package/dist/exceptions/NatsBulkException.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"NatsBulkException.d.ts","sourceRoot":"","sources":["../../src/exceptions/NatsBulkException.ts"],"names":[],"mappings":"AAAA,OAAO,EAAC,SAAS,EAAC,MAAM,UAAU,CAAA;AAElC;;;;GAIG;AACH,qBAAa,iBAAkB,SAAQ,SAAS;IACrC,KAAK,EAAE,MAAM,GAAG,MAAM,CAAgB;IACtC,UAAU,EAAE,MAAM,CAAM;CAClC"}

package/dist/exceptions/NatsBulkException.js

@@ -0,0 +1,17 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.NatsBulkException = void 0;
+const lakutata_1 = require("lakutata");
+/**
+ * bulk 中转层故障(Object Store put/get 失败、引用过期取不到、bulk 未启用等)。
+ * 表示"大数据通道出问题",区别于业务错误;不应自动重试(响应取不到时对侧可能已处理)。
+ * message 由抛出处给出具体原因(不设默认值,以保留原因)。
+ */
+class NatsBulkException extends lakutata_1.Exception {
+    constructor() {
+        super(...arguments);
+        this.errno = 'E_NATS_BULK';
+        this.statusCode = 502;
+    }
+}
+exports.NatsBulkException = NatsBulkException;

package/dist/interfaces/NatsClientOptions.d.ts

@@ -14,5 +14,13 @@ export interface NatsClientOptions {
     noRandomize?: boolean;
     pingInterval?: number;
     reconnect?: boolean;
+    /** 是否启用 bulk 大数据旁路(启动建第二条连接 + Object Store),默认 true */
+    bulk?: boolean;
+    /** bulk Object Store bucket 名,默认 lkt-bulk-${name} */
+    bulkBucket?: string;
+    /** bulk 对象 TTL(毫秒),默认 5 分钟 */
+    bulkTTL?: number;
+    /** bulk bucket 副本数,默认 1(中转数据用完即弃) */
+    bulkReplicas?: number;
 }
 //# sourceMappingURL=NatsClientOptions.d.ts.map

package/dist/interfaces/NatsClientOptions.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"NatsClientOptions.d.ts","sourceRoot":"","sources":["../../src/interfaces/NatsClientOptions.ts"],"names":[],"mappings":"AAAA,OAAO,EAAC,KAAK,EAAC,MAAM,MAAM,CAAA;AAE1B,MAAM,WAAW,iBAAiB;IAC9B,OAAO,EAAE,MAAM,GAAG,MAAM,EAAE,CAAA;IAC1B,KAAK,CAAC,EAAE,KAAK,CAAC,OAAO,CAAC,CAAA;IACtB,OAAO,CAAC,EAAE,MAAM,CAAA;IAChB,KAAK,CAAC,EAAE,MAAM,CAAA;IACd,IAAI,CAAC,EAAE,MAAM,CAAA;IACb,IAAI,CAAC,EAAE,MAAM,CAAA;IACb,KAAK,CAAC,EAAE,OAAO,CAAA;IACf,UAAU,CAAC,EAAE,MAAM,CAAA;IACnB,oBAAoB,CAAC,EAAE,MAAM,CAAA;IAC7B,IAAI,CAAC,EAAE,MAAM,CAAA;IACb,MAAM,CAAC,EAAE,OAAO,CAAA;IAChB,WAAW,CAAC,EAAE,OAAO,CAAA;IACrB,YAAY,CAAC,EAAE,MAAM,CAAA;IACrB,SAAS,CAAC,EAAE,OAAO,CAAA;CACtB"}
+{"version":3,"file":"NatsClientOptions.d.ts","sourceRoot":"","sources":["../../src/interfaces/NatsClientOptions.ts"],"names":[],"mappings":"AAAA,OAAO,EAAC,KAAK,EAAC,MAAM,MAAM,CAAA;AAE1B,MAAM,WAAW,iBAAiB;IAC9B,OAAO,EAAE,MAAM,GAAG,MAAM,EAAE,CAAA;IAC1B,KAAK,CAAC,EAAE,KAAK,CAAC,OAAO,CAAC,CAAA;IACtB,OAAO,CAAC,EAAE,MAAM,CAAA;IAChB,KAAK,CAAC,EAAE,MAAM,CAAA;IACd,IAAI,CAAC,EAAE,MAAM,CAAA;IACb,IAAI,CAAC,EAAE,MAAM,CAAA;IACb,KAAK,CAAC,EAAE,OAAO,CAAA;IACf,UAAU,CAAC,EAAE,MAAM,CAAA;IACnB,oBAAoB,CAAC,EAAE,MAAM,CAAA;IAC7B,IAAI,CAAC,EAAE,MAAM,CAAA;IACb,MAAM,CAAC,EAAE,OAAO,CAAA;IAChB,WAAW,CAAC,EAAE,OAAO,CAAA;IACrB,YAAY,CAAC,EAAE,MAAM,CAAA;IACrB,SAAS,CAAC,EAAE,OAAO,CAAA;IACnB,uDAAuD;IACvD,IAAI,CAAC,EAAE,OAAO,CAAA;IACd,qDAAqD;IACrD,UAAU,CAAC,EAAE,MAAM,CAAA;IACnB,8BAA8B;IAC9B,OAAO,CAAC,EAAE,MAAM,CAAA;IAChB,qCAAqC;IACrC,YAAY,CAAC,EAAE,MAAM,CAAA;CACxB"}

package/dist/lib/ServiceResponseCodec.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"ServiceResponseCodec.d.ts","sourceRoot":"","sources":["../../src/lib/ServiceResponseCodec.ts"],"names":[],"mappings":"AAAA,OAAO,EAAC,SAAS,EAAC,MAAM,UAAU,CAAA;AAGlC,UAAU,eAAe;IACrB,QAAQ,CAAC,OAAO,EAAE,OAAO,CAAA;IACzB,QAAQ,CAAC,KAAK,EAAE,KAAK,GAAG,SAAS,GAAG,IAAI,CAAA;IACxC,QAAQ,CAAC,OAAO,EAAE,GAAG,GAAG,IAAI,CAAA;CAC/B;AAED,qBAAa,oBAAoB;IAC7B;;;;OAIG;WACW,MAAM,CAAC,IAAI,EAAE,GAAG,EAAE,OAAO,EAAE,OAAO,GAAG,eAAe;IAYlE;;;;OAIG;WACW,MAAM,CAAC,QAAQ,EAAE,eAAe,EAAE,SAAS,CAAC,EAAE,MAAM,GAAG,GAAG;CAS3E"}
+{"version":3,"file":"ServiceResponseCodec.d.ts","sourceRoot":"","sources":["../../src/lib/ServiceResponseCodec.ts"],"names":[],"mappings":"AAAA,OAAO,EAAC,SAAS,EAAC,MAAM,UAAU,CAAA;AAGlC,UAAU,eAAe;IACrB,QAAQ,CAAC,OAAO,EAAE,OAAO,CAAA;IACzB,QAAQ,CAAC,KAAK,EAAE,KAAK,GAAG,SAAS,GAAG,IAAI,CAAA;IACxC,QAAQ,CAAC,OAAO,EAAE,GAAG,GAAG,IAAI,CAAA;CAC/B;AAED,qBAAa,oBAAoB;IAC7B;;;;OAIG;WACW,MAAM,CAAC,IAAI,EAAE,GAAG,EAAE,OAAO,EAAE,OAAO,GAAG,eAAe;IAYlE;;;;OAIG;WACW,MAAM,CAAC,QAAQ,EAAE,eAAe,EAAE,SAAS,CAAC,EAAE,MAAM,GAAG,GAAG;CAoB3E"}

package/dist/lib/ServiceResponseCodec.js

@@ -27,10 +27,22 @@ class ServiceResponseCodec {
     static decode(response, serviceId) {
         if (!response.success) {
             const remoteError = response.error;
-            const serviceInvokeException = new ServiceInvokeException_1.ServiceInvokeException(remoteError.message || 'Unknown Error');
+            const serviceInvokeException = new ServiceInvokeException_1.ServiceInvokeException(remoteError?.message || 'Unknown Error');
             if (serviceId)
                 serviceInvokeException.service = serviceId;
-            throw Object.assign(serviceInvokeException, response.error);
+            // 安全拷贝远端错误的自有属性:逐个赋值并跳过只读属性(如 NatsError 的 name),
+            // 避免 Object.assign 碰到只读属性时整体抛 TypeError。
+            if (remoteError && typeof remoteError === 'object') {
+                for (const key of Object.keys(remoteError)) {
+                    try {
+                        serviceInvokeException[key] = remoteError[key];
+                    }
+                    catch {
+                        // 只读属性,跳过
+                    }
+                }
+            }
+            throw serviceInvokeException;
         }
         return response.payload;
     }

package/dist/providers/ServiceProxy.d.ts

@@ -6,6 +6,10 @@ import { NATS } from '../components/NATS';
 export type BuildServiceProxyOptions = {
     readonly natsComponentName: string;
     readonly serviceId: string;
+    /** 仅对 NoResponders(对侧确定没处理)自动重试的次数,默认 3;超时/业务异常不重试 */
+    readonly maxRetries?: number;
+    /** 每次重试前等待的毫秒,默认 100 */
+    readonly retryDelay?: number;
 };
 /**
  * Build service proxy
@@ -32,6 +36,16 @@ export declare class ServiceProxy extends Provider {
      * @protected
      */
     protected readonly serviceId: string;
+    /**
+     * 仅对 NoResponders(对侧确定没处理)自动重试的次数;超时/业务异常不重试。
+     * @protected
+     */
+    protected readonly maxRetries: number;
+    /**
+     * 每次重试前等待的毫秒。
+     * @protected
+     */
+    protected readonly retryDelay: number;
     /**
      * NATS component instance
      * @protected
@@ -45,7 +59,7 @@ export declare class ServiceProxy extends Provider {
     /**
      * Invoke service registered method by pattern
      * @param input
-     * @param timeout
+     * @param timeout 默认 10 分钟。服务不存在/无响应者由 NoResponders 立即失败,此超时仅兜底"已被接收但处理太慢"的情况;已知的慢操作可显式传更长值。
      */
     invoke<T extends Record<string, any>>(input: ActionPattern<T>, timeout?: number): Promise<any>;
     /**

package/dist/providers/ServiceProxy.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"ServiceProxy.d.ts","sourceRoot":"","sources":["../../src/providers/ServiceProxy.ts"],"names":[],"mappings":"AAAA,OAAO,EAAC,aAAa,EAAE,WAAW,EAAO,QAAQ,EAAE,sBAAsB,EAAC,MAAM,UAAU,CAAA;AAE1F,OAAO,EAAC,IAAI,EAAC,MAAM,oBAAoB,CAAA;AAGvC;;GAEG;AACH,MAAM,MAAM,wBAAwB,GAAG;IACnC,QAAQ,CAAC,iBAAiB,EAAE,MAAM,CAAA;IAClC,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAA;CAC7B,CAAA;AAED;;;;GAIG;AACH,eAAO,MAAM,iBAAiB,EAAE,sBAAsB,CAAC,wBAAwB,CAM9E,CAAA;AAED;;GAEG;AACH,qBACa,YAAa,SAAQ,QAAQ;IACtC;;;OAGG;IAEH,SAAS,CAAC,QAAQ,CAAC,GAAG,EAAE,WAAW,CAAA;IAEnC;;;OAGG;IAEH,SAAS,CAAC,QAAQ,CAAC,iBAAiB,EAAE,MAAM,CAAA;IAE5C;;;OAGG;IAEH,SAAS,CAAC,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAA;IAEpC;;;OAGG;IACH,SAAS,CAAC,IAAI,EAAE,IAAI,CAAA;IAEpB;;;OAGG;cACa,IAAI,IAAI,OAAO,CAAC,IAAI,CAAC;IAIrC;;;;OAIG;IACU,MAAM,CAAC,CAAC,SAAS,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,EAAE,KAAK,EAAE,aAAa,CAAC,CAAC,CAAC,EAAE,OAAO,GAAE,MAAuB,GAAG,OAAO,CAAC,GAAG,CAAC;IAK3H;;;;;OAKG;IACI,EAAE,CAAC,SAAS,EAAE,MAAM,EAAE,QAAQ,EAAE,CAAC,GAAG,IAAI,EAAE,GAAG,EAAE,KAAK,IAAI,EAAE,wBAAwB,GAAE,OAAe,GAAG,IAAI;IAKjH;;;;OAIG;IACI,IAAI,CAAC,SAAS,EAAE,MAAM,EAAE,QAAQ,EAAE,CAAC,GAAG,IAAI,EAAE,GAAG,EAAE,KAAK,IAAI,GAAG,IAAI;IAKxE;;;;OAIG;IACI,GAAG,CAAC,SAAS,EAAE,MAAM,EAAE,QAAQ,CAAC,EAAE,CAAC,GAAG,IAAI,EAAE,GAAG,EAAE,KAAK,IAAI,GAAG,IAAI;CAI3E"}
+{"version":3,"file":"ServiceProxy.d.ts","sourceRoot":"","sources":["../../src/providers/ServiceProxy.ts"],"names":[],"mappings":"AAAA,OAAO,EAAC,aAAa,EAAE,WAAW,EAAO,QAAQ,EAAE,sBAAsB,EAAC,MAAM,UAAU,CAAA;AAG1F,OAAO,EAAC,IAAI,EAAC,MAAM,oBAAoB,CAAA;AAIvC;;GAEG;AACH,MAAM,MAAM,wBAAwB,GAAG;IACnC,QAAQ,CAAC,iBAAiB,EAAE,MAAM,CAAA;IAClC,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAA;IAC1B,sDAAsD;IACtD,QAAQ,CAAC,UAAU,CAAC,EAAE,MAAM,CAAA;IAC5B,wBAAwB;IACxB,QAAQ,CAAC,UAAU,CAAC,EAAE,MAAM,CAAA;CAC/B,CAAA;AAED;;;;GAIG;AACH,eAAO,MAAM,iBAAiB,EAAE,sBAAsB,CAAC,wBAAwB,CAQ9E,CAAA;AAED;;GAEG;AACH,qBACa,YAAa,SAAQ,QAAQ;IACtC;;;OAGG;IAEH,SAAS,CAAC,QAAQ,CAAC,GAAG,EAAE,WAAW,CAAA;IAEnC;;;OAGG;IAEH,SAAS,CAAC,QAAQ,CAAC,iBAAiB,EAAE,MAAM,CAAA;IAE5C;;;OAGG;IAEH,SAAS,CAAC,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAA;IAEpC;;;OAGG;IAEH,SAAS,CAAC,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAA;IAErC;;;OAGG;IAEH,SAAS,CAAC,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAA;IAErC;;;OAGG;IACH,SAAS,CAAC,IAAI,EAAE,IAAI,CAAA;IAEpB;;;OAGG;cACa,IAAI,IAAI,OAAO,CAAC,IAAI,CAAC;IAIrC;;;;OAIG;IACU,MAAM,CAAC,CAAC,SAAS,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,EAAE,KAAK,EAAE,aAAa,CAAC,CAAC,CAAC,EAAE,OAAO,GAAE,MAAuB,GAAG,OAAO,CAAC,GAAG,CAAC;IAkB3H;;;;;OAKG;IACI,EAAE,CAAC,SAAS,EAAE,MAAM,EAAE,QAAQ,EAAE,CAAC,GAAG,IAAI,EAAE,GAAG,EAAE,KAAK,IAAI,EAAE,wBAAwB,GAAE,OAAe,GAAG,IAAI;IAKjH;;;;OAIG;IACI,IAAI,CAAC,SAAS,EAAE,MAAM,EAAE,QAAQ,EAAE,CAAC,GAAG,IAAI,EAAE,GAAG,EAAE,KAAK,IAAI,GAAG,IAAI;IAKxE;;;;OAIG;IACI,GAAG,CAAC,SAAS,EAAE,MAAM,EAAE,QAAQ,CAAC,EAAE,CAAC,GAAG,IAAI,EAAE,GAAG,EAAE,KAAK,IAAI,GAAG,IAAI;CAI3E"}

package/dist/providers/ServiceProxy.js

@@ -12,7 +12,9 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.ServiceProxy = exports.BuildServiceProxy = void 0;
 const lakutata_1 = require("lakutata");
 const di_1 = require("lakutata/decorator/di");
+const helper_1 = require("lakutata/helper");
 const ServiceResponseCodec_1 = require("../lib/ServiceResponseCodec");
+const NatsNoRespondersAvailableException_1 = require("../exceptions/NatsNoRespondersAvailableException");
 /**
  * Build service proxy
  * @param options
@@ -22,7 +24,9 @@ const BuildServiceProxy = (options) => {
     return {
         class: ServiceProxy,
         natsComponentName: options.natsComponentName,
-        serviceId: options.serviceId
+        serviceId: options.serviceId,
+        maxRetries: options.maxRetries,
+        retryDelay: options.retryDelay
     };
 };
 exports.BuildServiceProxy = BuildServiceProxy;
@@ -40,11 +44,25 @@ let ServiceProxy = class ServiceProxy extends lakutata_1.Provider {
     /**
      * Invoke service registered method by pattern
      * @param input
-     * @param timeout
+     * @param timeout 默认 10 分钟。服务不存在/无响应者由 NoResponders 立即失败,此超时仅兜底"已被接收但处理太慢"的情况;已知的慢操作可显式传更长值。
      */
-    async invoke(input, timeout = 60 * 60 * 1000) {
-        const response = await this.nats.request(this.serviceId, input, timeout);
-        return ServiceResponseCodec_1.ServiceResponseCodec.decode(response, this.serviceId);
+    async invoke(input, timeout = 10 * 60 * 1000) {
+        // 安全重试红线:只对 NoResponders 重试 —— NATS 明确告知"当时没人订阅",对侧【确定没处理】,
+        // 重试到其他副本是首次处理,不会重复。超时(可能已处理但响应丢失)、业务异常(对侧已处理并返回)
+        // 都【不】重试,直接抛给调用方,避免重复执行非幂等操作。
+        for (let attempt = 0;; attempt++) {
+            try {
+                const response = await this.nats.request(this.serviceId, input, timeout);
+                return ServiceResponseCodec_1.ServiceResponseCodec.decode(response, this.serviceId);
+            }
+            catch (e) {
+                if (e instanceof NatsNoRespondersAvailableException_1.NatsNoRespondersAvailableException && attempt < this.maxRetries) {
+                    await (0, helper_1.Delay)(this.retryDelay);
+                    continue;
+                }
+                throw e;
+            }
+        }
     }
     /**
      * On service event
@@ -93,6 +111,14 @@ __decorate([
     (0, di_1.Configurable)(lakutata_1.DTO.String().required()),
     __metadata("design:type", String)
 ], ServiceProxy.prototype, "serviceId", void 0);
+__decorate([
+    (0, di_1.Configurable)(lakutata_1.DTO.Number().integer().optional().default(3)),
+    __metadata("design:type", Number)
+], ServiceProxy.prototype, "maxRetries", void 0);
+__decorate([
+    (0, di_1.Configurable)(lakutata_1.DTO.Number().integer().optional().default(100)),
+    __metadata("design:type", Number)
+], ServiceProxy.prototype, "retryDelay", void 0);
 exports.ServiceProxy = ServiceProxy = __decorate([
     (0, di_1.Singleton)()
 ], ServiceProxy);

package/dist/types/SubscribeOptions.d.ts

@@ -2,5 +2,11 @@ export type SubscribeOptions = {
     queue?: string;
     max?: number;
     iterator?: boolean;
+    /**
+     * 当消息处理出错且该消息是请求(带 reply 地址)时,用此工厂生成回传给请求方的 payload。
+     * subscribe 会用当前 codec 编码它并 respond;返回 undefined 则不回响应(请求方靠超时感知)。
+     * 用于让上层(如服务入口)注入自己的错误响应协议,而不让通用 subscribe 依赖该协议。
+     */
+    errorResponse?: (error: any) => any;
 };
 //# sourceMappingURL=SubscribeOptions.d.ts.map

package/dist/types/SubscribeOptions.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"SubscribeOptions.d.ts","sourceRoot":"","sources":["../../src/types/SubscribeOptions.ts"],"names":[],"mappings":"AAAA,MAAM,MAAM,gBAAgB,GAAG;IAC3B,KAAK,CAAC,EAAE,MAAM,CAAA;IACd,GAAG,CAAC,EAAE,MAAM,CAAA;IACZ,QAAQ,CAAC,EAAE,OAAO,CAAA;CACrB,CAAA"}
+{"version":3,"file":"SubscribeOptions.d.ts","sourceRoot":"","sources":["../../src/types/SubscribeOptions.ts"],"names":[],"mappings":"AAAA,MAAM,MAAM,gBAAgB,GAAG;IAC3B,KAAK,CAAC,EAAE,MAAM,CAAA;IACd,GAAG,CAAC,EAAE,MAAM,CAAA;IACZ,QAAQ,CAAC,EAAE,OAAO,CAAA;IAClB;;;;OAIG;IACH,aAAa,CAAC,EAAE,CAAC,KAAK,EAAE,GAAG,KAAK,GAAG,CAAA;CACtC,CAAA"}

package/docs/large-payload-design.md

@@ -0,0 +1,199 @@
+# 大消息传输方案设计（@lakutata/nats）
+
+> 状态:**架构已定,工程细节待敲定**(见末尾 checklist)。
+> 本文档是多轮设计讨论的沉淀,目标是让后续实现不必重推已排除的弯路。
+
+## 1. 背景与硬约束
+
+这个包用于 K8s 集群中、跨语言服务之间的 RPC 通讯(core NATS request-reply + pub/sub)。
+现实中存在大 payload(查大表、读文件等,8M+)。设计必须同时满足:
+
+| 约束 | 说明 |
+|---|---|
+| **业务 API 不变** | 业务两端保持 `invoke(pattern)→完整对象`、`@ServiceAction return 完整对象`、`publish/subscribe`。中间件断面只在传输+调用层。 |
+| **跨语言** | 有非 JS 服务,必须保证标准 JSON 子集语义(原生 codec 的 `JSON.parse(JSON.stringify())` 清洗必须保留,不能用 msgpack 富类型)。 |
+| **不能 break 已上线服务** | 滚动升级新旧共存,必须向后兼容(能力协商 + 退化)。 |
+| **不重复响应** | 多副本下一个请求只能一个副本处理(已由 queue group 保证)。 |
+
+## 2. 两个阻塞机制(问题根源)
+
+| 机制 | 现象 | 本质 | 能否消除 |
+|---|---|---|---|
+| **机制1:TCP 队头阻塞** | 单条 16M 帧在连接上传输的 ~100ms 里,堵住该连接上后续所有消息 | 单 TCP 连接、协议帧不可交错 | 可隔离(独立连接) |
+| **机制2:事件循环卡顿** | `codec.decode`/`encode` 是同步 CPU,16M 各 ~100ms 卡住**整个进程**的事件循环 | 完整对象 materialize 是物理成本 + **V8 对象只能在主线程构建** | **不能消除,只能隔离/分散** |
+
+实测(11KB→132µs encode;8.5M→50ms;16M→~100ms),decode/encode 随大小线性增长。
+
+## 3. 总体架构
+
+> **一句话:小消息走现状 core RPC(零影响);大消息自动经 Object Store 中转(独立 bulk 连接 + 可选 bulk 副本双隔离);用 NATS header 协商保证灰度不破坏;业务两端 API 完全不变。**
+
+```
+┌─────────────────────────────────────────────────────────┐
+│ 常规副本(处理高频小请求)                                    │
+│   连接① nats(core)   : invoke/event/publish 的小消息        │
+│   连接② natsBulk     : 大数据 Object Store put/get(默认建)  │
+├─────────────────────────────────────────────────────────┤
+│ bulk 副本(可选,第二层,独立 deployment)                    │
+│   订阅 serviceId.bulk,用原生 codec,烧自己的事件循环         │
+│   → 机制2 的处理隔离(没有它就退化到常规副本处理)            │
+├─────────────────────────────────────────────────────────┤
+│ NATS + JetStream Object Store(local-path 块存储)           │
+│   bucket:大对象中转,持久存储(get 不删),短 MaxAge 自动清    │
+└─────────────────────────────────────────────────────────┘
+```
+
+**双隔离:**
+- 独立连接(`natsBulk`)→ 解机制1(传输互不挤);
+- 独立进程(bulk 副本)→ 解机制2(CPU 互不卡)。
+- 两者是两件事,连接独立 ≠ 处理独立。
+
+## 4. bulk 连接策略(本次更新重点)
+
+**`bulk` 默认 `true`:NATS 客户端启动时默认建立 bulk 连接 + 准备 Object Store 旁路。**
+
+```ts
+nats: buildNatsClientOptions({
+    servers: '...',
+    bulk: true    // 默认 true:启动即建 bulk 连接 + 准备 Object Store 旁路
+})
+```
+
+设计要点:
+- **预建立**(启动就连,无 cold start),符合 lakutata Component 的 init/destroy 生命周期;
+- **连接配置自动复用 core**(servers/认证/codec 继承),**不用重复配**;但仍是**第二条独立 TCP**(隔离需要),不是共用一条;
+- **连接与 Object Store 绑定**:默认开 = 连接 + Object Store 旁路一起就绪,**避免建一条空连接**;
+- **可关**:`bulk: false` 给明确从不收发大数据的服务关掉省资源;
+- **代价**:每副本 2 条连接,NATS server 端连接数翻倍,超大规模需评估;
+- **bulk 副本是第二层可选**:没有它,大请求退化到常规副本处理(卡常规副本但功能正常);有它才完整隔离机制2。
+
+`bulkNatsComponentName` 降级为**可选高级覆盖**:仅当想把 bulk 流量隔离到**另一个 NATS 集群**(不同 servers)时才用;默认同集群、自动复用配置,无需此项。
+
+## 5. 阈值:自动从 server 拿,零配置
+
+判断标准 = **encode 后的字节长度**(不是对象逻辑大小)。
+
+```ts
+private get bulkThreshold(): number {
+    const maxPayload = this.#conn.info?.max_payload ?? 1024 * 1024  // fallback 1M
+    return Math.floor(maxPayload * 0.9)   // 留 framing 余量
+}
+```
+
+- `max_payload` 由 NATS 握手的 `INFO` 消息提供,`nc.info.max_payload` 现成可读(已验证 `ServerInfo.max_payload` 存在);
+- 阈值 = `max_payload × 0.9`,**跟随集群配置自动变化**,保证"core 发不出去的必走 bulk";
+- 每次读、不缓存(应对 server 运行时重配,成本几乎为零);
+- 可由用户配置向下覆盖(极低延迟场景想更激进隔离时)。
+
+**诚实局限:判断需先 encode,而 encode 大对象本身就卡(机制2)。** 小消息 encode 微秒级无负担;大消息发送侧 encode 那一下卡躲不过(见 §11)。不能靠"预估大小"绕过(遍历估大小也是 O(size) 卡顿)。
+
+## 6. 数据流
+
+### (A) 小请求 RPC —— 完全是现状,零额外开销
+```
+invoke(pattern) → encode < 阈值 → nats.request(serviceId, bytes) → 常规副本 → 响应
+```
+
+### (B) 大请求/大响应 RPC —— Object Store 传引用
+```
+客户端: encode ≥ 阈值 → natsBulk.put(TTL)→objId → nats.request(serviceId.bulk, {__ref:objId}, header)
+bulk 副本: 收 {__ref} → natsBulk.get → decode → handler(完整对象)
+          → return 大对象 → put → 回 {__ref:objId2}
+客户端: 收 {__ref:objId2} → natsBulk.get → decode → resolve
+```
+- core 连接上只跑**小引用消息**;大数据字节走 natsBulk + Object Store,离开 core;
+- decode/encode 卡顿烧在 bulk 副本进程,常规副本无感;
+- 业务两端只看到 `invoke(pattern)`/`return 对象`,看不到任何 ref。
+
+### (C) 大 publish/event —— Object Store 发引用(一对多更优)
+```
+emitServiceEvent(evt, big) → encode ≥ 阈值 → put → publish(subject, {__ref})
+每个订阅方: 收 {__ref} → 按需 get → decode → listener(完整对象)
+```
+- 广播的是小引用,所有订阅方 core 连接都不被砸;
+- **一份存储多方按需取,没有 N× 流量放大**(优于 natsBulk 直传广播);
+- 不关心的订阅方可以不下载。
+
+## 7. 协议:全部走 NATS header,payload 不动
+
+| header 键 | 方向 | 含义 |
+|---|---|---|
+| `X-Lkt-Chunk: 1` | 请求 | 客户端能力声明:能处理引用中转 |
+
+- payload 永远是业务数据或 `{__ref}`,协议元信息只在 header → 不污染、跨语言干净;
+- `server` 是否支持 header:从 `nc.info.headers` 自动判断,不支持则自动退化。
+
+## 8. 向后兼容 + 灰度
+
+能力声明 header(`X-Lkt-Bulk`)可选,缺失即"对端不支持"→ 不给它发引用:
+
+| 客户端 | 服务端 | 行为 |
+|---|---|---|
+| 旧 | 新 | 旧客户端不带 `X-Lkt-Bulk` → 新服务端响应直传退化 |
+| 新 | 旧 | 旧服务端响应不带 `X-Lkt-Bulk` → 新客户端学到"不支持"→ 后续不发引用、直传 |
+| 新 | 新 | 双向都声明 → 大数据走 Object Store 引用 |
+| 旧 | 旧 | 完全不变 |
+
+**已验证**:用裸 NATS 模拟真旧版(无 header、无中转),两个方向(旧→新、新→旧)wire 兼容均通过(`compat.test.ts`)。关键保证:**新版只在对端声明能力时才发引用,旧版不声明 → 自动退化直传**,新旧混部署 / 滚动升级不破坏。
+
+**上线顺序(无 flag day):**
+1. 发新版(带能力,默认旁路可退化),`max_payload` 暂保持现值;
+2. 滚动升级所有服务;
+3. 部署 bulk 副本、开启旁路;
+4. 全升级确认后,把 `max_payload` 调回安全值(如 1M)。
+
+## 9. 清理 / 容量(Object Store)
+
+- JetStream/Object Store **默认不会"消费即删"**(那是 WorkQueue retention);Object Store 是**持久存储,get 不删**;
+- 必须配**短 `MaxAge`**(如 5min)兜底自动清;RPC 点对点可加"下载后显式 `delete`"双保险;publish 一对多只能靠 `MaxAge`;
+- `max_file_store` 按 `峰值并发大对象数 × 大小 × TTL` 估算,别撑爆 local-path 磁盘。
+
+## 10. 分阶段落地
+
+| 阶段 | 内容 | 状态 |
+|---|---|---|
+| **S1** | NATS 组件 bulk 基础能力:bulk 连接默认开(复用 core 配置)、Object Store `putBulk`/`getBulk`/`deleteBulk`/`bulkStatus`、阈值(`max_payload×0.9` 从 info)、`headersSupported` 探针、TTL/replicas/bucket 配置 | ✅ 已落地(`bulk.test.ts` 7 例) |
+| **S2** | `request`/`subscribe` 透明中转:自适应阈值路由、双向能力协商(`X-Lkt-Bulk`/`X-Lkt-Ref`/`{__ref}`)、客户端缓存对端能力(`#peerCapabilityCache`)、退化兼容、引用用完即删 + TTL 兜底、`NatsBulkException` 错误语义化 | ✅ 已落地(`bulk-rpc.test.ts` 5 例 + `compat.test.ts` 真旧版兼容 2 例) |
+| S3 | publish/event 的引用中转(一对多用 Object Store 发引用,不放大流量) | 待做 |
+| S4 | bulk 副本(机制2 处理隔离)+ 部署/路由(没有 bulk 副本时退化常规副本) | 待做 |
+| S5 | 背压(#1,bulk 副本尤其必要)+ 全集群升级后调回 `max_payload` | 待做 |
+
+**S1+S2 = MVP 核心链路**:RPC 大请求/大响应透明走 Object Store、双向协商、退化兼容、API 完全不变,全部有测试。每阶段向后兼容、可单独测、不破坏现状。
+
+## 11. 已知边界 / 删不掉的代价(诚实记录)
+
+- **调用方侧机制2躲不过**:调用方 `invoke` 大数据时,它自己 encode 请求 + decode 响应卡**它自己**的事件循环。自适应路由 + bulk 副本只隔离了**被调用方**侧;调用方侧的卡顿是物理成本,且调用方预知不了响应大小,无法提前隔离。**接受它。**
+- 大数据请求**本身慢**(Object Store 多一跳 + encode/decode 物理成本)——但被关在 bulk 连接 + bulk 副本里,只烧自己,不连累高频小 RPC。
+- bulk 副本需**单独部署**(运维多一份);Object Store 占磁盘 + 需 TTL 管理;依赖 JetStream(已开、底座已修为 local-path)。
+
+## 12. 待敲定的工程细节(实现前 checklist)
+
+- [x] **objId 生命周期**:`randomUUID` 命名;取回后即删(请求 obj 在响应返回后删、响应 obj 客户端 get 后删),均 + 5min TTL 兜底 ✅
+- [x] **配置 API**:`bulk`(默认 true)/`bulkBucket`/`bulkTTL`/`bulkReplicas`;`bulkNatsComponentName` 降级为可选高级覆盖 ✅
+- [x] **测试策略**:容器加 `-js` 启 JetStream;`bulk.test.ts`(基础 7 例)+ `bulk-rpc.test.ts`(中转/协商/退化 4 例)✅
+- [x] **超时/重试**:已在 §14 落地(超时 10min、NoResponders 安全重试)✅
+- [x] **错误传播**:`NatsBulkException` 语义化(put/get 失败、引用取不到、未启用);服务端 bulk 失败 → errorResponse → 客户端收带 `E_NATS_BULK` 的 `ServiceInvokeException`;客户端 bulk 失败 → `NatsBulkException`(**不被 #7 重试**);`ServiceResponseCodec.decode` 只读属性 bug 已修。测试:`bulk.test.ts` / `bulk-rpc.test.ts`(端到端不同 bucket)/ 单元。Object Store 完全不可用靠 code review ✅
+- [ ] **bulk 副本部署/路由**:常规 vs bulk 副本角色区分;没有 bulk 副本时大请求落哪 —— 留待 **S4**
+- [ ] **背压(#1)**:bulk 副本尤其必要 —— 留待 **S5**
+
+## 13. 明确排除的弯路(不要重走)
+
+| 方案 | 为什么不行 |
+|---|---|
+| 调大 max_payload 单条传 | 机制1 + 机制2 双重打击 |
+| 自建 chunking + 流控 | 造轮子;Object Store 已内建分块/流控 |
+| worker thread 放 codec | 对象跨边界结构化克隆 ≈ 序列化,还在主线程付账,多构建一次 |
+| 异步 JSON 库 / stream-json | "异步"≠不占 CPU;JS 流式实现慢 5–10×;对象只能主线程构建 |
+| 给 core RPC 开连接池 | 单线程瓶颈不变,多 socket ≠ 多处理能力 |
+
+**根本原因**:只要"业务要完整对象 + API 不变",完整对象的 materialize(CPU + 内存)就删不掉、躲不出主线程。序列化层没有银弹,**解法只在架构隔离层**。
+
+## 14. 相关的独立改进项(与本方案正交,可先做)
+
+- **✅ #3 优雅停机(drain)**:`destroy()` 已改为 `drain()` + `close()` 兜底,滚动升级不切断 in-flight(测试 `test/integration/drain.test.ts`)
+- **✅ #2 超时默认值**:`invoke` 默认已从 1 小时改为 **10 分钟**(可显式覆盖;慢操作显式传更长值)
+- **✅ #7 NoResponders 快速失败(已有)**:`request` 收到 503 立即抛 `NatsNoRespondersAvailableException`,不等超时——故障立即暴露,使 #2 的 10 分钟默认只兜底"处理慢"(测试 `errors.test.ts`)
+- **✅ #7 NoResponders 安全重试**:`invoke` 只对 NoResponders(对侧确定没处理)自动重试(默认 3 次、间隔 100ms,均可配);**超时/业务异常一律不重试**,避免"对侧已处理但响应丢失"时重复执行非幂等操作(测试 `retry.test.ts`)
+- **#1 背压(待做)**:服务端并发上限(bulk 副本尤其需要)
+
+drain + 10 分钟超时 + NoResponders 立即失败 + NoResponders 安全重试 已齐,**滚动升级韧性完整**;仅剩 #1 背压作为增强。

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lakutata/nats",
-  "version": "2.0.1",
+  "version": "2.1.0",
   "description": "Lakutata NATS Client",
   "keywords": [
     "lakutata",
@@ -23,7 +23,9 @@
     "clean": "shx rm -rf ./dist",
     "build": "tsc",
     "rebuild": "npm run clean && npm run build",
-    "test": "bun src/tests/NatsTest.spec.ts"
+    "test": "npm run test:unit && npm run test:integration",
+    "test:unit": "bun test test/unit",
+    "test:integration": "bun test/run-integration.ts"
   },
   "bugs": {
     "url": "https://github.com/lakutata/lakutata-packages/issues"
@@ -32,5 +34,9 @@
     "lakutata": "^2.0.121",
     "nats": "^2.29.3"
   },
-  "gitHead": "a6041bb579a295aed99b7f94301af373858b9624"
+  "gitHead": "d936b7289cccf1bf6d567fb99b7557d87da66f5f",
+  "devDependencies": {
+    "@types/bun": "^1.3.14",
+    "testcontainers": "^12.0.3"
+  }
 }

package/tsconfig.json

@@ -3,5 +3,6 @@
   "compilerOptions": {
     "rootDir": "src",
     "outDir": "dist"
-  }
+  },
+  "exclude": ["dist", "node_modules", "test"]
 }

package/dist/tests/NatsTest.spec.d.ts

@@ -1,2 +0,0 @@
-export {};
-//# sourceMappingURL=NatsTest.spec.d.ts.map

package/dist/tests/NatsTest.spec.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"NatsTest.spec.d.ts","sourceRoot":"","sources":["../../src/tests/NatsTest.spec.ts"],"names":[],"mappings":""}

package/dist/tests/NatsTest.spec.js

@@ -1,129 +0,0 @@
-"use strict";
-var __decorate = (this && this.__decorate) || function (decorators, target, key, desc) {
-    var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
-    if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
-    else for (var i = decorators.length - 1; i >= 0; i--) if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
-    return c > 3 && r && Object.defineProperty(target, key, r), r;
-};
-var __metadata = (this && this.__metadata) || function (k, v) {
-    if (typeof Reflect === "object" && typeof Reflect.metadata === "function") return Reflect.metadata(k, v);
-};
-Object.defineProperty(exports, "__esModule", { value: true });
-const lakutata_1 = require("lakutata");
-const entrypoint_1 = require("lakutata/com/entrypoint");
-const di_1 = require("lakutata/decorator/di");
-const CommonExports_1 = require("../CommonExports");
-const ctrl_1 = require("lakutata/decorator/ctrl");
-const ServiceProxy_1 = require("../providers/ServiceProxy");
-class TestComponent extends lakutata_1.Component {
-    async init() {
-        // this.nats.subscribe('test-invoke', (msg) => {
-        //     console.log('msg:', msg)
-        //     return Date.now()
-        // })
-        // this.nats.subscribe('test', (data: any) => {
-        //     console.log(data)
-        // })
-        //
-        // setInterval(async () => {
-        //     this.nats.publish('test', 1234)
-        //     console.log('res:', await this.nats.request('test-invoke', JSON.stringify({haha: true})), 1000000)
-        // }, 1)
-        // console.log(await this.nats.request(this.app.appId, {test: true}))
-        // this.nats.subscribe('test', async (inp) => {
-        //     console.log(inp)
-        //     await Delay(1000)
-        // }, {iterator: true})
-        //
-        // for (let i = 0; i < 1000; i++) {
-        //     this.nats.publish('test', i)
-        // }
-        const handler1 = async (data1, data2) => {
-            console.log('data1:', data1, data2);
-            // this.nats.offServiceEvent(this.app.appId, 'testEvt', handler1)
-            // this.self.off('testEvt', handler1)
-        };
-        const handler2 = async (data1, data2) => {
-            console.log('data2:', data1, data2);
-            // this.nats.offServiceEvent(this.app.appId, 'testEvt', handler1)
-            // this.nats.offServiceEvent(this.app.appId, 'testEvt')
-        };
-        this.self.on('testEvt', handler1);
-        this.self.on('testEvt', handler2);
-        // this.nats.onServiceEvent(this.app.appId, 'testEvt', handler1)
-        // this.nats.onServiceEvent(this.app.appId, 'testEvt', handler2)
-        // setInterval(() => {
-        //     this.nats.emitServiceEvent('testEvt', 123, 456)
-        // }, 1000)
-        try {
-            console.log(await this.self.invoke({ test: true, start: new Date() }));
-        }
-        catch (e) {
-            // console.error(JSON.parse(JSON.stringify(e)))
-            console.error(e);
-        }
-    }
-}
-__decorate([
-    (0, di_1.Inject)(lakutata_1.Application),
-    __metadata("design:type", lakutata_1.Application)
-], TestComponent.prototype, "app", void 0);
-__decorate([
-    (0, di_1.Inject)('nats'),
-    __metadata("design:type", CommonExports_1.NATS)
-], TestComponent.prototype, "nats", void 0);
-__decorate([
-    (0, di_1.Inject)('self'),
-    __metadata("design:type", ServiceProxy_1.ServiceProxy)
-], TestComponent.prototype, "self", void 0);
-class TestController extends entrypoint_1.Controller {
-    async test(inp) {
-        console.log(inp);
-        // throw new Error('fuck')
-        // throw new NatsForbiddenException('fuck')
-        // return 'hahahah'
-        return {
-            test: true,
-            num: 1234,
-            sub: {
-                a: 1234,
-                b: '1234234',
-                c: [{ test: true }]
-            }
-        };
-        // return ['hahahah']
-        // return {
-        //     test: 123456
-        // }
-    }
-}
-__decorate([
-    (0, ctrl_1.ServiceAction)({ test: true }),
-    __metadata("design:type", Function),
-    __metadata("design:paramtypes", [Object]),
-    __metadata("design:returntype", Promise)
-], TestController.prototype, "test", null);
-lakutata_1.Application.run({
-    id: 'test.app',
-    name: 'TestApp',
-    components: {
-        entrypoint: (0, entrypoint_1.BuildEntrypoints)({
-            controllers: [TestController],
-            service: (0, CommonExports_1.SetupNatsServiceEntrypoint)('nats')
-        }),
-        nats: (0, CommonExports_1.buildNatsClientOptions)({
-            // servers: '127.0.0.1:4222'
-            servers: '10.11.11.21:30422'
-        }),
-        test: {
-            class: TestComponent
-        }
-    },
-    providers: {
-        self: (0, CommonExports_1.BuildServiceProxy)({ serviceId: 'test.app', natsComponentName: 'nats' })
-    },
-    bootstrap: [
-        'entrypoint',
-        'test'
-    ]
-});