@zlink-systems/http-client 0.25.0 → 0.27.0

package/dist/runtime/request-performer.js

@@ -2,12 +2,15 @@
 /* SPDX-License-Identifier: Apache-2.0 */
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.RequestPerformer = void 0;
+const compression_1 = require("./compression");
+const text_1 = require("./text");
 const node_stream_1 = require("node:stream");
 const undici_1 = require("undici");
 const redirect_policy_1 = require("./redirect-policy");
 const response_body_reader_1 = require("./response-body-reader");
 const http_client_errors_1 = require("./http-client-errors");
 const version_1 = require("./version");
+const retry_policy_1 = require("./retry-policy");
 /**
  * Performs a single logical request, driving the wrapper-owned redirect loop, cookie jar
  * integration, and same-origin `Authorization` scrubbing. Redirect/URL rules live in
@@ -39,17 +42,23 @@ class RequestPerformer {
             const keepAuthorization = current.origin === origin;
             const hasBody = body !== undefined || bodyProvider !== undefined;
             const headers = this.buildHeaders(spec, current, keepAuthorization, hasBody);
-            const response = await (0, undici_1.request)(current.href, {
-                method,
-                headers,
-                body: this.buildBody(body, bodyProvider),
-                dispatcher: this.dispatcher,
-                maxRedirections: 0,
-                signal
-            });
+            let response;
+            try {
+                response = await (0, undici_1.request)(current.href, {
+                    method,
+                    headers,
+                    body: this.buildBody(body, bodyProvider, signal),
+                    dispatcher: this.dispatcher,
+                    maxRedirections: 0,
+                    signal
+                });
+            }
+            catch (error) {
+                throw (0, retry_policy_1.mapFailure)(error, signal.aborted, retry_policy_1.HttpFailureStage.Transport);
+            }
             const status = response.statusCode;
             if (this.options.cookies) {
-                const setCookie = response.headers['set-cookie'];
+                const setCookie = response.headers[text_1.HttpHeaderName.SetCookie];
                 const values = Array.isArray(setCookie)
                     ? setCookie
                     : setCookie === undefined
@@ -59,28 +68,47 @@ class RequestPerformer {
                     this.cookieJar.store(current.hostname, value);
                 }
             }
-            const location = headerValue(response.headers, 'location');
+            const location = headerValue(response.headers, text_1.HttpHeaderName.Location);
             if (this.options.followRedirects > 0 &&
                 (0, redirect_policy_1.isRedirectStatus)(status) &&
                 location !== undefined &&
                 location.length > 0) {
                 if (redirectsLeft === 0) {
-                    await drain(response.body);
+                    await drain(response.body, signal);
                     throw (0, http_client_errors_1.redirectLimitExceeded)();
                 }
                 redirectsLeft--;
                 ({ method, body } = (0, redirect_policy_1.rewriteForRedirect)(status, method, body));
                 bodyProvider = undefined; // consumed; never replay a non-rewindable stream on a redirect
-                await drain(response.body);
+                await drain(response.body, signal);
                 current = (0, redirect_policy_1.resolveLocation)(current, location);
                 continue;
             }
             const collectedHeaders = response_body_reader_1.ResponseBodyReader.collectHeaders(response.headers);
             if (spec.sink !== undefined) {
-                await this.bodyReader.streamToSink(response.body, spec.sink);
+                const sink = spec.sink;
+                try {
+                    await this.bodyReader.streamToSink(response.body, (chunk) => {
+                        try {
+                            sink(chunk);
+                        }
+                        catch (error) {
+                            throw (0, retry_policy_1.mapFailure)(error, signal.aborted, retry_policy_1.HttpFailureStage.Application);
+                        }
+                    });
+                }
+                catch (error) {
+                    throw (0, retry_policy_1.mapFailure)(error, signal.aborted, retry_policy_1.HttpFailureStage.Transport);
+                }
                 return { status, headers: collectedHeaders, body: '' };
             }
-            let bytes = await this.bodyReader.readBuffered(response.body);
+            let bytes;
+            try {
+                bytes = await this.bodyReader.readBuffered(response.body);
+            }
+            catch (error) {
+                throw (0, retry_policy_1.mapFailure)(error, signal.aborted, retry_policy_1.HttpFailureStage.Transport);
+            }
             let finalHeaders = collectedHeaders;
             if (this.options.compression) {
                 const result = await this.bodyReader.decompress(bytes, finalHeaders);
@@ -102,11 +130,11 @@ class RequestPerformer {
     }
     buildHeaders(spec, target, keepAuthorization, hasBody) {
         const headers = {
-            'user-agent': version_1.httpClientUserAgent,
-            accept: 'application/json'
+            [text_1.HttpHeaderName.UserAgent]: version_1.httpClientUserAgent,
+            [text_1.HttpHeaderName.Accept]: text_1.HttpContentType.Json
         };
         if (this.options.compression) {
-            headers['accept-encoding'] = 'gzip, deflate';
+            headers[text_1.HttpHeaderName.AcceptEncoding] = compression_1.HTTP_ACCEPTED_CONTENT_ENCODINGS;
         }
         // Proxy authentication is carried by the ProxyAgent dispatcher (see runtime.ts), not a header,
         // so it is not leaked to the target over a CONNECT tunnel.
@@ -114,19 +142,26 @@ class RequestPerformer {
         applyHeaders(headers, spec.headers, keepAuthorization);
         if (!hasBody) {
             // A body source dropped by a redirect must not leave stale content-type metadata behind.
-            delete headers['content-type'];
+            delete headers[text_1.HttpHeaderName.ContentType];
         }
         if (this.options.cookies) {
             const cookieHeader = this.cookieJar.headerFor(target.hostname, target.pathname, target.protocol === 'https:');
             if (cookieHeader.length > 0) {
-                headers['cookie'] = cookieHeader;
+                headers[text_1.HttpHeaderName.Cookie] = cookieHeader;
             }
         }
         return headers;
     }
-    buildBody(body, bodyProvider) {
+    buildBody(body, bodyProvider, signal) {
         if (bodyProvider !== undefined) {
-            const provider = bodyProvider;
+            const provider = () => {
+                try {
+                    return bodyProvider();
+                }
+                catch (error) {
+                    throw (0, retry_policy_1.mapFailure)(error, signal.aborted, retry_policy_1.HttpFailureStage.Application);
+                }
+            };
             return node_stream_1.Readable.from((function* () {
                 for (let chunk = provider(); chunk !== null; chunk = provider()) {
                     if (chunk.length > 0) {
@@ -142,7 +177,7 @@ exports.RequestPerformer = RequestPerformer;
 function applyHeaders(target, headers, keepAuthorization) {
     for (const [name, value] of Object.entries(headers)) {
         const lower = name.toLowerCase();
-        if (!keepAuthorization && lower === 'authorization') {
+        if (!keepAuthorization && lower === text_1.HttpHeaderName.Authorization) {
             continue;
         }
         target[lower] = value;
@@ -155,8 +190,13 @@ function headerValue(headers, name) {
     }
     return Array.isArray(value) ? value[0] : value;
 }
-async function drain(stream) {
-    for await (const _chunk of stream) {
-        // discard
+async function drain(stream, signal) {
+    try {
+        for await (const _chunk of stream) {
+            // discard
+        }
+    }
+    catch (error) {
+        throw (0, retry_policy_1.mapFailure)(error, signal.aborted, retry_policy_1.HttpFailureStage.Transport);
     }
 }

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

@@ -2,8 +2,9 @@
 /* SPDX-License-Identifier: Apache-2.0 */
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.ResponseBodyReader = void 0;
+const text_1 = require("./text");
 const compression_1 = require("./compression");
