@zlink-systems/http-client 0.25.0 → 0.27.0

package/dist/client.d.ts

@@ -1,5 +1,5 @@
-import { HttpClientRuntime } from './runtime/runtime';
 import { ZLinkHttpRequestBuilder } from './request-builder';
+import { HttpClientRuntime } from './runtime/runtime';
 import type { ZLinkHttpExecutionScheduler } from './types';
 /**
  * ZLink-style fluent HTTP client. Wraps undici behind a builder so transport types never leak into

package/dist/client.js

@@ -2,10 +2,10 @@
 /* SPDX-License-Identifier: Apache-2.0 */
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.ZLinkHttpClientBuilder = exports.ZLinkHttpClient = void 0;
-const framework_1 = require("@zlink-systems/framework");
-const runtime_1 = require("./runtime/runtime");
 const text_1 = require("./runtime/text");
+const framework_1 = require("@zlink-systems/framework");
 const request_builder_1 = require("./request-builder");
+const runtime_1 = require("./runtime/runtime");
 /**
  * ZLink-style fluent HTTP client. Wraps undici behind a builder so transport types never leak into
  * application code. A general HTTP client; the typed-JSON path (`body(dto)` / `submit<T>()`) is a
@@ -53,11 +53,14 @@ class ZLinkHttpClient {
     }
 }
 exports.ZLinkHttpClient = ZLinkHttpClient;
+const DEFAULT_HTTP_CLIENT_TIMEOUT_MS = 3000;
+const DEFAULT_HTTP_RESPONSE_BODY_SIZE = 16 * 1024 * 1024;
+const DEFAULT_HTTP_MAX_REDIRECTS = 5;
 /** Fluent builder for {@link ZLinkHttpClient}. Mirrors the C++ `client_builder_t`. */
 class ZLinkHttpClientBuilder {
     baseUrlValue = '';
-    timeoutMsValue = 3000;
-    maxResponseBodySizeValue = 16 * 1024 * 1024;
+    timeoutMsValue = DEFAULT_HTTP_CLIENT_TIMEOUT_MS;
+    maxResponseBodySizeValue = DEFAULT_HTTP_RESPONSE_BODY_SIZE;
     headersValue = {};
     trustCertificateFileValue;
     clientCertificateValue;
@@ -85,12 +88,12 @@ class ZLinkHttpClientBuilder {
     }
     basicAuth(user, password) {
         (0, text_1.requireNonBlank)(user, 'HTTP client basic auth user is required');
-        this.headersValue['authorization'] = (0, text_1.basicAuthorization)(user, password);
+        this.headersValue[text_1.HttpHeaderName.Authorization] = (0, text_1.basicAuthorization)(user, password);
         return this;
     }
     bearerToken(token) {
         (0, text_1.requireNonBlank)(token, 'HTTP client bearer token is required');
-        this.headersValue['authorization'] = `Bearer ${token}`;
+        this.headersValue[text_1.HttpHeaderName.Authorization] = `Bearer ${token}`;
         return this;
     }
     maxResponseBodySize(bytes) {
@@ -111,7 +114,7 @@ class ZLinkHttpClientBuilder {
         this.clientCertificateValue = { certificatePath, keyPath };
         return this;
     }
-    followRedirects(maxRedirects = 5) {
+    followRedirects(maxRedirects = DEFAULT_HTTP_MAX_REDIRECTS) {
         if (!(maxRedirects > 0)) {
             throw new framework_1.ZLinkFrameworkException(framework_1.ZLinkFrameworkErrorKind.ProtocolError, 'HTTP client follow_redirects must be greater than zero');
         }

package/dist/request-builder.d.ts

@@ -21,7 +21,7 @@ export declare class ZLinkHttpRequestBuilder {
     private consumed;
     constructor(client: ZLinkHttpClient | undefined, method: ZLinkHttpMethod, path: string, clientFactory?: ZLinkHttpClientBuilder);
     private resolveClient;
-    private closeIfOwned;
+    private execute;
     header(name: string, value: string): this;
     query(name: string, value: string): this;
     timeout(milliseconds: number): this;
@@ -46,6 +46,7 @@ export declare class ZLinkHttpRequestBuilder {
     submit<T>(): Promise<HttpResponse<T>>;
     submit<T>(callback: ZLinkHttpCallback<T>): void;
     protected executeTyped<T>(): Promise<HttpResponse<T>>;
+    private decodeResponse;
     /** Returns only the decoded body for client-side scenarios that do not need the HTTP envelope. */
     fetch<T>(): Promise<T>;
     private completeCallback;

package/dist/request-builder.js

@@ -5,6 +5,7 @@ exports.ZLinkHttpRequestBuilder = void 0;
 exports.createZLinkHttpRequestBuilder = createZLinkHttpRequestBuilder;
 const framework_1 = require("@zlink-systems/framework");
 const text_1 = require("./runtime/text");
+const HTTP_FAILURE_STATUS_MIN = 400;
 /**
  * Fluent builder for a single request. Mirrors the C++ `request_builder_t`. Submission returns a
  * `Promise`; the event loop is never blocked while the request is in flight.
@@ -53,11 +54,21 @@ class ZLinkHttpRequestBuilder {
         }
         return this.clientInstance;
     }
-    async closeIfOwned() {
-        if (this.ownsClient && this.clientInstance !== undefined) {
-            // A one-shot cleanup failure must not mask the request result.
-            await this.clientInstance.close().catch(() => undefined);
+    async execute(client, operation) {
+        if (!this.ownsClient)
+            return operation;
+        const [outcome] = await Promise.allSettled([operation]);
+        try {
+            await client.close();
+        }
+        catch (closeError) {
+            // HTTP client builder §1: a request failure takes precedence over close.
+            if (outcome.status === 'fulfilled')
+                throw closeError;
         }
+        if (outcome.status === 'rejected')
+            throw outcome.reason;
+        return outcome.value;
     }
     header(name, value) {
         (0, text_1.requireNonBlank)(name, 'HTTP request header name is required');
@@ -81,11 +92,11 @@ class ZLinkHttpRequestBuilder {
             }
             (0, text_1.requireNonBlank)(contentType, 'HTTP request body content type is required');
             this.bodyValue = value;
-            this.headersValue['content-type'] = contentType;
+            this.headersValue[text_1.HttpHeaderName.ContentType] = contentType;
             return this;
         }
         this.bodyValue = JSON.stringify(value);
-        this.headersValue['content-type'] ??= 'application/json';
+        this.headersValue[text_1.HttpHeaderName.ContentType] ??= text_1.HttpContentType.Json;
         return this;
     }
     /**
@@ -98,7 +109,7 @@ class ZLinkHttpRequestBuilder {
         }
         (0, text_1.requireNonBlank)(contentType, 'HTTP request body content type is required');
         this.bodyProviderValue = provider;
-        this.headersValue['content-type'] = contentType;
+        this.headersValue[text_1.HttpHeaderName.ContentType] = contentType;
         return this;
     }
     form(name, value) {
@@ -122,12 +133,7 @@ class ZLinkHttpRequestBuilder {
     async submitRaw() {
         const request = this.makeRequest(undefined);
         const client = this.resolveClient();
-        try {
-            return await client.runtime.executeAsync(request);
-        }
-        finally {
-            await this.closeIfOwned();
-        }
+        return this.execute(client, client.runtime.executeAsync(request));
     }
     /**
      * Streams the response body to `sink` chunk by chunk instead of buffering it; the returned
@@ -139,12 +145,7 @@ class ZLinkHttpRequestBuilder {
         }
         const request = this.makeRequest(sink);
         const client = this.resolveClient();
-        try {
-            return await client.runtime.executeAsync(request);
-        }
-        finally {
-            await this.closeIfOwned();
-        }
+        return this.execute(client, client.runtime.executeAsync(request));
     }
     submit(callback) {
         const pending = this.executeTyped();
@@ -154,8 +155,13 @@ class ZLinkHttpRequestBuilder {
         void pending.then((response) => this.completeCallback(() => callback(undefined, response)), (error) => this.completeCallback(() => callback(error, undefined)));
     }
     async executeTyped() {
-        const raw = await this.submitRaw();
-        if (raw.status >= 400) {
+        const request = this.makeRequest(undefined);
+        const client = this.resolveClient();
+        return this.execute(client, this.decodeResponse(client.runtime.executeAsync(request)));
+    }
+    async decodeResponse(pending) {
+        const raw = await pending;
+        if (raw.status >= HTTP_FAILURE_STATUS_MIN) {
             throw new framework_1.ZLinkFrameworkException(framework_1.ZLinkFrameworkErrorKind.InternalFailure, `HTTP request failed with status ${raw.status}`);
         }
         let body;
@@ -216,12 +222,12 @@ class ZLinkHttpRequestBuilder {
             return { body: this.bodyValue, headers };
         }
         if (this.formValue.length > 0) {
-            headers['content-type'] = 'application/x-www-form-urlencoded';
+            headers[text_1.HttpHeaderName.ContentType] = text_1.HttpContentType.UrlEncoded;
             return { body: this.encodeFormBody(), headers };
         }
         if (this.multipartValue.length > 0) {
             const boundary = (0, text_1.makeMultipartBoundary)();
-            headers['content-type'] = `multipart/form-data; boundary=${boundary}`;
+            headers[text_1.HttpHeaderName.ContentType] = `${text_1.HttpContentType.Multipart}; boundary=${boundary}`;
             return { body: this.encodeMultipartBody(boundary), headers };
         }
         return { body: undefined, headers };

package/dist/runtime/bounded-response-body.d.ts

@@ -0,0 +1,2 @@
+/** Owns the received-byte limit for buffered and streaming responses on both transports. */
+export declare function readResponseBody<T extends Uint8Array>(stream: AsyncIterable<T>, maximumSize: number, consume: (chunk: T) => void): Promise<void>;

package/dist/runtime/bounded-response-body.js

@@ -0,0 +1,16 @@
+"use strict";
+/* SPDX-License-Identifier: Apache-2.0 */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.readResponseBody = readResponseBody;
+const http_client_errors_1 = require("./http-client-errors");
+/** Owns the received-byte limit for buffered and streaming responses on both transports. */
+async function readResponseBody(stream, maximumSize, consume) {
+    let total = 0;
+    for await (const chunk of stream) {
+        total += chunk.length;
+        if (total > maximumSize) {
+            throw (0, http_client_errors_1.responseBodySizeExceeded)();
+        }
+        consume(chunk);
+    }
+}

package/dist/runtime/browser-runtime.js

@@ -2,10 +2,12 @@
 /* SPDX-License-Identifier: Apache-2.0 */
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.HttpClientRuntime = void 0;
+const text_1 = require("./text");
 const framework_1 = require("@zlink-systems/framework");
 const redirect_policy_1 = require("./redirect-policy");
 const retry_policy_1 = require("./retry-policy");
 const http_client_errors_1 = require("./http-client-errors");
+const bounded_response_body_1 = require("./bounded-response-body");
 /** Browser transport for the same public client surface used by the Node runtime. */
 class HttpClientRuntime {
     options;
@@ -16,10 +18,11 @@ class HttpClientRuntime {
         this.retryPolicy = new retry_policy_1.RetryPolicy(options);
     }
     async executeAsync(spec) {
-        return await this.retryPolicy.execute(spec, (request, signal) => this.perform(request, signal));
+        return await this.retryPolicy.execute(spec, (request, controller) => this.perform(request, controller));
     }
     async close() { }
-    async perform(spec, signal) {
+    async perform(spec, controller) {
+        const signal = controller.signal;
         const baseUri = new URL(this.options.baseUrl);
         const origin = baseUri.origin;
         let current = new URL(origin + (0, redirect_policy_1.makeTarget)(baseUri.pathname, spec.target));
@@ -29,47 +32,77 @@ class HttpClientRuntime {
         let redirectsLeft = this.options.followRedirects;
         for (;;) {
             const headers = this.buildHeaders(spec, current.origin === origin, body !== undefined || bodyProvider !== undefined);
-            const response = await fetch(current, {
-                method,
-                headers,
-                body: body ?? bodyStream(bodyProvider),
-                credentials: this.options.cookies ? 'include' : 'same-origin',
-                redirect: 'manual',
-                signal
-            });
-            const location = response.headers.get('location');
+            let response;
+            try {
+                const init = {
+                    method,
+                    headers,
+                    body: body ?? bodyStream(bodyProvider, controller),
+                    duplex: 'half',
+                    credentials: this.options.cookies ? 'include' : 'same-origin',
+                    redirect: 'manual',
+                    signal
+                };
+                response = await fetch(current, init);
+            }
+            catch (error) {
+                throw (0, retry_policy_1.mapFailure)(error, signal.aborted, retry_policy_1.HttpFailureStage.Transport);
+            }
+            const location = response.headers.get(text_1.HttpHeaderName.Location);
             if (this.options.followRedirects > 0 &&
                 (0, redirect_policy_1.isRedirectStatus)(response.status) &&
                 location !== null) {
                 if (redirectsLeft === 0) {
-                    await response.body?.cancel();
+                    try {
+                        await response.body?.cancel();
+                    }
+                    catch (error) {
+                        throw (0, retry_policy_1.mapFailure)(error, signal.aborted, retry_policy_1.HttpFailureStage.Transport);
+                    }
                     throw (0, http_client_errors_1.redirectLimitExceeded)();
                 }
                 redirectsLeft--;
                 ({ method, body } = (0, redirect_policy_1.rewriteForRedirect)(response.status, method, body));
                 bodyProvider = undefined;
-                await response.body?.cancel();
+                try {
+                    await response.body?.cancel();
+                }
+                catch (error) {
+                    throw (0, retry_policy_1.mapFailure)(error, signal.aborted, retry_policy_1.HttpFailureStage.Transport);
+                }
                 current = (0, redirect_policy_1.resolveLocation)(current, location);
                 continue;
             }
             const headersResult = collectHeaders(response.headers);
             if (spec.sink !== undefined) {
-                await streamResponse(response, spec.sink, this.options.maxResponseBodySize);
+                const sink = spec.sink;
+                await (0, bounded_response_body_1.readResponseBody)(responseChunks(response, signal), this.options.maxResponseBodySize, (chunk) => {
+                    try {
+                        sink(chunk);
+                    }
+                    catch (error) {
+                        throw (0, retry_policy_1.mapFailure)(error, signal.aborted, retry_policy_1.HttpFailureStage.Application);
+                    }
+                });
                 return { status: response.status, headers: headersResult, body: '' };
             }
-            const text = await response.text();
-            if (new TextEncoder().encode(text).length > this.options.maxResponseBodySize) {
-                throw (0, http_client_errors_1.responseBodySizeExceeded)();
-            }
-            return { status: response.status, headers: headersResult, body: text };
+            const decoder = new TextDecoder();
+            const text = [];
+            await (0, bounded_response_body_1.readResponseBody)(responseChunks(response, signal), this.options.maxResponseBodySize, (chunk) => {
+                text.push(decoder.decode(chunk, { stream: true }));
+            });
+            text.push(decoder.decode());
+            return { status: response.status, headers: headersResult, body: text.join('') };
         }
     }
     buildHeaders(spec, keepAuthorization, hasBody) {
-        const headers = { accept: 'application/json' };
+        const headers = {
+            [text_1.HttpHeaderName.Accept]: text_1.HttpContentType.Json
+        };
         applyHeaders(headers, this.options.headers, keepAuthorization);
         applyHeaders(headers, spec.headers, keepAuthorization);
         if (!hasBody)
-            delete headers['content-type'];
+            delete headers[text_1.HttpHeaderName.ContentType];
         return headers;
     }
 }
@@ -81,12 +114,20 @@ function rejectUnsupportedTransportOptions(options) {
         throw new framework_1.ZLinkFrameworkException(framework_1.ZLinkFrameworkErrorKind.ProtocolError, 'Browser HTTP clients cannot configure certificate files or a transport proxy.');
     }
 }
-function bodyStream(provider) {
+function bodyStream(provider, abortController) {
     if (provider === undefined)
         return undefined;
     return new ReadableStream({
         pull(controller) {
-            const chunk = provider();
+            let chunk;
+            try {
+                chunk = provider();
+            }
+            catch (error) {
+                const failure = (0, retry_policy_1.mapFailure)(error, abortController.signal.aborted, retry_policy_1.HttpFailureStage.Application);
+                abortController.abort(failure);
+                throw failure;
+            }
             if (chunk === null)
                 controller.close();
             else
@@ -94,21 +135,36 @@ function bodyStream(provider) {
         }
     });
 }
-async function streamResponse(response, sink, maximumSize) {
+async function* responseChunks(response, signal) {
     if (response.body === null)
         return;
     const reader = response.body.getReader();
-    let total = 0;
-    for (;;) {
-        const result = await reader.read();
-        if (result.done)
-            return;
-        total += result.value.length;
-        if (total > maximumSize) {
-            await reader.cancel();
-            throw (0, http_client_errors_1.responseBodySizeExceeded)();
+    try {
+        for (;;) {
+            let result;
+            try {
+                result = await reader.read();
+            }
+            catch (error) {
+                throw (0, retry_policy_1.mapFailure)(error, signal.aborted, retry_policy_1.HttpFailureStage.Transport);
+            }
+            if (result.done)
+                return;
+            yield result.value;
+        }
+    }
+    finally {
+        try {
+            try {
+                await reader.cancel();
+            }
+            catch (error) {
+                throw (0, retry_policy_1.mapFailure)(error, signal.aborted, retry_policy_1.HttpFailureStage.Transport);
+            }
+        }
+        finally {
+            reader.releaseLock();
         }
-        sink(result.value);
     }
 }
 function collectHeaders(headers) {
@@ -121,7 +177,7 @@ function collectHeaders(headers) {
 function applyHeaders(target, source, keepAuthorization) {
     for (const [name, value] of Object.entries(source)) {
         const lower = name.toLowerCase();
-        if (keepAuthorization || lower !== 'authorization')
+        if (keepAuthorization || lower !== text_1.HttpHeaderName.Authorization)
             target[lower] = value;
     }
 }

package/dist/runtime/compression.d.ts

@@ -1,3 +1,8 @@
+export declare const CONTENT_ENCODING: Readonly<{
+    readonly Gzip: "gzip";
+    readonly Deflate: "deflate";
+}>;
+export declare const HTTP_ACCEPTED_CONTENT_ENCODINGS: string;
 /**
  * Wrapper-controlled response decompression mirroring the C++ `compression.cpp`: gzip and deflate
  * are decoded, the decoded size is bounded by the configured body limit (enforced by zlib's

package/dist/runtime/compression.js

@@ -1,12 +1,16 @@
 "use strict";
 /* SPDX-License-Identifier: Apache-2.0 */
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.HTTP_ACCEPTED_CONTENT_ENCODINGS = exports.CONTENT_ENCODING = void 0;
 exports.gunzip = gunzip;
 exports.inflateDeflate = inflateDeflate;
 const node_zlib_1 = require("node:zlib");
 const node_util_1 = require("node:util");
 const framework_1 = require("@zlink-systems/framework");
 const http_client_errors_1 = require("./http-client-errors");
+exports.CONTENT_ENCODING = Object.freeze({ Gzip: 'gzip', Deflate: 'deflate' });
+exports.HTTP_ACCEPTED_CONTENT_ENCODINGS = `${exports.CONTENT_ENCODING.Gzip}, ${exports.CONTENT_ENCODING.Deflate}`;
+const HTTP_DECOMPRESSION_CHUNK_SIZE = 1 << 20;
 const gunzipAsync = (0, node_util_1.promisify)(node_zlib_1.gunzip);
 const inflateAsync = (0, node_util_1.promisify)(node_zlib_1.inflate);
 const inflateRawAsync = (0, node_util_1.promisify)(node_zlib_1.inflateRaw);
@@ -20,14 +24,17 @@ const inflateRawAsync = (0, node_util_1.promisify)(node_zlib_1.inflateRaw);
  * synchronous variants would block the event loop for the whole decode of a large body.
  */
 function gunzip(input, maxBytes) {
-    return decode(() => gunzipAsync(input, { maxOutputLength: maxBytes, chunkSize: 1 << 20 }));
+    return decode(() => gunzipAsync(input, { maxOutputLength: maxBytes, chunkSize: HTTP_DECOMPRESSION_CHUNK_SIZE }));
 }
 function inflateDeflate(input, maxBytes) {
     // Detect a zlib-wrapped stream (CMF/FLG: method deflate, header a multiple of 31) vs raw deflate.
     const zlibWrapped = input.length >= 2 && (input[0] & 0x0f) === 8 && ((input[0] << 8) | input[1]) % 31 === 0;
     return decode(() => zlibWrapped
-        ? inflateAsync(input, { maxOutputLength: maxBytes, chunkSize: 1 << 20 })
-        : inflateRawAsync(input, { maxOutputLength: maxBytes, chunkSize: 1 << 20 }));
+        ? inflateAsync(input, { maxOutputLength: maxBytes, chunkSize: HTTP_DECOMPRESSION_CHUNK_SIZE })
+        : inflateRawAsync(input, {
+            maxOutputLength: maxBytes,
+            chunkSize: HTTP_DECOMPRESSION_CHUNK_SIZE
+        }));
 }
 async function decode(run) {
     try {

package/dist/runtime/cookie-jar.js

@@ -2,6 +2,11 @@
 /* SPDX-License-Identifier: Apache-2.0 */
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.CookieJar = void 0;
+const COOKIE_ATTRIBUTE = Object.freeze({
+    Path: 'path',
+    Secure: 'secure',
+    MaxAge: 'max-age'
+});
 const MAX_COOKIES_PER_HOST = 128;
 class CookieJar {
     cookies = [];
@@ -25,13 +30,14 @@ class CookieJar {
             const attrEquals = attribute.indexOf('=');
             const attrName = (attrEquals < 0 ? attribute : attribute.slice(0, attrEquals)).trim();
             const attrValue = attrEquals < 0 ? '' : attribute.slice(attrEquals + 1).trim();
-            if (attrName.toLowerCase() === 'path' && attrValue.length > 0) {
+            const normalizedName = attrName.toLowerCase();
+            if (normalizedName === COOKIE_ATTRIBUTE.Path && attrValue.length > 0) {
                 path = attrValue;
             }
-            else if (attrName.toLowerCase() === 'secure') {
+            else if (normalizedName === COOKIE_ATTRIBUTE.Secure) {
                 secure = true;
             }
-            else if (attrName.toLowerCase() === 'max-age') {
+            else if (normalizedName === COOKIE_ATTRIBUTE.MaxAge) {
                 const maxAge = Number.parseInt(attrValue, 10);
                 if (!Number.isNaN(maxAge)) {
                     expired = maxAge <= 0;

package/dist/runtime/redirect-policy.js

@@ -10,7 +10,14 @@ const http_client_errors_1 = require("./http-client-errors");
  * Stateless redirect and target-URL rules for the wrapper-owned redirect loop. Isolates the redirect
  * contract (allowed statuses, location resolution, method rewrite) from the request flow.
  */
-const REDIRECT_STATUSES = new Set([301, 302, 303, 307, 308]);
+const RedirectStatus = {
+    MovedPermanently: 301,
+    Found: 302,
+    SeeOther: 303,
+    TemporaryRedirect: 307,
+    PermanentRedirect: 308
+};
+const REDIRECT_STATUSES = new Set(Object.values(RedirectStatus));
 function isRedirectStatus(status) {
     return REDIRECT_STATUSES.has(status);
 }
@@ -26,7 +33,9 @@ function makeTarget(prefix, path) {
  * bodyless GET; all other redirects preserve the method and body.
  */
 function rewriteForRedirect(status, method, body) {
-    if (status === 303 || ((status === 301 || status === 302) && method === 'POST')) {
+    if (status === RedirectStatus.SeeOther ||
+        ((status === RedirectStatus.MovedPermanently || status === RedirectStatus.Found) &&
+            method === 'POST')) {
         return { method: 'GET', body: undefined };
     }
     return { method, body };