@zlink-systems/http-client 0.10.0

package/dist/runtime/retry-policy.d.ts

@@ -0,0 +1,14 @@
+import type { HttpClientOptions } from './options';
+import type { HttpRequestSpec, RawResult } from './request-performer';
+/**
+ * Applies the wrapper's retry policy around a single request attempt: streaming requests are never
+ * retried (they cannot be rewound), each attempt is bounded by the effective timeout via an
+ * `AbortController`, and only retriable transport failures (timeout, connection errors) are retried
+ * at a fixed delay. Separated from the runtime so the retry/timeout policy is independent of
+ * dispatcher construction.
+ */
+export declare class RetryPolicy {
+    private readonly options;
+    constructor(options: HttpClientOptions);
+    execute(spec: HttpRequestSpec, perform: (spec: HttpRequestSpec, signal: AbortSignal) => Promise<RawResult>): Promise<RawResult>;
+}

package/dist/runtime/retry-policy.js

@@ -0,0 +1,69 @@
+"use strict";
+/* SPDX-License-Identifier: Apache-2.0 */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.RetryPolicy = void 0;
+const framework_1 = require("@zlink-systems/framework");
+// Exponential backoff with full jitter: base 50ms, doubling per attempt, capped at 1s.
+// Fixed delays synchronize retries from many clients against an ailing server.
+function delayMsFor(attempt) {
+    const ceiling = Math.min(1000, 50 << Math.min(attempt, 5));
+    return Math.floor(Math.random() * (ceiling + 1));
+}
+/**
+ * Applies the wrapper's retry policy around a single request attempt: streaming requests are never
+ * retried (they cannot be rewound), each attempt is bounded by the effective timeout via an
+ * `AbortController`, and only retriable transport failures (timeout, connection errors) are retried
+ * at a fixed delay. Separated from the runtime so the retry/timeout policy is independent of
+ * dispatcher construction.
+ */
+class RetryPolicy {
+    options;
+    constructor(options) {
+        this.options = options;
+    }
+    async execute(spec, perform) {
+        const maxRetries = spec.sink !== undefined || spec.bodyProvider !== undefined ? 0 : this.options.retryAttempts;
+        const timeoutMs = spec.timeoutMs ?? this.options.timeoutMs;
+        for (let attempt = 0;; attempt++) {
+            const controller = new AbortController();
+            const timer = setTimeout(() => {
+                controller.abort();
+            }, timeoutMs);
+            try {
+                return await perform(spec, controller.signal);
+            }
+            catch (error) {
+                const failure = mapFailure(error, controller.signal.aborted);
+                if (isRetriableHttpFailure(failure) && attempt < maxRetries) {
+                    await delay(delayMsFor(attempt));
+                    continue;
+                }
+                throw failure;
+            }
+            finally {
+                clearTimeout(timer);
+            }
+        }
+    }
+}
+exports.RetryPolicy = RetryPolicy;
+function mapFailure(error, aborted) {
+    if (error instanceof framework_1.ZLinkFrameworkException) {
+        return error;
+    }
+    if (aborted || (error instanceof Error && error.name === 'AbortError')) {
+        return new framework_1.ZLinkFrameworkException(framework_1.ZLinkFrameworkErrorKind.DeadlineExceeded, 'HTTP request exceeded timeout', error);
+    }
+    // Transport failures (connection refused/reset, undici errors) are retriable.
+    const message = error instanceof Error ? error.message : 'HTTP transport failure';
+    return new framework_1.ZLinkFrameworkException(framework_1.ZLinkFrameworkErrorKind.Unavailable, message, error);
+}
+function isRetriableHttpFailure(error) {
+    return error.kind === framework_1.ZLinkFrameworkErrorKind.Unavailable
+        || error.kind === framework_1.ZLinkFrameworkErrorKind.DeadlineExceeded;
+}
+function delay(ms) {
+    return new Promise((resolve) => {
+        setTimeout(resolve, ms);
+    });
+}

package/dist/runtime/runtime.d.ts

@@ -0,0 +1,16 @@
+import type { HttpClientOptions } from './options';
+import { type HttpRequestSpec, type RawResult } from './request-performer';
+/**
+ * Wires the undici dispatcher, request performer, and retry policy. Dispatcher construction lives in
+ * `transport-factory` and the retry/timeout loop in {@link RetryPolicy}. Submission is the caller's
+ * native `Promise`; the event loop is never blocked. Mirrors the C++ `http_client_runtime.cpp`.
+ */
+export declare class HttpClientRuntime {
+    private readonly cookieJar;
+    private readonly dispatcher;
+    private readonly performer;
+    private readonly retryPolicy;
+    constructor(options: HttpClientOptions);
+    executeAsync(spec: HttpRequestSpec): Promise<RawResult>;
+    close(): Promise<void>;
+}

package/dist/runtime/runtime.js

