@blamejs/blamejs-shop 0.4.31 → 0.4.33

package/lib/vendor/blamejs/test/integration/queue-sqs.test.js

@@ -0,0 +1,322 @@
+"use strict";
+/**
+ * Live SQS queue-backend round-trip — exercises lib/queue-sqs.js against
+ * LocalStack's SQS API (AWSJsonProtocol_1.0) over TLS.
+ *
+ * What this proves (real, end-to-end against a live SQS server):
+ *   - The adapter's SendMessage wire shape is correct: X-Amz-Target
+ *     AmazonSQS.SendMessage, Content-Type application/x-amz-json-1.0, a
+ *     { QueueUrl, MessageBody } body — and the message actually lands in
+ *     the queue (size() rises, ReceiveMessage returns it).
+ *   - The sealed-envelope round-trip: enqueue seals the job row through
+ *     cryptoField.sealRow("_blamejs_jobs", ...) before SendMessage; lease
+ *     unseals it on receive. A structured payload round-trips
+ *     field-identical through the SQS wire (the message body in transit is
+ *     the sealed envelope, not the cleartext payload).
+ *   - ReceiveMessage surfaces a ReceiptHandle + MessageId, and complete()
+ *     (DeleteMessage by that handle) removes the message so it does NOT
+ *     redeliver — the queue drains.
+ *   - The visibility-timeout / redelivery path: a leased-but-not-deleted
+ *     message becomes invisible for VisibilityTimeout, and fail()
+ *     (ChangeMessageVisibility VisibilityTimeout=0) makes it immediately
+ *     visible again so another consumer re-leases it.
+ *   - size() (GetQueueAttributes ApproximateNumberOfMessages) and purge()
+ *     (PurgeQueue) hit the wire and reflect the queue state.
+ *   - The endpoint override (cfg.endpoint / cfg.queueUrlByName) is
+ *     honoured — requests reach 127.0.0.1:4566, not
+ *     sqs.<region>.amazonaws.com.
+ *
+ * Scope honesty — what this does NOT prove:
+ *   LocalStack accepts the test credentials and does NOT verify the SigV4
+ *   signature (it ignores the secret key). So this proves the SQS wire /
+ *   marshalling + the send/receive/delete/ack + visibility-timeout flow,
+ *   NOT signature correctness. (Signature correctness against a server
+ *   that DOES verify SigV4 is covered by object-store-sigv4.test.js
+ *   against MinIO.)
+ *
+ * No security bypass: TLS to LocalStack trusts the test CA via
+ * NODE_EXTRA_CA_CERTS (exported by scripts/test-integration.js).
+ * rejectUnauthorized stays on; allowInternal:true only permits the
+ * loopback host, it does not disable verification. The job payload is
+ * sealed at rest in the queue (vault key + framework crypto stack) — the
+ * test registers the seal table and inits the vault exactly as a queue
+ * node would.
+ *
+ * To run:
+ *   docker compose -f docker-compose.test.yml up -d --wait
+ *   node scripts/test-integration.js --skip-service-check queue-sqs
+ */
+var fs         = require("node:fs");
+var os         = require("node:os");
+var path       = require("node:path");
+var nodeCrypto = require("node:crypto");
+var helpers    = require("../helpers");
+var check      = helpers.check;
+var services   = require("../helpers/services");
+var b          = require("../../");
+
+var queueSqs    = require("../../lib/queue-sqs");
+var cryptoField = require("../../lib/crypto-field");
+var sigv4       = require("../../lib/object-store/sigv4");
+var httpClient  = require("../../lib/http-client");
+var safeUrl     = require("../../lib/safe-url");
+
+var REGION = "us-east-1";
+var ACCESS = "test";
+var SECRET = "test";
+
+// ---- raw SigV4-signed SQS control-plane helper ----
+// The adapter intentionally has no CreateQueue / DeleteQueue (queue
+// lifecycle is operator/IaC territory), so the test stands the queue up
+// and tears it down with its own signed AWSJsonProtocol_1.0 calls — the
+// same signer the adapter uses. Returns the parsed JSON body; throws on a
+// non-2xx so the caller sees the AWS exception text.
+function _sqsCall(endpoint, action, payload) {
+  var body = Buffer.from(JSON.stringify(payload || {}), "utf8");
+  var payloadHash = nodeCrypto.createHash("sha256").update(body).digest("hex");
+  var signed = sigv4.signRequest({
+    method:           "POST",
+    url:              endpoint,
+    headers: {
+      "Content-Type": "application/x-amz-json-1.0",
+      "X-Amz-Target": "AmazonSQS." + action,
+    },
+    payloadHash:      payloadHash,
+    region:           REGION,
+    service:          "sqs",
+    accessKeyId:      ACCESS,
+    secretAccessKey:  SECRET,
+    allowedProtocols: safeUrl.ALLOW_HTTP_TLS,
+  });
+  return httpClient.request({
+    method:           "POST",
+    url:              endpoint,
+    headers:          signed.headers,
+    body:             body,
+    allowInternal:    true,
+    allowedProtocols: safeUrl.ALLOW_HTTP_TLS,
+  }).then(function (res) {
+    var text = Buffer.isBuffer(res.body) ? res.body.toString("utf8")
+            : (res.body || "").toString();
+    return text.length ? JSON.parse(text) : {};
+  });
+}
+
+async function run() {
+  var ls = await services.requireService("localstack");
+  if (!ls.ok) throw new Error("localstack unreachable: " + ls.reason);
+
+  var endpoint = services.URLS.localstack; // https://127.0.0.1:4566
+
+  // ---- 0) framework-side seal wiring ----
+  // The SQS adapter seals the job row through cryptoField.sealRow(
+  // "_blamejs_jobs", ...) before SendMessage and unsealRow()s it on
+  // receive. Without registering the table + a live vault key, sealRow is
+  // a no-op pass-through and the round-trip wouldn't actually exercise the
+  // seal/unseal envelope — so init the vault + register the table exactly
+  // as a standalone SQS queue node would (queue.init() calls
+  // _ensureSealTable() for the same reason).
+  var dataDir = fs.mkdtempSync(path.join(os.tmpdir(), "blamejs-queue-sqs-"));
+  if (typeof b.vault._resetForTest === "function") b.vault._resetForTest();
+  await b.vault.init({ dataDir: dataDir, mode: "plaintext" });
+  cryptoField.registerTable("_blamejs_jobs", { sealedFields: ["payload", "lastError"] });
+
+  // ---- 1) create a unique queue out-of-band ----
+  // LocalStack's default AWS account is 000000000000; CreateQueue echoes
+  // an AWS-shaped advertised URL (sqs.us-east-1.localhost.localstack.cloud),
+  // but the adapter routes every action to cfg.endpoint and only carries
+  // the QueueUrl in the JSON body — LocalStack accepts the path-style
+  // endpoint+accountId+name URL the adapter's own resolver synthesizes.
+  var ACCOUNT_ID = "000000000000";
+  var queueName = "blamejs-sqs-test-" + Date.now() + "-" + Math.floor(Math.random() * 1e6);
+  var created = await _sqsCall(endpoint, "CreateQueue", { QueueName: queueName });
+  var advertisedUrl = created && created.QueueUrl;
+  check("CreateQueue: returned a QueueUrl", typeof advertisedUrl === "string" && advertisedUrl.length > 0);
+  check("CreateQueue: QueueUrl carries the queue name", advertisedUrl.indexOf(queueName) !== -1);
+
+  // ---- 2) build the adapter pointed at LocalStack ----
+  // No queueUrlByName override: this exercises the adapter's built-in
+  // endpoint + accountId + name URL synthesis (the single-account default
+  // path), so the test proves that path too — not just a hand-fed resolver.
+  var q = queueSqs.create({
+    endpoint:         endpoint,
+    region:           REGION,
+    accountId:        ACCOUNT_ID,
+    accessKeyId:      ACCESS,
+    secretAccessKey:  SECRET,
+    allowInternal:    true,
+    allowedProtocols: safeUrl.ALLOW_HTTP_TLS,
+  });
+
+  // endpoint override honoured — the synthesized queue URL points at the
+  // LocalStack host, not the AWS regional host.
+  check("endpoint override honoured (queue URL is the LocalStack host, not sqs.<region>.amazonaws.com)",
+        q._queueUrl(queueName).indexOf("127.0.0.1:4566") !== -1 &&
+        q._queueUrl(queueName).indexOf("amazonaws.com") === -1);
+
+  try {
+    // ---- 3) enqueue → receive round-trip + sealed-payload fidelity ----
+    var Q = queueName;
+    var payload = {
+      kind:    "report.generate",
+      orderId: "ord-" + Math.floor(Math.random() * 1e9),
+      nested:  { tags: ["alpha", "beta"], count: 3, flag: true },
+      unicode: "café — naïve — 日本語",
+      amount:  1234.56,
+    };
+    var sentId = await q.enqueue(Q, payload, { traceId: "t-sqs-1" });
+    check("enqueue: SendMessage returned a message id", typeof sentId === "string" && sentId.length > 0);
+
+    // size() reflects the just-enqueued message (ApproximateNumberOfMessages
+    // is eventually-consistent on real SQS; LocalStack is prompt — poll).
+    var sz1 = await helpers.waitUntil(async function () {
+      var n = await q.size(Q);
+      return n >= 1 ? n : false;
+    }, { timeoutMs: 8000, label: "queue-sqs: size() reflects the enqueued message" });
+    check("size: >= 1 after enqueue", sz1 >= 1);
+
+    // Receive it. The body on the wire is the sealed envelope; lease()
+    // unseals it back to the structured payload.
+    var leased = await helpers.waitUntil(async function () {
+      var rv = await q.lease(Q, { maxRows: 5, waitTimeSec: 1, visibilityTimeoutSec: 30 });
+      return rv.length >= 1 ? rv : false;
+    }, { timeoutMs: 10000, label: "queue-sqs: ReceiveMessage returns the enqueued job" });
+    check("lease: ReceiveMessage returned exactly one job", leased.length === 1);
+
+    var job = leased[0];
+    check("lease: surfaces a ReceiptHandle (the only key for delete/visibility)",
+          typeof job.receiptHandle === "string" && job.receiptHandle.length > 0);
+    check("lease: surfaces the SQS MessageId",
+          typeof job.sqsMessageId === "string" && job.sqsMessageId.length > 0);
+    check("lease: jobId present (the framework job id, not the SQS id)",
+          typeof job.jobId === "string" && job.jobId.length > 0);
+    check("lease: queueName round-tripped through the sealed row",
+          job.queueName === Q);
+
+    // The headline proof: structured payload survives the seal → SQS wire
+    // → unseal round-trip byte/field-identical (deep equality).
+    check("lease: payload round-trips field-identical through seal + SQS wire",
+          JSON.stringify(job.payload) === JSON.stringify(payload));
+    check("lease: nested object fields intact",
+          job.payload && job.payload.nested &&
+          job.payload.nested.count === 3 && job.payload.nested.flag === true &&
+          job.payload.nested.tags.length === 2 &&
+          job.payload.nested.tags[0] === "alpha" && job.payload.nested.tags[1] === "beta");
+    check("lease: unicode payload byte-identical (no mojibake on the wire)",
+          job.payload.unicode === "café — naïve — 日本語");
+    check("lease: numeric field preserved (not stringified)",
+          job.payload.amount === 1234.56 && job.payload.orderId === payload.orderId);
+
+    // ---- 4) ack (DeleteMessage) → does NOT redeliver, queue drains ----
+    var compRv = await q.complete(Q, job.jobId, { receiptHandle: job.receiptHandle });
+    check("complete: DeleteMessage returned true", compRv === true);
+
+    // After delete, the message must not come back. Long-poll a couple of
+    // times with a fresh (short) visibility window; nothing should appear.
+    var redelivered = await q.lease(Q, { maxRows: 5, waitTimeSec: 2, visibilityTimeoutSec: 5 });
+    check("complete: deleted message does NOT redeliver (queue drained)",
+          redelivered.length === 0);
+
+    // NOTE on size() semantics: ApproximateNumberOfMessages counts only
+    // VISIBLE messages — a leased-but-not-deleted message is in-flight
+    // (NotVisible) and reports 0 here. So 0 after complete confirms the
+    // message is neither visible nor in-flight. (waitUntil treats a falsy
+    // return as "not ready", so the predicate returns true on success,
+    // not the numeric 0.)
+    var szDrained = await helpers.waitUntil(async function () {
+      var n = await q.size(Q);
+      return n === 0 ? true : false;
+    }, { timeoutMs: 8000, label: "queue-sqs: size() back to 0 after complete" });
+    check("size: 0 after complete (no in-flight, no visible)", szDrained === true);
+
+    // ---- 5) visibility-timeout / redelivery path via fail() ----
+    // Enqueue, lease with a long visibility timeout (so it would NOT come
+    // back on its own within the test window), then fail() — which sets
+    // VisibilityTimeout=0 and makes it immediately visible to the next
+    // consumer. Proves ChangeMessageVisibility re-delivery, the SQS-native
+    // retry the adapter relies on (server-side RedrivePolicy decides DLQ).
+    var redeliverPayload = { step: "retry-me", n: 7 };
+    await q.enqueue(Q, redeliverPayload, { traceId: "t-sqs-redeliver" });
+
+    var firstLease = await helpers.waitUntil(async function () {
+      var rv = await q.lease(Q, { maxRows: 1, waitTimeSec: 1, visibilityTimeoutSec: 300 });
+      return rv.length >= 1 ? rv : false;
+    }, { timeoutMs: 10000, label: "queue-sqs: redelivery job first lease" });
+    check("redelivery: first lease grabbed the job under a 300s visibility window",
+          firstLease.length === 1 && firstLease[0].payload &&
+          firstLease[0].payload.step === "retry-me");
+
+    // While the 300s visibility window is in effect, a second lease sees
+    // nothing — the message is in-flight (invisible).
+    var whileInflight = await q.lease(Q, { maxRows: 1, waitTimeSec: 1, visibilityTimeoutSec: 5 });
+    check("redelivery: message invisible to a second consumer during the visibility window",
+          whileInflight.length === 0);
+
+    // fail() → VisibilityTimeout=0 → immediately visible again.
+    var failRv = await q.fail(Q, firstLease[0].jobId, { receiptHandle: firstLease[0].receiptHandle });
+    check("fail: ChangeMessageVisibility(0) returned true", failRv === true);
+
+    var reLease = await helpers.waitUntil(async function () {
+      var rv = await q.lease(Q, { maxRows: 1, waitTimeSec: 2, visibilityTimeoutSec: 30 });
+      return rv.length >= 1 ? rv : false;
+    }, { timeoutMs: 12000, label: "queue-sqs: fail() re-delivered the job to a new consumer" });
+    check("redelivery: fail() made the message visible again (re-leased)",
+          reLease.length === 1 && reLease[0].payload &&
+          reLease[0].payload.step === "retry-me" && reLease[0].payload.n === 7);
+    check("redelivery: re-leased message carries a fresh receipt handle",
+          typeof reLease[0].receiptHandle === "string" &&
+          reLease[0].receiptHandle.length > 0);
+
+    // Clean it up so the purge leg starts from a known state.
+    await q.complete(Q, reLease[0].jobId, { receiptHandle: reLease[0].receiptHandle });
+
+    // ---- 6) extendLease (ChangeMessageVisibility to a longer window) ----
+    await q.enqueue(Q, { step: "extend-me" }, {});
+    var extLease = await helpers.waitUntil(async function () {
+      var rv = await q.lease(Q, { maxRows: 1, waitTimeSec: 1, visibilityTimeoutSec: 30 });
+      return rv.length >= 1 ? rv : false;
+    }, { timeoutMs: 10000, label: "queue-sqs: extendLease job leased" });
+    check("extendLease: job leased", extLease.length === 1);
+    var extRv = await q.extendLease(Q, extLease[0].jobId, {
+      receiptHandle: extLease[0].receiptHandle, visibilityTimeoutSec: 120,
+    });
+    check("extendLease: ChangeMessageVisibility(120) returned true", extRv === true);
+    await q.complete(Q, extLease[0].jobId, { receiptHandle: extLease[0].receiptHandle });
+
+    // ---- 7) purge clears the queue ----
+    // Re-fill, confirm size, purge, confirm drained. (PurgeQueue is
+    // 60s-rate-limited server-side; this test calls it once.)
+    await q.enqueue(Q, { p: 1 }, {});
+    await q.enqueue(Q, { p: 2 }, {});
+    await q.enqueue(Q, { p: 3 }, {});
+    var preSize = await helpers.waitUntil(async function () {
+      var n = await q.size(Q);
+      return n >= 3 ? n : false;
+    }, { timeoutMs: 8000, label: "queue-sqs: size() reflects 3 enqueued before purge" });
+    check("purge: pre-purge size >= 3", preSize >= 3);
+
+    var purgeRv = await q.purge(Q);
+    check("purge: PurgeQueue returned (count 0 — SQS doesn't report a count)", purgeRv === 0);
+
+    var postPurge = await helpers.waitUntil(async function () {
+      var n = await q.size(Q);
+      return n === 0 ? true : false;
+    }, { timeoutMs: 12000, label: "queue-sqs: size() back to 0 after PurgeQueue" });
+    check("purge: post-purge size 0", postPurge === true);
+
+  } finally {
+    // Tear the queue down (control-plane, out-of-band like creation).
+    try { await _sqsCall(endpoint, "DeleteQueue", { QueueUrl: advertisedUrl }); } catch (_e) {}
+    try { fs.rmSync(dataDir, { recursive: true, force: true }); } catch (_e) {}
+    if (typeof b.vault._resetForTest === "function") b.vault._resetForTest();
+  }
+}
+
+module.exports = { run: run };
+
+if (require.main === module) {
+  run().then(
+    function () { console.log("OK — " + helpers.getChecks() + " checks passed"); process.exit(0); },
+    function (e) { console.error("FAIL:", e.stack || e); process.exit(1); }
+  );
+}

