@vereda/http 1.0.0

package/src/core/errors.ts

@@ -0,0 +1,194 @@
+export type AppError =
+	| NetworkError
+	| HttpError
+	| RetryableStatusError
+	| TimeoutError
+	| DeadlineExceededError
+	| ValidationError
+	| CancelledError
+	| QueueFullError
+	| ConfigurationError
+	| MaxRetriesExceededError
+	| CircuitOpenError;
+
+/**
+ * Base class for failures that prevent a request from
+ * producing a successful result.
+ */
+export class RequestError extends Error {
+	public readonly kind: string;
+	public cause?: unknown;
+
+	constructor(kind: string, message: string, cause?: unknown) {
+		super(message);
+		this.name = this.constructor.name;
+		this.kind = kind;
+		if (cause !== undefined) {
+			this.cause = cause;
+		}
+	}
+}
+
+export class NetworkError extends RequestError {
+	declare readonly kind: "network";
+
+	constructor(message: string, options?: { cause?: unknown }) {
+		super("network", message, options?.cause);
+	}
+}
+
+export class HttpError extends RequestError {
+	declare readonly kind: "http";
+	public readonly statusCode: number;
+	public readonly response: Response;
+
+	constructor(message: string, statusCode: number, response: Response) {
+		super("http", message);
+		this.statusCode = statusCode;
+		this.response = response;
+	}
+}
+
+export class RetryableStatusError extends RequestError {
+	declare readonly kind: "retryable_status";
+	public readonly statusCode: number;
+	public readonly response: Response;
+	public readonly retryAfterMs?: number;
+
+	constructor(message: string, statusCode: number, response: Response, retryAfterMs?: number) {
+		super("retryable_status", message);
+		this.statusCode = statusCode;
+		this.response = response;
+		if (retryAfterMs !== undefined) {
+			this.retryAfterMs = retryAfterMs;
+		}
+	}
+}
+
+/** Sentinel `timeoutMs` value reported on `TimeoutError` when no per-attempt
+ *  timeout (`TimeoutConfig.attemptMs`) was configured. Callers that construct
+ *  a `TimeoutError` for an unconfigured timeout should pass this instead of
+ *  a bare `0` so there is one place this convention is spelled out. */
+export const NO_TIMEOUT_CONFIGURED = 0;
+
+export class TimeoutError extends RequestError {
+	declare readonly kind: "timeout";
+	public readonly timeoutMs: number;
+	public readonly url: string;
+
+	constructor(url: string, timeoutMs: number) {
+		const message =
+			timeoutMs > NO_TIMEOUT_CONFIGURED
+				? `Request to ${url} timed out after ${timeoutMs}ms`
+				: `Request to ${url} timed out (no timeout configured)`;
+		super("timeout", message);
+		this.timeoutMs = timeoutMs;
+		this.url = url;
+	}
+}
+
+export class DeadlineExceededError extends RequestError {
+	declare readonly kind: "deadline";
+	public readonly url: string;
+	public readonly totalMs: number;
+
+	constructor(url: string, totalMs: number) {
+		super("deadline", `Request to ${url} exceeded total deadline of ${totalMs}ms`);
+		this.url = url;
+		this.totalMs = totalMs;
+	}
+}
+
+export class ValidationError extends RequestError {
+	declare readonly kind: "validation";
+	public readonly issues: unknown[];
+
+	constructor(message: string, issues: unknown[], cause?: unknown) {
+		super("validation", message, cause);
+		this.issues = issues;
+	}
+}
+
+export class CancelledError extends RequestError {
+	declare readonly kind: "cancelled";
+
+	constructor(message = "Request was cancelled") {
+		super("cancelled", message);
+	}
+}
+
+export class QueueFullError extends RequestError {
+	declare readonly kind: "queue_full";
+	public readonly partition: string;
+	public readonly queueSize: number;
+	public readonly maxQueueSize: number;
+
+	constructor(partition: string, queueSize: number, maxQueueSize: number) {
+		super("queue_full", `Queue for partition '${partition}' is full (${queueSize}/${maxQueueSize})`);
+		this.partition = partition;
+		this.queueSize = queueSize;
+		this.maxQueueSize = maxQueueSize;
+	}
+}
+
+export class ConfigurationError extends RequestError {
+	declare readonly kind: "configuration";
+	public readonly key: string;
+
+	constructor(key: string, options?: { cause?: unknown }) {
+		super("configuration", `Invalid configuration: ${key}`, options?.cause);
+		this.key = key;
+	}
+}
+
+export class MaxRetriesExceededError extends RequestError {
+	declare readonly kind: "max_retries";
+	public readonly attempts: number;
+	public readonly lastError: AppError;
+
+	constructor(attempts: number, lastError: AppError) {
+		super(
+			"max_retries",
+			`Request failed after ${attempts} attempt${attempts === 1 ? "" : "s"}: ${lastError.message}`,
+			lastError,
+		);
+		this.attempts = attempts;
+		this.lastError = lastError;
+	}
+}
+
+export class CircuitOpenError extends RequestError {
+	declare readonly kind: "circuit_open";
+	public readonly partition: string;
+
+	constructor(partition: string) {
+		super("circuit_open", `Circuit breaker is open for partition '${partition}'`);
+		this.partition = partition;
+	}
+}
+
+/**
+ * Narrows an unknown throw to one of this library's own error classes, so
+ * internal catch sites can preserve a pre-typed failure (e.g. a
+ * `QueueFullError` from the bulkhead) and wrap anything else.
+ */
+export function isAppError(err: unknown): err is AppError {
+	// instanceof, not a `kind` lookup: a subclass of one of these still carries
+	// its fields (e.g. statusCode), whereas a bare RequestError with a matching
+	// kind string would not.
+	return APP_ERROR_CLASSES.some((cls) => err instanceof cls);
+}
+
+const APP_ERROR_CLASSES = [
+	NetworkError,
+	HttpError,
+	RetryableStatusError,
+	TimeoutError,
+	DeadlineExceededError,
+	ValidationError,
+	CancelledError,
+	QueueFullError,
+	ConfigurationError,
+	MaxRetriesExceededError,
+	CircuitOpenError,
+] as const;

