@eserstack/httpclient 0.0.0-stage → 5.0.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/LICENSE +13 -0
- package/README.md +303 -2
- package/dist/client.d.ts +85 -0
- package/dist/client.js +468 -0
- package/dist/errors.d.ts +70 -0
- package/dist/errors.js +132 -0
- package/dist/ffi-client.d.ts +9 -0
- package/dist/ffi-client.js +10 -0
- package/dist/go-client.d.ts +141 -0
- package/dist/go-client.js +177 -0
- package/dist/go-transport.d.ts +15 -0
- package/dist/go-transport.js +74 -0
- package/dist/h3-fetch.d.ts +32 -0
- package/dist/h3-fetch.js +38 -0
- package/dist/interceptors.d.ts +28 -0
- package/dist/interceptors.js +57 -0
- package/dist/mod.d.ts +11 -0
- package/dist/mod.js +10 -0
- package/dist/retry-policy.d.ts +32 -0
- package/dist/retry-policy.js +93 -0
- package/dist/types.d.ts +137 -0
- package/dist/types.js +2 -0
- package/package.json +52 -3
|
@@ -0,0 +1,93 @@
|
|
|
1
|
+
// Copyright 2023-present Eser Ozvataf and other contributors. All rights reserved. Apache-2.0 license.
|
|
2
|
+
import * as errors from "./errors.js";
|
|
3
|
+
import * as ffiClient from "./ffi-client.js";
|
|
4
|
+
/** JSON has no NaN or infinities; the bridge reads them by name. */
|
|
5
|
+
const toWireNumber = (value) => Number.isFinite(value)
|
|
6
|
+
? value
|
|
7
|
+
: String(value);
|
|
8
|
+
const fromWireNumber = (value) => typeof value === "number" ? value : Number(value);
|
|
9
|
+
/**
|
|
10
|
+
* Writes a number field for the wire. A value of another type is sent as it
|
|
11
|
+
* is, so Go refuses it by name instead of this module guessing.
|
|
12
|
+
*/
|
|
13
|
+
const wireField = (value) => typeof value === "number" ? toWireNumber(value) : value;
|
|
14
|
+
const toWireSetting = (setting) => {
|
|
15
|
+
if (setting === undefined || setting === false) {
|
|
16
|
+
return setting;
|
|
17
|
+
}
|
|
18
|
+
if (typeof setting !== "object" || setting === null) {
|
|
19
|
+
// Outside the type; Go answers what it expected.
|
|
20
|
+
return setting;
|
|
21
|
+
}
|
|
22
|
+
const statuses = setting.retryableStatuses;
|
|
23
|
+
return {
|
|
24
|
+
maxAttempts: wireField(setting.maxAttempts),
|
|
25
|
+
initialDelay: wireField(setting.initialDelay),
|
|
26
|
+
maxDelay: wireField(setting.maxDelay),
|
|
27
|
+
factor: wireField(setting.factor),
|
|
28
|
+
jitter: setting.jitter,
|
|
29
|
+
retryableStatuses: Array.isArray(statuses)
|
|
30
|
+
? statuses.map((status) => wireField(status))
|
|
31
|
+
: statuses,
|
|
32
|
+
respectRetryAfter: setting.respectRetryAfter,
|
|
33
|
+
};
|
|
34
|
+
};
|
|
35
|
+
const bridge = () => {
|
|
36
|
+
try {
|
|
37
|
+
return ffiClient.requireLibSync();
|
|
38
|
+
}
|
|
39
|
+
catch (error) {
|
|
40
|
+
const cause = error instanceof Error ? error : new Error(String(error));
|
|
41
|
+
throw new errors.HttpClientError(`HttpClient runs its retry policy in Go through @eserstack/ajan: ${cause.message}`, { cause });
|
|
42
|
+
}
|
|
43
|
+
};
|
|
44
|
+
const refused = (answer) => new errors.HttpClientError(`HttpClient: the retry policy refused the request: ${answer}; check the retry settings against RetryConfig`);
|
|
45
|
+
/**
|
|
46
|
+
* Resolves the plan of one request from the client's and the request's retry
|
|
47
|
+
* settings. A stream body, which the first attempt consumes, gets one
|
|
48
|
+
* attempt.
|
|
49
|
+
*
|
|
50
|
+
* @throws {errors.HttpClientError} When the bridge is unavailable (its load
|
|
51
|
+
* error as `cause`) or Go refuses a setting outside RetryConfig.
|
|
52
|
+
*/
|
|
53
|
+
export const resolveRetryPlan = (clientRetry, requestRetry, streamBody) => {
|
|
54
|
+
const answer = bridge().call("httpRetryResolve", {
|
|
55
|
+
client: toWireSetting(clientRetry),
|
|
56
|
+
request: toWireSetting(requestRetry),
|
|
57
|
+
streamBody,
|
|
58
|
+
});
|
|
59
|
+
if (typeof answer.error === "string" && answer.error !== "") {
|
|
60
|
+
throw refused(answer.error);
|
|
61
|
+
}
|
|
62
|
+
if (answer.plan === undefined) {
|
|
63
|
+
throw refused("the answer has no plan");
|
|
64
|
+
}
|
|
65
|
+
return {
|
|
66
|
+
maxAttempts: fromWireNumber(answer.plan.maxAttempts),
|
|
67
|
+
wire: answer.plan,
|
|
68
|
+
};
|
|
69
|
+
};
|
|
70
|
+
/**
|
|
71
|
+
* Decides after the failed attempt number `attempt` (0 for the first).
|
|
72
|
+
* `status` is the response status, 0 for a network failure; `retryAfterMs` is
|
|
73
|
+
* the response's Retry-After, null when it has none.
|
|
74
|
+
*
|
|
75
|
+
* @throws {errors.HttpClientError} When the bridge is unavailable or refuses
|
|
76
|
+
* the request.
|
|
77
|
+
*/
|
|
78
|
+
export const nextRetry = (plan, attempt, status, retryAfterMs) => {
|
|
79
|
+
const answer = bridge().call("httpRetryNext", {
|
|
80
|
+
plan: plan.wire,
|
|
81
|
+
attempt,
|
|
82
|
+
status,
|
|
83
|
+
retryAfterMs: retryAfterMs === null ? null : toWireNumber(retryAfterMs),
|
|
84
|
+
random: Math.random(),
|
|
85
|
+
});
|
|
86
|
+
if (typeof answer.error === "string" && answer.error !== "") {
|
|
87
|
+
throw refused(answer.error);
|
|
88
|
+
}
|
|
89
|
+
return {
|
|
90
|
+
retry: answer.retry === true,
|
|
91
|
+
delayMs: fromWireNumber(answer.delayMs ?? 0),
|
|
92
|
+
};
|
|
93
|
+
};
|
package/dist/types.d.ts
ADDED
|
@@ -0,0 +1,137 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Public type definitions for @eserstack/httpclient.
|
|
3
|
+
*
|
|
4
|
+
* Provides compatibility with @eserstack/functions patterns:
|
|
5
|
+
* - Result<T,E> re-exported for consumer convenience
|
|
6
|
+
* - RetryConfig shape mirrors @eserstack/functions/resources.ts retryWithBackoff options
|
|
7
|
+
*
|
|
8
|
+
* @module
|
|
9
|
+
*/
|
|
10
|
+
export type { Fail, Ok, Result } from "@eserstack/primitives/results";
|
|
11
|
+
import type * as goClient from "./go-client.ts";
|
|
12
|
+
export type HttpMethod = "GET" | "POST" | "PUT" | "PATCH" | "DELETE" | "HEAD";
|
|
13
|
+
/** Rate-limit metadata extracted from response headers. */
|
|
14
|
+
export interface RateLimitInfo {
|
|
15
|
+
remaining?: number;
|
|
16
|
+
limit?: number;
|
|
17
|
+
resetAt?: number;
|
|
18
|
+
retryAfterSeconds?: number;
|
|
19
|
+
}
|
|
20
|
+
/** Structured response returned by all HttpClient methods. */
|
|
21
|
+
export interface HttpResponse<T = unknown> {
|
|
22
|
+
data: T;
|
|
23
|
+
status: number;
|
|
24
|
+
statusText: string;
|
|
25
|
+
headers: Headers;
|
|
26
|
+
request: Request;
|
|
27
|
+
raw: Response;
|
|
28
|
+
retries: number;
|
|
29
|
+
rateLimit?: RateLimitInfo;
|
|
30
|
+
}
|
|
31
|
+
/**
|
|
32
|
+
* Response from a streaming request.
|
|
33
|
+
* Body is NOT consumed — the caller owns the ReadableStream lifecycle.
|
|
34
|
+
*
|
|
35
|
+
* Response interceptors do NOT run on stream responses because they expect a
|
|
36
|
+
* typed `HttpResponse<T>` with parsed `data`, which streaming doesn't have.
|
|
37
|
+
* Request interceptors run normally.
|
|
38
|
+
*/
|
|
39
|
+
export interface HttpStreamResponse {
|
|
40
|
+
/** Raw body stream — caller reads and closes this. */
|
|
41
|
+
body: ReadableStream<Uint8Array>;
|
|
42
|
+
/** HTTP status code. */
|
|
43
|
+
status: number;
|
|
44
|
+
/** HTTP status text. */
|
|
45
|
+
statusText: string;
|
|
46
|
+
/** Response headers. */
|
|
47
|
+
headers: Headers;
|
|
48
|
+
/** The Request object that was sent (after request interceptors). */
|
|
49
|
+
request: Request;
|
|
50
|
+
/** Original Response object (escape hatch). */
|
|
51
|
+
raw: Response;
|
|
52
|
+
/** Number of retries attempted before the stream connected. */
|
|
53
|
+
retries: number;
|
|
54
|
+
/** Rate-limit metadata extracted from response headers. */
|
|
55
|
+
rateLimit?: RateLimitInfo;
|
|
56
|
+
}
|
|
57
|
+
/** Named request interceptor — transforms a Request before sending. */
|
|
58
|
+
export type RequestInterceptor = {
|
|
59
|
+
name?: string;
|
|
60
|
+
intercept: (request: Request) => Request | Promise<Request>;
|
|
61
|
+
};
|
|
62
|
+
/** Named response interceptor — transforms an HttpResponse after receiving. */
|
|
63
|
+
export type ResponseInterceptor = {
|
|
64
|
+
name?: string;
|
|
65
|
+
intercept: <T>(response: HttpResponse<T>) => HttpResponse<T> | Promise<HttpResponse<T>>;
|
|
66
|
+
};
|
|
67
|
+
/** Interceptor collections for client configuration. */
|
|
68
|
+
export interface Interceptors {
|
|
69
|
+
request?: ReadonlyArray<RequestInterceptor>;
|
|
70
|
+
response?: ReadonlyArray<ResponseInterceptor>;
|
|
71
|
+
}
|
|
72
|
+
/**
|
|
73
|
+
* Retry configuration.
|
|
74
|
+
* Shape mirrors @eserstack/functions/resources.ts retryWithBackoff options
|
|
75
|
+
* for consistency across the monorepo.
|
|
76
|
+
*/
|
|
77
|
+
export interface RetryConfig {
|
|
78
|
+
/** Maximum number of attempts (default: 3). Matches @eserstack/functions. */
|
|
79
|
+
maxAttempts?: number;
|
|
80
|
+
/** Initial backoff delay in ms (default: 1000). Matches @eserstack/functions. */
|
|
81
|
+
initialDelay?: number;
|
|
82
|
+
/** Maximum backoff delay in ms (default: 30_000). Matches @eserstack/functions. */
|
|
83
|
+
maxDelay?: number;
|
|
84
|
+
/** Backoff multiplication factor (default: 2). Matches @eserstack/functions. */
|
|
85
|
+
factor?: number;
|
|
86
|
+
/** Add randomness to delays to avoid thundering herd (default: true). */
|
|
87
|
+
jitter?: boolean;
|
|
88
|
+
/** HTTP status codes that trigger a retry (default: [408, 429, 500, 502, 503, 504]). */
|
|
89
|
+
retryableStatuses?: readonly number[];
|
|
90
|
+
/** Honour the Retry-After response header for 429 responses (default: true). */
|
|
91
|
+
respectRetryAfter?: boolean;
|
|
92
|
+
}
|
|
93
|
+
/**
|
|
94
|
+
* How requests leave the process. `"fetch"` (the default) uses `fetchFn` or
|
|
95
|
+
* the global `fetch`. `"native"` uses the Go HTTP client of `@eserstack/ajan`,
|
|
96
|
+
* whose calls block the JavaScript thread; the README's Native Client section
|
|
97
|
+
* lists what else differs.
|
|
98
|
+
*/
|
|
99
|
+
export type HttpTransport = "fetch" | "native";
|
|
100
|
+
/** Client-level configuration. */
|
|
101
|
+
export interface HttpClientConfig {
|
|
102
|
+
/** Prefix for request paths that are not absolute URLs. */
|
|
103
|
+
baseUrl?: string;
|
|
104
|
+
/** Headers sent with every request; a request's own headers win. */
|
|
105
|
+
headers?: Record<string, string>;
|
|
106
|
+
/** Request timeout in ms (default: 30_000). */
|
|
107
|
+
timeout?: number;
|
|
108
|
+
/** Retry policy — pass false to disable retry entirely. */
|
|
109
|
+
retry?: RetryConfig | false;
|
|
110
|
+
/** Request and response interceptors, run in order. */
|
|
111
|
+
interceptors?: Interceptors;
|
|
112
|
+
/** Where requests are sent; see {@link HttpTransport}. Default: "fetch". */
|
|
113
|
+
transport?: HttpTransport;
|
|
114
|
+
/** Inject a custom fetch for testing. Not allowed with transport "native". */
|
|
115
|
+
fetchFn?: typeof fetch;
|
|
116
|
+
/** Inject a custom delay function to control timing in tests. */
|
|
117
|
+
_delayFn?: (ms: number) => Promise<void>;
|
|
118
|
+
/** Inject the Go client factory in tests of transport "native". */
|
|
119
|
+
_createGoClient?: (options: goClient.GoHttpClientOptions) => Promise<goClient.GoHttpClient>;
|
|
120
|
+
}
|
|
121
|
+
/** Per-request overrides. */
|
|
122
|
+
export interface RequestOptions {
|
|
123
|
+
headers?: Record<string, string>;
|
|
124
|
+
/**
|
|
125
|
+
* Request body. Auto-serialization rules:
|
|
126
|
+
* - Plain object / array → `JSON.stringify(body)`, sets `Content-Type: application/json`
|
|
127
|
+
* (header is NOT overwritten if already set by the caller)
|
|
128
|
+
* - `string`, `ArrayBuffer`, `ArrayBufferView`, `Blob`, `FormData`,
|
|
129
|
+
* `URLSearchParams`, `ReadableStream` → forwarded as-is to `fetch()`
|
|
130
|
+
* - `undefined` → no body sent
|
|
131
|
+
*/
|
|
132
|
+
body?: BodyInit | Record<string, unknown>;
|
|
133
|
+
params?: Record<string, string>;
|
|
134
|
+
timeout?: number;
|
|
135
|
+
retry?: RetryConfig | false;
|
|
136
|
+
signal?: AbortSignal;
|
|
137
|
+
}
|
package/dist/types.js
ADDED
package/package.json
CHANGED
|
@@ -1,6 +1,55 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@eserstack/httpclient",
|
|
3
|
-
"version": "
|
|
4
|
-
"
|
|
5
|
-
"
|
|
3
|
+
"version": "5.0.0",
|
|
4
|
+
"type": "module",
|
|
5
|
+
"repository": {
|
|
6
|
+
"type": "git",
|
|
7
|
+
"url": "https://github.com/eser/stack",
|
|
8
|
+
"directory": "pkg/@eserstack/httpclient"
|
|
9
|
+
},
|
|
10
|
+
"files": [
|
|
11
|
+
"dist/**/*.js",
|
|
12
|
+
"dist/**/*.d.ts",
|
|
13
|
+
"dist/**/*.json"
|
|
14
|
+
],
|
|
15
|
+
"exports": {
|
|
16
|
+
".": {
|
|
17
|
+
"types": "./dist/mod.d.ts",
|
|
18
|
+
"import": "./dist/mod.js"
|
|
19
|
+
},
|
|
20
|
+
"./client": {
|
|
21
|
+
"types": "./dist/client.d.ts",
|
|
22
|
+
"import": "./dist/client.js"
|
|
23
|
+
},
|
|
24
|
+
"./errors": {
|
|
25
|
+
"types": "./dist/errors.d.ts",
|
|
26
|
+
"import": "./dist/errors.js"
|
|
27
|
+
},
|
|
28
|
+
"./interceptors": {
|
|
29
|
+
"types": "./dist/interceptors.d.ts",
|
|
30
|
+
"import": "./dist/interceptors.js"
|
|
31
|
+
},
|
|
32
|
+
"./types": {
|
|
33
|
+
"types": "./dist/types.d.ts",
|
|
34
|
+
"import": "./dist/types.js"
|
|
35
|
+
},
|
|
36
|
+
"./go-client": {
|
|
37
|
+
"types": "./dist/go-client.d.ts",
|
|
38
|
+
"import": "./dist/go-client.js"
|
|
39
|
+
},
|
|
40
|
+
"./h3-fetch": {
|
|
41
|
+
"types": "./dist/h3-fetch.d.ts",
|
|
42
|
+
"import": "./dist/h3-fetch.js"
|
|
43
|
+
}
|
|
44
|
+
},
|
|
45
|
+
"dependencies": {
|
|
46
|
+
"@eserstack/primitives": "5.0.0",
|
|
47
|
+
"@eserstack/ajan": "5.0.0"
|
|
48
|
+
},
|
|
49
|
+
"devDependencies": {
|
|
50
|
+
"@eserstack/test-kit": "5.0.0"
|
|
51
|
+
},
|
|
52
|
+
"scripts": {
|
|
53
|
+
"build": "node ../../../etc/scripts/build-library.ts"
|
|
54
|
+
}
|
|
6
55
|
}
|