hanzio 2.2.0 → 3.1.0

package/dist/src/redis/index.js

@@ -0,0 +1,577 @@
+// src/redis/client.ts
+var CONNECTION_OPTIONS = {
+  autoReconnect: true,
+  maxRetries: 1e9,
+  enableOfflineQueue: true
+};
+function defaultCreateClient(url, options) {
+  return new Bun.RedisClient(url, options);
+}
+function defaultOnError(error, context) {
+  const channel = context.channel ? ` (${context.channel})` : "";
+  console.error(`Redis ${context.role} ${context.stage} failed${channel}`, error);
+}
+function createManagedRedis(options) {
+  const createClient = options.createClient ?? defaultCreateClient;
+  const report = options.onError ?? defaultOnError;
+  const url = () => typeof options.url === "function" ? options.url() : options.url;
+  let client = null;
+  let subscriber = null;
+  const handlers = new Map;
+  const listeners = new Map;
+  const subscribing = new Map;
+  function listenerFor(channel) {
+    let listener = listeners.get(channel);
+    if (!listener) {
+      listener = (message, messageChannel) => {
+        if (messageChannel !== channel)
+          return;
+        for (const entry of [...handlers.get(channel) ?? []]) {
+          try {
+            entry.handler(message, channel);
+          } catch (error) {
+            report(error, { role: "subscriber", stage: "handler", channel });
+          }
+        }
+      };
+      listeners.set(channel, listener);
+    }
+    return listener;
+  }
+  async function resubscribe(connection) {
+    for (const channel of handlers.keys()) {
+      try {
+        await connection.subscribe(channel, listenerFor(channel));
+      } catch (error) {
+        report(error, { role: "subscriber", stage: "resubscribe", channel });
+      }
+    }
+  }
+  function getSubscriber() {
+    if (subscriber)
+      return subscriber;
+    const connection = createClient(url(), CONNECTION_OPTIONS);
+    connection.onconnect = () => {
+      resubscribe(connection);
+    };
+    connection.onclose = (error) => {
+      if (subscriber !== connection)
+        return;
+      subscriber = null;
+      listeners.clear();
+      report(error, { role: "subscriber", stage: "close" });
+      if (handlers.size > 0)
+        getSubscriber();
+    };
+    subscriber = connection;
+    return connection;
+  }
+  function getClient() {
+    if (client)
+      return client;
+    const connection = createClient(url(), CONNECTION_OPTIONS);
+    connection.onclose = (error) => {
+      if (client !== connection)
+        return;
+      client = null;
+      if (error)
+        report(error, { role: "client", stage: "close" });
+    };
+    client = connection;
+    return connection;
+  }
+  async function subscribe(channel, handler) {
+    const entry = { handler };
+    let entries = handlers.get(channel);
+    if (!entries) {
+      entries = new Set;
+      handlers.set(channel, entries);
+    }
+    entries.add(entry);
+    let pending = subscribing.get(channel);
+    const first = !pending && entries.size === 1;
+    if (first) {
+      pending = getSubscriber().subscribe(channel, listenerFor(channel));
+      subscribing.set(channel, pending);
+      pending.catch(() => {}).finally(() => {
+        if (subscribing.get(channel) === pending)
+          subscribing.delete(channel);
+      });
+    }
+    try {
+      await pending;
+    } catch (error) {
+      entries.delete(entry);
+      if (entries.size === 0 && handlers.get(channel) === entries) {
+        handlers.delete(channel);
+        listeners.delete(channel);
+      }
+      if (first)
+        report(error, { role: "subscriber", stage: "subscribe", channel });
+      throw error;
+    }
+    let left = false;
+    return async () => {
+      if (left)
+        return;
+      left = true;
+      const current = handlers.get(channel);
+      if (!current?.delete(entry) || current.size > 0)
+        return;
+      handlers.delete(channel);
+      const listener = listeners.get(channel);
+      listeners.delete(channel);
+      const connection = subscriber;
+      try {
+        if (listener)
+          await connection?.unsubscribe(channel, listener);
+      } catch (error) {
+        if (subscriber !== connection)
+          return;
+        report(error, { role: "subscriber", stage: "unsubscribe", channel });
+      }
+    };
+  }
+  function close() {
+    const connections = [client, subscriber];
+    client = null;
+    subscriber = null;
+    handlers.clear();
+    listeners.clear();
+    subscribing.clear();
+    for (const connection of connections) {
+      try {
+        connection?.close();
+      } catch {}
+    }
+  }
+  return {
+    getClient,
+    subscribe,
+    isConnected: () => client?.connected === true,
+    getStats: () => ({
+      channelCount: handlers.size,
+      channels: [...handlers.keys()],
+      isConnected: client?.connected === true,
+      isSubscriberConnected: subscriber?.connected === true
+    }),
+    close
+  };
+}
+// src/redis/lua-script.ts
+function isNoScriptError(error) {
+  const message = error instanceof Error ? error.message : String(error);
+  return message.includes("NOSCRIPT");
+}
+function createLuaScript(send, source) {
+  let sha = null;
+  let loading = null;
+  function load() {
+    loading ??= send("SCRIPT", ["LOAD", source]).then(String).finally(() => {
+      loading = null;
+    });
+    return loading;
+  }
+  return async function evalScript(keys, args) {
+    const tail = [String(keys.length), ...keys, ...args];
+    sha ??= await load();
+    try {
+      return await send("EVALSHA", [sha, ...tail]);
+    } catch (error) {
+      if (!isNoScriptError(error))
+        throw error;
+      sha = null;
+      return await send("EVAL", [source, ...tail]);
+    }
+  };
+}
+
+// src/redis/concurrency-limit.ts
+var POLL_MS = 100;
+var FAILURE_LOG_THROTTLE_MS = 1e4;
+var DEFAULT_FAIL_OPEN_AFTER_MS = 15000;
+var DEFAULT_COMMAND_TIMEOUT_MS = 3000;
+var START_WINDOW_MS = 1000;
+var MAX_COOLDOWN_MS = 5 * 60 * 1000;
+var BREAKER_PROBE_INTERVAL_MS = 5000;
+var MAX_RENEW_BATCH = 200;
+var NOW_MS_LUA = `
+local time = redis.call('TIME')
+local now = tonumber(time[1]) * 1000 + math.floor(tonumber(time[2]) / 1000)
+`;
+var ACQUIRE_SCRIPT = `
+local inflightKey = KEYS[1]
+local cooldownKey = KEYS[2]
+local limit = tonumber(ARGV[1])
+local ttlMs = tonumber(ARGV[2])
+local cooldownMs = redis.call('PTTL', cooldownKey)
+if cooldownMs > 0 then
+  return {0, cooldownMs}
+end
+${NOW_MS_LUA}
+redis.call('ZREMRANGEBYSCORE', inflightKey, '-inf', now)
+local free = limit - redis.call('ZCARD', inflightKey)
+local granted = 0
+while granted < free and (granted + 3) <= #ARGV do
+  redis.call('ZADD', inflightKey, now + ttlMs, ARGV[granted + 3])
+  granted = granted + 1
+end
+if granted > 0 then
+  redis.call('PEXPIRE', inflightKey, ttlMs)
+end
+return {granted, 0}
+`.trim();
+var START_SCRIPT = `
+local startsKey = KEYS[1]
+local cooldownKey = KEYS[2]
+local limit = tonumber(ARGV[1])
+local windowMs = tonumber(ARGV[2])
+local cooldownMs = redis.call('PTTL', cooldownKey)
+if cooldownMs > 0 then
+  return {0, cooldownMs}
+end
+${NOW_MS_LUA}
+redis.call('ZREMRANGEBYSCORE', startsKey, '-inf', now - windowMs)
+local free = limit - redis.call('ZCARD', startsKey)
+local granted = 0
+while granted < free and (granted + 3) <= #ARGV do
+  redis.call('ZADD', startsKey, now, ARGV[granted + 3])
+  granted = granted + 1
+end
+if granted > 0 then
+  redis.call('PEXPIRE', startsKey, windowMs)
+end
+local waitMs = 0
+if granted < (#ARGV - 2) then
+  local oldest = redis.call('ZRANGE', startsKey, 0, 0, 'WITHSCORES')
+  if oldest[2] then
+    waitMs = math.ceil(tonumber(oldest[2]) + windowMs - now)
+    if waitMs < 0 then
+      waitMs = 0
+    end
+  end
+end
+return {granted, waitMs}
+`.trim();
+var RENEW_SCRIPT = `
+local key = KEYS[1]
+local ttlMs = tonumber(ARGV[1])
+${NOW_MS_LUA}
+local renewed = 0
+for i = 2, #ARGV do
+  if redis.call('ZSCORE', key, ARGV[i]) then
+    redis.call('ZADD', key, now + ttlMs, ARGV[i])
+    renewed = renewed + 1
+  end
+end
+if renewed > 0 then
+  redis.call('PEXPIRE', key, ttlMs)
+end
+return renewed
+`.trim();
+var TRIP_COOLDOWN_SCRIPT = `
+local key = KEYS[1]
+local waitMs = tonumber(ARGV[1])
+local ttl = redis.call('PTTL', key)
+if ttl < waitMs then
+  redis.call('SET', key, '1', 'PX', ARGV[1])
+end
+return 1
+`.trim();
+function withCommandTimeout(send, timeoutMs) {
+  return async (command, args) => {
+    let timer;
+    try {
+      return await Promise.race([
+        send(command, args),
+        new Promise((_, reject) => {
+          timer = setTimeout(() => reject(new Error(`Redis command timed out after ${timeoutMs}ms`)), timeoutMs);
+        })
+      ]);
+    } finally {
+      if (timer)
+        clearTimeout(timer);
+    }
+  };
+}
+function createToken() {
+  const pid = globalThis.process?.pid;
+  return pid === undefined ? crypto.randomUUID() : `${pid}:${crypto.randomUUID()}`;
+}
+function jitterMs() {
+  return Math.floor(Math.random() * POLL_MS);
+}
+function unref(timer) {
+  timer.unref?.();
+}
+function parseGrantReply(reply) {
+  const [granted, waitMs] = Array.isArray(reply) ? reply : [];
+  return {
+    granted: Math.max(0, Number(granted) || 0),
+    waitMs: Math.min(MAX_COOLDOWN_MS, Math.max(0, Number(waitMs) || 0))
+  };
+}
+function createRedisConcurrencyLimit(input) {
+  if (!Number.isInteger(input.max) || input.max < 1)
+    throw new Error(`max must be a positive integer, got ${input.max}`);
+  const logger = input.logger ?? console;
+  const commandTimeoutMs = input.commandTimeoutMs ?? DEFAULT_COMMAND_TIMEOUT_MS;
+  const send = withCommandTimeout(input.send, commandTimeoutMs);
+  const ttlMs = String(input.slotTtlMs);
+  const renewEveryMs = Math.max(100, Math.floor(input.slotTtlMs / 3));
+  const failOpenAfterMs = input.failOpenAfterMs ?? DEFAULT_FAIL_OPEN_AFTER_MS;
+  const maxStartsPerSecond = input.maxStartsPerSecond;
+  const inflightKey = `{${input.key}}:inflight`;
+  const startsKey = `{${input.key}}:starts`;
+  const cooldownKey = `{${input.key}}:cooldown`;
+  const acquireScript = createLuaScript(send, ACQUIRE_SCRIPT);
+  const startScript = createLuaScript(send, START_SCRIPT);
+  const renewScript = createLuaScript(send, RENEW_SCRIPT);
+  const tripScript = createLuaScript(send, TRIP_COOLDOWN_SCRIPT);
+  const lastFailureLogAtMs = new Map;
+  function logFailure(message, error) {
+    const nowMs = Date.now();
+    if (nowMs - (lastFailureLogAtMs.get(message) ?? 0) < FAILURE_LOG_THROTTLE_MS)
+      return;
+    lastFailureLogAtMs.set(message, nowMs);
+    logger.warn(message, { key: input.key, error });
+  }
+  let firstFailureAtMs = null;
+  let degraded = false;
+  let probeTimer = null;
+  function scheduleProbe() {
+    if (probeTimer)
+      return;
+    probeTimer = setTimeout(() => {
+      probeTimer = null;
+      probeRedis();
+    }, BREAKER_PROBE_INTERVAL_MS);
+    unref(probeTimer);
+  }
+  async function probeRedis() {
+    try {
+      await acquireScript([inflightKey, cooldownKey], [String(input.max), ttlMs]);
+      noteRedisSuccess();
+    } catch (error) {
+      logFailure("Redis concurrency probe failed", error);
+      scheduleProbe();
+    }
+  }
+  function noteRedisSuccess() {
+    firstFailureAtMs = null;
+    if (!degraded)
+      return;
+    degraded = false;
+    if (probeTimer) {
+      clearTimeout(probeTimer);
+      probeTimer = null;
+    }
+    logger.warn("Redis reachable again, concurrency limiting re-enabled", {
+      key: input.key
+    });
+  }
+  function noteRedisFailure(error) {
+    logFailure("Redis concurrency command failed, retrying", error);
+    if (degraded)
+      return true;
+    firstFailureAtMs ??= Date.now();
+    if (Date.now() - firstFailureAtMs < failOpenAfterMs)
+      return false;
+    degraded = true;
+    scheduleProbe();
+    logger.warn("Redis unreachable, running without a concurrency slot", {
+      key: input.key
+    });
+    return true;
+  }
+  function createPump(stage, maxBatch, grant) {
+    const queue = [];
+    let running = false;
+    let wakeSleeper = null;
+    function sleep(ms) {
+      return new Promise((resolve) => {
+        const timer = setTimeout(() => {
+          wakeSleeper = null;
+          resolve();
+        }, ms);
+        wakeSleeper = () => {
+          wakeSleeper = null;
+          clearTimeout(timer);
+          resolve();
+        };
+      });
+    }
+    function settleAll(grantedSlot) {
+      for (const waiter of queue.splice(0))
+        waiter.settle(grantedSlot);
+    }
+    async function loop() {
+      running = true;
+      try {
+        await Promise.resolve();
+        while (queue.length > 0) {
+          let reply;
+          try {
+            reply = await grant(queue.slice(0, maxBatch).map((waiter) => waiter.token));
+            noteRedisSuccess();
+          } catch (error) {
+            if (noteRedisFailure(error)) {
+              settleAll(false);
+              continue;
+            }
+            await sleep(POLL_MS + jitterMs());
+            continue;
+          }
+          for (const waiter of queue.splice(0, reply.granted))
+            waiter.settle(true);
+          if (queue.length === 0)
+            break;
+          await sleep((reply.waitMs || POLL_MS) + jitterMs());
+        }
+      } finally {
+        running = false;
+      }
+    }
+    return {
+      depth: () => queue.length,
+      acquire(token) {
+        const stopWait = input.onWait?.(stage);
+        const granted = new Promise((resolve) => {
+          queue.push({ token, settle: resolve });
+        });
+        if (!running)
+          loop();
+        return stopWait ? granted.finally(stopWait) : granted;
+      },
+      wake() {
+        wakeSleeper?.();
+      }
+    };
+  }
+  const slotPump = createPump("slot", input.max, async (tokens) => parseGrantReply(await acquireScript([inflightKey, cooldownKey], [String(input.max), ttlMs, ...tokens])));
+  const startPump = maxStartsPerSecond === undefined ? null : createPump("start", maxStartsPerSecond, async (tokens) => parseGrantReply(await startScript([startsKey, cooldownKey], [String(maxStartsPerSecond), String(START_WINDOW_MS), ...tokens])));
+  const queueDepth = () => slotPump.depth() + (startPump?.depth() ?? 0);
+  const heldTokens = new Set;
+  let heartbeatTimer = null;
+  function scheduleHeartbeat() {
+    if (heartbeatTimer || heldTokens.size === 0)
+      return;
+    heartbeatTimer = setTimeout(() => {
+      heartbeatTimer = null;
+      renewHeldSlots();
+    }, renewEveryMs);
+    unref(heartbeatTimer);
+  }
+  async function renewHeldSlots() {
+    const tokens = [...heldTokens];
+    for (let index = 0;index < tokens.length; index += MAX_RENEW_BATCH) {
+      try {
+        await renewScript([inflightKey], [ttlMs, ...tokens.slice(index, index + MAX_RENEW_BATCH)]);
+        noteRedisSuccess();
+      } catch (error) {
+        logFailure("Failed to renew Redis concurrency slots", error);
+      }
+    }
+    scheduleHeartbeat();
+  }
+  let pendingReleases = [];
+  let releaseFlush = null;
+  function release(token) {
+    pendingReleases.push(token);
+    releaseFlush ??= (async () => {
+      await Promise.resolve();
+      const tokens = pendingReleases;
+      pendingReleases = [];
+      releaseFlush = null;
+      try {
+        await send("ZREM", [inflightKey, ...tokens]);
+        noteRedisSuccess();
+      } catch (error) {
+        logFailure("Failed to release Redis concurrency slot", error);
+      }
+      slotPump.wake();
+    })();
+    return releaseFlush;
+  }
+  async function tripCooldown(retryAfterMs) {
+    const waitMs = Math.min(MAX_COOLDOWN_MS, Math.max(0, Math.ceil(retryAfterMs)));
+    if (waitMs === 0)
+      return;
+    try {
+      await tripScript([cooldownKey], [String(waitMs)]);
+    } catch (error) {
+      logFailure("Failed to trip Redis rate-limit cooldown", error);
+    }
+  }
+  async function waitForGrant(pending, signal, lateGrant) {
+    if (!signal)
+      return pending;
+    let aborted = false;
+    let abort;
+    try {
+      return await Promise.race([
+        pending.then((granted) => {
+          if (aborted && granted)
+            lateGrant();
+          return granted;
+        }),
+        new Promise((_, reject) => {
+          abort = () => {
+            aborted = true;
+            reject(signal.reason);
+          };
+          signal.addEventListener("abort", abort, { once: true });
+          if (signal.aborted)
+            abort();
+        })
+      ]);
+    } finally {
+      if (abort)
+        signal.removeEventListener("abort", abort);
+    }
+  }
+  async function withRedisConcurrencyLimit(run, signal) {
+    signal?.throwIfAborted();
+    if (degraded)
+      return run();
+    const token = createToken();
+    const granted = await waitForGrant(slotPump.acquire(token), signal, () => {
+      release(token);
+    });
+    if (!granted) {
+      signal?.throwIfAborted();
+      return run();
+    }
+    heldTokens.add(token);
+    scheduleHeartbeat();
+    try {
+      if (startPump)
+        await waitForGrant(startPump.acquire(createToken()), signal, () => {});
+      signal?.throwIfAborted();
+      return await run();
+    } finally {
+      heldTokens.delete(token);
+      await release(token);
+    }
+  }
+  function dispose() {
+    if (probeTimer) {
+      clearTimeout(probeTimer);
+      probeTimer = null;
+    }
+    if (heartbeatTimer) {
+      clearTimeout(heartbeatTimer);
+      heartbeatTimer = null;
+    }
+  }
+  return Object.assign(withRedisConcurrencyLimit, {
+    tripCooldown,
+    queueDepth,
+    dispose
+  });
+}
+export {
+  createLuaScript,
+  createManagedRedis,
+  createRedisConcurrencyLimit
+};