hanzio 3.0.0 → 3.1.1

package/src/promise/index.ts

@@ -253,6 +253,106 @@ export async function pMap<T, R>(
 	return results
 }
 
+export type TaskPool = {
+	/** Queues `task`; it starts once a slot is free. */
+	run<T>(task: () => Promise<T>): Promise<T>
+	/** Resolves once every queued and active task has settled; rejects with the first failure. */
+	drain(): Promise<void>
+	/** Throws the abort reason or the first failure, if any. */
+	throwIfFailed(): void
+}
+
+/**
+ * A bounded pool for work that arrives over time, such as a crawl that queues
+ * pages as it discovers them (`pMap` needs the whole list up front).
+ *
+ * The first failure, or an abort, discards queued tasks and rejects later
+ * `run` calls; `drain` waits for active tasks to settle before rejecting with
+ * it. Pass the same `signal` to the tasks' IO so an abort interrupts them too.
+ * `stopOnError: false` keeps the pool running when a task fails, for callers
+ * that retry or fall back per task.
+ *
+ * A `run` promise that is never awaited does not cause an unhandled rejection;
+ * `drain` still reports its failure.
+ *
+ * @example
+ * const pool = createTaskPool({ concurrency: 4, signal })
+ * for await (const page of discoverPages(signal)) void pool.run(() => scrape(page, signal))
+ * await pool.drain()
+ */
+export function createTaskPool(options: {
+	concurrency: number
+	signal?: AbortSignal
+	stopOnError?: boolean
+}): TaskPool {
+	const { concurrency, signal, stopOnError = true } = options
+	if (!Number.isInteger(concurrency) || concurrency < 1)
+		throw new Error(
+			`Task concurrency must be a positive integer, got ${concurrency}`
+		)
+	const queued: { start: () => void; reject: (error: unknown) => void }[] = []
+	const idle: (() => void)[] = []
+	let active = 0
+	let failed = false
+	let failure: unknown
+	const throwIfFailed = () => {
+		signal?.throwIfAborted()
+		if (failed) throw failure
+	}
+	const stop = (error: unknown) => {
+		if (!failed) {
+			failed = true
+			failure = error
+		}
+		for (const task of queued.splice(0)) task.reject(failure)
+	}
+	const dispatch = () => {
+		if (signal?.aborted) stop(signal.reason)
+		while (!failed && active < concurrency && queued.length) {
+			active += 1
+			queued.shift()!.start()
+		}
+		if (!active && !queued.length)
+			for (const resolve of idle.splice(0)) resolve()
+	}
+	const run = <T>(task: () => Promise<T>): Promise<T> => {
+		const result = new Promise<T>((resolve, reject) => {
+			if (failed || signal?.aborted) {
+				stop(signal?.aborted ? signal.reason : failure)
+				reject(failure)
+				return
+			}
+			queued.push({
+				reject,
+				start: () => {
+					void Promise.resolve()
+						.then(() => {
+							throwIfFailed()
+							return task()
+						})
+						.then(resolve, (error: unknown) => {
+							if (stopOnError || signal?.aborted) stop(error)
+							reject(error)
+						})
+						.finally(() => {
+							active -= 1
+							dispatch()
+						})
+				}
+			})
+			dispatch()
+		})
+		void result.catch(() => {})
+		return result
+	}
+	const drain = async () => {
+		if (active || queued.length)
+			await new Promise<void>((resolve) => idle.push(resolve))
+		throwIfFailed()
+	}
+	return { run, drain, throwIfFailed }
+}
+
 const clock = (): number => globalThis.performance?.now() ?? Date.now()
 
 /** Starts a clock; call the returned function to read elapsed ms. */

package/src/redis/README.md