package/src/core/index.ts

@@ -0,0 +1,56 @@
+export type { RetryPolicy, RetryPolicyContext } from "../queue/policy.ts";
+export { defaultRetryPolicy } from "../queue/policy.ts";
+export type { TicketStatus, TicketUpdate } from "../ticket/ticket.ts";
+export { Ticket } from "../ticket/ticket.ts";
+export { DEFAULT_BASE_DELAY_MS, DEFAULT_JITTER, DEFAULT_MAX_DELAY_MS } from "./backoff.ts";
+export { HttpClient, json } from "./client.ts";
+export type { AppError } from "./errors.ts";
+export {
+	CancelledError,
+	CircuitOpenError,
+	ConfigurationError,
+	DeadlineExceededError,
+	HttpError,
+	MaxRetriesExceededError,
+	NetworkError,
+	NO_TIMEOUT_CONFIGURED,
+	QueueFullError,
+	RequestError,
+	RetryableStatusError,
+	TimeoutError,
+	ValidationError,
+} from "./errors.ts";
+export type { MetricsSink, MetricTags } from "./metrics.ts";
+export { METRICS } from "./metrics.ts";
+export { redactUrl } from "./redact.ts";
+export type {
+	BackoffFn,
+	BackoffOptions,
+	CircuitBreakerConfig,
+	ClientConfig,
+	ClientTimeoutConfig,
+	CloseOptions,
+	LifecycleEventMap,
+	Logger,
+	ParsedRequestOptions,
+	ParseFn,
+	PartitionConfig,
+	RequestOptions,
+	Result,
+	RetryConfig,
+	TimeoutConfig,
+	UnparsedRequestOptions,
+} from "./types.ts";
+export {
+	DEFAULT_CONCURRENCY,
+	DEFAULT_FAILURE_THRESHOLD,
+	DEFAULT_GLOBAL_CONCURRENCY,
+	DEFAULT_GLOBAL_QUEUE_SIZE,
+	DEFAULT_HALF_OPEN_MAX_ATTEMPTS,
+	DEFAULT_MAX_QUEUE_SIZE,
+	DEFAULT_MAX_RETRIES,
+	DEFAULT_RESET_TIMEOUT_MS,
+	DEFAULT_RETRY_ON_STATUS,
+	isBoundedMs,
+} from "./types.ts";
+export { validateConfig } from "./validate.ts";

