@vereda/http 1.0.0

package/src/core/validate.ts

@@ -0,0 +1,163 @@
+import { ConfigurationError } from "./errors.ts";
+import type {
+	CircuitBreakerConfig,
+	ClientConfig,
+	PartitionConfig,
+	RequestOptions,
+	RetryConfig,
+	TimeoutConfig,
+} from "./types.ts";
+
+// Every numeric check is written so that NaN fails it: `NaN <= 0` is false,
+// so a bare `x <= 0` guard would let NaN through (and `attemptMs: NaN` would
+// silently mean "no timeout"). `!(x > 0)` rejects it.
+
+function isPositiveInteger(value: number): boolean {
+	return Number.isInteger(value) && value >= 1;
+}
+
+/** Realm-safe ReadableStream detection — instanceof fails across realms
+ *  (vm contexts, other copies of node:stream/web). No non-stream BodyInit
+ *  member has getReader, so duck-typing is safe here. */
+export function isReadableStream(body: unknown): body is ReadableStream {
+	return body != null && typeof (body as { getReader?: unknown }).getReader === "function";
+}
+
+/** A raw ReadableStream body cannot be replayed across retries, so it must be
+ *  supplied via a factory. Throws ConfigurationError otherwise. */
+export function validateRequestBody(body: BodyInit | (() => BodyInit) | undefined): void {
+	if (isReadableStream(body)) {
+		throw new ConfigurationError("body must be supplied as a factory (() => BodyInit) when it is a ReadableStream");
+	}
+}
+
+export function validateConfig(config: ClientConfig): void {
+	if (config.baseUrl !== undefined && !URL.canParse(config.baseUrl)) {
+		throw new ConfigurationError("baseUrl must be an absolute URL");
+	}
+
+	if (config.concurrency !== undefined && !isPositiveInteger(config.concurrency)) {
+		throw new ConfigurationError("concurrency must be a positive integer");
+	}
+
+	// 0 is valid globally: no waiting, overflow rejects with QueueFullError.
+	if (config.maxQueueSize !== undefined && !(Number.isInteger(config.maxQueueSize) && config.maxQueueSize >= 0)) {
+		throw new ConfigurationError("maxQueueSize must be a non-negative integer");
+	}
+
+	if (!config.timeout || config.timeout.attemptMs === undefined) {
+		throw new ConfigurationError(
+			"timeout.attemptMs is required — pass a positive number, or Infinity to explicitly opt out of a per-attempt timeout",
+		);
+	}
+	validateTimeoutConfig(config.timeout, "timeout");
+	validateRetryConfig(config.retry, "retry");
+	validateCircuitBreakerConfig(config.circuitBreaker, "circuitBreaker");
+	validatePartitions(config.partitions);
+}
+
+/** Validates a single request's own `timeout`/`retry` options — the raw
+ *  values passed to `client.get()`/`.post()`/etc., before they're merged onto
+ *  partition/client defaults. Reuses the same rules as `validateConfig`, so
+ *  an invalid request-level value (e.g. `timeout: { attemptMs: -5 }`) is
+ *  rejected the same way an invalid client config is, just surfaced as a
+ *  ticket `ConfigurationError` instead of a throw from `create()`. Omitted
+ *  fields stay valid (inherit the client/partition default), and `Infinity`
+ *  stays a legal explicit `attemptMs`/`totalMs`. */
+export function validateRequestOptions(options: Pick<RequestOptions, "timeout" | "retry">): void {
+	validateTimeoutConfig(options.timeout, "request.timeout");
+	validateRetryConfig(options.retry, "request.retry");
+}
+
+function validateTimeoutConfig(timeout: TimeoutConfig | undefined, prefix: string): void {
+	if (!timeout) return;
+
+	if (timeout.attemptMs !== undefined && !(timeout.attemptMs > 0)) {
+		throw new ConfigurationError(`${prefix}.attemptMs must be positive`);
+	}
+
+	if (timeout.totalMs !== undefined && !(timeout.totalMs > 0)) {
+		throw new ConfigurationError(`${prefix}.totalMs must be positive`);
+	}
+}
+
+function validateRetryConfig(retry: RetryConfig | undefined, prefix: string): void {
+	if (!retry) return;
+
+	if (retry.maxRetries !== undefined && !(Number.isInteger(retry.maxRetries) && retry.maxRetries >= 0)) {
+		throw new ConfigurationError(`${prefix}.maxRetries must be a non-negative integer`);
+	}
+
+	if (retry.retryOnStatus !== undefined) {
+		for (const status of retry.retryOnStatus) {
+			if (!Number.isInteger(status) || status < 400 || status > 599) {
+				throw new ConfigurationError(
+					`${prefix}.retryOnStatus must contain only integer HTTP error status codes (400-599)`,
+				);
+			}
+		}
+	}
+
+	if (retry.backoff && typeof retry.backoff === "object") {
+		const { baseDelayMs, maxDelayMs } = retry.backoff;
+		if (baseDelayMs !== undefined && !(baseDelayMs >= 0)) {
+			throw new ConfigurationError(`${prefix}.backoff.baseDelayMs must be non-negative`);
+		}
+		if (maxDelayMs !== undefined && !(maxDelayMs >= 0)) {
+			throw new ConfigurationError(`${prefix}.backoff.maxDelayMs must be non-negative`);
+		}
+		if (baseDelayMs !== undefined && maxDelayMs !== undefined && baseDelayMs > maxDelayMs) {
+			throw new ConfigurationError(`${prefix}.backoff.baseDelayMs must not exceed maxDelayMs`);
+		}
+	}
+}
+
+function validatePartitions(partitions: Record<string, PartitionConfig> | undefined): void {
+	if (!partitions) return;
+	for (const [name, config] of Object.entries(partitions)) {
+		if (config.concurrency !== undefined && !isPositiveInteger(config.concurrency)) {
+			throw new ConfigurationError(`partitions.${name}.concurrency must be a positive integer`);
+		}
+		if (config.maxQueueSize !== undefined && !isPositiveInteger(config.maxQueueSize)) {
+			throw new ConfigurationError(`partitions.${name}.maxQueueSize must be a positive integer`);
+		}
+		validateRetryConfig(config.retry, `partitions.${name}.retry`);
+		validateTimeoutConfig(config.timeout, `partitions.${name}.timeout`);
+		validateCircuitBreakerConfig(config.circuitBreaker, `partitions.${name}.circuitBreaker`);
+	}
+}
+
+function validateCircuitBreakerConfig(breaker: CircuitBreakerConfig | undefined, prefix: string): void {
+	if (!breaker) return;
+
+	if (breaker.failureThreshold !== undefined && !isPositiveInteger(breaker.failureThreshold)) {
+		throw new ConfigurationError(`${prefix}.failureThreshold must be a positive integer`);
+	}
+	// Finite: the open -> half-open transition is a timer, and an unbounded
+	// reset would keep the circuit open forever.
+	if (
+		breaker.resetTimeoutMs !== undefined &&
+		!(Number.isFinite(breaker.resetTimeoutMs) && breaker.resetTimeoutMs > 0)
+	) {
+		throw new ConfigurationError(`${prefix}.resetTimeoutMs must be a positive finite number`);
+	}
+	// 0 would admit no half-open trial, so the circuit could never close again.
+	if (breaker.halfOpenMaxAttempts !== undefined && !isPositiveInteger(breaker.halfOpenMaxAttempts)) {
+		throw new ConfigurationError(`${prefix}.halfOpenMaxAttempts must be a positive integer`);
+	}
+	if (breaker.isFailure !== undefined && typeof breaker.isFailure !== "function") {
+		throw new ConfigurationError(`${prefix}.isFailure must be a function`);
+	}
+
+	const { window } = breaker;
+	if (window === undefined) return;
+	if (!(Number.isFinite(window.sizeMs) && window.sizeMs > 0)) {
+		throw new ConfigurationError(`${prefix}.window.sizeMs must be a positive finite number`);
+	}
+	if (!(window.failureRatePercent > 0 && window.failureRatePercent <= 100)) {
+		throw new ConfigurationError(`${prefix}.window.failureRatePercent must be greater than 0 and at most 100`);
+	}
+	if (!isPositiveInteger(window.minimumRequests)) {
+		throw new ConfigurationError(`${prefix}.window.minimumRequests must be a positive integer`);
+	}
+}

