@azure-net/kit 6.0.0-next.12 → 6.0.0-next.14

package/README.md

@@ -390,7 +390,7 @@ const http = new HttpServiceInstance({
 	retry: {
 		limit: 1,
 		statuses: [401],
-		async shouldRetry({ error }) {
+		async shouldRetry({ error, http }) {
 			if (!isExpiredAccessToken(error.data)) return false;
 			const refreshed = await http.post('/api/auth/refresh', {
 				json: { refreshToken: readRefreshToken() },
@@ -421,8 +421,8 @@ implement token rotation or cross-tab coordination.
 - Exceptions from hooks (including `shouldRetry`) propagate without further
   recovery. They are not treated as another failed transport attempt.
 - Cancelled requests and streaming request bodies are never replayed. Cancellation
-  is checked again after awaiting recovery; the callback must manage its own async
-  work and cancellation if needed.
+  also stops waiting for recovery; the callback must manage cancellation of its
+  own underlying work.
 - `limit` must be a finite non-negative safe integer. There is no implicit retry
   delay/backoff. Timeout is applied separately to each HTTP attempt.
 
@@ -430,3 +430,39 @@ Retries are opt-in for all HTTP methods. Do not blindly retry writes after netwo
 errors: the server may already have applied them. Use a narrow status/code policy
 or backend-supported idempotency keys. Numerical `retry: 3` is no longer supported;
 write `retry: { limit: 3 }` instead.
+
+HTTP hooks use these signatures:
+
+```ts
+retry: {
+ limit: 1,
+ shouldRetry: async ({ error, http }) => {
+  // The same client instance. Nested refresh must specify retry: { limit: 0 }.
+  return false;
+ }
+},
+onError: ({ error, request }) => {
+ // Terminal failure notification / validation mapping. No http is exposed.
+}
+```
+
+This is a breaking change from positional `onError(error, request, http)`.
+Request-level hook overrides use the same signatures. Nested requests use instance
+settings plus their own options, not the outer request's body or signal.
+
+AbortSignal stops waiting for hooks as well as transport operations. Arbitrary
+user promises cannot be forcibly terminated: hooks must cooperate to stop their
+own side effects. Hooks have no implicit timeout; supply and abort a signal to
+bound their waiting time. The per-attempt timeout covers transport and body
+parsing, including custom `doFetch`. With `responseFormat: 'body'`, it ends when
+the stream is returned; reading/cancelling that stream is then the caller's job.
+Timers/listeners are removed on success, failure, timeout and cancellation.
+
+JSON serialization errors now reject before sending rather than silently sending
+an empty body. The default JSON serializer does not support cyclic values or
+BigInt; provide `stringifyJson` if a custom wire format is required.
+
+Removing `http` from `onError` does not prevent recursion through a client captured
+in a closure. Do not initiate the same failing operation from its error handler.
+Refresh via `shouldRetry` still requires an explicit `retry: { limit: 0 }` on the
+nested refresh call. Limits apply per HTTP call, not to arbitrary nested user code.

package/dist/infra/http-service/HttpServiceInstance.d.ts

@@ -1,3 +1,4 @@
+import { type RequestErrors, SchemaFail } from '../../delivery/schema/Schema.js';
 export type SearchParamsInit = string | string[][] | Record<string, string> | URLSearchParams | undefined;
 export type SearchParamsOption = SearchParamsInit | Record<string, string | number | boolean | undefined> | Array<Array<string | number | boolean>>;
 export declare enum HttpInstanceFetchMethods {
@@ -24,6 +25,7 @@ export interface IHttpServiceError<T = unknown> {
     message: string;
     status: number;
     data?: T;
+    validation?: unknown;
 }
 export declare class HttpServiceResponse<T> implements IHttpServiceResponse<T> {
     headers: Record<string, string>;
@@ -45,7 +47,10 @@ export declare class HttpServiceError<T> extends Error implements IHttpServiceEr
     type: HttpErrorTypes;
     original?: Error;
     response?: Response;
+    validation?: SchemaFail<Record<string, unknown>>;
     constructor({ status, data, message, original, type, response }: Partial<IHttpServiceError<T>>);
+    addAsValidation(validation: RequestErrors<Record<string, unknown>>): void;
+    getSelfTypedData<T = unknown>(): T;
 }
 export interface IHttpInstanceNormalizedRequest {
     url: string | URL;
@@ -61,7 +66,10 @@ export interface IHttpInstanceNormalizedRequest {
     requestInit: Omit<RequestInit, 'method' | 'headers' | 'body'>;
 }
 export type IHttpInstanceOnRequest = (request: IHttpInstanceNormalizedRequest) => void | Promise<void>;
-export type IHttpInstanceOnError = (error: HttpServiceError<unknown>, request: IHttpInstanceNormalizedRequest) => void | Promise<void>;
+export type IHttpInstanceOnError = (context: {
+    error: HttpServiceError<unknown>;
+    request: IHttpInstanceNormalizedRequest;
+}) => void | Promise<void>;
 export type IHttpInstanceDoFetch = <T = unknown>(request: IHttpInstanceNormalizedRequest) => Promise<IHttpServiceResponse<T>>;
 export interface IHttpInstanceRetryOptions {
     /** Number of additional attempts. Zero disables retries, including inherited policies. */
@@ -69,6 +77,7 @@ export interface IHttpInstanceRetryOptions {
     statuses?: readonly number[];
     shouldRetry?: (context: {
         error: HttpServiceError<unknown>;
+        http: IHttpServiceInstance;
     }) => boolean | Promise<boolean>;
 }
 export interface IHttpInstanceOptions<T = unknown> extends Omit<RequestInit, 'headers' | 'method'> {

package/dist/infra/http-service/HttpServiceInstance.js

@@ -1,5 +1,6 @@
 import { BROWSER } from '../../external/tools/index.js';
 import { RequestContext } from '../../shared/request-context/Internal.js';
+import { SchemaFail } from '../../delivery/schema/Schema.js';
 export var HttpInstanceFetchMethods;
 (function (HttpInstanceFetchMethods) {
     HttpInstanceFetchMethods["GET"] = "GET";
@@ -38,6 +39,7 @@ export class HttpServiceError extends Error {
     type;
     original;
     response;
+    validation;
     constructor({ status = 500, data, message = 'unknown error', original, type = HttpErrorTypes.Internal, response }) {
         super(message);
         this.status = status;
@@ -47,15 +49,14 @@ export class HttpServiceError extends Error {
         this.response = response;
         this.type = type;
     }
-}
-const stringifyJsonFunc = (data) => {
-    try {
-        return JSON.stringify(data);
+    addAsValidation(validation) {
+        this.validation = new SchemaFail(validation);
     }
-    catch {
-        return undefined;
+    getSelfTypedData() {
+        return this.data;
     }
-};
+}
+const stringifyJsonFunc = (data) => JSON.stringify(data);
 const isAbsoluteUrl = (value) => /^[a-zA-Z][a-zA-Z\d+\-.]*:/.test(value);
 const normalizeHeaders = (headers) => {
     if (!headers)
@@ -99,7 +100,7 @@ const mergeSearchParams = (base, extra) => {
     return result;
 };
 const mergeOptions = (base = {}, extra = {}) => {
-    const mergedHeaders = new Headers(normalizeHeaders(base.headers));
+    const mergedHeaders = normalizeHeaders(base.headers);
     for (const [key, value] of normalizeHeaders(extra.headers).entries()) {
         mergedHeaders.set(key, value);
     }
@@ -230,28 +231,46 @@ const parseResponse = async (response, request) => {
     return { data, headers: Object.fromEntries(response.headers.entries()), status: response.status, raw };
 };
 const defaultDoFetch = async (request) => {
-    const timeoutState = withTimeout(request.requestInit.signal, request.timeout);
-    try {
-        const response = await request.fetch(request.url, {
-            ...request.requestInit,
-            method: request.method,
-            headers: request.headers,
-            body: request.body,
-            signal: timeoutState.signal ?? undefined
+    const response = await request.fetch(request.url, {
+        ...request.requestInit,
+        ...(typeof ReadableStream !== 'undefined' && request.body instanceof ReadableStream ? { duplex: 'half' } : {}),
+        method: request.method,
+        headers: request.headers,
+        body: request.body
+    });
+    const { data, headers, status, raw } = await parseResponse(response, request);
+    return new HttpServiceResponse({ headers, status, success: true, data, message: 'Request completed', raw });
+};
+// Stop waiting even when a custom transport or hook ignores AbortSignal.
+// The underlying operation must cooperate to actually stop its own work.
+const waitForSignal = (value, signal) => {
+    if (!signal)
+        return Promise.resolve(value);
+    return new Promise((resolve, reject) => {
+        const abort = () => {
+            cleanup();
+            reject(signal.reason);
+        };
+        const cleanup = () => signal.removeEventListener('abort', abort);
+        if (signal.aborted)
+            abort();
+        else
+            signal.addEventListener('abort', abort, { once: true });
+        Promise.resolve(value).then((result) => {
+            cleanup();
+            resolve(result);
+        }, (error) => {
+            cleanup();
+            reject(error);
         });
-        const { data, headers, status, raw } = await parseResponse(response, request);
-        return new HttpServiceResponse({ headers, status, success: true, data, message: 'Request completed', raw });
-    }
-    finally {
-        timeoutState.clear();
-    }
+    });
 };
-const makeMethod = (method, defaults) => {
+const makeMethod = (method, defaults, http) => {
     return async (url, options = {}) => {
         const merged = mergeOptions(defaults, options);
         const stringifyJson = merged.stringifyJson ?? stringifyJsonFunc;
         const fetcher = !BROWSER ? (RequestContext.current()?.event?.fetch ?? fetch) : fetch;
-        const headers = normalizeHeaders(merged.headers);
+        const headers = merged.headers;
         let body = merged.body;
         if (merged.json !== undefined && body === undefined) {
             body = stringifyJson(merged.json);
@@ -289,6 +308,11 @@ const makeMethod = (method, defaults) => {
             }
         };
         // Snapshot the policy per call: hooks and concurrent requests cannot extend its budget.
+        const sourceSignal = merged.signal;
+        const timeout = normalizedRequest.timeout;
+        if (timeout !== false && (!Number.isFinite(timeout) || timeout < 0 || timeout > 2147483647)) {
+            throw new RangeError('timeout must be false or a finite number between 0 and 2147483647');
+        }
         const policy = merged.retry;
         const limit = policy?.limit ?? 0;
         if (!Number.isSafeInteger(limit) || limit < 0) {
@@ -299,13 +323,22 @@ const makeMethod = (method, defaults) => {
         const doFetch = merged.doFetch ?? defaultDoFetch;
         let fetched;
         for (let attempt = 0;; attempt++) {
-            normalizedRequest.requestInit.signal?.throwIfAborted();
+            sourceSignal?.throwIfAborted();
             // Re-run authentication/header hooks after recovery, without accumulating headers.
-            normalizedRequest.headers = new Headers(headers);
-            await merged.onRequest?.(normalizedRequest);
+            normalizedRequest.headers = merged.onRequest ? new Headers(headers) : headers;
+            if (merged.onRequest)
+                await waitForSignal(merged.onRequest(normalizedRequest), sourceSignal);
             normalizedRequest.requestInit.signal?.throwIfAborted();
             try {
-                fetched = await doFetch(normalizedRequest);
+                const timeoutState = withTimeout(sourceSignal, timeout);
+                normalizedRequest.requestInit.signal = timeoutState.signal;
+                try {
+                    fetched = await waitForSignal(doFetch(normalizedRequest), timeoutState.signal);
+                }
+                finally {
+                    timeoutState.clear();
+                    normalizedRequest.requestInit.signal = sourceSignal;
+                }
                 break;
             }
             catch (error) {
@@ -315,19 +348,22 @@ const makeMethod = (method, defaults) => {
                         message: normalizeUnknownError(error).message,
                         original: normalizeUnknownError(error)
                     });
-                const aborted = normalizedRequest.requestInit.signal?.aborted || normalizedError.original?.name === 'AbortError';
+                const aborted = sourceSignal?.aborted || normalizedError.original?.name === 'AbortError';
                 const streaming = typeof ReadableStream !== 'undefined' && normalizedRequest.body instanceof ReadableStream;
                 const eligible = !aborted && !streaming && attempt < limit && (!statuses || statuses.includes(normalizedError.status));
-                if (eligible && (!shouldRetry || (await shouldRetry({ error: normalizedError })))) {
+                if (eligible && (!shouldRetry || (await waitForSignal(shouldRetry({ error: normalizedError, http }), sourceSignal)))) {
                     normalizedRequest.requestInit.signal?.throwIfAborted();
                     continue;
                 }
-                await merged.onError?.(normalizedError, normalizedRequest);
+                if (merged.onError)
+                    await waitForSignal(merged.onError({ error: normalizedError, request: normalizedRequest }), sourceSignal);
                 throw normalizedError;
             }
         }
         // Consumer callback failures must never replay a successful HTTP operation.
-        await merged.onResponse?.(fetched);
+        sourceSignal?.throwIfAborted();
+        if (merged.onResponse)
+            await waitForSignal(merged.onResponse(fetched), sourceSignal);
         return fetched;
     };
 };
@@ -342,12 +378,12 @@ export class HttpServiceInstance {
     options;
     constructor(config = {}) {
         this.defaults = { ...config };
-        this.get = makeMethod(HttpInstanceFetchMethods.GET, this.defaults);
-        this.post = makeMethod(HttpInstanceFetchMethods.POST, this.defaults);
-        this.put = makeMethod(HttpInstanceFetchMethods.PUT, this.defaults);
-        this.delete = makeMethod(HttpInstanceFetchMethods.DELETE, this.defaults);
-        this.patch = makeMethod(HttpInstanceFetchMethods.PATCH, this.defaults);
-        this.head = makeMethod(HttpInstanceFetchMethods.HEAD, this.defaults);
-        this.options = makeMethod(HttpInstanceFetchMethods.OPTIONS, this.defaults);
+        this.get = makeMethod(HttpInstanceFetchMethods.GET, this.defaults, this);
+        this.post = makeMethod(HttpInstanceFetchMethods.POST, this.defaults, this);
+        this.put = makeMethod(HttpInstanceFetchMethods.PUT, this.defaults, this);
+        this.delete = makeMethod(HttpInstanceFetchMethods.DELETE, this.defaults, this);
+        this.patch = makeMethod(HttpInstanceFetchMethods.PATCH, this.defaults, this);
+        this.head = makeMethod(HttpInstanceFetchMethods.HEAD, this.defaults, this);
+        this.options = makeMethod(HttpInstanceFetchMethods.OPTIONS, this.defaults, this);
     }
 }

package/dist/shared/app-error/AppError.js

@@ -52,6 +52,7 @@ export class AppError extends Error {
                 this.type = ErrorTypes.Http;
                 this.external = this.error.type === HttpErrorTypes.External;
                 this.statusCode = this.error.status;
+                this.validation = this.error?.validation?.getSelfTypedData();
                 break;
             case this.error instanceof SchemaFail:
                 this.type = ErrorTypes.Schema;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@azure-net/kit",
-  "version": "6.0.0-next.12",
+  "version": "6.0.0-next.14",
   "license": "MIT",
   "author": "Pixel1917",
   "description": "Universal toolkit and library collection, developed as part of the Azure-net ecosystem",