@epztickets/common 1.82.0 → 1.83.0

package/build/events/jetstream-listener.d.ts

@@ -13,6 +13,12 @@ export declare abstract class JetStreamListener<T extends Event> {
     constructor(js: JetStreamClient, jsm: JetStreamManager);
     listen(): Promise<void>;
     private ensureConsumer;
+    /**
+     * Ask JetStream to redeliver this message later (NAK with backoff).
+     * Use for "not ready yet" (replica missing) and transient failures.
+     * Safe to call from handlers whose tests pass a bare { ack } mock.
+     */
+    protected defer(msg: JsMsg, reason?: string): void;
     abstract onMessage(data: T["data"], msg: JsMsg): Promise<void>;
 }
 export {};

package/build/events/jetstream-listener.js

@@ -18,6 +18,20 @@ var __asyncValues = (this && this.__asyncValues) || function (o) {
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.JetStreamListener = void 0;
 const nats_1 = require("nats");
+// Must match max_deliver in ensureConsumer below.
+const MAX_DELIVER = 5;
+// Retry backoff for defer(): 2s, 4s, 8s, 16s (capped at 30s).
+const BASE_RETRY_MS = 2000;
+const MAX_RETRY_MS = 30000;
+// ACK CONTRACT for onMessage implementations:
+//   - Return normally → the message is ACKed (done, never redelivered).
+//     This is true even if you didn't call msg.ack() yourself.
+//   - Want a retry (replica not caught up, transient DB/SMTP error)?
+//     `return this.defer(msg)` — NAKs with backoff so JetStream
+//     redelivers. Just returning without msg.ack() does NOT retry.
+//   - Throwing also retries (the base class defers for you).
+// After MAX_DELIVER attempts JetStream stops redelivering; defer()
+// logs an error on the final attempt so a dropped event is visible.
 class JetStreamListener {
     constructor(js, jsm) {
         this.js = js;
@@ -42,10 +56,13 @@ class JetStreamListener {
                     try {
                         const data = JSON.parse(msg.data.toString());
                         yield this.onMessage(data, msg);
+                        // No-op if onMessage already acked or deferred (nats ignores a
+                        // second ack/nak on the same message).
                         msg.ack();
                     }
                     catch (err) {
-                        console.error("Listener error", err);
+                        console.error(`[${this.durableName}] Listener error`, err);
+                        this.defer(msg);
                     }
                 }
             }
@@ -72,10 +89,29 @@ class JetStreamListener {
                     filter_subject: this.subject,
                     ack_policy: nats_1.AckPolicy.Explicit,
                     deliver_policy: nats_1.DeliverPolicy.All,
-                    max_deliver: 5,
+                    max_deliver: MAX_DELIVER,
                 });
             }
         });
     }
+    /**
+     * Ask JetStream to redeliver this message later (NAK with backoff).
+     * Use for "not ready yet" (replica missing) and transient failures.
+     * Safe to call from handlers whose tests pass a bare { ack } mock.
+     */
+    defer(msg, reason) {
+        var _a, _b;
+        const attempt = (_b = (_a = msg === null || msg === void 0 ? void 0 : msg.info) === null || _a === void 0 ? void 0 : _a.deliveryCount) !== null && _b !== void 0 ? _b : 1;
+        const delayMs = Math.min(BASE_RETRY_MS * 2 ** (attempt - 1), MAX_RETRY_MS);
+        const why = reason ? ` (${reason})` : "";
+        if (attempt >= MAX_DELIVER) {
+            console.error(`[${this.durableName}] giving up on ${this.subject} after ${attempt} attempts${why} — event will NOT be redelivered`);
+        }
+        else {
+            console.warn(`[${this.durableName}] deferring ${this.subject}${why}; attempt ${attempt}/${MAX_DELIVER}, retry in ${delayMs}ms`);
+        }
+        if (typeof (msg === null || msg === void 0 ? void 0 : msg.nak) === "function")
+            msg.nak(delayMs);
+    }
 }
 exports.JetStreamListener = JetStreamListener;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@epztickets/common",
-  "version": "1.82.0",
+  "version": "1.83.0",
   "main": "./build/index.js",
   "types": "./build/index.d.ts",
   "files": [