@cosmicdrift/kumiko-framework 0.328.0 → 0.329.0

package/src/rate-limit/resolver.ts

@@ -1,251 +0,0 @@
-import type {
-  RateLimitConfig,
-  RateLimitDecision,
-  RateLimitResolver,
-} from "@cosmicdrift/kumiko-types/rate-limit-types";
-import type Redis from "ioredis";
-// Value-only import, aliased to avoid shadowing the ambient global
-// `Temporal` TYPE that RateLimitDecision.resetAt resolves against (see
-// event-store.ts for the same #1438 dual-package-hazard pattern).
-import { Temporal as TemporalPolyfill } from "temporal-polyfill";
-import { RateLimitError } from "../errors";
-import { RedisKeys } from "../pipeline/redis-keys";
-
-// Token-Bucket rate limiter, atomic via Redis Lua. One round-trip per
-// check — the script computes the bucket state inline and either deducts
-// or rejects.
-//
-// Why Token Bucket: bursts are allowed up to `limit`, refill is steady
-// at `limit / windowSeconds` per second. Sliding window would be more
-// fair but needs more Redis ops; fixed window is simpler but gives 2x
-// burst at boundaries. Token Bucket sits in the right trade-off zone.
-//
-// Storage layout per bucket:
-//   <key> hash with two fields:
-//     tokens  — float, current tokens in the bucket
-//     ts      — last refill timestamp (ms since epoch)
-//   TTL = 2 × windowSeconds (long enough to not lose state across refill,
-//         short enough to clean up dead buckets)
-//
-// The Lua script does: load → refill based on elapsed time → check cost
-// → deduct or reject. Returns [allowed, remaining, resetAfterMs].
-
-// KEYS[1] — bucket key
-// ARGV[1] — limit (max tokens)
-// ARGV[2] — refillRatePerMs (limit / (windowSeconds * 1000))
-// ARGV[3] — cost (tokens to deduct, default 1)
-// ARGV[4] — nowMs (server time, passed in for testability + drift safety)
-// ARGV[5] — ttlSeconds (key TTL)
-//
-// Returns: { allowed (1|0), remainingTokens (int floor), retryAfterMs (int) }
-//
-// The peek script (TOKEN_BUCKET_PEEK_LUA) below is the same logic minus
-// the HMSET — used by ops queries to inspect a bucket without nudging
-// the refill timestamp. Two scripts so neither has to grow a "writeback"
-// flag and a state-machine.
-const TOKEN_BUCKET_LUA = `
-local key = KEYS[1]
-local limit = tonumber(ARGV[1])
-local refillRatePerMs = tonumber(ARGV[2])
-local cost = tonumber(ARGV[3])
-local nowMs = tonumber(ARGV[4])
-local ttl = tonumber(ARGV[5])
-
-local data = redis.call('HMGET', key, 'tokens', 'ts')
-local tokens = tonumber(data[1])
-local ts = tonumber(data[2])
-
-if tokens == nil then
-  tokens = limit
-  ts = nowMs
-else
-  local elapsed = math.max(0, nowMs - ts)
-  tokens = math.min(limit, tokens + elapsed * refillRatePerMs)
-  ts = nowMs
-end
-
-local allowed = 0
-local retryAfterMs = 0
-if tokens >= cost then
-  tokens = tokens - cost
-  allowed = 1
-else
-  -- Time until enough tokens accumulate to satisfy this request.
-  local deficit = cost - tokens
-  retryAfterMs = math.ceil(deficit / refillRatePerMs)
-end
-
-redis.call('HMSET', key, 'tokens', tokens, 'ts', ts)
-redis.call('EXPIRE', key, ttl)
-
-return { allowed, math.floor(tokens), retryAfterMs }
-`;
-
-// Read-only peek. Same refill maths, but writes nothing back — the
-// bucket state at peek time stays identical to the state the next real
-// check() would see. Used by ops/status queries that must not deduct
-// tokens or shift the refill timestamp.
-//
-// KEYS[1] — bucket key
-// ARGV[1] — limit
-// ARGV[2] — refillRatePerMs
-// ARGV[3] — nowMs
-//
-// Returns: { remainingTokens (int floor), retryAfterMs (int — until 1 token available) }
-const TOKEN_BUCKET_PEEK_LUA = `
-local key = KEYS[1]
-local limit = tonumber(ARGV[1])
-local refillRatePerMs = tonumber(ARGV[2])
-local nowMs = tonumber(ARGV[3])
-
-local data = redis.call('HMGET', key, 'tokens', 'ts')
-local tokens = tonumber(data[1])
-local ts = tonumber(data[2])
-
-if tokens == nil then
-  tokens = limit
-else
-  local elapsed = math.max(0, nowMs - ts)
-  tokens = math.min(limit, tokens + elapsed * refillRatePerMs)
-end
-
-local retryAfterMs = 0
-if tokens < 1 then
-  retryAfterMs = math.ceil((1 - tokens) / refillRatePerMs)
-end
-
-return { math.floor(tokens), retryAfterMs }
-`;
-
-export type {
-  RateLimitConfig,
-  RateLimitDecision,
-  RateLimitResolver,
-} from "@cosmicdrift/kumiko-types/rate-limit-types";
-
-export type RateLimitResolverOptions = {
-  readonly redis: Redis;
-  // Override the prefix for tests. Production uses RedisKeys.rateLimit.
-  readonly keyPrefix?: string;
-  // Override the time source for tests. Production uses Date.now().
-  readonly nowMs?: () => number;
-};
-
-type LuaResult = readonly [number, number, number];
-
-// We register the script once per Redis client via defineCommand so each
-// check is a single round-trip with the script already cached on the
-// server (ioredis falls back to LOADing the script if the SHA is
-// missing). Using defineCommand also keeps the call-site idiomatic
-// (`redis.kumikoRateLimit(...)`) instead of building raw protocol calls.
-type CommandClient = Redis & {
-  kumikoRateLimit(
-    key: string,
-    limit: string,
-    refillRatePerMs: string,
-    cost: string,
-    nowMs: string,
-    ttlSeconds: string,
-  ): Promise<LuaResult>;
-  kumikoRateLimitPeek(
-    key: string,
-    limit: string,
-    refillRatePerMs: string,
-    nowMs: string,
-  ): Promise<readonly [number, number]>;
-};
-
-const REGISTERED = new WeakSet<Redis>();
-
-function ensureCommand(redis: Redis): CommandClient {
-  if (!REGISTERED.has(redis)) {
-    redis.defineCommand("kumikoRateLimit", {
-      numberOfKeys: 1,
-      lua: TOKEN_BUCKET_LUA,
-    });
-    redis.defineCommand("kumikoRateLimitPeek", {
-      numberOfKeys: 1,
-      lua: TOKEN_BUCKET_PEEK_LUA,
-    });
-    REGISTERED.add(redis);
-  }
-  return redis as CommandClient; // @cast-boundary engine-bridge
-}
-
-export function createRateLimitResolver(opts: RateLimitResolverOptions): RateLimitResolver {
-  const client = ensureCommand(opts.redis);
-  const prefix = opts.keyPrefix ?? RedisKeys.rateLimit;
-  const now = opts.nowMs ?? (() => Date.now());
-
-  async function check(bucket: string, config: RateLimitConfig): Promise<RateLimitDecision> {
-    const cost = config.cost ?? 1;
-    const refillRatePerMs = config.limit / (config.windowSeconds * 1000);
-    const ttlSeconds = Math.max(1, config.windowSeconds * 2);
-    const nowMs = now();
-
-    const [allowedFlag, remaining, retryAfterMs] = await client.kumikoRateLimit(
-      `${prefix}${bucket}`,
-      String(config.limit),
-      String(refillRatePerMs),
-      String(cost),
-      String(nowMs),
-      String(ttlSeconds),
-    );
-
-    const retryAfterSeconds = Math.ceil(retryAfterMs / 1000);
-    const resetAt = TemporalPolyfill.Instant.fromEpochMilliseconds(nowMs + retryAfterMs);
-
-    return {
-      allowed: allowedFlag === 1,
-      limit: config.limit,
-      remaining,
-      retryAfterSeconds,
-      windowSeconds: config.windowSeconds,
-      resetAt,
-    };
-  }
-
-  async function enforce(bucket: string, config: RateLimitConfig): Promise<RateLimitDecision> {
-    const decision = await check(bucket, config);
-    if (decision.allowed) return decision;
-    throw new RateLimitError({
-      bucket,
-      limit: decision.limit,
-      windowSeconds: decision.windowSeconds,
-      remaining: decision.remaining,
-      retryAfterSeconds: decision.retryAfterSeconds,
-      resetAt: decision.resetAt.toString(),
-    });
-  }
-
-  async function peek(
-    bucket: string,
-    config: Omit<RateLimitConfig, "cost">,
-  ): Promise<RateLimitDecision> {
-    const refillRatePerMs = config.limit / (config.windowSeconds * 1000);
-    const nowMs = now();
-
-    const [remaining, retryAfterMs] = await client.kumikoRateLimitPeek(
-      `${prefix}${bucket}`,
-      String(config.limit),
-      String(refillRatePerMs),
-      String(nowMs),
-    );
-
-    const retryAfterSeconds = Math.ceil(retryAfterMs / 1000);
-    const resetAt = TemporalPolyfill.Instant.fromEpochMilliseconds(nowMs + retryAfterMs);
-
-    return {
-      // peek doesn't deduct, so a "would-be" allowed flag is meaningful:
-      // true iff at least one token is available right now.
-      allowed: remaining >= 1,
-      limit: config.limit,
-      remaining,
-      retryAfterSeconds,
-      windowSeconds: config.windowSeconds,
-      resetAt,
-    };
-  }
-
-  return { check, enforce, peek };
-}