package/lib/vendor/blamejs/test/integration/redis-reconnect-toxiproxy.test.js

@@ -0,0 +1,300 @@
+"use strict";
+/**
+ * Live reconnect / failover proof for lib/redis-client.js against a REAL
+ * redis dropped mid-connection via toxiproxy.
+ *
+ * The framework redis client points at toxiproxy's proxied redis
+ * (127.0.0.1:16379, upstream redis:6379). A working connection is
+ * established (SET/GET round-trips), then the proxy is DISABLED through
+ * the toxiproxy HTTP API (127.0.0.1:8474) so redis appears DOWN — every
+ * established connection is closed and new dials are refused. The test
+ * asserts:
+ *
+ *   1. An in-flight command issued during the outage REJECTS (with a
+ *      transport / timeout error code) rather than hanging the caller
+ *      forever — no caller wedge.
+ *   2. The client schedules a reconnect (the _state() reconnect machinery
+ *      advances) — the lost socket drives the reconnect loop.
+ *   3. No reconnect storm: one outage schedules at most ONE pending timer
+ *      at a time (the single-flight guard) — a socket failure surfacing
+ *      as BOTH `error` and `close` must not stack two reconnects and burn
+ *      the budget at 2x.
+ *   4. Re-enabling the proxy RECOVERS the client: it reconnects on its own
+ *      and a subsequent SET/GET round-trips, with the backoff counter +
+ *      give-up latch reset.
+ *
+ * Recovery is polled with helpers.waitUntil — no fixed sleep. Fault is
+ * injected over the toxiproxy HTTP control plane, not by killing the real
+ * redis (which other workflows may share); the upstream redis is never
+ * touched.
+ *
+ * Run:
+ *   node scripts/test-integration.js --skip-service-check redis-reconnect-toxiproxy
+ */
+var http = require("node:http");
+var helpers  = require("../helpers");
+var check    = helpers.check;
+var services = require("../helpers/services");
+var redisClient = require("../../lib/redis-client");
+
+// toxiproxy control plane. The proxy named "redis" listens on :16379 and
+// forwards to upstream redis:6379; flipping its `enabled` flag is the
+// outage switch (disabled = existing conns closed + new dials refused).
+var TOXIPROXY_API  = services.URLS.toxiproxy;   // http://127.0.0.1:8474
+var PROXY_NAME     = "redis";
+var PROXIED_REDIS  = services.URLS.toxiproxyRedis; // redis://127.0.0.1:16379
+
+// Minimal toxiproxy HTTP client over node:http — POST a JSON body to the
+// proxy endpoint to flip `enabled`. Returns the parsed proxy object.
+function _toxiproxyRequest(method, urlPath, bodyObj) {
+  return new Promise(function (resolve, reject) {
+    var u = new URL(TOXIPROXY_API + urlPath);
+    var payload = bodyObj === undefined ? null : Buffer.from(JSON.stringify(bodyObj), "utf8");
+    var req = http.request({
+      host:   u.hostname,
+      port:   u.port,
+      path:   u.pathname + (u.search || ""),
+      method: method,
+      headers: payload
+        ? { "content-type": "application/json", "content-length": payload.length }
+        : {},
+    }, function (res) {
+      var chunks = [];
+      res.on("data", function (c) { chunks.push(c); });
+      res.on("end", function () {
+        var raw = Buffer.concat(chunks).toString("utf8");
+        if (res.statusCode < 200 || res.statusCode >= 300) {
+          return reject(new Error("toxiproxy " + method + " " + urlPath +
+            " -> HTTP " + res.statusCode + ": " + raw));
+        }
+        var parsed = null;
+        try { parsed = raw ? JSON.parse(raw) : null; } catch (_e) { parsed = raw; }
+        resolve(parsed);
+      });
+    });
+    req.on("error", reject);
+    if (payload) req.write(payload);
+    req.end();
+  });
+}
+
+function _setProxyEnabled(enabled) {
+  return _toxiproxyRequest("POST", "/proxies/" + PROXY_NAME, { enabled: !!enabled });
+}
+
+async function run() {
+  // Probe both the proxied-redis port AND the toxiproxy control plane —
+  // either being down means we can't run the fault-injection proof.
+  var svcProxy = await services.requireService("toxiproxyRedis");
+  var svcApi   = await services.requireService("toxiproxy");
+  if (!svcProxy.ok || !svcApi.ok) {
+    console.log("  [redis-reconnect] toxiproxy unreachable — skipping " +
+      "(" + (svcProxy.ok ? "" : svcProxy.reason + " ") + (svcApi.ok ? "" : svcApi.reason) + ")");
+    console.log("  [redis-reconnect]   bring up: docker compose -f docker-compose.test.yml up -d --wait");
+    return;
+  }
+
+  // Always leave the proxy enabled when we exit, even on a mid-test
+  // failure — a left-disabled proxy would poison every later redis test.
+  var restored = false;
+  async function _restoreProxy() {
+    if (restored) return;
+    restored = true;
+    try { await _setProxyEnabled(true); } catch (_e) { /* best-effort */ }
+  }
+
+  var c = null;
+  try {
+    // Start from a known-good proxy state.
+    await _setProxyEnabled(true);
+
+    // Client through the proxy. A generous reconnect budget (the outage
+    // window spans several backoff steps) + short connect/command timeouts
+    // so an in-flight op against a dead proxy settles fast instead of
+    // sitting on the full default. db 15 isolates test data.
+    c = redisClient.create({
+      url:                  PROXIED_REDIS + "/15",
+      connectTimeoutMs:     1000,
+      commandTimeoutMs:     1500,
+      maxReconnectAttempts: 50,
+    });
+
+    // ---- 1. working connection ----
+    await c.connect();
+    check("connect: established through toxiproxy", c.isOpen());
+
+    var key = "blamejs:test:reconnect:" + Date.now();
+    var setRv = await c.command("SET", key, "before-outage");
+    check("pre-outage SET: returns OK",
+          setRv === "OK" || (Buffer.isBuffer(setRv) && setRv.toString() === "OK"));
+    var getRv = await c.command("GET", key);
+    check("pre-outage GET: round-trips",
+          Buffer.isBuffer(getRv) && getRv.toString() === "before-outage");
+
+    var stateBefore = c._state();
+    check("pre-outage _state: connected, no reconnect pending, attempt 0",
+          stateBefore.connected === true &&
+          stateBefore.reconnectPending === false &&
+          stateBefore.reconnect === 0);
+
+    // ---- 2. outage: disable the proxy. Existing conns are closed; new
+    //         dials are refused. This drives _teardownSocket → drain
+    //         pending + schedule reconnect. ----
+    await _setProxyEnabled(false);
+
+    // An in-flight op issued DURING the outage must reject, not wedge.
+    // Whether the socket-drop reaches the client before or after this
+    // write, the command settles with an error (drained pending, write
+    // failure, queued-timeout, or command-timeout) — never an unsettled
+    // await. Bound the whole thing well under any hang with waitUntil so
+    // a regression that DOES wedge fails the gate as a timeout instead of
+    // hanging the suite.
+    var inflightErr = null;
+    var inflightResolved = false;
+    var inflightSettled = false;
+    c.command("GET", key).then(
+      function ()  { inflightResolved = true; inflightSettled = true; },
+      function (e) { inflightErr = e;        inflightSettled = true; }
+    );
+    await helpers.waitUntil(function () { return inflightSettled; }, {
+      timeoutMs: 8000,
+      label:     "redis-reconnect: in-flight op settles during outage (no caller wedge)",
+    });
+    check("in-flight op during outage SETTLES (no wedge)", inflightSettled === true);
+    check("in-flight op during outage REJECTS with a transport/timeout error",
+          inflightResolved === false &&
+          inflightErr !== null && typeof inflightErr.code === "string");
+
+    // ---- 3. the lost socket scheduled a reconnect. The client is now
+    //         disconnected and the reconnect machinery is engaged
+    //         (a timer pending and/or attempts advancing). ----
+    var reconnecting = await helpers.waitUntil(function () {
+      var s = c._state();
+      // Engaged = no longer connected AND (a backoff timer is pending OR a
+      // dial is mid-flight OR at least one attempt has been counted).
+      if (s.connected) return false;
+      return (s.reconnectPending || s.connecting || s.reconnect > 0) ? s : false;
+    }, {
+      timeoutMs: 8000,
+      label:     "redis-reconnect: client schedules a reconnect after the socket drop",
+    });
+    check("outage: client is disconnected", reconnecting.connected === false);
+    check("outage: a reconnect is engaged (pending timer / dialing / attempt counted)",
+          reconnecting.reconnectPending === true ||
+          reconnecting.connecting === true ||
+          reconnecting.reconnect > 0);
+    check("outage: did NOT give up (budget not exhausted mid-outage)",
+          reconnecting.gaveUp === false);
+
+    // ---- 4. no reconnect storm. Single-flight means: at any instant at
+    //         most ONE backoff timer is pending, and the attempt counter
+    //         advances monotonically by the dial cadence — it must not
+    //         leap by 2 from a single socket failure surfacing as both
+    //         `error` and `close`. The first retry backoff is 100ms, so
+    //         sampling at 20ms (provably below the minimum inter-dial gap)
+    //         means at most ONE dial can complete per sample window; a
+    //         per-sample attempt delta of 2 would prove two reconnects
+    //         fired for one window — a storm / double-schedule. We sample
+    //         across ~2.4s, which spans the early small-backoff steps
+    //         (100/200/400/800ms) where stacking would show first. ----
+    var maxDelta = 0;
+    var prevAttempt = c._state().reconnect;
+    var sawNonBoolPending = false;    // (structurally a boolean — timer
+                                      // !== null — but assert it: a count
+                                      // here would mean stacked timers)
+    for (var i = 0; i < 120; i++) {
+      var s = c._state();
+      var delta = s.reconnect - prevAttempt;
+      if (delta > maxDelta) maxDelta = delta;
+      prevAttempt = s.reconnect;
+      if (s.reconnectPending !== true && s.reconnectPending !== false) sawNonBoolPending = true;
+      await helpers.passiveObserve(20, "redis-reconnect storm-watch sample " + i);
+    }
+    check("no reconnect storm: attempts advance by <= 1 per 20ms sample (single-flight, no double-schedule)",
+          maxDelta <= 1);
+    check("no reconnect storm: reconnectPending is always a single boolean (one timer max)",
+          sawNonBoolPending === false);
+
+    // ---- 5. recovery: re-enable the proxy. The next scheduled dial
+    //         succeeds and the client reconnects on its own. ----
+    await _setProxyEnabled(true);
+
+    // Poll a SYNCHRONOUS predicate (_state().connected) for the reconnect.
+    // Awaiting c.command() inside the predicate would backlog the command
+    // behind the client's reconnect timer — and that timer is unref'd by
+    // design (a backoff window must not by itself keep the loop alive), so
+    // with no other ref'd handle the loop could drain mid-await and the
+    // process would exit before the reconnect fires. waitUntil's own 25ms
+    // poll timer IS ref'd, so a sync predicate keeps the loop alive on each
+    // tick and lets the unref'd reconnect timer fire — the same role a
+    // real app's listening server socket plays in production.
+    var recovered = await helpers.waitUntil(function () {
+      return c._state().connected ? c._state() : false;
+    }, {
+      timeoutMs: 20000,
+      label:     "redis-reconnect: client reconnects on its own after proxy re-enabled",
+    });
+    check("recovery: client reconnected after outage", recovered.connected === true);
+    check("recovery: client reports open again", c.isOpen());
+
+    // Now that the socket is back, a fresh SET/GET must round-trip.
+    var setAfter = await c.command("SET", key, "after-recovery");
+    check("recovery: post-reconnect SET returns OK",
+          setAfter === "OK" || (Buffer.isBuffer(setAfter) && setAfter.toString() === "OK"));
+
+    var getAfter = await c.command("GET", key);
+    check("recovery: GET round-trips the post-recovery value",
+          Buffer.isBuffer(getAfter) && getAfter.toString() === "after-recovery");
+
+    var stateAfter = c._state();
+    check("recovery: reconnect counter reset to 0 on successful reconnect",
+          stateAfter.reconnect === 0);
+    check("recovery: give-up latch cleared", stateAfter.gaveUp === false);
+    check("recovery: no reconnect timer left pending", stateAfter.reconnectPending === false);
+
+    // ---- 6. the recovered connection survives a SECOND independent
+    //         outage — proves the reconnect path is reusable, not a
+    //         one-shot, and the budget genuinely reset. ----
+    await _setProxyEnabled(false);
+    await helpers.waitUntil(function () {
+      var s = c._state();
+      return (!s.connected && (s.reconnectPending || s.connecting || s.reconnect > 0)) ? s : false;
+    }, {
+      timeoutMs: 8000,
+      label:     "redis-reconnect: second outage re-engages the reconnect loop",
+    });
+    check("second outage: reconnect loop re-engaged (path is reusable)", !c._state().connected);
+
+    await _setProxyEnabled(true);
+    // Sync predicate again (see the phase-5 note on unref'd reconnect timers).
+    await helpers.waitUntil(function () {
+      return c._state().connected ? c._state() : false;
+    }, {
+      timeoutMs: 20000,
+      label:     "redis-reconnect: second recovery — client reconnects again",
+    });
+    check("second recovery: client reconnected", c.isOpen());
+    var getAfter2 = await c.command("GET", key);
+    check("second recovery: GET round-trips the prior value (path is reusable)",
+          Buffer.isBuffer(getAfter2) && getAfter2.toString() === "after-recovery");
+
+    // ---- cleanup ----
+    await c.command("DEL", key);
+  } finally {
+    await _restoreProxy();
+    if (c) { try { await c.close(); } catch (_e) {} }
+  }
+}
+
+module.exports = { run: run };
+
+if (require.main === module) {
+  run().then(
+    // No process.exit(0) on success: an immediate exit after console.log
+    // can drop the buffered banner when stdout is a pipe (the integration
+    // runner pipes it). close() + unref'd timers let the loop drain on its
+    // own, so the line flushes. The failure path still hard-exits 1.
+    function () { console.log("OK — " + helpers.getChecks() + " checks passed"); },
+    function (e) { console.error("FAIL:", e.stack || e); process.exit(1); }
+  );
+}