package/src/core/listeners.ts

@@ -0,0 +1,28 @@
+import type { EventEmitter } from "node:events";
+
+/** Surface an error thrown by user code (an event listener or a metrics sink)
+ *  without letting it unwind through vereda's internals. It is rethrown on a
+ *  fresh microtask, so it reaches `process.on("uncaughtException")` exactly
+ *  like a throwing listener on any other emitter would — the same contract as
+ *  `node:diagnostics_channel` subscribers. Swallowing it would hide the bug;
+ *  letting it propagate synchronously would abort whatever state transition
+ *  was in progress (a ticket that never resolves, B2; a success rewritten
+ *  as a failure, B3). */
+export function reportCallbackError(err: unknown): void {
+	queueMicrotask(() => {
+		throw err;
+	});
+}
+
+/** `emitter.emit()` with per-listener isolation: every listener runs even if
+ *  an earlier one throws, and no throw escapes to the caller. */
+export function emitIsolated(emitter: EventEmitter, event: string, ...args: unknown[]): void {
+	// rawListeners, not listeners: calling a `once` wrapper also unregisters it.
+	for (const listener of emitter.rawListeners(event)) {
+		try {
+			listener(...args);
+		} catch (err) {
+			reportCallbackError(err);
+		}
+	}
+}

package/src/core/metrics.ts

@@ -0,0 +1,42 @@
+// ---------------------------------------------------------------------------
+// Metrics sink — pluggable observability (O2)
+// ---------------------------------------------------------------------------
+
+/** Tags attached to every metric emission. All values are strings so that
+ *  callers can use whatever cardinality they need. */
+export type MetricTags = Record<string, string>;
+
+/** Pluggable sink for vereda metrics. Implement this interface to wire
+ *  vereda into OpenTelemetry, Prometheus, Datadog, or any other metrics
+ *  backend. The client calls these methods at well-defined lifecycle points;
+ *  all calls are synchronous and non-blocking. */
+export interface MetricsSink {
+	/** Monotonically increasing counter (e.g. total requests, total retries). */
+	counter(name: string, value: number, tags?: MetricTags): void;
+	/** Latency distribution (e.g. request duration in ms). */
+	histogram(name: string, value: number, tags?: MetricTags): void;
+	/** Point-in-time gauge (e.g. current in-flight requests, queue depth). */
+	gauge(name: string, value: number, tags?: MetricTags): void;
+}
+
+// ---------------------------------------------------------------------------
+// Standard metric names
+// ---------------------------------------------------------------------------
+
+export const METRICS = {
+	/** Total requests initiated. Tags: partition, method. */
+	REQUESTS: "vereda.requests",
+	/** Total retries executed. Tags: partition, kind. */
+	RETRIES: "vereda.retries",
+	/** Request duration in ms (histogram). Tags: partition (omitted when the URL
+	 *  never resolved), kind. */
+	DURATION: "vereda.duration_ms",
+	/** Current queue depth per partition. Tags: partition. */
+	QUEUE_DEPTH: "vereda.queue_depth",
+	/** Current in-flight requests across all partitions. */
+	IN_FLIGHT: "vereda.in_flight",
+	/** Callers currently waiting for a global concurrency permit (the D1 cap). */
+	GLOBAL_QUEUE_DEPTH: "vereda.global_queue_depth",
+	/** Total circuit breaker trips to open. Tags: partition. */
+	CIRCUIT_OPEN: "vereda.circuit_open",
+} as const;