package/src/redis/__tests__/redis-options.test.ts

@@ -1,54 +0,0 @@
-import { describe, expect, test } from "bun:test";
-import { redisClientOptionsFromEnv } from "../index";
-
-describe("redisClientOptionsFromEnv", () => {
-  test("empty env → empty options", () => {
-    expect(redisClientOptionsFromEnv({})).toEqual({});
-  });
-
-  test("reads all three supported keys", () => {
-    const opts = redisClientOptionsFromEnv({
-      REDIS_CONNECT_TIMEOUT_MS: "3000",
-      REDIS_COMMAND_TIMEOUT_MS: "5000",
-      REDIS_MAX_RETRIES_PER_REQUEST: "2",
-    });
-    expect(opts).toEqual({
-      connectTimeoutMs: 3000,
-      commandTimeoutMs: 5000,
-      maxRetriesPerRequest: 2,
-    });
-  });
-
-  test("empty string is treated as unset", () => {
-    const opts = redisClientOptionsFromEnv({
-      REDIS_CONNECT_TIMEOUT_MS: "",
-      REDIS_COMMAND_TIMEOUT_MS: "7500",
-    });
-    expect(opts).toEqual({ commandTimeoutMs: 7500 });
-  });
-
-  test("zero is allowed (e.g. 0 retries = fail-fast)", () => {
-    const opts = redisClientOptionsFromEnv({
-      REDIS_MAX_RETRIES_PER_REQUEST: "0",
-    });
-    expect(opts).toEqual({ maxRetriesPerRequest: 0 });
-  });
-
-  test("negative number → throws", () => {
-    expect(() => redisClientOptionsFromEnv({ REDIS_CONNECT_TIMEOUT_MS: "-1" })).toThrow(
-      /REDIS_CONNECT_TIMEOUT_MS="-1".*non-negative/i,
-    );
-  });
-
-  test("non-numeric → throws", () => {
-    expect(() => redisClientOptionsFromEnv({ REDIS_COMMAND_TIMEOUT_MS: "ten" })).toThrow(
-      /REDIS_COMMAND_TIMEOUT_MS="ten"/,
-    );
-  });
-
-  test("decimal → throws (ioredis expects integer ms)", () => {
-    expect(() => redisClientOptionsFromEnv({ REDIS_CONNECT_TIMEOUT_MS: "250.5" })).toThrow(
-      /REDIS_CONNECT_TIMEOUT_MS="250.5".*integer/i,
-    );
-  });
-});

