@blamejs/core 0.7.18 → 0.7.19

package/lib/redis-client.js

@@ -1,519 +1,519 @@
-"use strict";
-/**
- * Bespoke RESP2 Redis client — zero npm runtime deps.
- *
- * Single-connection client with auto-reconnect, auth, optional TLS,
- * and request/response pipelining. Scope:
- *   - RESP2 protocol only (RESP3 not needed for queue-redis ops)
- *   - Single-node mode (no Cluster, no Sentinel)
- *   - TCP via node:net OR TLS via node:tls (rediss:// auto-detected)
- *   - AUTH (legacy single-arg AND ACL-style username + password)
- *   - SELECT db
- *   - Pipelining (writes are FIFO; responses dispatched in arrival order)
- *   - Lua scripting (EVAL / EVALSHA via runScript())
- *   - Reconnect with exponential backoff
- *
- * Operator API:
- *   var c = redis.create({ url: "redis://localhost:6379/0", password: "..." });
- *   await c.connect();
- *   var pong = await c.command("PING");                   // "PONG"
- *   var n   = await c.command("ZADD", "key", "1", "m");   // 1
- *   var rv  = await c.runScript(luaSrc, 1, "k1", "arg1");
- *   await c.close();
- *
- * Error convention: every failure throws a RedisError with .code so
- * callers can branch on transport vs server-side errors.
- */
-var net = require("node:net");
-var tls = require("node:tls");
-var url = require("node:url");
-var C = require("./constants");
-var safeAsync = require("./safe-async");
-var validateOpts = require("./validate-opts");
-var { RedisError } = require("./framework-error");
-
-var _err = RedisError.factory;
-
-// Radix for `.toString(N)` hex conversion. Numeric, not a byte count.
-var HEX_RADIX = 16;
-
-// ---- Wire-format encoder ----
-//
-// RESP2 inline command form for arbitrary args:
-//   *<argc>\r\n
-//   $<arglen>\r\n<argbytes>\r\n
-//   ... repeat per arg ...
-function _encodeCommand(args) {
-  if (!Array.isArray(args) || args.length === 0) {
-    throw _err("BAD_ARGS", "encodeCommand: args must be a non-empty array");
-  }
-  var parts = ["*" + args.length + "\r\n"];
-  for (var i = 0; i < args.length; i++) {
-    var a = args[i];
-    var buf;
-    if (Buffer.isBuffer(a)) {
-      buf = a;
-    } else if (a === null || a === undefined) {
-      throw _err("BAD_ARGS", "encodeCommand: arg " + i + " is null/undefined");
-    } else {
-      buf = Buffer.from(String(a), "utf8");
-    }
-    parts.push("$" + buf.length + "\r\n");
-    parts.push(buf);
-    parts.push("\r\n");
-  }
-  // Concat as Buffer — supports binary args (sealed payloads etc.)
-  var bufs = parts.map(function (p) {
-    return Buffer.isBuffer(p) ? p : Buffer.from(p, "utf8");
-  });
-  return Buffer.concat(bufs);
-}
-
-// ---- Wire-format decoder ----
-//
-// Stateful streaming parser. Returns one of:
-//   { type: "incomplete" }                — need more bytes
-//   { type: "string", value, consumed }   — simple string (+OK)
-//   { type: "error",  value, consumed }   — error line (-ERR ...)
-//   { type: "int",    value, consumed }   — integer (:42)
-//   { type: "bulk",   value, consumed }   — bulk string buffer (or null)
-//   { type: "array",  value, consumed }   — array of decoded items
-function _parseFrame(buf, offset) {
-  if (offset >= buf.length) return { type: "incomplete" };
-  var marker = buf[offset];
-  // Find next CRLF after the marker
-  var crlf = buf.indexOf("\r\n", offset + 1);
-  if (crlf === -1) return { type: "incomplete" };
-  var headerEnd = crlf;
-  var payloadStr = buf.slice(offset + 1, headerEnd).toString("utf8");
-
-  if (marker === 0x2b /* + */) {
-    return { type: "string", value: payloadStr, consumed: crlf + 2 - offset };
-  }
-  if (marker === 0x2d /* - */) {
-    return { type: "error", value: payloadStr, consumed: crlf + 2 - offset };
-  }
-  if (marker === 0x3a /* : */) {
-    var n = Number(payloadStr);
-    if (!Number.isFinite(n)) {
-      throw _err("PROTOCOL", "integer reply not finite: " + payloadStr);
-    }
-    return { type: "int", value: n, consumed: crlf + 2 - offset };
-  }
-  if (marker === 0x24 /* $ */) {
-    var len = Number(payloadStr);
-    if (!Number.isFinite(len)) {
-      throw _err("PROTOCOL", "bulk length not finite: " + payloadStr);
-    }
-    if (len === -1) return { type: "bulk", value: null, consumed: crlf + 2 - offset };
-    var dataStart = crlf + 2;
-    var dataEnd = dataStart + len;
-    if (dataEnd + 2 > buf.length) return { type: "incomplete" };
-    var bulk = buf.slice(dataStart, dataEnd);
-    return { type: "bulk", value: bulk, consumed: dataEnd + 2 - offset };
-  }
-  if (marker === 0x2a /* * */) {
-    var arrLen = Number(payloadStr);
-    if (!Number.isFinite(arrLen)) {
-      throw _err("PROTOCOL", "array length not finite: " + payloadStr);
-    }
-    if (arrLen === -1) return { type: "array", value: null, consumed: crlf + 2 - offset };
-    var items = [];
-    var cursor = crlf + 2;
-    for (var i = 0; i < arrLen; i++) {
-      var sub = _parseFrame(buf, cursor);
-      if (sub.type === "incomplete") return { type: "incomplete" };
-      items.push(sub);
-      cursor += sub.consumed;
-    }
-    return { type: "array", value: items, consumed: cursor - offset };
-  }
-  throw _err("PROTOCOL", "unknown reply marker 0x" + marker.toString(HEX_RADIX));
-}
-
-// Convert a parsed frame tree into a JavaScript-friendly value.
-// Bulks are returned as Buffer (caller decides encoding); arrays
-// recurse; errors are surfaced as { error: msg }; integers are numbers.
-function _frameToValue(frame) {
-  if (frame.type === "string")  return frame.value;
-  if (frame.type === "int")     return frame.value;
-  if (frame.type === "bulk")    return frame.value;
-  if (frame.type === "error")   return { _redisError: true, message: frame.value };
-  if (frame.type === "array") {
-    if (frame.value === null) return null;
-    return frame.value.map(_frameToValue);
-  }
-  throw _err("PROTOCOL", "_frameToValue: unknown frame type " + frame.type);
-}
-
-// ---- Client ----
-//
-// Single connection, FIFO request queue, auto-reconnect on socket
-// close. Pipelining is implicit — every command appends to the queue
-// and writes immediately; responses are dispatched in arrival order.
-function create(opts) {
-  opts = opts || {};
-  validateOpts.requireNonEmptyString(opts.url, "redis.create: opts.url", RedisError, "BAD_OPTS");
-  var parsed = _parseRedisUrl(opts.url);
-  var host = opts.host || parsed.host;
-  var port = opts.port || parsed.port;
-  var useTls = opts.tls !== undefined ? !!opts.tls : parsed.tls;
-  var password = opts.password !== undefined ? opts.password : parsed.password;
-  var username = opts.username !== undefined ? opts.username : parsed.username;
-  var db = opts.db !== undefined ? Number(opts.db) : parsed.db;
-  var connectTimeoutMs = Number(opts.connectTimeoutMs) || 5000;
-  var commandTimeoutMs = Number(opts.commandTimeoutMs) || 10000;
-  var maxReconnectAttempts = opts.maxReconnectAttempts === undefined ? 10
-                                                                    : Number(opts.maxReconnectAttempts);
-  // TLS verification controls. Operators using rediss:// against private
-  // CAs (managed Redis services, on-prem clusters with internal PKI)
-  // pin the trust roots via opts.ca; rejectUnauthorized stays on by
-  // default — never weaken verification to make a connection succeed.
-  var caBundle = opts.ca || null;
-  // SNI is only legal for hostnames; IP literals must omit servername.
-  var servername = opts.servername;
-  if (servername === undefined) {
-    servername = (/^\d+\.\d+\.\d+\.\d+$/.test(host) || host.indexOf(":") !== -1)
-                   ? undefined : host;
-  }
-
-  var socket = null;
-  var connected = false;
-  var connecting = false;
-  var closing = false;
-  var rxBuffer = Buffer.alloc(0);
-  // FIFO of in-flight commands awaiting a response
-  var pending = [];
-  // Backlog of commands queued before connect resolved
-  var backlog = [];
-  var reconnectAttempt = 0;
-  // Pub/sub demultiplex hook. When set, the receive path dispatches
-  // server-pushed "message" / "pmessage" frames (RESP arrays whose
-  // first element is one of those literals) to onPushMessage instead
-  // of consuming a pending request slot. SUBSCRIBE / UNSUBSCRIBE /
-  // PSUBSCRIBE / PUNSUBSCRIBE acks still flow through pending — they
-  // ARE responses to caller-issued commands. The split lets a single
-  // socket handle subscribe-mode acks AND the asynchronous fan-out
-  // events without confusing the FIFO.
-  var onPushMessage = typeof opts.onPushMessage === "function"
-    ? opts.onPushMessage : null;
-
-  function _scheduleReconnect() {
-    if (closing) return;
-    if (maxReconnectAttempts >= 0 && reconnectAttempt >= maxReconnectAttempts) {
-      // Drain pending callbacks with a clear error
-      var err = _err("RECONNECT_GAVE_UP",
-        "redis: gave up after " + reconnectAttempt + " reconnect attempts");
-      _drainPending(err);
-      return;
-    }
-    reconnectAttempt++;
-    var delay = Math.min(C.TIME.seconds(30), 100 * Math.pow(2, reconnectAttempt - 1));
-    setTimeout(function () { _connect().catch(function () { /* will reschedule */ }); }, delay);
-  }
-
-  function _drainPending(err) {
-    var batch = pending.slice();
-    pending.length = 0;
-    batch.forEach(function (p) { p.reject(err); });
-    var bl = backlog.slice();
-    backlog.length = 0;
-    bl.forEach(function (p) { p.reject(err); });
-  }
-
-  function _onData(chunk) {
-    rxBuffer = rxBuffer.length === 0 ? chunk : Buffer.concat([rxBuffer, chunk]);
-    while (rxBuffer.length > 0) {
-      var frame = _parseFrame(rxBuffer, 0);
-      if (frame.type === "incomplete") return;
-      var value = _frameToValue(frame);
-      rxBuffer = rxBuffer.slice(frame.consumed);
-
-      // Pub/sub push detection — server-initiated arrays beginning with
-      // "message" (3-tuple: type / channel / payload) or "pmessage"
-      // (4-tuple: type / pattern / channel / payload). Routed to
-      // onPushMessage; do not consume a pending entry.
-      if (onPushMessage && Array.isArray(value) && value.length >= 3 &&
-          Buffer.isBuffer(value[0])) {
-        var typeStr = value[0].toString("utf8");
-        if (typeStr === "message" && value.length === 3) {
-          onPushMessage({
-            pattern: null,
-            channel: Buffer.isBuffer(value[1]) ? value[1].toString("utf8") : String(value[1]),
-            payload: value[2],
-          });
-          continue;
-        }
-        if (typeStr === "pmessage" && value.length === 4) {
-          onPushMessage({
-            pattern: Buffer.isBuffer(value[1]) ? value[1].toString("utf8") : String(value[1]),
-            channel: Buffer.isBuffer(value[2]) ? value[2].toString("utf8") : String(value[2]),
-            payload: value[3],
-          });
-          continue;
-        }
-      }
-
-      if (pending.length === 0) {
-        // Orphan frame with no pending request — drop. This is the
-        // expected path for subscribe/unsubscribe acks if onPushMessage
-        // is wired but the caller didn't await them.
-        continue;
-      }
-      var p = pending.shift();
-      if (value && value._redisError) {
-        p.reject(_err("REDIS_REPLY", value.message));
-      } else {
-        p.resolve(value);
-      }
-    }
-  }
-
-  function _onSocketError(err) {
-    var werr = _err("SOCKET", "redis socket error: " + ((err && err.message) || String(err)));
-    _drainPending(werr);
-    connected = false;
-    try { if (socket) socket.destroy(); } catch (_e) { /* best-effort socket teardown */ }
-    socket = null;
-    if (!closing) _scheduleReconnect();
-  }
-
-  function _onSocketClose() {
-    connected = false;
-    if (!closing) {
-      var err = _err("SOCKET_CLOSED", "redis socket closed unexpectedly");
-      _drainPending(err);
-      socket = null;
-      _scheduleReconnect();
-    }
-  }
-
-  async function _connect() {
-    if (connected) return;
-    if (connecting) {
-      // Wait until current connect attempt resolves
-      while (connecting) await safeAsync.sleep(20);
-      return;
-    }
-    connecting = true;
-    rxBuffer = Buffer.alloc(0);
-    try {
-      socket = await new Promise(function (resolve, reject) {
-        var sock;
-        var timer = setTimeout(function () {
-          try { if (sock) sock.destroy(); } catch (_e) { /* best-effort socket teardown */ }
-          reject(_err("CONNECT_TIMEOUT",
-            "redis connect timed out after " + connectTimeoutMs + "ms (host=" + host + ":" + port + ")"));
-        }, connectTimeoutMs);
-        function onOk() {
-          clearTimeout(timer);
-          sock.removeListener("error", onErr);
-          resolve(sock);
-        }
-        function onErr(e) {
-          clearTimeout(timer);
-          try { sock.destroy(); } catch (_e) { /* best-effort socket teardown */ }
-          reject(_err("CONNECT", "redis connect failed: " + ((e && e.message) || String(e))));
-        }
-        if (useTls) {
-          var tlsConnectOpts = { host: host, port: port };
-          if (servername) tlsConnectOpts.servername = servername;
-          if (caBundle)   tlsConnectOpts.ca = caBundle;
-          sock = tls.connect(tlsConnectOpts, onOk);
-        } else {
-          sock = net.connect({ host: host, port: port }, onOk);
-        }
-        sock.once("error", onErr);
-      });
-      socket.setNoDelay(true);
-      socket.on("data", _onData);
-      socket.on("error", _onSocketError);
-      socket.on("close", _onSocketClose);
-      connected = true;
-      reconnectAttempt = 0;
-
-      // Auth + select db on (re)connect — without resetting the
-      // backlog of commands queued during disconnect. Send these
-      // BEFORE the backlog so the server is ready when backlog flushes.
-      if (password) {
-        var authArgs = username ? ["AUTH", username, password] : ["AUTH", password];
-        await _sendNoQueue(authArgs);
-      }
-      if (Number.isFinite(db) && db !== 0) {
-        await _sendNoQueue(["SELECT", String(db)]);
-      }
-
-      // Flush backlog
-      var bl = backlog.slice();
-      backlog.length = 0;
-      bl.forEach(function (entry) { _writeAndAwait(entry.args, entry.resolve, entry.reject); });
-    } catch (err) {
-      connecting = false;
-      throw err;
-    }
-    connecting = false;
-  }
-
-  // Internal helper that bypasses the connect-pending backlog (used
-  // for AUTH / SELECT during connect itself, where the socket is
-  // already up but `connected = true` is set immediately above).
-  function _sendNoQueue(args) {
-    return new Promise(function (resolve, reject) {
-      pending.push({
-        resolve: resolve,
-        reject:  reject,
-        timer:   setTimeout(function () {
-          var idx = pending.findIndex(function (p) { return p.resolve === resolve; });
-          if (idx !== -1) pending.splice(idx, 1);
-          reject(_err("COMMAND_TIMEOUT", "redis " + args[0] + " timed out"));
-        }, commandTimeoutMs),
-      });
-      try { socket.write(_encodeCommand(args)); }
-      catch (e) { reject(_err("WRITE", "redis write failed: " + ((e && e.message) || String(e)))); }
-    });
-  }
-
-  function _writeAndAwait(args, resolve, reject) {
-    var entry = {
-      resolve: function (v) { clearTimeout(entry.timer); resolve(v); },
-      reject:  function (e) { clearTimeout(entry.timer); reject(e); },
-      timer:   null,
-    };
-    entry.timer = setTimeout(function () {
-      var idx = pending.indexOf(entry);
-      if (idx !== -1) pending.splice(idx, 1);
-      reject(_err("COMMAND_TIMEOUT", "redis " + args[0] + " timed out"));
-    }, commandTimeoutMs);
-    pending.push(entry);
-    try { socket.write(_encodeCommand(args)); }
-    catch (e) {
-      var i = pending.indexOf(entry);
-      if (i !== -1) pending.splice(i, 1);
-      clearTimeout(entry.timer);
-      reject(_err("WRITE", "redis write failed: " + ((e && e.message) || String(e))));
-    }
-  }
-
-  function command() {
-    var args = Array.prototype.slice.call(arguments);
-    return new Promise(function (resolve, reject) {
-      if (closing) {
-        reject(_err("CLOSED", "redis client is closed"));
-        return;
-      }
-      if (!connected) {
-        backlog.push({ args: args, resolve: resolve, reject: reject });
-        return;
-      }
-      _writeAndAwait(args, resolve, reject);
-    });
-  }
-
-  // runScript — Redis EVAL helper. script + numKeys + key1..keyN +
-  // arg1..argM. Returns whatever the script returns, decoded by
-  // _frameToValue. Named runScript (not evalScript) so source-scan
-  // tooling looking for the JavaScript eval() pattern doesn't
-  // false-positive on this file.
-  function runScript(script, numKeys /* ...keysAndArgs */) {
-    var rest = Array.prototype.slice.call(arguments, 2);
-    var args = ["EVAL", script, String(numKeys)].concat(rest);
-    return command.apply(null, args);
-  }
-
-  async function close() {
-    closing = true;
-    var err = _err("CLOSED", "redis client closed");
-    _drainPending(err);
-    if (socket) {
-      try { socket.end(); } catch (_e) { /* best-effort socket close */ }
-      try { socket.destroy(); } catch (_e) { /* best-effort socket teardown */ }
-      socket = null;
-    }
-    connected = false;
-  }
-
-  return {
-    connect:    _connect,
-    command:    command,
-    runScript:  runScript,
-    close:      close,
-    isOpen:     function () { return connected && !closing; },
-    setOnPushMessage: function (fn) {
-      onPushMessage = typeof fn === "function" ? fn : null;
-    },
-    // Diagnostic — exposed for tests + observability
-    _state:     function () {
-      return {
-        connected: connected, closing: closing,
-        pending:   pending.length, backlog: backlog.length,
-        reconnect: reconnectAttempt,
-        host:      host, port: port, db: db, tls: useTls,
-      };
-    },
-  };
-}
-
-// Parse `redis://[username:password@]host[:port][/db]` and `rediss://...` URLs.
-// Empty-username + non-empty password is the legacy single-arg AUTH form.
-function _parseRedisUrl(s) {
-  var u;
-  try { u = new url.URL(s); }
-  catch (e) {
-    throw _err("BAD_URL", "redis url parse failed: " + ((e && e.message) || String(e)));
-  }
-  if (u.protocol !== "redis:" && u.protocol !== "rediss:") {
-    throw _err("BAD_URL", "redis url protocol must be redis: or rediss:, got " + u.protocol);
-  }
-  var dbStr = (u.pathname || "/").replace(/^\//, "");
-  var db = dbStr === "" ? 0 : Number(dbStr);
-  if (!Number.isFinite(db) || db < 0 || db > 15 || Math.floor(db) !== db) {
-    throw _err("BAD_URL", "redis url db must be integer 0..15, got " + dbStr);
-  }
-  return {
-    host:     u.hostname || "127.0.0.1",
-    port:     u.port ? Number(u.port) : 6379,
-    tls:      u.protocol === "rediss:",
-    username: u.username ? decodeURIComponent(u.username) : null,
-    password: u.password ? decodeURIComponent(u.password) : null,
-    db:       db,
-  };
-}
-
-// pickClientOpts(cfg, prefix?) — extract the standard redis-client opts
-// from a larger config bag. Lets cache-redis / pubsub-redis / queue-redis
-// / etc. forward to redisClient.create without each repeating the 9-key
-// list. The optional `prefix` lets callers whose operator-facing opts
-// are namespaced (`redisUrl`, `redisPassword`, ...) reuse the same
-// helper by passing prefix="redis" — the helper camel-cases the prefix
-// onto each key.
-//
-//   var opts = redisClient.pickClientOpts(cfg);                // unprefixed
-//   var opts = redisClient.pickClientOpts(operatorOpts, "redis"); // redisUrl etc.
-function pickClientOpts(cfg, prefix) {
-  if (!cfg || typeof cfg !== "object") return {};
-  function pick(name) {
-    if (!prefix) return cfg[name];
-    return cfg[prefix + name.charAt(0).toUpperCase() + name.slice(1)];
-  }
-  return {
-    url:                  pick("url"),
-    password:             pick("password"),
-    username:             pick("username"),
-    tls:                  pick("tls"),
-    ca:                   pick("ca"),
-    servername:           pick("servername"),
-    connectTimeoutMs:     pick("connectTimeoutMs"),
-    commandTimeoutMs:     pick("commandTimeoutMs"),
-    maxReconnectAttempts: pick("maxReconnectAttempts"),
-  };
-}
-
-module.exports = {
-  create:           create,
-  pickClientOpts:   pickClientOpts,
-  // Exposed for tests / direct callers that already manage their own socket.
-  _encodeCommand:   _encodeCommand,
-  _parseFrame:      _parseFrame,
-  _frameToValue:    _frameToValue,
-  _parseRedisUrl:   _parseRedisUrl,
-};
+"use strict";
+/**
+ * Bespoke RESP2 Redis client — zero npm runtime deps.
+ *
+ * Single-connection client with auto-reconnect, auth, optional TLS,
+ * and request/response pipelining. Scope:
+ *   - RESP2 protocol only (RESP3 not needed for queue-redis ops)
+ *   - Single-node mode (no Cluster, no Sentinel)
+ *   - TCP via node:net OR TLS via node:tls (rediss:// auto-detected)
+ *   - AUTH (legacy single-arg AND ACL-style username + password)
+ *   - SELECT db
+ *   - Pipelining (writes are FIFO; responses dispatched in arrival order)
+ *   - Lua scripting (EVAL / EVALSHA via runScript())
+ *   - Reconnect with exponential backoff
+ *
+ * Operator API:
+ *   var c = redis.create({ url: "redis://localhost:6379/0", password: "..." });
+ *   await c.connect();
+ *   var pong = await c.command("PING");                   // "PONG"
+ *   var n   = await c.command("ZADD", "key", "1", "m");   // 1
+ *   var rv  = await c.runScript(luaSrc, 1, "k1", "arg1");
+ *   await c.close();
+ *
+ * Error convention: every failure throws a RedisError with .code so
+ * callers can branch on transport vs server-side errors.
+ */
+var net = require("node:net");
+var tls = require("node:tls");
+var url = require("node:url");
+var C = require("./constants");
+var safeAsync = require("./safe-async");
+var validateOpts = require("./validate-opts");
+var { RedisError } = require("./framework-error");
+
+var _err = RedisError.factory;
+
+// Radix for `.toString(N)` hex conversion. Numeric, not a byte count.
+var HEX_RADIX = 16;
+
+// ---- Wire-format encoder ----
+//
+// RESP2 inline command form for arbitrary args:
+//   *<argc>\r\n
+//   $<arglen>\r\n<argbytes>\r\n
+//   ... repeat per arg ...
+function _encodeCommand(args) {
+  if (!Array.isArray(args) || args.length === 0) {
+    throw _err("BAD_ARGS", "encodeCommand: args must be a non-empty array");
+  }
+  var parts = ["*" + args.length + "\r\n"];
+  for (var i = 0; i < args.length; i++) {
+    var a = args[i];
+    var buf;
+    if (Buffer.isBuffer(a)) {
+      buf = a;
+    } else if (a === null || a === undefined) {
+      throw _err("BAD_ARGS", "encodeCommand: arg " + i + " is null/undefined");
+    } else {
+      buf = Buffer.from(String(a), "utf8");
+    }
+    parts.push("$" + buf.length + "\r\n");
+    parts.push(buf);
+    parts.push("\r\n");
+  }
+  // Concat as Buffer — supports binary args (sealed payloads etc.)
+  var bufs = parts.map(function (p) {
+    return Buffer.isBuffer(p) ? p : Buffer.from(p, "utf8");
+  });
+  return Buffer.concat(bufs);
+}
+
+// ---- Wire-format decoder ----
+//
+// Stateful streaming parser. Returns one of:
+//   { type: "incomplete" }                — need more bytes
+//   { type: "string", value, consumed }   — simple string (+OK)
+//   { type: "error",  value, consumed }   — error line (-ERR ...)
+//   { type: "int",    value, consumed }   — integer (:42)
+//   { type: "bulk",   value, consumed }   — bulk string buffer (or null)
+//   { type: "array",  value, consumed }   — array of decoded items
+function _parseFrame(buf, offset) {
+  if (offset >= buf.length) return { type: "incomplete" };
+  var marker = buf[offset];
+  // Find next CRLF after the marker
+  var crlf = buf.indexOf("\r\n", offset + 1);
+  if (crlf === -1) return { type: "incomplete" };
+  var headerEnd = crlf;
+  var payloadStr = buf.slice(offset + 1, headerEnd).toString("utf8");
+
+  if (marker === 0x2b /* + */) {
+    return { type: "string", value: payloadStr, consumed: crlf + 2 - offset };
+  }
+  if (marker === 0x2d /* - */) {
+    return { type: "error", value: payloadStr, consumed: crlf + 2 - offset };
+  }
+  if (marker === 0x3a /* : */) {
+    var n = Number(payloadStr);
+    if (!Number.isFinite(n)) {
+      throw _err("PROTOCOL", "integer reply not finite: " + payloadStr);
+    }
+    return { type: "int", value: n, consumed: crlf + 2 - offset };
+  }
+  if (marker === 0x24 /* $ */) {
+    var len = Number(payloadStr);
+    if (!Number.isFinite(len)) {
+      throw _err("PROTOCOL", "bulk length not finite: " + payloadStr);
+    }
+    if (len === -1) return { type: "bulk", value: null, consumed: crlf + 2 - offset };
+    var dataStart = crlf + 2;
+    var dataEnd = dataStart + len;
+    if (dataEnd + 2 > buf.length) return { type: "incomplete" };
+    var bulk = buf.slice(dataStart, dataEnd);
+    return { type: "bulk", value: bulk, consumed: dataEnd + 2 - offset };
+  }
+  if (marker === 0x2a /* * */) {
+    var arrLen = Number(payloadStr);
+    if (!Number.isFinite(arrLen)) {
+      throw _err("PROTOCOL", "array length not finite: " + payloadStr);
+    }
+    if (arrLen === -1) return { type: "array", value: null, consumed: crlf + 2 - offset };
+    var items = [];
+    var cursor = crlf + 2;
+    for (var i = 0; i < arrLen; i++) {
+      var sub = _parseFrame(buf, cursor);
+      if (sub.type === "incomplete") return { type: "incomplete" };
+      items.push(sub);
+      cursor += sub.consumed;
+    }
+    return { type: "array", value: items, consumed: cursor - offset };
+  }
+  throw _err("PROTOCOL", "unknown reply marker 0x" + marker.toString(HEX_RADIX));
+}
+
+// Convert a parsed frame tree into a JavaScript-friendly value.
+// Bulks are returned as Buffer (caller decides encoding); arrays
+// recurse; errors are surfaced as { error: msg }; integers are numbers.
+function _frameToValue(frame) {
+  if (frame.type === "string")  return frame.value;
+  if (frame.type === "int")     return frame.value;
+  if (frame.type === "bulk")    return frame.value;
+  if (frame.type === "error")   return { _redisError: true, message: frame.value };
+  if (frame.type === "array") {
+    if (frame.value === null) return null;
+    return frame.value.map(_frameToValue);
+  }
+  throw _err("PROTOCOL", "_frameToValue: unknown frame type " + frame.type);
+}
+
+// ---- Client ----
+//
+// Single connection, FIFO request queue, auto-reconnect on socket
+// close. Pipelining is implicit — every command appends to the queue
+// and writes immediately; responses are dispatched in arrival order.
+function create(opts) {
+  opts = opts || {};
+  validateOpts.requireNonEmptyString(opts.url, "redis.create: opts.url", RedisError, "BAD_OPTS");
+  var parsed = _parseRedisUrl(opts.url);
+  var host = opts.host || parsed.host;
+  var port = opts.port || parsed.port;
+  var useTls = opts.tls !== undefined ? !!opts.tls : parsed.tls;
+  var password = opts.password !== undefined ? opts.password : parsed.password;
+  var username = opts.username !== undefined ? opts.username : parsed.username;
+  var db = opts.db !== undefined ? Number(opts.db) : parsed.db;
+  var connectTimeoutMs = Number(opts.connectTimeoutMs) || 5000;
+  var commandTimeoutMs = Number(opts.commandTimeoutMs) || 10000;
+  var maxReconnectAttempts = opts.maxReconnectAttempts === undefined ? 10
+                                                                    : Number(opts.maxReconnectAttempts);
+  // TLS verification controls. Operators using rediss:// against private
+  // CAs (managed Redis services, on-prem clusters with internal PKI)
+  // pin the trust roots via opts.ca; rejectUnauthorized stays on by
+  // default — never weaken verification to make a connection succeed.
+  var caBundle = opts.ca || null;
+  // SNI is only legal for hostnames; IP literals must omit servername.
+  var servername = opts.servername;
+  if (servername === undefined) {
+    servername = (/^\d+\.\d+\.\d+\.\d+$/.test(host) || host.indexOf(":") !== -1)
+                   ? undefined : host;
+  }
+
+  var socket = null;
+  var connected = false;
+  var connecting = false;
+  var closing = false;
+  var rxBuffer = Buffer.alloc(0);
+  // FIFO of in-flight commands awaiting a response
+  var pending = [];
+  // Backlog of commands queued before connect resolved
+  var backlog = [];
+  var reconnectAttempt = 0;
+  // Pub/sub demultiplex hook. When set, the receive path dispatches
+  // server-pushed "message" / "pmessage" frames (RESP arrays whose
+  // first element is one of those literals) to onPushMessage instead
+  // of consuming a pending request slot. SUBSCRIBE / UNSUBSCRIBE /
+  // PSUBSCRIBE / PUNSUBSCRIBE acks still flow through pending — they
+  // ARE responses to caller-issued commands. The split lets a single
+  // socket handle subscribe-mode acks AND the asynchronous fan-out
+  // events without confusing the FIFO.
+  var onPushMessage = typeof opts.onPushMessage === "function"
+    ? opts.onPushMessage : null;
+
+  function _scheduleReconnect() {
+    if (closing) return;
+    if (maxReconnectAttempts >= 0 && reconnectAttempt >= maxReconnectAttempts) {
+      // Drain pending callbacks with a clear error
+      var err = _err("RECONNECT_GAVE_UP",
+        "redis: gave up after " + reconnectAttempt + " reconnect attempts");
+      _drainPending(err);
+      return;
+    }
+    reconnectAttempt++;
+    var delay = Math.min(C.TIME.seconds(30), 100 * Math.pow(2, reconnectAttempt - 1));
+    setTimeout(function () { _connect().catch(function () { /* will reschedule */ }); }, delay);
+  }
+
+  function _drainPending(err) {
+    var batch = pending.slice();
+    pending.length = 0;
+    batch.forEach(function (p) { p.reject(err); });
+    var bl = backlog.slice();
+    backlog.length = 0;
+    bl.forEach(function (p) { p.reject(err); });
+  }
+
+  function _onData(chunk) {
+    rxBuffer = rxBuffer.length === 0 ? chunk : Buffer.concat([rxBuffer, chunk]);
+    while (rxBuffer.length > 0) {
+      var frame = _parseFrame(rxBuffer, 0);
+      if (frame.type === "incomplete") return;
+      var value = _frameToValue(frame);
+      rxBuffer = rxBuffer.slice(frame.consumed);
+
+      // Pub/sub push detection — server-initiated arrays beginning with
+      // "message" (3-tuple: type / channel / payload) or "pmessage"
+      // (4-tuple: type / pattern / channel / payload). Routed to
+      // onPushMessage; do not consume a pending entry.
+      if (onPushMessage && Array.isArray(value) && value.length >= 3 &&
+          Buffer.isBuffer(value[0])) {
+        var typeStr = value[0].toString("utf8");
+        if (typeStr === "message" && value.length === 3) {
+          onPushMessage({
+            pattern: null,
+            channel: Buffer.isBuffer(value[1]) ? value[1].toString("utf8") : String(value[1]),
+            payload: value[2],
+          });
+          continue;
+        }
+        if (typeStr === "pmessage" && value.length === 4) {
+          onPushMessage({
+            pattern: Buffer.isBuffer(value[1]) ? value[1].toString("utf8") : String(value[1]),
+            channel: Buffer.isBuffer(value[2]) ? value[2].toString("utf8") : String(value[2]),
+            payload: value[3],
+          });
+          continue;
+        }
+      }
+
+      if (pending.length === 0) {
+        // Orphan frame with no pending request — drop. This is the
+        // expected path for subscribe/unsubscribe acks if onPushMessage
+        // is wired but the caller didn't await them.
+        continue;
+      }
+      var p = pending.shift();
+      if (value && value._redisError) {
+        p.reject(_err("REDIS_REPLY", value.message));
+      } else {
+        p.resolve(value);
+      }
+    }
+  }
+
+  function _onSocketError(err) {
+    var werr = _err("SOCKET", "redis socket error: " + ((err && err.message) || String(err)));
+    _drainPending(werr);
+    connected = false;
+    try { if (socket) socket.destroy(); } catch (_e) { /* best-effort socket teardown */ }
+    socket = null;
+    if (!closing) _scheduleReconnect();
+  }
+
+  function _onSocketClose() {
+    connected = false;
+    if (!closing) {
+      var err = _err("SOCKET_CLOSED", "redis socket closed unexpectedly");
+      _drainPending(err);
+      socket = null;
+      _scheduleReconnect();
+    }
+  }
+
+  async function _connect() {
+    if (connected) return;
+    if (connecting) {
+      // Wait until current connect attempt resolves
+      while (connecting) await safeAsync.sleep(20);
+      return;
+    }
+    connecting = true;
+    rxBuffer = Buffer.alloc(0);
+    try {
+      socket = await new Promise(function (resolve, reject) {
+        var sock;
+        var timer = setTimeout(function () {
+          try { if (sock) sock.destroy(); } catch (_e) { /* best-effort socket teardown */ }
+          reject(_err("CONNECT_TIMEOUT",
+            "redis connect timed out after " + connectTimeoutMs + "ms (host=" + host + ":" + port + ")"));
+        }, connectTimeoutMs);
+        function onOk() {
+          clearTimeout(timer);
+          sock.removeListener("error", onErr);
+          resolve(sock);
+        }
+        function onErr(e) {
+          clearTimeout(timer);
+          try { sock.destroy(); } catch (_e) { /* best-effort socket teardown */ }
+          reject(_err("CONNECT", "redis connect failed: " + ((e && e.message) || String(e))));
+        }
+        if (useTls) {
+          var tlsConnectOpts = { host: host, port: port };
+          if (servername) tlsConnectOpts.servername = servername;
+          if (caBundle)   tlsConnectOpts.ca = caBundle;
+          sock = tls.connect(tlsConnectOpts, onOk);
+        } else {
+          sock = net.connect({ host: host, port: port }, onOk);
+        }
+        sock.once("error", onErr);
+      });
+      socket.setNoDelay(true);
+      socket.on("data", _onData);
+      socket.on("error", _onSocketError);
+      socket.on("close", _onSocketClose);
+      connected = true;
+      reconnectAttempt = 0;
+
+      // Auth + select db on (re)connect — without resetting the
+      // backlog of commands queued during disconnect. Send these
+      // BEFORE the backlog so the server is ready when backlog flushes.
+      if (password) {
+        var authArgs = username ? ["AUTH", username, password] : ["AUTH", password];
+        await _sendNoQueue(authArgs);
+      }
+      if (Number.isFinite(db) && db !== 0) {
+        await _sendNoQueue(["SELECT", String(db)]);
+      }
+
+      // Flush backlog
+      var bl = backlog.slice();
+      backlog.length = 0;
+      bl.forEach(function (entry) { _writeAndAwait(entry.args, entry.resolve, entry.reject); });
+    } catch (err) {
+      connecting = false;
+      throw err;
+    }
+    connecting = false;
+  }
+
+  // Internal helper that bypasses the connect-pending backlog (used
+  // for AUTH / SELECT during connect itself, where the socket is
+  // already up but `connected = true` is set immediately above).
+  function _sendNoQueue(args) {
+    return new Promise(function (resolve, reject) {
+      pending.push({
+        resolve: resolve,
+        reject:  reject,
+        timer:   setTimeout(function () {
+          var idx = pending.findIndex(function (p) { return p.resolve === resolve; });
+          if (idx !== -1) pending.splice(idx, 1);
+          reject(_err("COMMAND_TIMEOUT", "redis " + args[0] + " timed out"));
+        }, commandTimeoutMs),
+      });
+      try { socket.write(_encodeCommand(args)); }
+      catch (e) { reject(_err("WRITE", "redis write failed: " + ((e && e.message) || String(e)))); }
+    });
+  }
+
+  function _writeAndAwait(args, resolve, reject) {
+    var entry = {
+      resolve: function (v) { clearTimeout(entry.timer); resolve(v); },
+      reject:  function (e) { clearTimeout(entry.timer); reject(e); },
+      timer:   null,
+    };
+    entry.timer = setTimeout(function () {
+      var idx = pending.indexOf(entry);
+      if (idx !== -1) pending.splice(idx, 1);
+      reject(_err("COMMAND_TIMEOUT", "redis " + args[0] + " timed out"));
+    }, commandTimeoutMs);
+    pending.push(entry);
+    try { socket.write(_encodeCommand(args)); }
+    catch (e) {
+      var i = pending.indexOf(entry);
+      if (i !== -1) pending.splice(i, 1);
+      clearTimeout(entry.timer);
+      reject(_err("WRITE", "redis write failed: " + ((e && e.message) || String(e))));
+    }
+  }
+
+  function command() {
+    var args = Array.prototype.slice.call(arguments);
+    return new Promise(function (resolve, reject) {
+      if (closing) {
+        reject(_err("CLOSED", "redis client is closed"));
+        return;
+      }
+      if (!connected) {
+        backlog.push({ args: args, resolve: resolve, reject: reject });
+        return;
+      }
+      _writeAndAwait(args, resolve, reject);
+    });
+  }
+
+  // runScript — Redis EVAL helper. script + numKeys + key1..keyN +
+  // arg1..argM. Returns whatever the script returns, decoded by
+  // _frameToValue. Named runScript (not evalScript) so source-scan
+  // tooling looking for the JavaScript eval() pattern doesn't
+  // false-positive on this file.
+  function runScript(script, numKeys /* ...keysAndArgs */) {
+    var rest = Array.prototype.slice.call(arguments, 2);
+    var args = ["EVAL", script, String(numKeys)].concat(rest);
+    return command.apply(null, args);
+  }
+
+  async function close() {
+    closing = true;
+    var err = _err("CLOSED", "redis client closed");
+    _drainPending(err);
+    if (socket) {
+      try { socket.end(); } catch (_e) { /* best-effort socket close */ }
+      try { socket.destroy(); } catch (_e) { /* best-effort socket teardown */ }
+      socket = null;
+    }
+    connected = false;
+  }
+
+  return {
+    connect:    _connect,
+    command:    command,
+    runScript:  runScript,
+    close:      close,
+    isOpen:     function () { return connected && !closing; },
+    setOnPushMessage: function (fn) {
+      onPushMessage = typeof fn === "function" ? fn : null;
+    },
+    // Diagnostic — exposed for tests + observability
+    _state:     function () {
+      return {
+        connected: connected, closing: closing,
+        pending:   pending.length, backlog: backlog.length,
+        reconnect: reconnectAttempt,
+        host:      host, port: port, db: db, tls: useTls,
+      };
+    },
+  };
+}
+
+// Parse `redis://[username:password@]host[:port][/db]` and `rediss://...` URLs.
+// Empty-username + non-empty password is the legacy single-arg AUTH form.
+function _parseRedisUrl(s) {
+  var u;
+  try { u = new url.URL(s); }
+  catch (e) {
+    throw _err("BAD_URL", "redis url parse failed: " + ((e && e.message) || String(e)));
+  }
+  if (u.protocol !== "redis:" && u.protocol !== "rediss:") {
+    throw _err("BAD_URL", "redis url protocol must be redis: or rediss:, got " + u.protocol);
+  }
+  var dbStr = (u.pathname || "/").replace(/^\//, "");
+  var db = dbStr === "" ? 0 : Number(dbStr);
+  if (!Number.isFinite(db) || db < 0 || db > 15 || Math.floor(db) !== db) {
+    throw _err("BAD_URL", "redis url db must be integer 0..15, got " + dbStr);
+  }
+  return {
+    host:     u.hostname || "127.0.0.1",
+    port:     u.port ? Number(u.port) : 6379,
+    tls:      u.protocol === "rediss:",
+    username: u.username ? decodeURIComponent(u.username) : null,
+    password: u.password ? decodeURIComponent(u.password) : null,
+    db:       db,
+  };
+}
+
+// pickClientOpts(cfg, prefix?) — extract the standard redis-client opts
+// from a larger config bag. Lets cache-redis / pubsub-redis / queue-redis
+// / etc. forward to redisClient.create without each repeating the 9-key
+// list. The optional `prefix` lets callers whose operator-facing opts
+// are namespaced (`redisUrl`, `redisPassword`, ...) reuse the same
+// helper by passing prefix="redis" — the helper camel-cases the prefix
+// onto each key.
+//
+//   var opts = redisClient.pickClientOpts(cfg);                // unprefixed
+//   var opts = redisClient.pickClientOpts(operatorOpts, "redis"); // redisUrl etc.
+function pickClientOpts(cfg, prefix) {
+  if (!cfg || typeof cfg !== "object") return {};
+  function pick(name) {
+    if (!prefix) return cfg[name];
+    return cfg[prefix + name.charAt(0).toUpperCase() + name.slice(1)];
+  }
+  return {
+    url:                  pick("url"),
+    password:             pick("password"),
+    username:             pick("username"),
+    tls:                  pick("tls"),
+    ca:                   pick("ca"),
+    servername:           pick("servername"),
+    connectTimeoutMs:     pick("connectTimeoutMs"),
+    commandTimeoutMs:     pick("commandTimeoutMs"),
+    maxReconnectAttempts: pick("maxReconnectAttempts"),
+  };
+}
+
+module.exports = {
+  create:           create,
+  pickClientOpts:   pickClientOpts,
+  // Exposed for tests / direct callers that already manage their own socket.
+  _encodeCommand:   _encodeCommand,
+  _parseFrame:      _parseFrame,
+  _frameToValue:    _frameToValue,
+  _parseRedisUrl:   _parseRedisUrl,
+};