@@ -0,0 +1,112 @@
+---
+description: Bun Redis client that reconnects and shares subscriptions, plus a fleet-wide concurrency limiter built on Lua scripts.
+---
+
+# hanzio/redis
+
+For Bun servers. The client wraps `Bun.RedisClient`; the limiter takes any
+`send(command, args)` function, so it also works with other clients.
+
+```ts
+import {
+	createLuaScript,
+	createManagedRedis,
+	createRedisConcurrencyLimit
+} from 'hanzio/redis'
+```
+
+## Managed client
+
+```ts
+export const redis = createManagedRedis({
+	url: () => getSecret('REDIS_URL'),
+	onError: (error, { role, stage, channel }) =>
+		captureException(error, 'redis', { role, stage, channel })
+})
+
+await redis.getClient().set('key', 'value')
+
+const unsubscribe = await redis.subscribe('orders', (message, channel) => {
+	handle(JSON.parse(message))
+})
+await unsubscribe()
+
+redis.getStats() // { channelCount, channels, isConnected, isSubscriberConnected }
+redis.close() // on shutdown
+```
+
+- `getClient()` returns one shared command connection. Both connections retry
+  forever (Bun gives up after about 20 seconds by default) and queue commands
+  while offline. If Bun closes one permanently, the next call builds a new one.
+- `subscribe` shares one Redis `SUBSCRIBE` per channel, however many handlers
+  listen. The channel is unsubscribed when its last handler leaves. After a
+  reconnect, or a replaced subscriber connection, every channel is subscribed
+  again. A failed `SUBSCRIBE` rejects and leaves nothing behind.
+- `onError` receives every failure: a connection that closed unexpectedly
+  (`stage: 'close'`), a failed subscribe, resubscribe or unsubscribe, and a
+  handler that threw. It defaults to `console.error`. It is not throttled, so
+  throttle error tracking yourself if a Redis outage would flood it.
+- `close()` closes both connections. Errors caused by the close itself, such as
+  an in-flight unsubscribe rejected with "Connection closed", are not reported.
+- `createClient(url, options)` replaces `new Bun.RedisClient(url, options)`,
+  for example in tests.
+
+## Concurrency limiter
+
+`createRedisConcurrencyLimit` is a semaphore shared by every process: at most
+`max` callbacks run at once for `key`.
+
+```ts
+const withOpenAiSlot = createRedisConcurrencyLimit({
+	key: 'openai',
+	max: 20,
+	slotTtlMs: 30_000,
+	maxStartsPerSecond: 10, // optional: also cap starts in a sliding 1s window
+	send: (command, args) => redis.getClient().send(command, args)
+})
+
+const reply = await withOpenAiSlot(() => openai.chat(request), signal)
+
+// After a 429 with Retry-After, pause every process together:
+await withOpenAiSlot.tripCooldown(retryAfterMs)
+```
+
+- Redis owns the clock (`TIME`), so drifting pod clocks cannot evict a slot
+  that is still held.
+- A held slot is renewed for as long as the callback runs. `slotTtlMs` is how
+  quickly a crashed process's slots free themselves, not a time limit.
+- Waiters in one process queue locally and are granted in one batched script
+  call, so Redis traffic follows the cap, not the number of waiters.
+- If Redis has been unreachable for `failOpenAfterMs` (15s) the limiter runs
+  callbacks uncapped, and later calls skip Redis until a background probe sees
+  it again. Commands time out after `commandTimeoutMs` (3s).
+- Aborting `signal` stops waiting; a slot granted at the same moment is
+  released.
+- Keys use a hash tag (`{key}:inflight`), so the scripts work on Redis Cluster.
+
+Metrics and logs are hooks:
+
+```ts
+const withLimit = createRedisConcurrencyLimit({
+	...options,
+	logger, // throttled warnings; defaults to console
+	onWait: (stage) => {
+		const timer = waitHistogram.startTimer({ pool: 'openai', stage })
+		return () => timer.stop()
+	}
+})
+queueDepthGauge.observe(() => withLimit.queueDepth())
+```
+
+A limiter created per tenant or per host should report under a shared pool
+label, not its key, and must be `dispose()`d when discarded.
+
+## Lua scripts
+
+`createLuaScript(send, source)` sends a script by SHA (`EVALSHA`) and falls back
+to `EVAL` when Redis has forgotten it after a restart or `SCRIPT FLUSH`.
+
+```ts
+const increment = createLuaScript(send, `return redis.call('INCRBY', KEYS[1], ARGV[1])`)
+await increment(['counter'], ['2'])
+```

package/src/redis/client.ts