package/src/middleware/index.ts

@@ -0,0 +1,63 @@
+import { redactUrl } from "../core/redact.ts";
+
+export type { MiddlewareFn, NextFn, RequestContext } from "../queue/executor.ts";
+
+/**
+ * Adds a base set of headers to every request. Only sets a header the
+ * request doesn't already have — comparison is case-insensitive, so a
+ * request-level `authorization` header wins over a default `Authorization`.
+ *
+ * @example
+ * client.use(defaultHeaders({ 'X-Api-Key': 'secret' }));
+ */
+export function defaultHeaders(headers: HeadersInit): import("../queue/executor.ts").MiddlewareFn {
+	return async (ctx, next) => {
+		for (const [key, value] of new Headers(headers)) {
+			if (!ctx.headers.has(key)) {
+				ctx.headers.set(key, value);
+			}
+		}
+		return next(ctx);
+	};
+}
+
+/**
+ * Logs request timing to the console (or a provided logger). Logged URLs are
+ * redacted like the client's own (`redactUrl`): query values and userinfo
+ * credentials are replaced with `[redacted]`. Middleware can't see the
+ * client's `redactQuery` setting, so pass `redactQuery: false` here too to
+ * log raw URLs.
+ *
+ * @example
+ * client.use(requestLogger());
+ */
+export function requestLogger(options?: {
+	log?: (msg: string, meta: Record<string, unknown>) => void;
+	/** @default true */
+	redactQuery?: boolean;
+}): import("../queue/executor.ts").MiddlewareFn {
+	// biome-ignore lint/suspicious/noConsole: console is the intended default sink for this opt-in logger middleware; callers override it via options.log.
+	const log = options?.log ?? ((msg, meta) => console.log(msg, meta));
+
+	const shownUrl = options?.redactQuery === false ? (url: string) => url : redactUrl;
+
+	return async (ctx, next) => {
+		const start = Date.now();
+		try {
+			const response = await next(ctx);
+			log("Request completed", {
+				url: shownUrl(ctx.url),
+				status: response.status,
+				durationMs: Date.now() - start,
+			});
+			return response;
+		} catch (err) {
+			log("Request failed", {
+				url: shownUrl(ctx.url),
+				error: err instanceof Error ? err.message : String(err),
+				durationMs: Date.now() - start,
+			});
+			throw err;
+		}
+	};
+}