@@ -0,0 +1,33 @@
+"use strict";
+/* SPDX-License-Identifier: Apache-2.0 */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.HttpClientRuntime = void 0;
+const cookie_jar_1 = require("./cookie-jar");
+const request_performer_1 = require("./request-performer");
+const transport_factory_1 = require("./transport-factory");
+const retry_policy_1 = require("./retry-policy");
+/**
+ * Wires the undici dispatcher, request performer, and retry policy. Dispatcher construction lives in
+ * `transport-factory` and the retry/timeout loop in {@link RetryPolicy}. Submission is the caller's
+ * native `Promise`; the event loop is never blocked. Mirrors the C++ `http_client_runtime.cpp`.
+ */
+class HttpClientRuntime {
+    cookieJar = new cookie_jar_1.CookieJar();
+    dispatcher;
+    performer;
+    retryPolicy;
+    constructor(options) {
+        this.dispatcher = (0, transport_factory_1.createDispatcher)(options);
+        this.performer = new request_performer_1.RequestPerformer(options, this.cookieJar, this.dispatcher);
+        this.retryPolicy = new retry_policy_1.RetryPolicy(options);
+    }
+    async executeAsync(spec) {
+        return this.retryPolicy.execute(spec, (request, signal) => this.performer.perform(request, signal));
+    }
+    async close() {
+        if (this.dispatcher !== undefined) {
+            await this.dispatcher.close();
+        }
+    }
+}
+exports.HttpClientRuntime = HttpClientRuntime;

package/dist/runtime/text.d.ts

@@ -0,0 +1,5 @@
+export declare function requireNonBlank(value: string, message: string): void;
+export declare function requirePositiveTimeout(value: number): void;
+export declare function percentEncode(value: string): string;
+export declare function basicAuthorization(user: string, password: string): string;
+export declare function makeMultipartBoundary(): string;

package/dist/runtime/text.js

@@ -0,0 +1,44 @@
+"use strict";
+/* SPDX-License-Identifier: Apache-2.0 */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.requireNonBlank = requireNonBlank;
+exports.requirePositiveTimeout = requirePositiveTimeout;
+exports.percentEncode = percentEncode;
+exports.basicAuthorization = basicAuthorization;
+exports.makeMultipartBoundary = makeMultipartBoundary;
+const framework_1 = require("@zlink-systems/framework");
+/** Shared text helpers mirroring the C++ `client.cpp` anonymous-namespace utilities. */
+function isBlank(value) {
+    return value.length === 0 || /^[\s]*$/u.test(value);
+}
+function requireNonBlank(value, message) {
+    if (isBlank(value)) {
+        throw new framework_1.ZLinkFrameworkException(framework_1.ZLinkFrameworkErrorKind.ProtocolError, message);
+    }
+}
+function requirePositiveTimeout(value) {
+    if (!(value > 0)) {
+        throw new framework_1.ZLinkFrameworkException(framework_1.ZLinkFrameworkErrorKind.ProtocolError, 'HTTP client timeout must be greater than zero');
+    }
+}
+const unreserved = /[A-Za-z0-9\-_.~]/u;
+function percentEncode(value) {
+    const bytes = new TextEncoder().encode(value);
+    let encoded = '';
+    for (const byte of bytes) {
+        const char = String.fromCharCode(byte);
+        if (unreserved.test(char)) {
+            encoded += char;
+        }
+        else {
+            encoded += '%' + byte.toString(16).toUpperCase().padStart(2, '0');
+        }
+    }
+    return encoded;
+}
+function basicAuthorization(user, password) {
+    return 'Basic ' + Buffer.from(`${user}:${password}`, 'utf8').toString('base64');
+}
+function makeMultipartBoundary() {
+    return 'zlink-boundary-' + Math.random().toString(16).slice(2).padEnd(16, '0').slice(0, 16);
+}

package/dist/runtime/transport-factory.d.ts

@@ -0,0 +1,9 @@
+import { type Dispatcher } from 'undici';
+import type { HttpClientOptions } from './options';
+/**
+ * Builds the undici dispatcher for the wrapper: a `ProxyAgent` when a proxy is configured (proxy
+ * authentication carried as a token), otherwise a TLS `Agent` (trust certificate + mTLS client
+ * certificate) or the global dispatcher when no transport customisation is needed. Separated from
+ * the runtime so dispatcher construction is independent of request orchestration.
+ */
+export declare function createDispatcher(options: HttpClientOptions): Dispatcher | undefined;

package/dist/runtime/transport-factory.js