package/src/redis/client.ts

@@ -1,77 +0,0 @@
-// Thin factory for ioredis clients with Prod-sensible defaults.
-// ioredis itself doesn't enforce a command-timeout — an unreachable Redis
-// will silently hang a request forever unless the caller sets
-// `commandTimeout`. Same story for connectTimeout: the default is 10s,
-// which is too long for a /health/ready probe with a 2s budget.
-//
-// Apps are expected to build their Redis clients via this helper so
-// production defaults stay consistent and env-var wiring lives in one
-// place. Tests / one-off scripts can still `new Redis()` directly.
-//
-// Split out of index.ts (fw#2625) so pubsub-signal.ts can import this
-// without a same-directory cycle back through the barrel.
-
-import IoRedis, { type Redis, type RedisOptions } from "ioredis";
-import { readPositiveIntEnv } from "../utils/env-parse";
-
-// Connection-tuning options. The fields mirror the most consequential
-// ioredis settings; anything else can be passed through via `extra` to
-// keep the helper from re-declaring the full ioredis surface.
-export type RedisClientOptions = {
-  // Milliseconds to wait when opening the TCP connection. Default 5s —
-  // long enough for a cold cache/standby to handshake, short enough that
-  // /health/ready can surface "Redis is gone" inside its 2s-ish probe
-  // window (probe runs in parallel, so 5s here + 2s timeout on the probe
-  // side gives the probe a real answer instead of a hang).
-  readonly connectTimeoutMs?: number;
-  // Milliseconds to wait for a single command to round-trip. Default 10s.
-  // Without this, ioredis waits forever on a stalled connection — a
-  // single bad network partition quietly exhausts the whole command queue.
-  readonly commandTimeoutMs?: number;
-  // Retries per request before bubbling up as an error. Default 3 — enough
-  // to ride out a transient blip but not so many that a dead Redis keeps
-  // requests stuck waiting for retries.
-  readonly maxRetriesPerRequest?: number;
-  // Escape hatch for any ioredis option the helper doesn't expose
-  // explicitly (TLS config, Sentinel, ReadyCheck toggles, …).
-  readonly extra?: Readonly<
-    Omit<RedisOptions, "connectTimeout" | "commandTimeout" | "maxRetriesPerRequest">
-  >;
-};
-
-const DEFAULT_CONNECT_TIMEOUT_MS = 5_000;
-const DEFAULT_COMMAND_TIMEOUT_MS = 10_000;
-const DEFAULT_MAX_RETRIES_PER_REQUEST = 3;
-
-export function createRedisClient(url: string, options: RedisClientOptions = {}): Redis {
-  const connectTimeout = options.connectTimeoutMs ?? DEFAULT_CONNECT_TIMEOUT_MS;
-  const commandTimeout = options.commandTimeoutMs ?? DEFAULT_COMMAND_TIMEOUT_MS;
-  const maxRetriesPerRequest = options.maxRetriesPerRequest ?? DEFAULT_MAX_RETRIES_PER_REQUEST;
-
-  return new IoRedis(url, {
-    ...options.extra,
-    connectTimeout,
-    commandTimeout,
-    maxRetriesPerRequest,
-  });
-}
-
-// Env-var reader — mirrors dbConnectionOptionsFromEnv's contract. Strict:
-// malformed values throw at boot rather than silently falling back to
-// defaults.
-export function redisClientOptionsFromEnv(
-  env: Readonly<Record<string, string | undefined>> = process.env,
-): RedisClientOptions {
-  const opts: RedisClientOptions & {
-    connectTimeoutMs?: number;
-    commandTimeoutMs?: number;
-    maxRetriesPerRequest?: number;
-  } = {};
-  const connect = readPositiveIntEnv(env, "REDIS_CONNECT_TIMEOUT_MS");
-  const command = readPositiveIntEnv(env, "REDIS_COMMAND_TIMEOUT_MS");
-  const retries = readPositiveIntEnv(env, "REDIS_MAX_RETRIES_PER_REQUEST");
-  if (connect !== undefined) opts.connectTimeoutMs = connect;
-  if (command !== undefined) opts.commandTimeoutMs = command;
-  if (retries !== undefined) opts.maxRetriesPerRequest = retries;
-  return opts;
-}