package/src/queue/bulkhead.ts

@@ -0,0 +1,243 @@
+import { CancelledError, QueueFullError } from "../core/errors.ts";
+import { DEFAULT_CONCURRENCY, DEFAULT_MAX_QUEUE_SIZE, type PartitionConfig } from "../core/types.ts";
+import type { Semaphore } from "./semaphore.ts";
+
+/** Default TTL (ms) before an idle partition registry entry (bulkhead or
+ *  circuit breaker) is swept from its registry. Shared by both registries
+ *  so the eviction policy stays in one place. */
+export const DEFAULT_PARTITION_TTL_MS = 60_000;
+
+export class Bulkhead {
+	public readonly name: string;
+	private readonly concurrency: number;
+	private readonly maxQueueSize: number;
+	private readonly _limitFirstAttempts: boolean;
+	private running = 0;
+	private readonly _waitQueue: Array<() => void> = [];
+
+	constructor(name: string, config: PartitionConfig = {}) {
+		this.name = name;
+		this.concurrency = config.concurrency ?? DEFAULT_CONCURRENCY;
+		this.maxQueueSize = config.maxQueueSize ?? DEFAULT_MAX_QUEUE_SIZE;
+		this._limitFirstAttempts = config.limitFirstAttempts ?? false;
+	}
+
+	get queueSize(): number {
+		return this._waitQueue.length;
+	}
+
+	get runningCount(): number {
+		return this.running;
+	}
+
+	get concurrencyLimit(): number {
+		return this.concurrency;
+	}
+
+	get maxQueueSizeLimit(): number {
+		return this.maxQueueSize;
+	}
+
+	get limitFirstAttempts(): boolean {
+		return this._limitFirstAttempts;
+	}
+
+	/** Acquire a concurrency slot, execute `task`, release the slot.
+	 *  Rejects with `QueueFullError` when the queue is at capacity.
+	 *  `this.running` is decremented *before* the returned Promise resolves,
+	 *  giving consumers an accurate count immediately after `await`.
+	 *  When a global `semaphore` is provided, a permit is acquired after the
+	 *  partition slot and released before it (D4).
+	 *  `onDequeue`, if given, fires once — right before `task()` starts —
+	 *  with the ms elapsed since `run()` was called, covering both the
+	 *  partition wait and the semaphore wait.
+	 *  If `signal` aborts while the caller is still waiting (for a partition
+	 *  slot or a global permit), it leaves the queue and the promise rejects
+	 *  with `CancelledError` without running `task` (B9). Once `task` has
+	 *  started, cancelling it is the task's own job. */
+	run<T>(
+		task: () => Promise<T>,
+		semaphore?: Semaphore,
+		onDequeue?: (queuedMs: number) => void,
+		signal?: AbortSignal,
+	): Promise<T> {
+		const enqueuedAt = Date.now();
+		return new Promise<T>((resolve, reject) => {
+			if (signal?.aborted) {
+				reject(new CancelledError());
+				return;
+			}
+
+			const onAbort = () => {
+				const idx = this._waitQueue.indexOf(execute);
+				if (idx !== -1) this._waitQueue.splice(idx, 1);
+				reject(new CancelledError());
+			};
+
+			const execute = () => {
+				signal?.removeEventListener("abort", onAbort);
+				this.running++;
+				// `release`, when given, must run BEFORE _releaseSlot(): releasing
+				// the slot synchronously drains the next waiter, which may call
+				// semaphore.acquire() immediately — if the permit hasn't actually
+				// been freed yet (i.e. this ran after _releaseSlot instead of
+				// before), that acquire can spuriously see none available and
+				// reject even though one was about to free.
+				const runTask = (release?: () => void) => {
+					onDequeue?.(Date.now() - enqueuedAt);
+					return task().then(
+						(result) => {
+							release?.();
+							this._releaseSlot();
+							resolve(result);
+						},
+						(err) => {
+							release?.();
+							this._releaseSlot();
+							reject(err);
+						},
+					);
+				};
+
+				if (semaphore) {
+					semaphore.acquire(signal).then(
+						(release) => {
+							// void: outcomes are routed to the outer resolve/reject inside runTask.
+							void runTask(release);
+						},
+						(err) => {
+							// The partition slot was granted but the global semaphore
+							// rejected (queue full, or cancelled while waiting for a
+							// permit) — release the slot we already
+							// counted, or it leaks as a permanently phantom-running slot.
+							// Report how long this attempt actually waited before being
+							// told no; it never reached runTask's own onDequeue call.
+							onDequeue?.(Date.now() - enqueuedAt);
+							this._releaseSlot();
+							reject(err);
+						},
+					);
+				} else {
+					// void: outcomes are routed to the outer resolve/reject inside runTask.
+					void runTask();
+				}
+			};
+
+			if (this.running < this.concurrency) {
+				execute();
+			} else if (this._waitQueue.length < this.maxQueueSize) {
+				signal?.addEventListener("abort", onAbort, { once: true });
+				this._waitQueue.push(execute);
+			} else {
+				reject(new QueueFullError(this.name, this._waitQueue.length, this.maxQueueSize));
+			}
+		});
+	}
+
+	/** Free a counted slot and hand it to the next waiter, if any. Every path
+	 *  that decrements `running` — task success, task failure, and a rejected
+	 *  semaphore acquire after the slot was already granted — must go through
+	 *  this, or a slot leaks as permanently phantom-running. */
+	private _releaseSlot(): void {
+		this.running--;
+		this._drainWaitQueue();
+	}
+
+	private _drainWaitQueue(): void {
+		while (this.running < this.concurrency && this._waitQueue.length > 0) {
+			const next = this._waitQueue.shift()!;
+			next();
+		}
+	}
+}
+
+// ---------------------------------------------------------------------------
+// Bulkhead registry — one bulkhead per partition
+// ---------------------------------------------------------------------------
+
+export interface BulkheadSnapshot {
+	name: string;
+	running: number;
+	queued: number;
+	concurrency: number;
+	maxQueueSize: number;
+}
+
+type BulkheadEntry = [Bulkhead, number];
+
+export class BulkheadRegistry {
+	private readonly bulkheads = new Map<string, BulkheadEntry>();
+	private readonly ttlMs: number;
+	private readonly globalConfig: PartitionConfig;
+	private readonly partitionConfigs: Record<string, PartitionConfig>;
+	private readonly sweepInterval: number;
+	private readonly semaphore?: Semaphore;
+	private callCounter = 0;
+
+	constructor(
+		globalConfig: PartitionConfig = {},
+		partitionConfigs: Record<string, PartitionConfig> = {},
+		ttlMs: number = DEFAULT_PARTITION_TTL_MS,
+		semaphore?: Semaphore,
+	) {
+		this.ttlMs = ttlMs;
+		this.globalConfig = globalConfig;
+		this.partitionConfigs = partitionConfigs;
+		this.sweepInterval = 10;
+		this.semaphore = semaphore;
+	}
+
+	get(partitionName: string): Bulkhead {
+		this.callCounter++;
+
+		if (!this.bulkheads.has(partitionName)) {
+			const partitionConfig = this.partitionConfigs[partitionName] ?? {};
+			const merged: PartitionConfig = {
+				...this.globalConfig,
+				...partitionConfig,
+			};
+			this.bulkheads.set(partitionName, [new Bulkhead(partitionName, merged), Date.now()]);
+		}
+		const [bh] = this.bulkheads.get(partitionName)!;
+		// Update last accessed time
+		this.bulkheads.set(partitionName, [bh, Date.now()]);
+
+		// Sweep stale entries periodically
+		if (this.callCounter % this.sweepInterval === 0 || this.bulkheads.size > 100) {
+			this.prune();
+		}
+
+		return bh;
+	}
+
+	prune(): void {
+		const now = Date.now();
+		for (const [key, [, lastAccessed]] of this.bulkheads) {
+			if (now - lastAccessed > this.ttlMs) {
+				this.bulkheads.delete(key);
+			}
+		}
+	}
+
+	delete(partitionName: string): void {
+		this.bulkheads.delete(partitionName);
+	}
+
+	getAll(): BulkheadSnapshot[] {
+		const result: BulkheadSnapshot[] = [];
+		for (const [, [bh]] of this.bulkheads) {
+			result.push({
+				name: bh.name,
+				running: bh.runningCount,
+				queued: bh.queueSize,
+				concurrency: bh.concurrencyLimit,
+				maxQueueSize: bh.maxQueueSizeLimit,
+			});
+		}
+		return result;
+	}
+
+	getSemaphore(): Semaphore | undefined {
+		return this.semaphore;
+	}
+}