-const http_client_errors_1 = require("./http-client-errors");
+const bounded_response_body_1 = require("./bounded-response-body");
 /**
  * Reads and decodes undici response bodies for the wrapper: buffered read with the configured size
  * limit, streaming delivery to a sink, header collection, and wrapper-controlled gzip/deflate
@@ -15,44 +16,33 @@ class ResponseBodyReader {
         this.options = options;
     }
     async streamToSink(stream, sink) {
-        let total = 0;
-        for await (const chunk of stream) {
-            const buffer = chunk;
-            total += buffer.length;
-            if (total > this.options.maxResponseBodySize) {
-                throw (0, http_client_errors_1.responseBodySizeExceeded)();
-            }
+        await (0, bounded_response_body_1.readResponseBody)(stream, this.options.maxResponseBodySize, (buffer) => {
             sink(new Uint8Array(buffer));
-        }
+        });
     }
     async readBuffered(stream) {
         const chunks = [];
-        let total = 0;
-        for await (const chunk of stream) {
-            const buffer = chunk;
-            total += buffer.length;
-            if (total > this.options.maxResponseBodySize) {
-                throw (0, http_client_errors_1.responseBodySizeExceeded)();
-            }
+        await (0, bounded_response_body_1.readResponseBody)(stream, this.options.maxResponseBodySize, (buffer) => {
             chunks.push(buffer);
-        }
+        });
         return Buffer.concat(chunks);
     }
     async decompress(bytes, headers) {
-        const encoding = Object.prototype.hasOwnProperty.call(headers, 'content-encoding')
-            ? headers['content-encoding']
+        const encoding = Object.prototype.hasOwnProperty.call(headers, text_1.HttpHeaderName.ContentEncoding)
+            ? headers[text_1.HttpHeaderName.ContentEncoding]
             : undefined;
         // An empty body (HEAD / 204 / 304) carries no payload to decode even with Content-Encoding.
         if (encoding === undefined || bytes.length === 0) {
             return { body: bytes, headers };
         }
-        if (encoding.toLowerCase() === 'gzip') {
+        const normalizedEncoding = encoding.toLowerCase();
+        if (normalizedEncoding === compression_1.CONTENT_ENCODING.Gzip) {
             return {
                 body: await (0, compression_1.gunzip)(bytes, this.options.maxResponseBodySize),
                 headers: stripEncodingHeaders(headers)
             };
         }
-        if (encoding.toLowerCase() === 'deflate') {
+        if (normalizedEncoding === compression_1.CONTENT_ENCODING.Deflate) {
             return {
                 body: await (0, compression_1.inflateDeflate)(bytes, this.options.maxResponseBodySize),
                 headers: stripEncodingHeaders(headers)
@@ -78,7 +68,7 @@ function stripEncodingHeaders(headers) {
     const copy = {};
     for (const [key, value] of Object.entries(headers)) {
         const lower = key.toLowerCase();
-        if (lower !== 'content-encoding' && lower !== 'content-length') {
+        if (lower !== text_1.HttpHeaderName.ContentEncoding && lower !== text_1.HttpHeaderName.ContentLength) {
             copy[key] = value;
         }
     }

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

@@ -1,3 +1,4 @@
+import { ZLinkFrameworkException } from '@zlink-systems/framework';
 import type { HttpClientOptions } from './options';
 import type { HttpRequestSpec, RawResult } from './request-performer';
 /**
@@ -10,5 +11,10 @@ import type { HttpRequestSpec, RawResult } from './request-performer';
 export declare class RetryPolicy {
     private readonly options;
     constructor(options: HttpClientOptions);
-    execute(spec: HttpRequestSpec, perform: (spec: HttpRequestSpec, signal: AbortSignal) => Promise<RawResult>): Promise<RawResult>;
+    execute(spec: HttpRequestSpec, perform: (spec: HttpRequestSpec, controller: AbortController) => Promise<RawResult>): Promise<RawResult>;
 }
+export declare enum HttpFailureStage {
+    Transport = 0,
+    Application = 1
+}
+export declare function mapFailure(error: unknown, aborted: boolean, stage: HttpFailureStage): ZLinkFrameworkException;

package/dist/runtime/retry-policy.js

@@ -1,12 +1,16 @@
 "use strict";
 /* SPDX-License-Identifier: Apache-2.0 */
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.RetryPolicy = void 0;
+exports.HttpFailureStage = exports.RetryPolicy = void 0;
+exports.mapFailure = mapFailure;
 const framework_1 = require("@zlink-systems/framework");