package/src/redis/index.ts

@@ -1,4 +0,0 @@
-export type { RedisClientOptions } from "./client";
-export { createRedisClient, redisClientOptionsFromEnv } from "./client";
-export type { PubSubSignal, PubSubSignalOptions } from "./pubsub-signal";
-export { createRedisPubSubSignal } from "./pubsub-signal";

package/src/redis/pubsub-signal.ts

@@ -1,107 +0,0 @@
-import { createRedisClient } from "./client";
-
-// Generic Redis Pub/Sub transport for cross-replica fanout (fw#2625).
-// Shared by the SSE broker (api/redis-sse-broker.ts, several logical
-// channels multiplexed under one prefix) and feature-toggles' cache-sync
-// signal (bundled-features, a single fixed channel) — both need the same
-// mechanics: two connections (ioredis forbids normal commands on a
-// subscriber connection), one psubscribe per instance (no per-channel
-// subscribe/unsubscribe), JSON payloads, and defensive parsing so a
-// malformed or foreign message on the pattern never crashes the listener.
-export type PubSubSignal = {
-  publish(channel: string, payload: unknown): void;
-  onMessage(listener: (channel: string, payload: unknown) => void): void;
-  close(): Promise<void>;
-};
-
-export type PubSubSignalOptions = {
-  readonly redisUrl: string;
-  // psubscribe pattern: a literal channel name is a valid (exact-match)
-  // pattern for a caller with a single fixed channel; a "prefix:*" glob
-  // is for a caller that multiplexes several logical channels under one
-  // subscription (e.g. the SSE broker's per-tenant/per-user channels).
-  readonly channelPattern: string;
-  // Included in every log line so two signals running in the same process
-  // (sse-broker, feature-toggles cache-sync) can be told apart in output.
-  readonly label: string;
-};
-
-// Redis emits 'error' on connection blips (reconnects transparently); an
-// unhandled listener crashes the process (fw#1805 — job-runner hit the same
-// class with BullMQ's internal client).
-function logConnectionError(label: string, role: string): (err: Error) => void {
-  return (err) => {
-    // biome-ignore lint/suspicious/noConsole: ops-visible fallback — no logger is threaded through PubSubSignalOptions.
-    console.error(`[kumiko:${label}] ${role} connection error:`, err.message);
-  };
-}
-
-export function createRedisPubSubSignal(opts: PubSubSignalOptions): PubSubSignal {
-  const publisher = createRedisClient(opts.redisUrl);
-  const subscriber = createRedisClient(opts.redisUrl);
-  publisher.on("error", logConnectionError(opts.label, "publisher"));
-  subscriber.on("error", logConnectionError(opts.label, "subscriber"));
-
-  const listeners = new Set<(channel: string, payload: unknown) => void>();
-  // Sole purpose: stop close() from racing the initial psubscribe (see
-  // below) and silence its logging once a shutdown is already underway —
-  // not a defense against ioredis auto-reconnecting later (quit() below
-  // never reconnects once it resolves).
-  let closed = false;
-
-  subscriber.on("pmessage", (_pattern: string, channel: string, message: string) => {
-    let payload: unknown;
-    try {
-      payload = JSON.parse(message);
-    } catch (err) {
-      // biome-ignore lint/suspicious/noConsole: ops-visible fallback, see logConnectionError above.
-      console.error(`[kumiko:${opts.label}] dropping unparseable message on "${channel}":`, err);
-      // skip: unparseable payload already logged above, nothing to deliver
-      return;
-    }
-    for (const listener of listeners) listener(channel, payload);
-  });
-
-  // ponytail: psubscribe on one pattern rather than per-channel
-  // subscribe/unsubscribe — every instance receives every message that
-  // matches, filtered by the caller. That's strictly no worse than the
-  // pre-fw#2625 per-instance-cursor model (which already read every event
-  // from Postgres in every process) and sidesteps the subscribe-ack/
-  // first-publish race a per-channel scheme would have. Revisit with
-  // per-channel subscribe only if fanout volume becomes the bottleneck.
-  //
-  // Awaited by close() below — quitting while this is still in flight (a
-  // shutdown landing immediately after construction, e.g. a test closing
-  // right after building the signal) makes ioredis rejects the queued
-  // psubscribe with "Connection is closed" instead of it completing
-  // cleanly first. Not caught here or logged when a close is already
-  // underway (`closed`), so an intentional shutdown never surfaces this
-  // as an ops-visible error.
-  const initialSubscribe = subscriber.psubscribe(opts.channelPattern).catch((err: unknown) => {
-    // skip: a close() already underway intentionally quit both connections —
-    // this rejection is the expected side effect, not an ops-visible error.
-    if (closed) return;
-    // biome-ignore lint/suspicious/noConsole: ops-visible fallback, see logConnectionError above.
-    console.error(`[kumiko:${opts.label}] psubscribe failed:`, err);
-  });
-
-  return {
-    publish(channel, payload) {
-      publisher.publish(channel, JSON.stringify(payload)).catch((err: unknown) => {
-        // skip: a close() already underway intentionally quit both
-        // connections — this rejection is the expected side effect.
-        if (closed) return;
-        // biome-ignore lint/suspicious/noConsole: ops-visible fallback, see logConnectionError above.
-        console.error(`[kumiko:${opts.label}] publish failed:`, err);
-      });
-    },
-    onMessage(listener) {
-      listeners.add(listener);
-    },
-    async close(): Promise<void> {
-      closed = true;
-      await initialSubscribe;
-      await Promise.all([publisher.quit(), subscriber.quit()]);
-    },
-  };
-}