brass-runtime 1.13.8 → 1.14.0

package/dist/http/index.d.ts

@@ -1,15 +1,96 @@
-import { A as Async, a as AsyncWithPromise } from '../effect-ISvXPLgc.js';
-import { Z as ZStream } from '../stream-BvukHxCv.js';
+import { A as Async, a as AsyncWithPromise } from '../effect-DM56H743.js';
+import { Z as ZStream, C as CircuitBreakerConfig, T as Tracer } from '../stream-Oqe6WeLE.js';
 
 type RetryPolicy = {
     maxRetries: number;
     baseDelayMs: number;
     maxDelayMs: number;
+    /** Optional total retry budget, including request attempts and sleeps. */
+    maxElapsedMs?: number;
+    /** Defaults to true. When true, Retry-After is honored but capped by maxDelayMs/budget. */
+    respectRetryAfter?: boolean;
     retryOnMethods?: HttpMethod[];
     retryOnStatus?: (status: number) => boolean;
     retryOnError?: (e: HttpError) => boolean;
+    /** Strict engine selector for retry planning. Defaults to ts. */
+    engine?: "ts" | "wasm";
+    /** Back-compat knob: wasm=true maps to engine="wasm", wasm=false maps to engine="ts". */
+    wasm?: boolean;
 };
 