+const INITIAL_RETRY_DELAY_MS = 50;
+const MAX_RETRY_DELAY_MS = 1000;
+const MAX_RETRY_DELAY_SHIFT = Math.ceil(Math.log2(MAX_RETRY_DELAY_MS / INITIAL_RETRY_DELAY_MS));
 // 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));
+    const ceiling = Math.min(MAX_RETRY_DELAY_MS, INITIAL_RETRY_DELAY_MS << Math.min(attempt, MAX_RETRY_DELAY_SHIFT));
     return Math.floor(Math.random() * (ceiling + 1));
 }
 /**
@@ -30,10 +34,10 @@ class RetryPolicy {
                 controller.abort();
             }, timeoutMs);
             try {
-                return await perform(spec, controller.signal);
+                return await perform(spec, controller);
             }
             catch (error) {
-                const failure = mapFailure(error, controller.signal.aborted);
+                const failure = mapFailure(error, controller.signal.aborted, HttpFailureStage.Application);
                 if (isRetriableHttpFailure(failure) && attempt < maxRetries) {
                     await delay(delayMsFor(attempt));
                     continue;
@@ -47,16 +51,23 @@ class RetryPolicy {
     }
 }
 exports.RetryPolicy = RetryPolicy;
-function mapFailure(error, aborted) {
+var HttpFailureStage;
+(function (HttpFailureStage) {
+    HttpFailureStage[HttpFailureStage["Transport"] = 0] = "Transport";
+    HttpFailureStage[HttpFailureStage["Application"] = 1] = "Application";
+})(HttpFailureStage || (exports.HttpFailureStage = HttpFailureStage = {}));
+function mapFailure(error, aborted, stage) {
     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);
+    if (stage === HttpFailureStage.Transport && aborted) {
+        const cause = new DOMException('HTTP request exceeded timeout', 'TimeoutError');
+        return new framework_1.ZLinkFrameworkException(framework_1.ZLinkFrameworkErrorKind.DeadlineExceeded, cause.message, cause);
     }
-    // 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);
+    const message = error instanceof Error ? error.message : 'HTTP execution failure';
+    return new framework_1.ZLinkFrameworkException(stage === HttpFailureStage.Transport
+        ? framework_1.ZLinkFrameworkErrorKind.Unavailable
+        : framework_1.ZLinkFrameworkErrorKind.InternalFailure, message, error);
 }
 function isRetriableHttpFailure(error) {
     return (error.kind === framework_1.ZLinkFrameworkErrorKind.Unavailable ||

package/dist/runtime/runtime.js

@@ -22,7 +22,7 @@ class HttpClientRuntime {
         this.retryPolicy = new retry_policy_1.RetryPolicy(options);
     }
     async executeAsync(spec) {
-        return this.retryPolicy.execute(spec, (request, signal) => this.performer.perform(request, signal));
+        return this.retryPolicy.execute(spec, (request, controller) => this.performer.perform(request, controller.signal));
     }
     async close() {
         if (this.dispatcher !== undefined) {

package/dist/runtime/text.d.ts

@@ -1,3 +1,20 @@
+export declare const HttpHeaderName: Readonly<{
+    Accept: "accept";
+    Authorization: "authorization";
+    ContentType: "content-type";
+    Location: "location";
+    SetCookie: "set-cookie";
+    UserAgent: "user-agent";
+    AcceptEncoding: "accept-encoding";
+    Cookie: "cookie";
+    ContentEncoding: "content-encoding";
+    ContentLength: "content-length";
+}>;
+export declare const HttpContentType: Readonly<{
+    Json: "application/json";
+    UrlEncoded: "application/x-www-form-urlencoded";
+    Multipart: "multipart/form-data";
+}>;
 export declare function requireNonBlank(value: string, message: string): void;
 export declare function requirePositiveTimeout(value: number): void;
 export declare function percentEncode(value: string): string;

package/dist/runtime/text.js

@@ -1,12 +1,30 @@
 "use strict";
 /* SPDX-License-Identifier: Apache-2.0 */
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.HttpContentType = exports.HttpHeaderName = void 0;
 exports.requireNonBlank = requireNonBlank;
 exports.requirePositiveTimeout = requirePositiveTimeout;
 exports.percentEncode = percentEncode;
 exports.basicAuthorization = basicAuthorization;
 exports.makeMultipartBoundary = makeMultipartBoundary;
 const framework_1 = require("@zlink-systems/framework");