package/src/core/nanoid.ts

@@ -0,0 +1,11 @@
+import { randomBytes } from "node:crypto";
+
+export function nanoid(size = 21): string {
+	const bytes = randomBytes(size);
+	const chars = "ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789_-";
+	let id = "";
+	for (let i = 0; i < size; i++) {
+		id += chars[bytes[i]! & 63];
+	}
+	return id;
+}

package/src/core/redact.ts

@@ -0,0 +1,46 @@
+// ---------------------------------------------------------------------------
+// URL redaction for safe logging
+// ---------------------------------------------------------------------------
+
+/** Userinfo in an absolute URL's authority: `scheme://user:pass@`. Greedy up
+ *  to the last `@` before the path/query/fragment, as the URL spec parses it. */
+const USERINFO = /^([a-zA-Z][a-zA-Z\d+.-]*:\/\/)[^/?#]*@/;
+
+/**
+ * Redacts the secret-bearing parts of a URL for safe logging: userinfo
+ * credentials become `[redacted]@`, and each query parameter value becomes
+ * `[redacted]` while its key is preserved.
+ *
+ * Example: `https://bob:hunter2@api.example.com/auth?token=abc123&user=joe`
+ *      → `https://[redacted]@api.example.com/auth?token=[redacted]&user=[redacted]`
+ *
+ * URLs with neither are returned unchanged.
+ */
+export function redactUrl(url: string): string {
+	const withoutUserinfo = url.replace(USERINFO, "$1[redacted]@");
+	return redactQueryValues(withoutUserinfo);
+}
+
+function redactQueryValues(url: string): string {
+	const qIdx = url.indexOf("?");
+	if (qIdx === -1) return url;
+
+	const base = url.slice(0, qIdx);
+	const rest = url.slice(qIdx + 1);
+
+	// Separate fragment from query string (# is the fragment delimiter)
+	const fIdx = rest.indexOf("#");
+	const query = fIdx === -1 ? rest : rest.slice(0, fIdx);
+	const fragment = fIdx === -1 ? "" : rest.slice(fIdx);
+
+	const redacted = query
+		.split("&")
+		.map((pair) => {
+			const eqIdx = pair.indexOf("=");
+			if (eqIdx === -1) return pair; // bare key, no value
+			return `${pair.slice(0, eqIdx + 1)}[redacted]`;
+		})
+		.join("&");
+
+	return `${base}?${redacted}${fragment}`;
+}

package/src/core/types.ts

@@ -0,0 +1,306 @@
+import type { AppError } from "./errors.ts";
+import type { MetricsSink } from "./metrics.ts";
+
+// ---------------------------------------------------------------------------
+// Result type
+// ---------------------------------------------------------------------------
+
+export type Result<T> = { success: true; data: T; raw: Response } | { success: false; error: AppError };
+
+// ---------------------------------------------------------------------------
+// Parse function — schema-agnostic
+// ---------------------------------------------------------------------------
+
+export type ParseFn<T> = (data: unknown) => T;
+
+// ---------------------------------------------------------------------------
+// Backoff
+// ---------------------------------------------------------------------------
+
+export type BackoffFn = (attempt: number) => number;
+
+export interface BackoffOptions {
+	/** Base delay in ms. @default {@link DEFAULT_BASE_DELAY_MS} */
+	baseDelayMs?: number;
+	/** Maximum delay cap in ms. @default {@link DEFAULT_MAX_DELAY_MS} */
+	maxDelayMs?: number;
+	/** Whether to add jitter. @default {@link DEFAULT_JITTER} */
+	jitter?: boolean;
+}
+
+// ---------------------------------------------------------------------------
+// Timeout config
+// ---------------------------------------------------------------------------
+
+export interface TimeoutConfig {
+	/** Per-attempt timeout in ms. Omit to inherit the client-level default;
+	 *  `Infinity` explicitly means no per-attempt cap. Also bounds, from
+	 *  attempt start, how long the caller has to read the body of a Response
+	 *  handed back unread (a success without `parse`, or an `HttpError`'s
+	 *  `.response`) before that read is aborted. */
+	attemptMs?: number;
+	/** Whole-ticket deadline in ms. Starts at request(); cancels the ticket
+	 *  and resolves with DeadlineExceededError on expiry. Omit (or pass
+	 *  `Infinity`) for no total deadline. Also caps how long the caller has
+	 *  to read an unread Response's body handed back as above, if that's
+	 *  sooner than `attemptMs` would otherwise allow. */
+	totalMs?: number;
+}
+
+/** `ClientConfig.timeout` variant where `attemptMs` is mandatory. Every
+ *  client must explicitly decide its per-attempt timeout — `Infinity` is a
+ *  legal, deliberate choice to opt out of a cap. This is the one default in
+ *  the library that cannot safely be implicit: every other default (retries,
+ *  concurrency, queue sizes) fails safe when omitted; an omitted timeout
+ *  fails unbounded. Partition- and request-level `timeout` stay optional —
+ *  they inherit this client-level decision unless they override it. */
+export interface ClientTimeoutConfig extends Omit<TimeoutConfig, "attemptMs"> {
+	attemptMs: number;
+}
+
+/** True when `ms` is a real, finite bound — not omitted and not `Infinity`
+ *  (the explicit "no cap" value). Use instead of `!== undefined` wherever a
+ *  timeout/deadline value is checked, since `Infinity` must be treated the
+ *  same as "not set" everywhere a timer would otherwise be created. */
+export function isBoundedMs(ms: number | undefined): ms is number {
+	return ms !== undefined && Number.isFinite(ms);
+}
+
+// ---------------------------------------------------------------------------
+// Default retry-on-status codes (D1)
+// ---------------------------------------------------------------------------
+
+export const DEFAULT_RETRY_ON_STATUS: number[] = [408, 425, 429, 500, 502, 503, 504];
+
+// ---------------------------------------------------------------------------
+// Partition / bulkhead config
+// ---------------------------------------------------------------------------
+
+/** Default per-partition concurrency limit (decision D1). */
+export const DEFAULT_CONCURRENCY = 5;
+/** Default max queued items per partition before rejecting new ones. */
+export const DEFAULT_MAX_QUEUE_SIZE = 100;
+
+export interface PartitionConfig {
+	/** Max concurrent in-flight retries for this partition.
+	 *  @default {@link DEFAULT_CONCURRENCY} */
+	concurrency?: number;
+	/** Max number of pending items in the queue before rejecting new ones.
+	 *  @default {@link DEFAULT_MAX_QUEUE_SIZE} */
+	maxQueueSize?: number;
+	/** When true, the first attempt also goes through the bulkhead (R6).
+	 *  @default false */
+	limitFirstAttempts?: boolean;
+	retry?: RetryConfig;
+	timeout?: TimeoutConfig;
+	circuitBreaker?: CircuitBreakerConfig;
+}
+
+// ---------------------------------------------------------------------------
+// Circuit breaker config
+// ---------------------------------------------------------------------------
+
+/** Default consecutive-failure count that trips the circuit open. */
+export const DEFAULT_FAILURE_THRESHOLD = 5;
+/** Default ms to stay open before allowing a half-open trial. */
+export const DEFAULT_RESET_TIMEOUT_MS = 30_000;
+/** Default number of concurrent trial requests allowed while half-open. */
+export const DEFAULT_HALF_OPEN_MAX_ATTEMPTS = 1;
+
+export interface CircuitBreakerConfig {
+	/** @default false */
+	enabled?: boolean;
+	/** Consecutive-failure trip mode (default strategy).
+	 *  @default {@link DEFAULT_FAILURE_THRESHOLD} */
+	failureThreshold?: number;
+	/** Rolling-window trip mode. If set, used INSTEAD of failureThreshold. */
+	window?: {
+		sizeMs: number;
+		failureRatePercent: number;
+		minimumRequests: number;
+	};
+	/** ms to stay open before allowing a half-open trial.
+	 *  @default {@link DEFAULT_RESET_TIMEOUT_MS} */
+	resetTimeoutMs?: number;
+	/** concurrent trial requests allowed while half-open.
+	 *  @default {@link DEFAULT_HALF_OPEN_MAX_ATTEMPTS} */
+	halfOpenMaxAttempts?: number;
+	/** Override default failure classification (network/timeout/retryable_status).
+	 *  Not consulted for an error that shows the attempt never reached the host
+	 *  (e.g. a body factory that threw before the request was dispatched) —
+	 *  those are always ignored, since there is no host-health signal to classify. */
+	isFailure?: (error: AppError) => boolean;
+}
+
+// ---------------------------------------------------------------------------
+// Retry config
+// ---------------------------------------------------------------------------
+
+/** Default number of retries after the first attempt. */
+export const DEFAULT_MAX_RETRIES = 3;
+
+export interface RetryConfig {
+	/** Retries after the first attempt. `MaxRetriesExceededError.attempts` is
+	 *  total executions, i.e. `maxRetries + 1`.
+	 *  @default {@link DEFAULT_MAX_RETRIES} */
+	maxRetries?: number;
+	/** @default `{ baseDelayMs: 200, maxDelayMs: 30_000, jitter: true }` */
+	backoff?: BackoffFn | BackoffOptions;
+	/** HTTP status codes that trigger retry (e.g. 408, 429, 500, 502, 503, 504).
+	 *  @default {@link DEFAULT_RETRY_ON_STATUS} */
+	retryOnStatus?: number[];
+	/** Allows retrying non-idempotent methods (POST/PATCH/CONNECT). An
+	 *  `Idempotency-Key` header also enables retries. Default: false. */
+	idempotent?: boolean;
+	/** Optional predicate to decide whether a failed attempt should be retried.
+	 *  Called exactly once per failed attempt that could still be retried, with
+	 *  the zero-based attempt number:
+	 *  - 0 = the first attempt (called client-side before the retry loop)
+	 *  - 1, 2, … = retries (called inside the loop, after attempt 0)
+	 *  Returning `false` surfaces the error immediately without retrying. Not
+	 *  called after the final attempt when no retries remain — there is
+	 *  nothing left to decide. */
+	retryWhen?: (error: AppError, attempt: number) => boolean;
+}
+
+// ---------------------------------------------------------------------------
+// Logger
+// ---------------------------------------------------------------------------
+
+export interface Logger {
+	debug(msg: string, meta?: Record<string, unknown>): void;
+	info(msg: string, meta?: Record<string, unknown>): void;
+	warn(msg: string, meta?: Record<string, unknown>): void;
+	error(msg: string, meta?: Record<string, unknown>): void;
+}
+
+// ---------------------------------------------------------------------------
+// Lifecycle events
+// ---------------------------------------------------------------------------
+
+export type LifecycleEventMap = {
+	request: { ticketId: string; url: string; method: string; partition: string };
+	/** Zero-based retry index (0 = first retry after the initial attempt).
+	 *  Note: retryWhen's attempt parameter uses a different numbering —
+	 *  0 = first attempt, 1 = first retry, etc. */
+	retry: {
+		ticketId: string;
+		url: string;
+		partition: string;
+		attempt: number;
+		delayMs: number;
+		error: AppError;
+	};
+	success: {
+		ticketId: string;
+		url: string;
+		partition: string;
+		attempts: number;
+		durationMs: number;
+		queuedMs: number;
+		statusCode: number;
+	};
+	failure: {
+		ticketId: string;
+		url: string;
+		/** `undefined` only when the URL couldn't be resolved, so no partition
+		 *  was ever chosen (no `request` event is emitted in that case either). */
+		partition: string | undefined;
+		attempts: number;
+		durationMs: number;
+		queuedMs: number;
+		error: AppError;
+	};
+	cancelled: {
+		ticketId: string;
+		url: string;
+		partition: string;
+		attempts: number;
+		durationMs: number;
+		queuedMs: number;
+	};
+	circuitOpen: { partition: string };
+	circuitClose: { partition: string };
+};
+
+// ---------------------------------------------------------------------------
+// Request options
+// ---------------------------------------------------------------------------
+
+export interface RequestOptions<T = unknown> {
+	/** @default "GET" */
+	method?: string;
+	headers?: HeadersInit;
+	/** Request body, or a factory that returns a fresh body on every attempt
+	 *  (replayable body). A ReadableStream must be supplied via a factory. The
+	 *  factory must return a fresh body each invocation — reusing the same
+	 *  ReadableStream replays an already-consumed (empty) stream. */
+	body?: BodyInit | (() => BodyInit);
+	/** Named bulkhead partition. Defaults to `host` (hostname + port when non-default). */
+	partition?: string;
+	/** Schema parse function. Use withZod() or custom. */
+	parse?: ParseFn<T>;
+	retry?: RetryConfig;
+	timeout?: TimeoutConfig;
+	/** Signal to cancel the request externally */
+	signal?: AbortSignal;
+}
+
+/** Request options with `parse` set: the ticket resolves with `data: T`. */
+export type ParsedRequestOptions<T> = Omit<RequestOptions<T>, "parse"> & { parse: ParseFn<T> };
+
+/** Request options without `parse`: the body is left unread on `raw` and
+ *  `data` is `undefined`. `parse: undefined` is accepted so options can be
+ *  built conditionally. */
+export type UnparsedRequestOptions = Omit<RequestOptions, "parse"> & { parse?: undefined };
+
+// ---------------------------------------------------------------------------
+// Client config
+// ---------------------------------------------------------------------------
+
+/** Default global concurrency cap across all partitions (decision D1). */
+export const DEFAULT_GLOBAL_CONCURRENCY = 50;
+/** Default max requests queued globally, across all partitions, waiting for
+ *  a concurrency permit before new requests are rejected with QueueFullError. */
+export const DEFAULT_GLOBAL_QUEUE_SIZE = 100;
+
+export interface ClientConfig {
+	/** Base URL prepended to all requests */
+	baseUrl?: string;
+	/** Default retry config */
+	retry?: RetryConfig;
+	/** Default timeout config. `attemptMs` is required — pass `Infinity` to
+	 *  explicitly opt out of a per-attempt cap, so "no timeout" is always a
+	 *  deliberate choice rather than an accidental default. */
+	timeout: ClientTimeoutConfig;
+	/** Global concurrency across all partitions.
+	 *  @default {@link DEFAULT_GLOBAL_CONCURRENCY} */
+	concurrency?: number;
+	/** Max requests queued globally (across all partitions) waiting for a
+	 *  concurrency permit before new requests are rejected with QueueFullError.
+	 *  @default {@link DEFAULT_GLOBAL_QUEUE_SIZE} */
+	maxQueueSize?: number;
+	/** Per-partition overrides. Partitions not listed here use
+	 *  `{ concurrency: 5, maxQueueSize: 100 }`.
+	 *  @default {} */
+	partitions?: Record<string, PartitionConfig>;
+	/** Default circuit breaker config. Opt-in — inert unless `enabled: true`. */
+	circuitBreaker?: CircuitBreakerConfig;
+	/** Optional structured logger */
+	logger?: Logger;
+	/** Optional metrics sink for counters, histograms, and gauges. */
+	metrics?: MetricsSink;
+	/** Redact query parameter values in logged URLs.
+	 *  @default true */
+	redactQuery?: boolean;
+	/** Custom fetch function (defaults to globalThis.fetch). */
+	fetch?: typeof globalThis.fetch;
+}
+
+/** Options for `HttpClient.close()`.
+ *
+ *  Modelled as a union so the type mirrors the runtime contract: `timeoutMs` is
+ *  required only when draining. A single `{ drain?: boolean; timeoutMs: number }`
+ *  shape made `close({ drain: false })` a type error even though it is the
+ *  documented, working way to close without draining. */
+export type CloseOptions = { drain?: false; timeoutMs?: number } | { drain: true; timeoutMs: number };