+type HttpPoolKeyResolver = "global" | "origin" | "host" | ((req: HttpRequest, url: URL) => string);
+type HttpPoolConfig = {
+    /** Max concurrent downstream calls per resolved key. */
+    readonly concurrency?: number;
+    /** Max queued waiters per key. `0` means fail fast when the pool is full. */
+    readonly maxQueue?: number;
+    /** Max time a request may wait for a pool slot before failing fast. */
+    readonly queueTimeoutMs?: number;
+    /** How to isolate pools. Default: `origin`; useful values: `global`, `host`, `origin`. */
+    readonly key?: HttpPoolKeyResolver;
+    /**
+     * Strict engine selector for permit governance. Defaults to ts.
+     * - ts: TypeScript permit pool.
+     * - wasm: require BrassWasmHttpPermitPool from wasm/pkg; never falls back.
+     */
+    readonly engine?: "ts" | "wasm";
+    /** Back-compat knob: wasm=true maps to engine="wasm", wasm=false maps to engine="ts". */
+    readonly wasm?: boolean;
+};
+type HttpPoolKeyStats = {
+    readonly key: string;
+    readonly running: number;
+    readonly queued: number;
+    readonly concurrency: number;
+    readonly maxQueue: number;
+    readonly acquired: number;
+    readonly released: number;
+    readonly rejected: number;
+    readonly queueTimeouts: number;
+    readonly abortedWhileQueued: number;
+};
+type HttpPoolStats = {
+    readonly running: number;
+    readonly queued: number;
+    readonly acquired: number;
+    readonly released: number;
+    readonly rejected: number;
+    readonly queueTimeouts: number;
+    readonly abortedWhileQueued: number;
+    readonly wasm?: unknown;
+    readonly keys: HttpPoolKeyStats[];
+};
+type HttpPoolLease = {
+    readonly key: string;
+    release: () => void;
+};
+declare function resolveHttpPoolKey(resolver: HttpPoolKeyResolver | undefined, req: HttpRequest, url: URL): string;
+declare class HttpConcurrencyPool {
+    private readonly states;
+    private readonly concurrency;
+    private readonly maxQueue;
+    private readonly queueTimeoutMs;
+    readonly keyResolver: HttpPoolKeyResolver | undefined;
+    private readonly wasm;
+    private readonly wasmWaiters;
+    private wasmTimer;
+    private nextSubjectId;
+    constructor(config?: HttpPoolConfig);
+    acquire(key: string, signal: AbortSignal): Promise<HttpPoolLease>;
+    stats(): HttpPoolStats;
+    private acquireJs;
+    private acquireWasm;
+    private getState;
+    private makeLease;
+    private drain;
+    private handleWasmGrants;
+    private handleWasmTimeouts;
+    private scheduleWasmTimeoutPump;
+    private cleanupWaiter;
+    private removeWaiter;
+    private allocateSubjectId;
+}
+
 type HttpError = {
     _tag: "Abort";
 } | {
@@ -18,6 +99,21 @@ type HttpError = {
 } | {
     _tag: "FetchError";
     message: string;
+} | {
+    _tag: "Timeout";
+    timeoutMs: number;
+    message: string;
+    phase?: "request" | "queue" | "retry";
+} | {
+    _tag: "PoolRejected";
+    key: string;
+    limit: number;
+    message: string;
+} | {
+    _tag: "PoolTimeout";
+    key: string;
+    timeoutMs: number;
+    message: string;
 };
 type HttpMethod = "GET" | "POST" | "PUT" | "PATCH" | "DELETE" | "HEAD" | "OPTIONS";
 type HttpInit = Omit<RequestInit, "method" | "body" | "headers">;
@@ -27,6 +123,10 @@ type HttpRequest = {
     headers?: Record<string, string>;
     body?: string;
     init?: HttpInit;
+    /** Per-request override for `MakeHttpConfig.timeoutMs`. */
+    timeoutMs?: number;
+    /** Optional stable key for downstream isolation. When omitted, the pool uses origin/host/global config. */
+    poolKey?: string;
 };
 type HttpWireResponse = {
     status: number;
@@ -35,9 +135,25 @@ type HttpWireResponse = {
     bodyText: string;
     ms: number;
 };
+type HttpClientStats = {
+    readonly inFlight: number;
+    readonly started: number;
+    readonly succeeded: number;
+    readonly failed: number;
+    readonly aborted: number;
+    readonly timedOut: number;
+    readonly poolRejected: number;
+    readonly poolTimeouts: number;
+    readonly lastDurationMs?: number;
+    readonly pool?: HttpPoolStats;
+};
 type MakeHttpConfig = {
     baseUrl?: string;
     headers?: Record<string, string>;
+    /** Request budget covering pool wait + fetch + body read. Disabled when omitted. */
+    timeoutMs?: number;
+    /** Downstream pool/concurrency limiter. Disabled by default to preserve existing behavior. */
+    pool?: false | HttpPoolConfig;
 };
 type HttpWireResponseStream = {
     status: number;
@@ -46,20 +162,28 @@ type HttpWireResponseStream = {
     body: ZStream<unknown, HttpError, Uint8Array>;
     ms: number;
 };
-type HttpClientStream = (req: HttpRequest) => Async<unknown, HttpError, HttpWireResponseStream>;
+type HttpClientStreamFn = (req: HttpRequest) => Async<unknown, HttpError, HttpWireResponseStream>;
+type HttpClientStream = HttpClientStreamFn & {
+    stats: () => HttpClientStats;
+};
+type HttpClientFn = (req: HttpRequest) => Async<unknown, HttpError, HttpWireResponse>;
+type HttpMiddleware = (next: HttpClientFn) => HttpClientFn;
 type HttpClient = HttpClientFn & {
     with: (mw: HttpMiddleware) => HttpClient;
+    stats: () => HttpClientStats;
 };
+declare const decorate: (run: HttpClientFn, stats?: () => HttpClientStats) => HttpClient;
 declare const withMiddleware: (mw: HttpMiddleware) => (c: HttpClient) => HttpClient;
-declare const decorate: (run: HttpClientFn) => HttpClient;
-type HttpClientFn = (req: HttpRequest) => Async<unknown, HttpError, HttpWireResponse>;
-type HttpMiddleware = (next: HttpClientFn) => HttpClientFn;
 declare const normalizeHeadersInit: (h: any) => Record<string, string> | undefined;
 declare function makeHttpStream(cfg?: MakeHttpConfig): HttpClientStream;
 declare function makeHttp(cfg?: MakeHttpConfig): HttpClient;
 declare const withRetryStream: (p: RetryPolicy) => (next: HttpClientStream) => HttpClientStream;
 
-type InitNoMethodBody = Omit<RequestInit, "method" | "body">;
+type InitNoMethodBody = Omit<RequestInit, "method" | "body"> & {
+    timeoutMs?: number;
+    poolKey?: string;
+    headers?: any;
+};
 type HttpMeta = {
     request: HttpRequest;
     urlFinal: string;
@@ -83,6 +207,8 @@ type HttpResponseWithMeta<A> = {
 };
 type AnyInitWithHeaders = {
     headers?: any;
+    timeoutMs?: number;
+    poolKey?: string;
 } & Record<string, any>;
 type Dx = {
     request: (req: HttpRequest) => AsyncWithPromise<unknown, HttpError, HttpWireResponse>;
@@ -94,6 +220,7 @@ type Dx = {
     with: (mw: HttpMiddleware) => Dx;
     withRetry: (p: RetryPolicy) => Dx;
     wire: HttpClient;
+    stats: () => ReturnType<HttpClient["stats"]>;
 };
 declare function httpClient(cfg?: MakeHttpConfig): Dx;
 declare function httpClientWithMeta(cfg?: MakeHttpConfig): {
@@ -149,6 +276,52 @@ declare function httpClientStream(cfg?: MakeHttpConfig): {
     with: (mw: (n: HttpClientStream) => HttpClientStream) => /*elided*/ any;
     withRetry: (p: RetryPolicy) => /*elided*/ any;
     wire: HttpClientStream;
+    stats: () => HttpClientStats;
+};
+
+type HttpCircuitBreakerConfig = CircuitBreakerConfig & {
+    /** Key resolver for per-origin circuit breakers. Default: per-origin. */
+    perOrigin?: boolean;
+};
+/**
+ * HTTP middleware that wraps requests in a circuit breaker.
+ * When the circuit opens, requests fail fast with CircuitBreakerOpen error.
+ */
+declare function withCircuitBreaker(config?: HttpCircuitBreakerConfig): HttpMiddleware;
+
+/**
+ * HTTP middleware that creates a span for each request.
+ */
+declare function withTracing(tracer: Tracer): HttpMiddleware;
+
+type ValidationError = {
+    _tag: "ValidationError";
+    message: string;
+    body: string;
+    schema?: string;
+};
+type JsonValidator<A> = (data: unknown) => {
+    success: true;
+    data: A;
+} | {
+    success: false;
+    error: string;
 };
+/**
+ * Creates a validated JSON getter that checks the response body against a schema.
+ *
+ * Usage:
+ * ```ts
+ * const getUser = validatedJson<User>(client, (data) => {
+ *   if (typeof data === "object" && data !== null && "id" in data) {
+ *     return { success: true, data: data as User };
+ *   }
+ *   return { success: false, error: "Invalid user shape" };
+ * });
+ *
+ * const user = await run(getUser({ method: "GET", url: "/users/1" }));
+ * ```
+ */
+declare function validatedJson<A>(client: HttpClientFn, validator: JsonValidator<A>): (req: Parameters<HttpClientFn>[0]) => Async<unknown, HttpError | ValidationError, A>;
 
-export { type Dx, type HttpClient, type HttpClientFn, type HttpClientStream, type HttpError, type HttpInit, type HttpMeta, type HttpMethod, type HttpMiddleware, type HttpRequest, type HttpResponse, type HttpResponseWithMeta, type HttpWireResponse, type HttpWireResponseStream, type HttpWireWithMeta, type MakeHttpConfig, decorate, httpClient, httpClientStream, httpClientWithMeta, makeHttp, makeHttpStream, normalizeHeadersInit, withMiddleware, withRetryStream };
+export { type Dx, type HttpCircuitBreakerConfig, type HttpClient, type HttpClientFn, type HttpClientStats, type HttpClientStream, type HttpClientStreamFn, HttpConcurrencyPool, type HttpError, type HttpInit, type HttpMeta, type HttpMethod, type HttpMiddleware, type HttpPoolConfig, type HttpPoolKeyResolver, type HttpPoolKeyStats, type HttpPoolLease, type HttpPoolStats, type HttpRequest, type HttpResponse, type HttpResponseWithMeta, type HttpWireResponse, type HttpWireResponseStream, type HttpWireWithMeta, type JsonValidator, type MakeHttpConfig, type ValidationError, decorate, httpClient, httpClientStream, httpClientWithMeta, makeHttp, makeHttpStream, normalizeHeadersInit, resolveHttpPoolKey, validatedJson, withCircuitBreaker, withMiddleware, withRetryStream, withTracing };