@@ -0,0 +1,239 @@
+import type { RedisClient, RedisOptions } from 'bun'
+
+export type RedisRole = 'client' | 'subscriber'
+
+export type RedisErrorContext = {
+	role: RedisRole
+	stage: 'close' | 'subscribe' | 'resubscribe' | 'unsubscribe' | 'handler'
+	channel?: string
+}
+
+export type ManagedRedisOptions = {
+	/** Read when a connection is created, so a secret store can resolve it lazily. */
+	url: string | (() => string)
+	/** Every failure, for logging, metrics and error tracking. Defaults to `console.error`. */
+	onError?: (error: unknown, context: RedisErrorContext) => void
+	/** Builds each connection. Defaults to `new Bun.RedisClient(url, options)`. */
+	createClient?: (url: string, options: RedisOptions) => RedisClient
+}
+
+export type RedisMessageHandler = (message: string, channel: string) => void
+
+export type ManagedRedis = {
+	/** The shared command connection, created on first use. */
+	getClient(): RedisClient
+	/**
+	 * Subscribes `handler` to `channel` on the shared subscriber connection.
+	 * Channels are ref-counted: Redis sees one `SUBSCRIBE` however many handlers
+	 * share it, and the returned function unsubscribes when the last one leaves.
+	 */
+	subscribe(
+		channel: string,
+		handler: RedisMessageHandler
+	): Promise<() => Promise<void>>
+	isConnected(): boolean
+	getStats(): {
+		channelCount: number
+		channels: string[]
+		isConnected: boolean
+		isSubscriberConnected: boolean
+	}
+	/** Closes both connections. Errors from the shutdown itself are not reported. */
+	close(): void
+}
+
+/**
+ * Reconnect effectively forever. Bun caps its backoff at about 2s, so a large
+ * budget keeps a long-lived server reconnecting through extended outages
+ * (Bun's default of 10 gives up after about 20s). Transient drops re-fire
+ * `onconnect`, which resubscribes channels; `onclose` only fires on a
+ * permanent close or an explicit `close()`.
+ */
+const CONNECTION_OPTIONS: RedisOptions = {
+	autoReconnect: true,
+	maxRetries: 1_000_000_000,
+	enableOfflineQueue: true
+}
+
+function defaultCreateClient(url: string, options: RedisOptions) {
+	return new Bun.RedisClient(url, options)
+}
+
+function defaultOnError(error: unknown, context: RedisErrorContext) {
+	const channel = context.channel ? ` (${context.channel})` : ''
+	console.error(
+		`Redis ${context.role} ${context.stage} failed${channel}`,
+		error
+	)
+}
+
+/**
+ * A command connection plus one shared subscriber connection for a Bun
+ * server. Both reconnect on their own, and subscriptions come back after a
+ * reconnect.
+ *
+ * @example
+ * export const redis = createManagedRedis({
+ *   url: () => getSecret('REDIS_URL'),
+ *   onError: (error, context) => captureException(error, 'redis', context)
+ * })
+ * await redis.getClient().set('key', 'value')
+ * const unsubscribe = await redis.subscribe('events', (message) => handle(message))
+ */
+export function createManagedRedis(options: ManagedRedisOptions): ManagedRedis {
+	const createClient = options.createClient ?? defaultCreateClient
+	const report = options.onError ?? defaultOnError
+	const url = () =>
+		typeof options.url === 'function' ? options.url() : options.url
+
+	let client: RedisClient | null = null
+	let subscriber: RedisClient | null = null
+	const handlers = new Map<string, Set<{ handler: RedisMessageHandler }>>()
+	const listeners = new Map<string, RedisMessageHandler>()
+	const subscribing = new Map<string, Promise<unknown>>()
+
+	function listenerFor(channel: string) {
+		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: RedisClient) {
+		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 = () => {
+			void resubscribe(connection)
+		}
+		// close() detaches the connection first, so a deliberate close (which Bun
+		// still reports as an error) returns here without being reported.
+		connection.onclose = (error) => {
+			if (subscriber !== connection) return
+			subscriber = null
+			listeners.clear()
+			report(error, { role: 'subscriber', stage: 'close' })
+			// A fresh connection resubscribes the remaining channels on connect.
+			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
+			// Drop the dead reference so the next call builds a fresh client.
+			client = null
+			if (error) report(error, { role: 'client', stage: 'close' })
+		}
+		client = connection
+		return connection
+	}
+
+	async function subscribe(channel: string, handler: RedisMessageHandler) {
+		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)
+			void 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) {
+				// close() rejects in-flight commands; once this connection is no
+				// longer current the channel is already gone.
+				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 {
+				// Already closed.
+			}
+		}
+	}
+
+	return {
+		getClient,
+		subscribe,
+		isConnected: () => client?.connected === true,
+		getStats: () => ({
+			channelCount: handlers.size,
+			channels: [...handlers.keys()],
+			isConnected: client?.connected === true,
+			isSubscriberConnected: subscriber?.connected === true
+		}),
+		close
+	}
+}