@venizia/ignis-helpers 0.4.8 → 0.5.0-1
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/dist/esm/common/constants/http.d.ts +17 -1
- package/dist/esm/common/constants/http.js +17 -0
- package/dist/esm/common/constants/http.js.map +1 -1
- package/dist/esm/common/redact.js +2 -0
- package/dist/esm/common/redact.js.map +1 -1
- package/dist/esm/core.d.ts +5 -2
- package/dist/esm/core.js +5 -2
- package/dist/esm/core.js.map +1 -1
- package/dist/esm/modules/network/http-request/base-network-request.helper.d.ts +5 -0
- package/dist/esm/modules/network/http-request/base-network-request.helper.js +14 -17
- package/dist/esm/modules/network/http-request/base-network-request.helper.js.map +1 -1
- package/dist/esm/modules/network/http-request/common/constants.d.ts +2 -1
- package/dist/esm/modules/network/http-request/common/constants.js +2 -1
- package/dist/esm/modules/network/http-request/common/constants.js.map +1 -1
- package/dist/esm/modules/network/http-request/fetcher/axios-fetcher.d.ts +37 -11
- package/dist/esm/modules/network/http-request/fetcher/axios-fetcher.js +181 -38
- package/dist/esm/modules/network/http-request/fetcher/axios-fetcher.js.map +1 -1
- package/dist/esm/modules/network/http-request/fetcher/base-fetcher.d.ts +204 -18
- package/dist/esm/modules/network/http-request/fetcher/base-fetcher.js +433 -13
- package/dist/esm/modules/network/http-request/fetcher/base-fetcher.js.map +1 -1
- package/dist/esm/modules/network/http-request/fetcher/common/body-limit.d.ts +36 -0
- package/dist/esm/modules/network/http-request/fetcher/common/body-limit.js +119 -0
- package/dist/esm/modules/network/http-request/fetcher/common/body-limit.js.map +1 -0
- package/dist/esm/modules/network/http-request/fetcher/common/errors.d.ts +40 -0
- package/dist/esm/modules/network/http-request/fetcher/common/errors.js +37 -0
- package/dist/esm/modules/network/http-request/fetcher/common/errors.js.map +1 -0
- package/dist/esm/modules/network/http-request/fetcher/common/guard.d.ts +27 -0
- package/dist/esm/modules/network/http-request/fetcher/common/guard.js +2 -0
- package/dist/esm/modules/network/http-request/fetcher/common/guard.js.map +1 -0
- package/dist/esm/modules/network/http-request/fetcher/common/index.d.ts +6 -0
- package/dist/esm/modules/network/http-request/fetcher/common/index.js +6 -0
- package/dist/esm/modules/network/http-request/fetcher/common/index.js.map +1 -1
- package/dist/esm/modules/network/http-request/fetcher/common/request-context.d.ts +15 -0
- package/dist/esm/modules/network/http-request/fetcher/common/request-context.js +11 -0
- package/dist/esm/modules/network/http-request/fetcher/common/request-context.js.map +1 -0
- package/dist/esm/modules/network/http-request/fetcher/common/response-reader.d.ts +133 -0
- package/dist/esm/modules/network/http-request/fetcher/common/response-reader.js +264 -0
- package/dist/esm/modules/network/http-request/fetcher/common/response-reader.js.map +1 -0
- package/dist/esm/modules/network/http-request/fetcher/common/types.d.ts +65 -1
- package/dist/esm/modules/network/http-request/fetcher/common/types.js.map +1 -1
- package/dist/esm/modules/network/http-request/fetcher/common/utilities.d.ts +68 -0
- package/dist/esm/modules/network/http-request/fetcher/common/utilities.js +143 -0
- package/dist/esm/modules/network/http-request/fetcher/common/utilities.js.map +1 -0
- package/dist/esm/modules/network/http-request/fetcher/index.d.ts +2 -1
- package/dist/esm/modules/network/http-request/fetcher/index.js +2 -1
- package/dist/esm/modules/network/http-request/fetcher/index.js.map +1 -1
- package/dist/esm/modules/network/http-request/fetcher/native-fetcher.d.ts +85 -0
- package/dist/esm/modules/network/http-request/fetcher/native-fetcher.js +221 -0
- package/dist/esm/modules/network/http-request/fetcher/native-fetcher.js.map +1 -0
- package/dist/esm/modules/network/utilities/index.d.ts +1 -0
- package/dist/esm/modules/network/utilities/index.js +1 -0
- package/dist/esm/modules/network/utilities/index.js.map +1 -1
- package/dist/esm/modules/network/utilities/query-string.d.ts +6 -23
- package/dist/esm/modules/network/utilities/query-string.js +3 -17
- package/dist/esm/modules/network/utilities/query-string.js.map +1 -1
- package/dist/esm/modules/network/utilities/url-builder.d.ts +39 -0
- package/dist/esm/modules/network/utilities/url-builder.js +102 -0
- package/dist/esm/modules/network/utilities/url-builder.js.map +1 -0
- package/dist/esm/modules/network/utilities/url-safety/common/constants.d.ts +0 -3
- package/dist/esm/modules/network/utilities/url-safety/common/constants.js.map +1 -1
- package/dist/esm/modules/network/utilities/url-safety/common/errors.d.ts +38 -0
- package/dist/esm/modules/network/utilities/url-safety/common/errors.js +33 -1
- package/dist/esm/modules/network/utilities/url-safety/common/errors.js.map +1 -1
- package/dist/esm/modules/network/utilities/url-safety/common/types.d.ts +26 -3
- package/dist/esm/modules/network/utilities/url-safety/common/types.js.map +1 -1
- package/dist/esm/modules/network/utilities/url-safety/guard.d.ts +46 -0
- package/dist/esm/modules/network/utilities/url-safety/guard.js +145 -0
- package/dist/esm/modules/network/utilities/url-safety/guard.js.map +1 -0
- package/dist/esm/modules/network/utilities/url-safety/index.d.ts +1 -1
- package/dist/esm/modules/network/utilities/url-safety/index.js +1 -1
- package/dist/esm/modules/network/utilities/url-safety/index.js.map +1 -1
- package/dist/esm/modules/network/utilities/url-safety/policy.d.ts +52 -2
- package/dist/esm/modules/network/utilities/url-safety/policy.js +161 -14
- package/dist/esm/modules/network/utilities/url-safety/policy.js.map +1 -1
- package/dist/esm/modules/queue/bullmq/helper.d.ts +43 -7
- package/dist/esm/modules/queue/bullmq/helper.js +70 -2
- package/dist/esm/modules/queue/bullmq/helper.js.map +1 -1
- package/dist/esm/modules/retry/helper.d.ts +3 -1
- package/dist/esm/modules/retry/helper.js +8 -4
- package/dist/esm/modules/retry/helper.js.map +1 -1
- package/dist/esm/utilities/request.utility.d.ts +1 -25
- package/dist/esm/utilities/request.utility.js +0 -46
- package/dist/esm/utilities/request.utility.js.map +1 -1
- package/package.json +4 -4
- package/dist/esm/modules/network/http-request/fetcher/node-fetcher.d.ts +0 -41
- package/dist/esm/modules/network/http-request/fetcher/node-fetcher.js +0 -111
- package/dist/esm/modules/network/http-request/fetcher/node-fetcher.js.map +0 -1
- package/dist/esm/modules/network/utilities/url-safety/ingest.d.ts +0 -95
- package/dist/esm/modules/network/utilities/url-safety/ingest.js +0 -328
- package/dist/esm/modules/network/utilities/url-safety/ingest.js.map +0 -1
|
@@ -0,0 +1,264 @@
|
|
|
1
|
+
import { HTTP } from '../../../../../common/constants/http.js';
|
|
2
|
+
import { getError } from '../../../../error/index.js';
|
|
3
|
+
import { RecordUtility } from '../../../../../utilities/record.utility.js';
|
|
4
|
+
import { BodyLimit } from './body-limit.js';
|
|
5
|
+
/**
|
|
6
|
+
* What an IGNIS server answers - `Content-Range`, the error envelope - read once, here, for every
|
|
7
|
+
* client of that server: the http connector, and a client that reads it without the connector.
|
|
8
|
+
*/
|
|
9
|
+
export class HttpResponseReader {
|
|
10
|
+
/** A content type that names JSON: `application/json`, `application/problem+json`, `application/ld+json`. */
|
|
11
|
+
static { this.JSON_CONTENT_TYPE_PATTERN = /json/i; }
|
|
12
|
+
/** An empty string reads as absent, so a fallback still applies. */
|
|
13
|
+
static toText(value) {
|
|
14
|
+
return typeof value === 'string' && value !== '' ? value : undefined;
|
|
15
|
+
}
|
|
16
|
+
/**
|
|
17
|
+
* A `Content-Range` header as the IGNIS server writes it: `records 0-24/137` -> skip 0, total 137;
|
|
18
|
+
* an empty page, `records *\/137` -> total 137. Anything else, including an absent header or an
|
|
19
|
+
* unknown total, is `undefined`.
|
|
20
|
+
*/
|
|
21
|
+
static parseContentRange(opts) {
|
|
22
|
+
const { header } = opts;
|
|
23
|
+
if (!header) {
|
|
24
|
+
return undefined;
|
|
25
|
+
}
|
|
26
|
+
const range = header.match(/(\d+)\s*-\s*(\d+)\s*\/\s*(\d+)/);
|
|
27
|
+
if (range) {
|
|
28
|
+
return { skip: Number(range[1]), total: Number(range[3]) };
|
|
29
|
+
}
|
|
30
|
+
const unsatisfied = header.match(/\*\s*\/\s*(\d+)/);
|
|
31
|
+
if (unsatisfied) {
|
|
32
|
+
return { total: Number(unsatisfied[1]) };
|
|
33
|
+
}
|
|
34
|
+
return undefined;
|
|
35
|
+
}
|
|
36
|
+
/**
|
|
37
|
+
* The IGNIS error envelope - `{ message, statusCode, normalized: { text, code, args }, requestId,
|
|
38
|
+
* extra, details }` - read off a parsed response body. A server configured with `error.rootKey`
|
|
39
|
+
* wraps it under that key; pass the same `rootKey` to unwrap it. A body without that key, or with a
|
|
40
|
+
* non-object under it (a proxy's `{ error: 'Bad Gateway' }`), is read as it stands.
|
|
41
|
+
*
|
|
42
|
+
* A body that is not a plain object yields `{}`; any other body yields its known fields, each
|
|
43
|
+
* `undefined` when absent or mistyped. An empty string reads as absent.
|
|
44
|
+
*/
|
|
45
|
+
static readErrorEnvelope(opts) {
|
|
46
|
+
const { body, rootKey } = opts;
|
|
47
|
+
const wrapped = rootKey && RecordUtility.isPlainObject(body) ? body[rootKey] : undefined;
|
|
48
|
+
const envelope = RecordUtility.isPlainObject(wrapped) ? wrapped : body;
|
|
49
|
+
if (!RecordUtility.isPlainObject(envelope)) {
|
|
50
|
+
return {};
|
|
51
|
+
}
|
|
52
|
+
const { message, statusCode, normalized, requestId, extra, details } = envelope;
|
|
53
|
+
const normalizedRecord = RecordUtility.isPlainObject(normalized) ? normalized : {};
|
|
54
|
+
const { text, code, args } = normalizedRecord;
|
|
55
|
+
return {
|
|
56
|
+
message: HttpResponseReader.toText(message),
|
|
57
|
+
statusCode: typeof statusCode === 'number' ? statusCode : undefined,
|
|
58
|
+
normalized: {
|
|
59
|
+
text: HttpResponseReader.toText(text),
|
|
60
|
+
code: HttpResponseReader.toText(code),
|
|
61
|
+
args: RecordUtility.isPlainObject(args) ? { ...args } : undefined,
|
|
62
|
+
},
|
|
63
|
+
requestId: HttpResponseReader.toText(requestId),
|
|
64
|
+
extra: RecordUtility.isPlainObject(extra) ? { ...extra } : undefined,
|
|
65
|
+
details: RecordUtility.isPlainObject(details) ? { ...details } : undefined,
|
|
66
|
+
};
|
|
67
|
+
}
|
|
68
|
+
/** A failed response's envelope. A body that is not JSON yields `{}`, and the status alone still describes it. */
|
|
69
|
+
static async readError(opts) {
|
|
70
|
+
let text;
|
|
71
|
+
try {
|
|
72
|
+
const result = await opts.response.text();
|
|
73
|
+
text = result;
|
|
74
|
+
// eslint-disable-next-line venizia/no-silent-catch -- an unreadable body is read as no text; the status alone still describes the failure
|
|
75
|
+
}
|
|
76
|
+
catch {
|
|
77
|
+
text = '';
|
|
78
|
+
}
|
|
79
|
+
let body;
|
|
80
|
+
try {
|
|
81
|
+
body = text ? JSON.parse(text) : undefined;
|
|
82
|
+
// eslint-disable-next-line venizia/no-silent-catch -- a body that is not JSON yields `{}`; the status alone still describes the failure
|
|
83
|
+
}
|
|
84
|
+
catch {
|
|
85
|
+
return {};
|
|
86
|
+
}
|
|
87
|
+
return HttpResponseReader.readErrorEnvelope({ body, rootKey: opts.rootKey });
|
|
88
|
+
}
|
|
89
|
+
/**
|
|
90
|
+
* A failed response as the error the server threw: its status, code, args and text, and its
|
|
91
|
+
* `extra` with the `requestId` added. `message` is `context` plus the server's text, for logs; without
|
|
92
|
+
* `context` it is the server's text alone (`HTTP <status>` when it sent none), for a client that shows
|
|
93
|
+
* `message` to users. `normalized.text` is the server's either way - `HTTP <status>` when none.
|
|
94
|
+
* `cause` is the server's `details.cause` - a 422's per-field issues, `{ path, message, code }`.
|
|
95
|
+
*
|
|
96
|
+
* `requestId` names the request this client made. A relaying server's `extra` carries the id of
|
|
97
|
+
* the request it made upstream: it joins `upstreamRequestIds`, nearest first, at every hop.
|
|
98
|
+
*/
|
|
99
|
+
static async toApplicationError(opts) {
|
|
100
|
+
const { response, context, rootKey } = opts;
|
|
101
|
+
const server = await HttpResponseReader.readError({ response, rootKey });
|
|
102
|
+
const serverText = server.normalized?.text ?? server.message;
|
|
103
|
+
const displayText = serverText ?? `HTTP ${response.status}`;
|
|
104
|
+
const extra = { ...server.extra };
|
|
105
|
+
if (server.requestId) {
|
|
106
|
+
const upstreamRequestId = extra.requestId;
|
|
107
|
+
extra.requestId = server.requestId;
|
|
108
|
+
if (upstreamRequestId !== undefined && upstreamRequestId !== server.requestId) {
|
|
109
|
+
const known = Array.isArray(extra.upstreamRequestIds) ? extra.upstreamRequestIds : [];
|
|
110
|
+
extra.upstreamRequestIds = [upstreamRequestId, ...known];
|
|
111
|
+
}
|
|
112
|
+
}
|
|
113
|
+
return getError({
|
|
114
|
+
statusCode: response.status,
|
|
115
|
+
message: context === undefined ? displayText : serverText ? `${context} | ${serverText}` : context,
|
|
116
|
+
messageCode: server.normalized?.code,
|
|
117
|
+
messageArgs: server.normalized?.args,
|
|
118
|
+
extra: Object.keys(extra).length > 0 ? extra : undefined,
|
|
119
|
+
cause: server.details?.cause,
|
|
120
|
+
transform: ({ message }) => ({ ...message, text: displayText }),
|
|
121
|
+
});
|
|
122
|
+
}
|
|
123
|
+
/**
|
|
124
|
+
* `toApplicationError` for a fetcher's refused answer: it reads the body the `UrlFetchError` kept (the first 64 KiB),
|
|
125
|
+
* and an error that carries none is described by its status alone.
|
|
126
|
+
*/
|
|
127
|
+
static async fromFetchError(opts) {
|
|
128
|
+
const { error, context, rootKey } = opts;
|
|
129
|
+
// A hand-built error may carry a status a `Response` refuses (below 200 or above 599, e.g. 0): that is a bad gateway.
|
|
130
|
+
const isResponseStatus = error.status >= 200 && error.status <= 599;
|
|
131
|
+
const response = error.response ??
|
|
132
|
+
new Response(null, {
|
|
133
|
+
status: isResponseStatus ? error.status : HTTP.ResultCodes.RS_5.BadGateway,
|
|
134
|
+
headers: error.headers,
|
|
135
|
+
});
|
|
136
|
+
return HttpResponseReader.toApplicationError({ response, context, rootKey });
|
|
137
|
+
}
|
|
138
|
+
/** The body as text: `''` for a 204, an empty body or no body; with `maxBytes` the read stops and fails at the cap. */
|
|
139
|
+
static async readText(opts) {
|
|
140
|
+
const { response, maxBytes } = opts;
|
|
141
|
+
if (response.status === HTTP.ResultCodes.RS_2.NoContent || response.body === null) {
|
|
142
|
+
return '';
|
|
143
|
+
}
|
|
144
|
+
return maxBytes === undefined ? response.text() : BodyLimit.readText({ response, maxBytes });
|
|
145
|
+
}
|
|
146
|
+
/**
|
|
147
|
+
* The body of a success answer, by what it says it is: `null` for a 204 or an empty body, the parsed
|
|
148
|
+
* value when the content type names JSON (`application/json`, `application/problem+json`), the text itself
|
|
149
|
+
* for any other type (`text/plain`, `text/csv`). A body that claims JSON and is not is a `502` that names
|
|
150
|
+
* `context` (where it happened, e.g. `[Client][read] 200 | /tickets`), its size and its content type; its
|
|
151
|
+
* content stays out of the message, which a relaying server may pass to its own clients.
|
|
152
|
+
*/
|
|
153
|
+
static async readBody(opts) {
|
|
154
|
+
const { response, context } = opts;
|
|
155
|
+
const text = await HttpResponseReader.readText({ response });
|
|
156
|
+
if (!text) {
|
|
157
|
+
return null;
|
|
158
|
+
}
|
|
159
|
+
if (!HttpResponseReader.JSON_CONTENT_TYPE_PATTERN.test(response.headers.get(HTTP.Headers.CONTENT_TYPE) ?? '')) {
|
|
160
|
+
return text;
|
|
161
|
+
}
|
|
162
|
+
return HttpResponseReader.parseJson({ text, response, context });
|
|
163
|
+
}
|
|
164
|
+
/**
|
|
165
|
+
* A download as a file: its `blob`, the `filename` of its `Content-Disposition` (`filename*` first) and its `contentType`.
|
|
166
|
+
* A non-2xx answer throws what `toApplicationError({ response })` throws, so an error page is never saved as a file.
|
|
167
|
+
*/
|
|
168
|
+
static async readFile(opts) {
|
|
169
|
+
const { response } = opts;
|
|
170
|
+
if (!response.ok) {
|
|
171
|
+
const result = await HttpResponseReader.toApplicationError({ response });
|
|
172
|
+
throw result;
|
|
173
|
+
}
|
|
174
|
+
const { filename } = HttpResponseReader.parseContentDisposition({
|
|
175
|
+
header: response.headers.get(HTTP.Headers.CONTENT_DISPOSITION),
|
|
176
|
+
});
|
|
177
|
+
const blob = await response.blob();
|
|
178
|
+
return {
|
|
179
|
+
blob,
|
|
180
|
+
filename,
|
|
181
|
+
contentType: response.headers.get(HTTP.Headers.CONTENT_TYPE) ?? undefined,
|
|
182
|
+
};
|
|
183
|
+
}
|
|
184
|
+
/**
|
|
185
|
+
* The body as JSON whatever its content type says, `null` for a 204 or an empty body: for a route that
|
|
186
|
+
* answers JSON under a type a proxy rewrote. Errors as `readBody` does.
|
|
187
|
+
*/
|
|
188
|
+
static async readJson(opts) {
|
|
189
|
+
const { response, context } = opts;
|
|
190
|
+
const text = await HttpResponseReader.readText({ response });
|
|
191
|
+
if (!text) {
|
|
192
|
+
return null;
|
|
193
|
+
}
|
|
194
|
+
return HttpResponseReader.parseJson({ text, response, context });
|
|
195
|
+
}
|
|
196
|
+
static parseJson(opts) {
|
|
197
|
+
const { text, response, context } = opts;
|
|
198
|
+
try {
|
|
199
|
+
return JSON.parse(text);
|
|
200
|
+
}
|
|
201
|
+
catch {
|
|
202
|
+
const contentType = response.headers.get(HTTP.Headers.CONTENT_TYPE) ?? 'none';
|
|
203
|
+
throw getError({
|
|
204
|
+
statusCode: HTTP.ResultCodes.RS_5.BadGateway,
|
|
205
|
+
message: `${context} | The response body is not JSON (${text.length} chars, content-type: ${contentType})`,
|
|
206
|
+
});
|
|
207
|
+
}
|
|
208
|
+
}
|
|
209
|
+
/**
|
|
210
|
+
* A body the server marked with `x-response-extra` carries `extra` beside its rows. `body` is what
|
|
211
|
+
* the route answers without extras: the `{ count, data }` envelope when the count was asked for in
|
|
212
|
+
* the body, the rows otherwise. Any other body is returned as it stands - an unmarked object is
|
|
213
|
+
* never unwrapped, so a row that has `data` and `extra` columns of its own is never misread.
|
|
214
|
+
*/
|
|
215
|
+
static readExtra(opts) {
|
|
216
|
+
const { body, headers } = opts;
|
|
217
|
+
const isMarked = headers.has(HTTP.Headers.RESPONSE_EXTRA);
|
|
218
|
+
if (!isMarked ||
|
|
219
|
+
!RecordUtility.isPlainObject(body) ||
|
|
220
|
+
!RecordUtility.isPlainObject(body.extra)) {
|
|
221
|
+
return { body };
|
|
222
|
+
}
|
|
223
|
+
const { extra, ...envelope } = body;
|
|
224
|
+
return { body: 'count' in envelope ? envelope : envelope.data, extra: { ...extra } };
|
|
225
|
+
}
|
|
226
|
+
/**
|
|
227
|
+
* Reads a filename out of a `Content-Disposition` value.
|
|
228
|
+
*
|
|
229
|
+
* Three forms, in the order the RFC gives them precedence: `filename*=UTF-8''...` (percent-encoded,
|
|
230
|
+
* and the one hand-rolled parsers miss), a quoted `filename="..."`, and a bare `filename=...`.
|
|
231
|
+
* Splitting on `filename=` alone returns the percent-encoded bytes for any non-ASCII name, which in
|
|
232
|
+
* a product with non-English filenames is most of them.
|
|
233
|
+
*
|
|
234
|
+
* The pair of `RequestUtility.buildContentDispositionHeader`: one writes the header, this one reads it.
|
|
235
|
+
*/
|
|
236
|
+
static parseContentDisposition(opts) {
|
|
237
|
+
const { header } = opts;
|
|
238
|
+
if (!header) {
|
|
239
|
+
return {};
|
|
240
|
+
}
|
|
241
|
+
const type = header.split(';')[0]?.trim() || undefined;
|
|
242
|
+
// `filename*` wins when both are present - it is the one that can carry a non-ASCII name.
|
|
243
|
+
const extended = header.match(/filename\*\s*=\s*([^;]+)/i);
|
|
244
|
+
if (extended) {
|
|
245
|
+
const value = extended[1].trim();
|
|
246
|
+
// `UTF-8''name` or `UTF-8'lang'name`; anything before the last quote is charset and language.
|
|
247
|
+
const encoded = value.slice(value.lastIndexOf("'") + 1);
|
|
248
|
+
try {
|
|
249
|
+
return { type, filename: decodeURIComponent(encoded) };
|
|
250
|
+
// eslint-disable-next-line venizia/no-silent-catch -- a malformed `filename*` falls through to the plain `filename` parameter; only the extended name is lost
|
|
251
|
+
}
|
|
252
|
+
catch {
|
|
253
|
+
// A malformed sequence is not worth failing a download over - fall through to `filename`.
|
|
254
|
+
}
|
|
255
|
+
}
|
|
256
|
+
const quoted = header.match(/filename\s*=\s*"([^"]*)"/i);
|
|
257
|
+
if (quoted) {
|
|
258
|
+
return { type, filename: quoted[1] };
|
|
259
|
+
}
|
|
260
|
+
const bare = header.match(/filename\s*=\s*([^;]+)/i);
|
|
261
|
+
return { type, filename: bare ? bare[1].trim() : undefined };
|
|
262
|
+
}
|
|
263
|
+
}
|
|
264
|
+
//# sourceMappingURL=response-reader.js.map
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"response-reader.js","sourceRoot":"","sources":["../../../../../../../src/modules/network/http-request/fetcher/common/response-reader.ts"],"names":[],"mappings":"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","sourcesContent":["import { HTTP } from '@/common/constants/http';\nimport type { TJsonValue } from '@/common/types';\nimport { getError } from '@/modules/error';\nimport type { ApplicationError, TResponsedError } from '@/modules/error';\nimport type { UrlFetchError } from '@/modules/network/utilities/url-safety/common/errors';\nimport { RecordUtility } from '@/utilities/record.utility';\nimport { BodyLimit } from './body-limit';\n\n/**\n * What an IGNIS server answers - `Content-Range`, the error envelope - read once, here, for every\n * client of that server: the http connector, and a client that reads it without the connector.\n */\nexport class HttpResponseReader {\n /** A content type that names JSON: `application/json`, `application/problem+json`, `application/ld+json`. */\n static readonly JSON_CONTENT_TYPE_PATTERN = /json/i;\n\n /** An empty string reads as absent, so a fallback still applies. */\n private static toText(value: unknown): string | undefined {\n return typeof value === 'string' && value !== '' ? value : undefined;\n }\n\n /**\n * A `Content-Range` header as the IGNIS server writes it: `records 0-24/137` -> skip 0, total 137;\n * an empty page, `records *\\/137` -> total 137. Anything else, including an absent header or an\n * unknown total, is `undefined`.\n */\n static parseContentRange(opts: {\n header?: string | null;\n }): { skip?: number; total: number } | undefined {\n const { header } = opts;\n\n if (!header) {\n return undefined;\n }\n\n const range = header.match(/(\\d+)\\s*-\\s*(\\d+)\\s*\\/\\s*(\\d+)/);\n\n if (range) {\n return { skip: Number(range[1]), total: Number(range[3]) };\n }\n\n const unsatisfied = header.match(/\\*\\s*\\/\\s*(\\d+)/);\n\n if (unsatisfied) {\n return { total: Number(unsatisfied[1]) };\n }\n\n return undefined;\n }\n\n /**\n * The IGNIS error envelope - `{ message, statusCode, normalized: { text, code, args }, requestId,\n * extra, details }` - read off a parsed response body. A server configured with `error.rootKey`\n * wraps it under that key; pass the same `rootKey` to unwrap it. A body without that key, or with a\n * non-object under it (a proxy's `{ error: 'Bad Gateway' }`), is read as it stands.\n *\n * A body that is not a plain object yields `{}`; any other body yields its known fields, each\n * `undefined` when absent or mistyped. An empty string reads as absent.\n */\n static readErrorEnvelope(opts: { body: unknown; rootKey?: string }): TResponsedError {\n const { body, rootKey } = opts;\n\n const wrapped = rootKey && RecordUtility.isPlainObject(body) ? body[rootKey] : undefined;\n const envelope = RecordUtility.isPlainObject(wrapped) ? wrapped : body;\n\n if (!RecordUtility.isPlainObject(envelope)) {\n return {};\n }\n\n const { message, statusCode, normalized, requestId, extra, details } = envelope;\n const normalizedRecord = RecordUtility.isPlainObject(normalized) ? normalized : {};\n const { text, code, args } = normalizedRecord;\n\n return {\n message: HttpResponseReader.toText(message),\n statusCode: typeof statusCode === 'number' ? statusCode : undefined,\n normalized: {\n text: HttpResponseReader.toText(text),\n code: HttpResponseReader.toText(code),\n args: RecordUtility.isPlainObject(args) ? { ...args } : undefined,\n },\n requestId: HttpResponseReader.toText(requestId),\n extra: RecordUtility.isPlainObject(extra) ? { ...extra } : undefined,\n details: RecordUtility.isPlainObject(details) ? { ...details } : undefined,\n };\n }\n\n /** A failed response's envelope. A body that is not JSON yields `{}`, and the status alone still describes it. */\n static async readError(opts: { response: Response; rootKey?: string }): Promise<TResponsedError> {\n let text;\n\n try {\n const result = await opts.response.text();\n text = result;\n // eslint-disable-next-line venizia/no-silent-catch -- an unreadable body is read as no text; the status alone still describes the failure\n } catch {\n text = '';\n }\n\n let body: unknown;\n\n try {\n body = text ? JSON.parse(text) : undefined;\n // eslint-disable-next-line venizia/no-silent-catch -- a body that is not JSON yields `{}`; the status alone still describes the failure\n } catch {\n return {};\n }\n\n return HttpResponseReader.readErrorEnvelope({ body, rootKey: opts.rootKey });\n }\n\n /**\n * A failed response as the error the server threw: its status, code, args and text, and its\n * `extra` with the `requestId` added. `message` is `context` plus the server's text, for logs; without\n * `context` it is the server's text alone (`HTTP <status>` when it sent none), for a client that shows\n * `message` to users. `normalized.text` is the server's either way - `HTTP <status>` when none.\n * `cause` is the server's `details.cause` - a 422's per-field issues, `{ path, message, code }`.\n *\n * `requestId` names the request this client made. A relaying server's `extra` carries the id of\n * the request it made upstream: it joins `upstreamRequestIds`, nearest first, at every hop.\n */\n static async toApplicationError(opts: {\n response: Response;\n /** Where it failed, for logs - e.g. `[HttpDataSource][read] 404 | /tickets`. Left out, `message` is the server's text. */\n context?: string;\n rootKey?: string;\n }): Promise<ApplicationError> {\n const { response, context, rootKey } = opts;\n const server = await HttpResponseReader.readError({ response, rootKey });\n const serverText = server.normalized?.text ?? server.message;\n const displayText = serverText ?? `HTTP ${response.status}`;\n\n const extra: Record<string, unknown> = { ...server.extra };\n\n if (server.requestId) {\n const upstreamRequestId = extra.requestId;\n extra.requestId = server.requestId;\n\n if (upstreamRequestId !== undefined && upstreamRequestId !== server.requestId) {\n const known = Array.isArray(extra.upstreamRequestIds) ? extra.upstreamRequestIds : [];\n extra.upstreamRequestIds = [upstreamRequestId, ...known];\n }\n }\n\n return getError({\n statusCode: response.status,\n message:\n context === undefined ? displayText : serverText ? `${context} | ${serverText}` : context,\n messageCode: server.normalized?.code,\n messageArgs: server.normalized?.args,\n extra: Object.keys(extra).length > 0 ? extra : undefined,\n cause: server.details?.cause,\n transform: ({ message }) => ({ ...message, text: displayText }),\n });\n }\n\n /**\n * `toApplicationError` for a fetcher's refused answer: it reads the body the `UrlFetchError` kept (the first 64 KiB),\n * and an error that carries none is described by its status alone.\n */\n static async fromFetchError(opts: {\n error: UrlFetchError<Response>;\n context?: string;\n rootKey?: string;\n }): Promise<ApplicationError> {\n const { error, context, rootKey } = opts;\n // A hand-built error may carry a status a `Response` refuses (below 200 or above 599, e.g. 0): that is a bad gateway.\n const isResponseStatus = error.status >= 200 && error.status <= 599;\n const response =\n error.response ??\n new Response(null, {\n status: isResponseStatus ? error.status : HTTP.ResultCodes.RS_5.BadGateway,\n headers: error.headers,\n });\n\n return HttpResponseReader.toApplicationError({ response, context, rootKey });\n }\n\n /** The body as text: `''` for a 204, an empty body or no body; with `maxBytes` the read stops and fails at the cap. */\n static async readText(opts: { response: Response; maxBytes?: number }): Promise<string> {\n const { response, maxBytes } = opts;\n\n if (response.status === HTTP.ResultCodes.RS_2.NoContent || response.body === null) {\n return '';\n }\n\n return maxBytes === undefined ? response.text() : BodyLimit.readText({ response, maxBytes });\n }\n\n /**\n * The body of a success answer, by what it says it is: `null` for a 204 or an empty body, the parsed\n * value when the content type names JSON (`application/json`, `application/problem+json`), the text itself\n * for any other type (`text/plain`, `text/csv`). A body that claims JSON and is not is a `502` that names\n * `context` (where it happened, e.g. `[Client][read] 200 | /tickets`), its size and its content type; its\n * content stays out of the message, which a relaying server may pass to its own clients.\n */\n static async readBody(opts: { response: Response; context: string }): Promise<TJsonValue> {\n const { response, context } = opts;\n const text = await HttpResponseReader.readText({ response });\n\n if (!text) {\n return null;\n }\n\n if (\n !HttpResponseReader.JSON_CONTENT_TYPE_PATTERN.test(\n response.headers.get(HTTP.Headers.CONTENT_TYPE) ?? '',\n )\n ) {\n return text;\n }\n\n return HttpResponseReader.parseJson({ text, response, context });\n }\n\n /**\n * A download as a file: its `blob`, the `filename` of its `Content-Disposition` (`filename*` first) and its `contentType`.\n * A non-2xx answer throws what `toApplicationError({ response })` throws, so an error page is never saved as a file.\n */\n static async readFile(opts: {\n response: Response;\n }): Promise<{ blob: Blob; filename?: string; contentType?: string }> {\n const { response } = opts;\n\n if (!response.ok) {\n const result = await HttpResponseReader.toApplicationError({ response });\n throw result;\n }\n\n const { filename } = HttpResponseReader.parseContentDisposition({\n header: response.headers.get(HTTP.Headers.CONTENT_DISPOSITION),\n });\n\n const blob = await response.blob();\n\n return {\n blob,\n filename,\n contentType: response.headers.get(HTTP.Headers.CONTENT_TYPE) ?? undefined,\n };\n }\n\n /**\n * The body as JSON whatever its content type says, `null` for a 204 or an empty body: for a route that\n * answers JSON under a type a proxy rewrote. Errors as `readBody` does.\n */\n static async readJson(opts: { response: Response; context: string }): Promise<TJsonValue> {\n const { response, context } = opts;\n const text = await HttpResponseReader.readText({ response });\n\n if (!text) {\n return null;\n }\n\n return HttpResponseReader.parseJson({ text, response, context });\n }\n\n private static parseJson(opts: {\n text: string;\n response: Response;\n context: string;\n }): TJsonValue {\n const { text, response, context } = opts;\n\n try {\n return JSON.parse(text);\n } catch {\n const contentType = response.headers.get(HTTP.Headers.CONTENT_TYPE) ?? 'none';\n\n throw getError({\n statusCode: HTTP.ResultCodes.RS_5.BadGateway,\n message: `${context} | The response body is not JSON (${text.length} chars, content-type: ${contentType})`,\n });\n }\n }\n\n /**\n * A body the server marked with `x-response-extra` carries `extra` beside its rows. `body` is what\n * the route answers without extras: the `{ count, data }` envelope when the count was asked for in\n * the body, the rows otherwise. Any other body is returned as it stands - an unmarked object is\n * never unwrapped, so a row that has `data` and `extra` columns of its own is never misread.\n */\n static readExtra(opts: { body: unknown; headers: Pick<Headers, 'has'> }): {\n body: unknown;\n extra?: Record<string, unknown>;\n } {\n const { body, headers } = opts;\n const isMarked = headers.has(HTTP.Headers.RESPONSE_EXTRA);\n\n if (\n !isMarked ||\n !RecordUtility.isPlainObject(body) ||\n !RecordUtility.isPlainObject(body.extra)\n ) {\n return { body };\n }\n\n const { extra, ...envelope } = body;\n\n return { body: 'count' in envelope ? envelope : envelope.data, extra: { ...extra } };\n }\n\n /**\n * Reads a filename out of a `Content-Disposition` value.\n *\n * Three forms, in the order the RFC gives them precedence: `filename*=UTF-8''...` (percent-encoded,\n * and the one hand-rolled parsers miss), a quoted `filename=\"...\"`, and a bare `filename=...`.\n * Splitting on `filename=` alone returns the percent-encoded bytes for any non-ASCII name, which in\n * a product with non-English filenames is most of them.\n *\n * The pair of `RequestUtility.buildContentDispositionHeader`: one writes the header, this one reads it.\n */\n static parseContentDisposition(opts: { header: string | null | undefined }): {\n type?: string;\n filename?: string;\n } {\n const { header } = opts;\n\n if (!header) {\n return {};\n }\n\n const type = header.split(';')[0]?.trim() || undefined;\n\n // `filename*` wins when both are present - it is the one that can carry a non-ASCII name.\n const extended = header.match(/filename\\*\\s*=\\s*([^;]+)/i);\n\n if (extended) {\n const value = extended[1].trim();\n // `UTF-8''name` or `UTF-8'lang'name`; anything before the last quote is charset and language.\n const encoded = value.slice(value.lastIndexOf(\"'\") + 1);\n\n try {\n return { type, filename: decodeURIComponent(encoded) };\n // eslint-disable-next-line venizia/no-silent-catch -- a malformed `filename*` falls through to the plain `filename` parameter; only the extended name is lost\n } catch {\n // A malformed sequence is not worth failing a download over - fall through to `filename`.\n }\n }\n\n const quoted = header.match(/filename\\s*=\\s*\"([^\"]*)\"/i);\n\n if (quoted) {\n return { type, filename: quoted[1] };\n }\n\n const bare = header.match(/filename\\s*=\\s*([^;]+)/i);\n\n return { type, filename: bare ? bare[1].trim() : undefined };\n }\n}\n"]}
|
|
@@ -1,5 +1,69 @@
|
|
|
1
|
+
import type { ValueOrPromise } from '../../../../../common/index.js';
|
|
2
|
+
import type { IRetryBackoffOptions, IRetryContext } from '../../../../retry/common/types.js';
|
|
3
|
+
import type { IUrlSafetyPolicy } from '../../../utilities/url-safety/common/types.js';
|
|
1
4
|
import type { AxiosInstance, AxiosResponse } from 'axios';
|
|
2
5
|
import type { TFetcherVariant } from '../../common/index.js';
|
|
3
|
-
|
|
6
|
+
/** What a fetcher of this variant answers: a `Response` for `'native'`, an `AxiosResponse` for `'axios'`. */
|
|
7
|
+
export type TFetcherResponse<T extends TFetcherVariant> = T extends 'native' ? Response : AxiosResponse<unknown>;
|
|
8
|
+
/** The client a fetcher of this variant wraps (`getWorker()`): `fetch` or an axios instance. */
|
|
4
9
|
export type TFetcherWorker<T extends TFetcherVariant> = T extends 'axios' ? AxiosInstance : typeof fetch;
|
|
10
|
+
/** A header map as a call or a default writes it: a `Headers`, `[name, value]` pairs or a record. In a record a `null` or `undefined` value removes that header (a default included); a number is sent as text. */
|
|
11
|
+
export type THttpHeaders = Headers | Array<[string, string]> | Record<string, string | number | null | undefined>;
|
|
12
|
+
/** What a fetcher answers when the call passes a `schema`: the parsed body beside the raw response. */
|
|
13
|
+
export interface IFetchParsed<D, RS> {
|
|
14
|
+
data: D;
|
|
15
|
+
status: number;
|
|
16
|
+
headers: Headers;
|
|
17
|
+
response: RS;
|
|
18
|
+
}
|
|
19
|
+
/** Retry settings of a call; the presence of the object turns retrying on. They are `RetryHelper.executeWithRetry`'s. */
|
|
20
|
+
export interface IHttpRetryOptions {
|
|
21
|
+
/** @default 3 */
|
|
22
|
+
maxAttempts?: number;
|
|
23
|
+
/** The budget across every attempt and wait, in milliseconds; a `Retry-After` that does not fit ends the retries. */
|
|
24
|
+
maxTotalMs?: number;
|
|
25
|
+
backoff?: IRetryBackoffOptions;
|
|
26
|
+
/** Replaces the default decision (network error, timeout, 5xx and 429 retry; any other 4xx, a 3xx, a guard refusal, a schema mismatch and a caller abort do not). */
|
|
27
|
+
shouldRetry?: (context: IRetryContext) => ValueOrPromise<boolean>;
|
|
28
|
+
onRetry?: (context: IRetryContext & {
|
|
29
|
+
nextDelayMs: number;
|
|
30
|
+
}) => ValueOrPromise<void>;
|
|
31
|
+
}
|
|
32
|
+
/** What a fetcher applies to every call unless the call says otherwise. */
|
|
33
|
+
export interface IFetcherDefaults {
|
|
34
|
+
/** Per attempt, in milliseconds. */
|
|
35
|
+
timeout?: number;
|
|
36
|
+
headers?: THttpHeaders;
|
|
37
|
+
retry?: IHttpRetryOptions;
|
|
38
|
+
maxBytes?: number;
|
|
39
|
+
/** A call may replace this policy with its own; it cannot switch the guard off. */
|
|
40
|
+
guard?: IUrlSafetyPolicy;
|
|
41
|
+
}
|
|
42
|
+
/** The request a hook sees. The url is read-only: a hook cannot send the call elsewhere, so the guard vets what is sent. */
|
|
43
|
+
export interface IFetchRequestContext {
|
|
44
|
+
readonly method: string;
|
|
45
|
+
readonly url: string;
|
|
46
|
+
/** Mutable: `onRequest` signs or stamps the request here. */
|
|
47
|
+
readonly headers: Headers;
|
|
48
|
+
/** 1 for the first attempt, then one more per retry. */
|
|
49
|
+
readonly attempt: number;
|
|
50
|
+
}
|
|
51
|
+
/** One function per moment; none returns a value. */
|
|
52
|
+
export interface IFetcherHooks {
|
|
53
|
+
/** Before EVERY send, each retry attempt included, so a signature is fresh. */
|
|
54
|
+
onRequest?: (context: IFetchRequestContext) => ValueOrPromise<void>;
|
|
55
|
+
/** An answer arrived, BEFORE the status check and the schema parse. Once per attempt. */
|
|
56
|
+
onResponse?: (context: {
|
|
57
|
+
request: IFetchRequestContext;
|
|
58
|
+
status: number;
|
|
59
|
+
headers: Headers;
|
|
60
|
+
durationMs: number;
|
|
61
|
+
}) => ValueOrPromise<void>;
|
|
62
|
+
/** The call failed (a timeout, the network, a refused status, a schema mismatch, a guard refusal); once, with the final error, which is then rethrown. */
|
|
63
|
+
onError?: (context: {
|
|
64
|
+
request: IFetchRequestContext;
|
|
65
|
+
error: unknown;
|
|
66
|
+
attempt: number;
|
|
67
|
+
}) => ValueOrPromise<void>;
|
|
68
|
+
}
|
|
5
69
|
//# sourceMappingURL=types.d.ts.map
|
|
@@ -1 +1 @@
|
|
|
1
|
-
{"version":3,"file":"types.js","sourceRoot":"","sources":["../../../../../../../src/modules/network/http-request/fetcher/common/types.ts"],"names":[],"mappings":"","sourcesContent":["import type { AxiosInstance, AxiosResponse } from 'axios';\nimport type { TFetcherVariant } from '../../common';\n\nexport type TFetcherResponse<T extends TFetcherVariant> = T extends '
|
|
1
|
+
{"version":3,"file":"types.js","sourceRoot":"","sources":["../../../../../../../src/modules/network/http-request/fetcher/common/types.ts"],"names":[],"mappings":"","sourcesContent":["import type { ValueOrPromise } from '@/common';\nimport type { IRetryBackoffOptions, IRetryContext } from '@/modules/retry/common/types';\nimport type { IUrlSafetyPolicy } from '@/modules/network/utilities/url-safety/common/types';\nimport type { AxiosInstance, AxiosResponse } from 'axios';\nimport type { TFetcherVariant } from '../../common';\n\n/** What a fetcher of this variant answers: a `Response` for `'native'`, an `AxiosResponse` for `'axios'`. */\nexport type TFetcherResponse<T extends TFetcherVariant> = T extends 'native'\n ? Response\n : AxiosResponse<unknown>;\n\n/** The client a fetcher of this variant wraps (`getWorker()`): `fetch` or an axios instance. */\nexport type TFetcherWorker<T extends TFetcherVariant> = T extends 'axios'\n ? AxiosInstance\n : typeof fetch;\n\n/** A header map as a call or a default writes it: a `Headers`, `[name, value]` pairs or a record. In a record a `null` or `undefined` value removes that header (a default included); a number is sent as text. */\nexport type THttpHeaders =\n | Headers\n | Array<[string, string]>\n | Record<string, string | number | null | undefined>;\n\n/** What a fetcher answers when the call passes a `schema`: the parsed body beside the raw response. */\nexport interface IFetchParsed<D, RS> {\n data: D;\n status: number;\n headers: Headers;\n response: RS;\n}\n\n/** Retry settings of a call; the presence of the object turns retrying on. They are `RetryHelper.executeWithRetry`'s. */\nexport interface IHttpRetryOptions {\n /** @default 3 */\n maxAttempts?: number;\n /** The budget across every attempt and wait, in milliseconds; a `Retry-After` that does not fit ends the retries. */\n maxTotalMs?: number;\n backoff?: IRetryBackoffOptions;\n /** Replaces the default decision (network error, timeout, 5xx and 429 retry; any other 4xx, a 3xx, a guard refusal, a schema mismatch and a caller abort do not). */\n shouldRetry?: (context: IRetryContext) => ValueOrPromise<boolean>;\n onRetry?: (context: IRetryContext & { nextDelayMs: number }) => ValueOrPromise<void>;\n}\n\n/** What a fetcher applies to every call unless the call says otherwise. */\nexport interface IFetcherDefaults {\n /** Per attempt, in milliseconds. */\n timeout?: number;\n headers?: THttpHeaders;\n retry?: IHttpRetryOptions;\n maxBytes?: number;\n /** A call may replace this policy with its own; it cannot switch the guard off. */\n guard?: IUrlSafetyPolicy;\n}\n\n/** The request a hook sees. The url is read-only: a hook cannot send the call elsewhere, so the guard vets what is sent. */\nexport interface IFetchRequestContext {\n readonly method: string;\n readonly url: string;\n /** Mutable: `onRequest` signs or stamps the request here. */\n readonly headers: Headers;\n /** 1 for the first attempt, then one more per retry. */\n readonly attempt: number;\n}\n\n/** One function per moment; none returns a value. */\nexport interface IFetcherHooks {\n /** Before EVERY send, each retry attempt included, so a signature is fresh. */\n onRequest?: (context: IFetchRequestContext) => ValueOrPromise<void>;\n /** An answer arrived, BEFORE the status check and the schema parse. Once per attempt. */\n onResponse?: (context: {\n request: IFetchRequestContext;\n status: number;\n headers: Headers;\n durationMs: number;\n }) => ValueOrPromise<void>;\n /** The call failed (a timeout, the network, a refused status, a schema mismatch, a guard refusal); once, with the final error, which is then rethrown. */\n onError?: (context: {\n request: IFetchRequestContext;\n error: unknown;\n attempt: number;\n }) => ValueOrPromise<void>;\n}\n"]}
|
|
@@ -0,0 +1,68 @@
|
|
|
1
|
+
import type { THttpHeaders } from './types.js';
|
|
2
|
+
/** Header maps: merged per header, the call winning, a `null` or `undefined` value removing a header. */
|
|
3
|
+
export declare class HttpHeaders {
|
|
4
|
+
/** The headers of `layers` in order, later layers over earlier ones, as one `Headers`. */
|
|
5
|
+
static merge(opts: {
|
|
6
|
+
layers: ReadonlyArray<THttpHeaders | undefined>;
|
|
7
|
+
}): Headers;
|
|
8
|
+
/** `merge` under a JSON content type: the layers may replace it (any case) or remove it with `null`. */
|
|
9
|
+
static withJsonDefault(opts: {
|
|
10
|
+
layers: ReadonlyArray<THttpHeaders | undefined>;
|
|
11
|
+
}): Headers;
|
|
12
|
+
/** A copy of `headers` keeping only the names in `names`. */
|
|
13
|
+
static only(opts: {
|
|
14
|
+
headers: Headers;
|
|
15
|
+
names: ReadonlyArray<string>;
|
|
16
|
+
}): Headers;
|
|
17
|
+
/** A copy of `headers` without the names in `names`. */
|
|
18
|
+
static without(opts: {
|
|
19
|
+
headers: Headers;
|
|
20
|
+
names: ReadonlyArray<string>;
|
|
21
|
+
}): Headers;
|
|
22
|
+
}
|
|
23
|
+
/** Which statuses a fetcher takes as an answer. */
|
|
24
|
+
export declare class HttpStatus {
|
|
25
|
+
/** Whether `status` is 2xx. */
|
|
26
|
+
private static isSuccess;
|
|
27
|
+
/** The one place `acceptStatus` becomes a decision: a list adds to 2xx, a function replaces it, unset is 2xx. */
|
|
28
|
+
static toPredicate(opts: {
|
|
29
|
+
accept: ReadonlyArray<number> | ((status: number) => boolean) | undefined;
|
|
30
|
+
}): (status: number) => boolean;
|
|
31
|
+
}
|
|
32
|
+
/** The redirect rules of a fetcher that walks redirects by hand. */
|
|
33
|
+
export declare class HttpRedirects {
|
|
34
|
+
/** Request headers that name the body; they go when a redirect turns the request into a GET. */
|
|
35
|
+
static readonly BODY_HEADERS: ReadonlyArray<string>;
|
|
36
|
+
/**
|
|
37
|
+
* The only caller headers a cross-origin redirect keeps. Every other one is dropped: a tenant's webhook secret
|
|
38
|
+
* (`x-api-key`, a signature) must not follow a redirect to a host that tenant did not name.
|
|
39
|
+
*/
|
|
40
|
+
static readonly CROSS_ORIGIN_HEADERS: ReadonlyArray<string>;
|
|
41
|
+
static isRedirect(opts: {
|
|
42
|
+
status: number;
|
|
43
|
+
}): boolean;
|
|
44
|
+
/** 303, and a POST answered 301 or 302, continue as a GET without the body. */
|
|
45
|
+
static becomesGet(opts: {
|
|
46
|
+
status: number;
|
|
47
|
+
method: string;
|
|
48
|
+
}): boolean;
|
|
49
|
+
}
|
|
50
|
+
/** What a retried call retries, and for how long a server asks it to wait. */
|
|
51
|
+
export declare class HttpRetry {
|
|
52
|
+
/** The longest wait a call takes between two attempts unless `backoff.maxDelayMs` says otherwise; the retry helper's own default. */
|
|
53
|
+
static readonly DEFAULT_MAX_DELAY_MS = 30000;
|
|
54
|
+
/**
|
|
55
|
+
* The default decision: a network error, a timeout, a 5xx and a 429 are worth another attempt. Any other 4xx, a 3xx, a
|
|
56
|
+
* url the guard refused (refused forever), a schema mismatch and a caller's own abort are not.
|
|
57
|
+
*/
|
|
58
|
+
static isRetryable(opts: {
|
|
59
|
+
error: unknown;
|
|
60
|
+
signal?: AbortSignal;
|
|
61
|
+
}): boolean;
|
|
62
|
+
/** The wait a 429 or 503 asks for in `Retry-After`, in milliseconds: seconds, or an HTTP date. `undefined` when there is none. */
|
|
63
|
+
static readRetryAfterMs(opts: {
|
|
64
|
+
error: unknown;
|
|
65
|
+
now?: number;
|
|
66
|
+
}): number | undefined;
|
|
67
|
+
}
|
|
68
|
+
//# sourceMappingURL=utilities.d.ts.map
|
|
@@ -0,0 +1,143 @@
|
|
|
1
|
+
import { HTTP } from '../../../../../common/constants/http.js';
|
|
2
|
+
import { UrlFetchError, UrlSafetyRefusals, } from '../../../utilities/url-safety/common/errors.js';
|
|
3
|
+
import { FetchSchemaError } from './errors.js';
|
|
4
|
+
/** Header maps: merged per header, the call winning, a `null` or `undefined` value removing a header. */
|
|
5
|
+
export class HttpHeaders {
|
|
6
|
+
/** The headers of `layers` in order, later layers over earlier ones, as one `Headers`. */
|
|
7
|
+
static merge(opts) {
|
|
8
|
+
const merged = new Headers();
|
|
9
|
+
for (const layer of opts.layers) {
|
|
10
|
+
if (layer === undefined) {
|
|
11
|
+
continue;
|
|
12
|
+
}
|
|
13
|
+
if (layer instanceof Headers) {
|
|
14
|
+
layer.forEach((value, name) => merged.set(name, value));
|
|
15
|
+
continue;
|
|
16
|
+
}
|
|
17
|
+
for (const [name, value] of Array.isArray(layer) ? layer : Object.entries(layer)) {
|
|
18
|
+
if (value === null || value === undefined) {
|
|
19
|
+
merged.delete(name);
|
|
20
|
+
}
|
|
21
|
+
else {
|
|
22
|
+
merged.set(name, String(value));
|
|
23
|
+
}
|
|
24
|
+
}
|
|
25
|
+
}
|
|
26
|
+
return merged;
|
|
27
|
+
}
|
|
28
|
+
/** `merge` under a JSON content type: the layers may replace it (any case) or remove it with `null`. */
|
|
29
|
+
static withJsonDefault(opts) {
|
|
30
|
+
return HttpHeaders.merge({
|
|
31
|
+
layers: [
|
|
32
|
+
{ [HTTP.Headers.CONTENT_TYPE]: HTTP.HeaderValues.APPLICATION_JSON_UTF8 },
|
|
33
|
+
...opts.layers,
|
|
34
|
+
],
|
|
35
|
+
});
|
|
36
|
+
}
|
|
37
|
+
/** A copy of `headers` keeping only the names in `names`. */
|
|
38
|
+
static only(opts) {
|
|
39
|
+
const kept = new Headers();
|
|
40
|
+
opts.headers.forEach((value, name) => {
|
|
41
|
+
if (opts.names.includes(name.toLowerCase())) {
|
|
42
|
+
kept.set(name, value);
|
|
43
|
+
}
|
|
44
|
+
});
|
|
45
|
+
return kept;
|
|
46
|
+
}
|
|
47
|
+
/** A copy of `headers` without the names in `names`. */
|
|
48
|
+
static without(opts) {
|
|
49
|
+
const kept = new Headers();
|
|
50
|
+
opts.headers.forEach((value, name) => {
|
|
51
|
+
if (!opts.names.includes(name.toLowerCase())) {
|
|
52
|
+
kept.set(name, value);
|
|
53
|
+
}
|
|
54
|
+
});
|
|
55
|
+
return kept;
|
|
56
|
+
}
|
|
57
|
+
}
|
|
58
|
+
/** Which statuses a fetcher takes as an answer. */
|
|
59
|
+
export class HttpStatus {
|
|
60
|
+
/** Whether `status` is 2xx. */
|
|
61
|
+
static isSuccess(opts) {
|
|
62
|
+
return Math.floor(opts.status / 100) === 2;
|
|
63
|
+
}
|
|
64
|
+
/** The one place `acceptStatus` becomes a decision: a list adds to 2xx, a function replaces it, unset is 2xx. */
|
|
65
|
+
static toPredicate(opts) {
|
|
66
|
+
const { accept } = opts;
|
|
67
|
+
if (typeof accept === 'function') {
|
|
68
|
+
return accept;
|
|
69
|
+
}
|
|
70
|
+
const extra = new Set(accept);
|
|
71
|
+
return (status) => HttpStatus.isSuccess({ status }) || extra.has(status);
|
|
72
|
+
}
|
|
73
|
+
}
|
|
74
|
+
/** The statuses that name a new location; a 304 or a 300 is an answer, not a redirect. */
|
|
75
|
+
const REDIRECT_STATUSES = [301, 302, 303, 307, 308];
|
|
76
|
+
/** The redirect rules of a fetcher that walks redirects by hand. */
|
|
77
|
+
export class HttpRedirects {
|
|
78
|
+
/** Request headers that name the body; they go when a redirect turns the request into a GET. */
|
|
79
|
+
static { this.BODY_HEADERS = [
|
|
80
|
+
HTTP.Headers.CONTENT_TYPE,
|
|
81
|
+
HTTP.Headers.CONTENT_LENGTH,
|
|
82
|
+
HTTP.Headers.CONTENT_ENCODING,
|
|
83
|
+
]; }
|
|
84
|
+
/**
|
|
85
|
+
* The only caller headers a cross-origin redirect keeps. Every other one is dropped: a tenant's webhook secret
|
|
86
|
+
* (`x-api-key`, a signature) must not follow a redirect to a host that tenant did not name.
|
|
87
|
+
*/
|
|
88
|
+
static { this.CROSS_ORIGIN_HEADERS = [
|
|
89
|
+
HTTP.Headers.ACCEPT,
|
|
90
|
+
HTTP.Headers.ACCEPT_LANGUAGE,
|
|
91
|
+
HTTP.Headers.USER_AGENT,
|
|
92
|
+
]; }
|
|
93
|
+
static isRedirect(opts) {
|
|
94
|
+
return REDIRECT_STATUSES.includes(opts.status);
|
|
95
|
+
}
|
|
96
|
+
/** 303, and a POST answered 301 or 302, continue as a GET without the body. */
|
|
97
|
+
static becomesGet(opts) {
|
|
98
|
+
return (opts.status === 303 ||
|
|
99
|
+
((opts.status === 301 || opts.status === 302) && opts.method === 'POST'));
|
|
100
|
+
}
|
|
101
|
+
}
|
|
102
|
+
/** What a retried call retries, and for how long a server asks it to wait. */
|
|
103
|
+
export class HttpRetry {
|
|
104
|
+
/** The longest wait a call takes between two attempts unless `backoff.maxDelayMs` says otherwise; the retry helper's own default. */
|
|
105
|
+
static { this.DEFAULT_MAX_DELAY_MS = 30_000; }
|
|
106
|
+
/**
|
|
107
|
+
* The default decision: a network error, a timeout, a 5xx and a 429 are worth another attempt. Any other 4xx, a 3xx, a
|
|
108
|
+
* url the guard refused (refused forever), a schema mismatch and a caller's own abort are not.
|
|
109
|
+
*/
|
|
110
|
+
static isRetryable(opts) {
|
|
111
|
+
const { error, signal } = opts;
|
|
112
|
+
if (UrlFetchError.is(error)) {
|
|
113
|
+
return error.status >= 500 || error.status === 429;
|
|
114
|
+
}
|
|
115
|
+
if (FetchSchemaError.is(error) || UrlSafetyRefusals.is({ error })) {
|
|
116
|
+
return false;
|
|
117
|
+
}
|
|
118
|
+
// The caller's own abort ends the call; a per-attempt timeout is not the caller's and is retried.
|
|
119
|
+
return signal?.aborted !== true;
|
|
120
|
+
}
|
|
121
|
+
/** The wait a 429 or 503 asks for in `Retry-After`, in milliseconds: seconds, or an HTTP date. `undefined` when there is none. */
|
|
122
|
+
static readRetryAfterMs(opts) {
|
|
123
|
+
const { error } = opts;
|
|
124
|
+
if (!UrlFetchError.is(error) || (error.status !== 429 && error.status !== 503)) {
|
|
125
|
+
return undefined;
|
|
126
|
+
}
|
|
127
|
+
const header = error.headers.get(HTTP.Headers.RETRY_AFTER)?.trim();
|
|
128
|
+
if (!header) {
|
|
129
|
+
return undefined;
|
|
130
|
+
}
|
|
131
|
+
if (/^\d+$/.test(header)) {
|
|
132
|
+
const seconds = Number(header);
|
|
133
|
+
return Number.isSafeInteger(seconds) ? seconds * 1000 : undefined;
|
|
134
|
+
}
|
|
135
|
+
// An HTTP date has letters (`Thu, 19 Nov ...`); a bare number that is not whole seconds is garbage, not a date.
|
|
136
|
+
if (!/[a-z]/i.test(header)) {
|
|
137
|
+
return undefined;
|
|
138
|
+
}
|
|
139
|
+
const date = Date.parse(header);
|
|
140
|
+
return Number.isNaN(date) ? undefined : Math.max(0, date - (opts.now ?? Date.now()));
|
|
141
|
+
}
|
|
142
|
+
}
|
|
143
|
+
//# sourceMappingURL=utilities.js.map
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"utilities.js","sourceRoot":"","sources":["../../../../../../../src/modules/network/http-request/fetcher/common/utilities.ts"],"names":[],"mappings":"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","sourcesContent":["import { HTTP } from '@/common/constants/http';\nimport {\n UrlFetchError,\n UrlSafetyRefusals,\n} from '@/modules/network/utilities/url-safety/common/errors';\nimport { FetchSchemaError } from './errors';\nimport type { THttpHeaders } from './types';\n\n/** Header maps: merged per header, the call winning, a `null` or `undefined` value removing a header. */\nexport class HttpHeaders {\n /** The headers of `layers` in order, later layers over earlier ones, as one `Headers`. */\n static merge(opts: { layers: ReadonlyArray<THttpHeaders | undefined> }): Headers {\n const merged = new Headers();\n\n for (const layer of opts.layers) {\n if (layer === undefined) {\n continue;\n }\n\n if (layer instanceof Headers) {\n layer.forEach((value, name) => merged.set(name, value));\n continue;\n }\n\n for (const [name, value] of Array.isArray(layer) ? layer : Object.entries(layer)) {\n if (value === null || value === undefined) {\n merged.delete(name);\n } else {\n merged.set(name, String(value));\n }\n }\n }\n\n return merged;\n }\n\n /** `merge` under a JSON content type: the layers may replace it (any case) or remove it with `null`. */\n static withJsonDefault(opts: { layers: ReadonlyArray<THttpHeaders | undefined> }): Headers {\n return HttpHeaders.merge({\n layers: [\n { [HTTP.Headers.CONTENT_TYPE]: HTTP.HeaderValues.APPLICATION_JSON_UTF8 },\n ...opts.layers,\n ],\n });\n }\n\n /** A copy of `headers` keeping only the names in `names`. */\n static only(opts: { headers: Headers; names: ReadonlyArray<string> }): Headers {\n const kept = new Headers();\n\n opts.headers.forEach((value, name) => {\n if (opts.names.includes(name.toLowerCase())) {\n kept.set(name, value);\n }\n });\n\n return kept;\n }\n\n /** A copy of `headers` without the names in `names`. */\n static without(opts: { headers: Headers; names: ReadonlyArray<string> }): Headers {\n const kept = new Headers();\n\n opts.headers.forEach((value, name) => {\n if (!opts.names.includes(name.toLowerCase())) {\n kept.set(name, value);\n }\n });\n\n return kept;\n }\n}\n\n/** Which statuses a fetcher takes as an answer. */\nexport class HttpStatus {\n /** Whether `status` is 2xx. */\n private static isSuccess(opts: { status: number }): boolean {\n return Math.floor(opts.status / 100) === 2;\n }\n\n /** The one place `acceptStatus` becomes a decision: a list adds to 2xx, a function replaces it, unset is 2xx. */\n static toPredicate(opts: {\n accept: ReadonlyArray<number> | ((status: number) => boolean) | undefined;\n }): (status: number) => boolean {\n const { accept } = opts;\n\n if (typeof accept === 'function') {\n return accept;\n }\n\n const extra = new Set(accept);\n\n return (status) => HttpStatus.isSuccess({ status }) || extra.has(status);\n }\n}\n\n/** The statuses that name a new location; a 304 or a 300 is an answer, not a redirect. */\nconst REDIRECT_STATUSES: ReadonlyArray<number> = [301, 302, 303, 307, 308];\n\n/** The redirect rules of a fetcher that walks redirects by hand. */\nexport class HttpRedirects {\n /** Request headers that name the body; they go when a redirect turns the request into a GET. */\n static readonly BODY_HEADERS: ReadonlyArray<string> = [\n HTTP.Headers.CONTENT_TYPE,\n HTTP.Headers.CONTENT_LENGTH,\n HTTP.Headers.CONTENT_ENCODING,\n ];\n\n /**\n * The only caller headers a cross-origin redirect keeps. Every other one is dropped: a tenant's webhook secret\n * (`x-api-key`, a signature) must not follow a redirect to a host that tenant did not name.\n */\n static readonly CROSS_ORIGIN_HEADERS: ReadonlyArray<string> = [\n HTTP.Headers.ACCEPT,\n HTTP.Headers.ACCEPT_LANGUAGE,\n HTTP.Headers.USER_AGENT,\n ];\n\n static isRedirect(opts: { status: number }): boolean {\n return REDIRECT_STATUSES.includes(opts.status);\n }\n\n /** 303, and a POST answered 301 or 302, continue as a GET without the body. */\n static becomesGet(opts: { status: number; method: string }): boolean {\n return (\n opts.status === 303 ||\n ((opts.status === 301 || opts.status === 302) && opts.method === 'POST')\n );\n }\n}\n\n/** What a retried call retries, and for how long a server asks it to wait. */\nexport class HttpRetry {\n /** The longest wait a call takes between two attempts unless `backoff.maxDelayMs` says otherwise; the retry helper's own default. */\n static readonly DEFAULT_MAX_DELAY_MS = 30_000;\n\n /**\n * The default decision: a network error, a timeout, a 5xx and a 429 are worth another attempt. Any other 4xx, a 3xx, a\n * url the guard refused (refused forever), a schema mismatch and a caller's own abort are not.\n */\n static isRetryable(opts: { error: unknown; signal?: AbortSignal }): boolean {\n const { error, signal } = opts;\n\n if (UrlFetchError.is(error)) {\n return error.status >= 500 || error.status === 429;\n }\n\n if (FetchSchemaError.is(error) || UrlSafetyRefusals.is({ error })) {\n return false;\n }\n\n // The caller's own abort ends the call; a per-attempt timeout is not the caller's and is retried.\n return signal?.aborted !== true;\n }\n\n /** The wait a 429 or 503 asks for in `Retry-After`, in milliseconds: seconds, or an HTTP date. `undefined` when there is none. */\n static readRetryAfterMs(opts: { error: unknown; now?: number }): number | undefined {\n const { error } = opts;\n\n if (!UrlFetchError.is(error) || (error.status !== 429 && error.status !== 503)) {\n return undefined;\n }\n\n const header = error.headers.get(HTTP.Headers.RETRY_AFTER)?.trim();\n\n if (!header) {\n return undefined;\n }\n\n if (/^\\d+$/.test(header)) {\n const seconds = Number(header);\n\n return Number.isSafeInteger(seconds) ? seconds * 1000 : undefined;\n }\n\n // An HTTP date has letters (`Thu, 19 Nov ...`); a bare number that is not whole seconds is garbage, not a date.\n if (!/[a-z]/i.test(header)) {\n return undefined;\n }\n\n const date = Date.parse(header);\n\n return Number.isNaN(date) ? undefined : Math.max(0, date - (opts.now ?? Date.now()));\n }\n}\n"]}
|