+exports.HttpHeaderName = Object.freeze({
+    Accept: 'accept',
+    Authorization: 'authorization',
+    ContentType: 'content-type',
+    Location: 'location',
+    SetCookie: 'set-cookie',
+    UserAgent: 'user-agent',
+    AcceptEncoding: 'accept-encoding',
+    Cookie: 'cookie',
+    ContentEncoding: 'content-encoding',
+    ContentLength: 'content-length'
+});
+exports.HttpContentType = Object.freeze({
+    Json: 'application/json',
+    UrlEncoded: 'application/x-www-form-urlencoded',
+    Multipart: 'multipart/form-data'
+});
 /** Shared text helpers mirroring the C++ `client.cpp` anonymous-namespace utilities. */
 function isBlank(value) {
     return value.length === 0 || /^[\s]*$/u.test(value);
@@ -39,6 +57,13 @@ function percentEncode(value) {
 function basicAuthorization(user, password) {
     return 'Basic ' + Buffer.from(`${user}:${password}`, 'utf8').toString('base64');
 }
+const MULTIPART_BOUNDARY_PREFIX = 'zlink-boundary-';
+const MULTIPART_BOUNDARY_ENTROPY_CHARACTERS = 16;
 function makeMultipartBoundary() {
-    return 'zlink-boundary-' + Math.random().toString(16).slice(2).padEnd(16, '0').slice(0, 16);
+    return (MULTIPART_BOUNDARY_PREFIX +
+        Math.random()
+            .toString(16)
+            .slice(2)
+            .padEnd(MULTIPART_BOUNDARY_ENTROPY_CHARACTERS, '0')
+            .slice(0, MULTIPART_BOUNDARY_ENTROPY_CHARACTERS));
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zlink-systems/http-client",
-  "version": "0.25.0",
+  "version": "0.27.0",
   "license": "Apache-2.0",
   "repository": {
     "type": "git",
@@ -22,7 +22,7 @@
     }
   },
   "dependencies": {
-    "@zlink-systems/framework": "0.25.0",
+    "@zlink-systems/framework": "0.27.0",
     "undici": "6.27.0"
   }
 }