@@ -0,0 +1,39 @@
+"use strict";
+/* SPDX-License-Identifier: Apache-2.0 */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createDispatcher = createDispatcher;
+const node_fs_1 = require("node:fs");
+const node_tls_1 = require("node:tls");
+const undici_1 = require("undici");
+/**
+ * Builds the undici dispatcher for the wrapper: a `ProxyAgent` when a proxy is configured (proxy
+ * authentication carried as a token), otherwise a TLS `Agent` (trust certificate + mTLS client
+ * certificate) or the global dispatcher when no transport customisation is needed. Separated from
+ * the runtime so dispatcher construction is independent of request orchestration.
+ */
+function createDispatcher(options) {
+    const connect = {};
+    let hasTls = false;
+    if (options.trustCertificateFile !== undefined) {
+        // Add the custom certificate to the default roots rather than replacing them, so public-CA
+        // HTTPS targets keep working when a test/internal trust certificate is configured.
+        connect['ca'] = [...node_tls_1.rootCertificates, (0, node_fs_1.readFileSync)(options.trustCertificateFile, 'utf8')];
+        hasTls = true;
+    }
+    if (options.clientCertificate !== undefined) {
+        connect['cert'] = (0, node_fs_1.readFileSync)(options.clientCertificate.certificatePath);
+        connect['key'] = (0, node_fs_1.readFileSync)(options.clientCertificate.keyPath);
+        hasTls = true;
+    }
+    if (options.proxy !== undefined) {
+        return new undici_1.ProxyAgent({
+            uri: options.proxy,
+            ...(options.proxyAuthorization !== undefined ? { token: options.proxyAuthorization } : {}),
+            ...(hasTls ? { requestTls: connect } : {}),
+        });
+    }
+    if (hasTls) {
+        return new undici_1.Agent({ connect });
+    }
+    return undefined;
+}

package/dist/runtime/version.d.ts

@@ -0,0 +1 @@
+export declare const httpClientUserAgent: string;

package/dist/runtime/version.js

@@ -0,0 +1,12 @@
+"use strict";
+/* SPDX-License-Identifier: Apache-2.0 */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.httpClientUserAgent = void 0;
+// Version identity for outgoing requests. The single source of truth is the package.json
+// version; the User-Agent product token is derived as zlink-http-client/<major.minor>.
+// The relative path works both for the source tree and for the packaged dist/ layout.
+const packageVersion = require('../../package.json').version;
+exports.httpClientUserAgent = `zlink-http-client/${packageVersion
+    .split('.')
+    .slice(0, 2)
+    .join('.')}`;

package/dist/types.d.ts

@@ -0,0 +1,37 @@
+/** HTTP methods supported by the ZLink HTTP client. */
+export type ZLinkHttpMethod = 'GET' | 'POST' | 'PUT' | 'DELETE' | 'PATCH' | 'HEAD' | 'OPTIONS';
+/**
+ * Raw HTTP response with status, headers, and the buffered body as a string. Response header
+ * names are lowercase. Mirrors the C++ `raw_http_response_t`.
+ */
+export interface RawHttpResponse {
+    readonly status: number;
+    readonly headers: Readonly<Record<string, string>>;
+    readonly body: string;
+}
+/**
+ * Typed HTTP response. `body` is the JSON-decoded payload; `rawBody` keeps the original response
+ * text. Mirrors the C++ `http_response_t<T>`.
+ */
+export interface HttpResponse<T> {
+    readonly status: number;
+    readonly headers: Readonly<Record<string, string>>;
+    readonly body: T;
+    readonly rawBody: string;
+}
+/** Provider for a streamed request body; returns `null` when the body is complete. */
+export type BodyChunkProvider = () => Uint8Array | null;
+/** Sink for a streamed response download; receives chunks as they arrive (no decompression). */
+export type DownloadSink = (chunk: Uint8Array) => void;
+/** Completion scheduling seam supplied by a framework server integration. */
+export interface ZLinkHttpExecutionTurn {
+    yieldPromise<T>(pending: Promise<T>): Promise<T>;
+    post(callback: () => void): void;
+}
+/** Captures the current framework execution turn when an HTTP call is built. */
+export interface ZLinkHttpExecutionScheduler {
+    capture(): ZLinkHttpExecutionTurn | undefined;
+    reportError(error: unknown): void;
+}
+/** Callback completion path for callers that do not use an awaitable. */
+export type ZLinkHttpCallback<T> = (error: unknown | undefined, response: HttpResponse<T> | undefined) => void;

package/dist/types.js

@@ -0,0 +1,3 @@
+"use strict";
+/* SPDX-License-Identifier: Apache-2.0 */
+Object.defineProperty(exports, "__esModule", { value: true });

package/package.json

@@ -0,0 +1,22 @@
+{
+  "name": "@zlink-systems/http-client",
+  "version": "0.10.0",
+  "license": "Apache-2.0",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "files": [
+    "dist",
+    "LICENSE"
+  ],
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "browser": "./dist/browser/index.mjs",
+      "default": "./dist/index.js"
+    }
+  },
+  "dependencies": {
+    "@zlink-systems/framework": "0.10.0",
+    "undici": "6.27.0"
+  }
+}