@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,119 @@
|
|
|
1
|
+
import { HTTP } from '../../../../../common/constants/http.js';
|
|
2
|
+
import { getError } from '../../../../error/index.js';
|
|
3
|
+
import { UrlSafetyErrors } from '../../../utilities/url-safety/common/errors.js';
|
|
4
|
+
import { UrlSafetyDefaults } from '../../../utilities/url-safety/common/constants.js';
|
|
5
|
+
/** The largest body a call accepts when it names no `maxBytes` of its own. */
|
|
6
|
+
const DEFAULT_MAX_BYTES = UrlSafetyDefaults.MAX_BYTES;
|
|
7
|
+
/** A cap on a body, for a stream piped onward or a body read into memory. Browser-pure: streams and typed arrays only. */
|
|
8
|
+
export class BodyLimit {
|
|
9
|
+
/** The one refusal of a body over the cap; `detail` says how it was found (declared, received, a client's own words). */
|
|
10
|
+
static refuse(opts) {
|
|
11
|
+
return getError({
|
|
12
|
+
error: UrlSafetyErrors.URL_REFUSED,
|
|
13
|
+
message: `[fetch] Body exceeds the cap | ${opts.detail}`,
|
|
14
|
+
});
|
|
15
|
+
}
|
|
16
|
+
/** Enforces `maxBytes` on a stream nothing reads into this process: the cap fails the stream the moment the bytes cross it. */
|
|
17
|
+
static capStream(opts) {
|
|
18
|
+
const { source } = opts;
|
|
19
|
+
const maxBytes = opts.maxBytes ?? DEFAULT_MAX_BYTES;
|
|
20
|
+
let received = 0;
|
|
21
|
+
return source.pipeThrough(new TransformStream({
|
|
22
|
+
transform(chunk, controller) {
|
|
23
|
+
received += chunk.byteLength;
|
|
24
|
+
if (received > maxBytes) {
|
|
25
|
+
controller.error(BodyLimit.refuse({ detail: `received: ${received} | max: ${maxBytes}` }));
|
|
26
|
+
return;
|
|
27
|
+
}
|
|
28
|
+
controller.enqueue(chunk);
|
|
29
|
+
},
|
|
30
|
+
}));
|
|
31
|
+
}
|
|
32
|
+
/** The size a response declares, or `0` when it declares none or an unreadable one. */
|
|
33
|
+
static readDeclaredLength(opts) {
|
|
34
|
+
const declared = Number(opts.headers.get(HTTP.Headers.CONTENT_LENGTH) ?? 0);
|
|
35
|
+
return Number.isFinite(declared) ? declared : 0;
|
|
36
|
+
}
|
|
37
|
+
/** At most `maxBytes` of the body, then the rest released; a body that fails halfway answers what arrived. Never throws on size: a refused status must still say what it was. */
|
|
38
|
+
static async readPrefix(opts) {
|
|
39
|
+
const { response, maxBytes } = opts;
|
|
40
|
+
const reader = response.body?.getReader();
|
|
41
|
+
const chunks = [];
|
|
42
|
+
let received = 0;
|
|
43
|
+
if (!reader) {
|
|
44
|
+
return new Uint8Array();
|
|
45
|
+
}
|
|
46
|
+
try {
|
|
47
|
+
while (received < maxBytes) {
|
|
48
|
+
const { done, value } = await reader.read();
|
|
49
|
+
if (done) {
|
|
50
|
+
break;
|
|
51
|
+
}
|
|
52
|
+
chunks.push(value.subarray(0, maxBytes - received));
|
|
53
|
+
received += chunks[chunks.length - 1].length;
|
|
54
|
+
}
|
|
55
|
+
// eslint-disable-next-line venizia/no-silent-catch -- the status is the answer; a body that broke off is reported as the shorter body it was
|
|
56
|
+
}
|
|
57
|
+
catch {
|
|
58
|
+
// The chunks that arrived stand.
|
|
59
|
+
}
|
|
60
|
+
try {
|
|
61
|
+
await reader.cancel();
|
|
62
|
+
// eslint-disable-next-line venizia/no-silent-catch -- the stream is released as far as it can be; nothing is left to report
|
|
63
|
+
}
|
|
64
|
+
catch {
|
|
65
|
+
// Already closed or errored.
|
|
66
|
+
}
|
|
67
|
+
const bytes = new Uint8Array(received);
|
|
68
|
+
let offset = 0;
|
|
69
|
+
for (const chunk of chunks) {
|
|
70
|
+
bytes.set(chunk, offset);
|
|
71
|
+
offset += chunk.length;
|
|
72
|
+
}
|
|
73
|
+
return bytes;
|
|
74
|
+
}
|
|
75
|
+
/** `readBytes`, decoded as UTF-8 text. */
|
|
76
|
+
static async readText(opts) {
|
|
77
|
+
const bytes = await BodyLimit.readBytes(opts);
|
|
78
|
+
return new TextDecoder().decode(bytes);
|
|
79
|
+
}
|
|
80
|
+
/**
|
|
81
|
+
* Reads a body that must not exceed `maxBytes`, cancelling the moment it does. `content-length` is checked first
|
|
82
|
+
* because it is free, and counted anyway because it may be absent or lie.
|
|
83
|
+
*/
|
|
84
|
+
static async readBytes(opts) {
|
|
85
|
+
const { response } = opts;
|
|
86
|
+
const maxBytes = opts.maxBytes ?? DEFAULT_MAX_BYTES;
|
|
87
|
+
const declaredLength = BodyLimit.readDeclaredLength({ headers: response.headers });
|
|
88
|
+
if (declaredLength > maxBytes) {
|
|
89
|
+
await response.body?.cancel();
|
|
90
|
+
throw BodyLimit.refuse({ detail: `declared: ${declaredLength} | max: ${maxBytes}` });
|
|
91
|
+
}
|
|
92
|
+
const reader = response.body?.getReader();
|
|
93
|
+
if (!reader) {
|
|
94
|
+
throw getError({ message: '[readBytes] Response carried no body' });
|
|
95
|
+
}
|
|
96
|
+
const chunks = [];
|
|
97
|
+
let received = 0;
|
|
98
|
+
for (;;) {
|
|
99
|
+
const { done, value } = await reader.read();
|
|
100
|
+
if (done) {
|
|
101
|
+
break;
|
|
102
|
+
}
|
|
103
|
+
received += value.length;
|
|
104
|
+
if (received > maxBytes) {
|
|
105
|
+
await reader.cancel();
|
|
106
|
+
throw BodyLimit.refuse({ detail: `received: ${received} | max: ${maxBytes}` });
|
|
107
|
+
}
|
|
108
|
+
chunks.push(value);
|
|
109
|
+
}
|
|
110
|
+
const bytes = new Uint8Array(received);
|
|
111
|
+
let offset = 0;
|
|
112
|
+
for (const chunk of chunks) {
|
|
113
|
+
bytes.set(chunk, offset);
|
|
114
|
+
offset += chunk.length;
|
|
115
|
+
}
|
|
116
|
+
return bytes;
|
|
117
|
+
}
|
|
118
|
+
}
|
|
119
|
+
//# sourceMappingURL=body-limit.js.map
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"body-limit.js","sourceRoot":"","sources":["../../../../../../../src/modules/network/http-request/fetcher/common/body-limit.ts"],"names":[],"mappings":"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","sourcesContent":["import { HTTP } from '@/common/constants/http';\nimport { getError } from '@/modules/error';\nimport type { ApplicationError } from '@venizia/ignis-inversion';\nimport { UrlSafetyErrors } from '@/modules/network/utilities/url-safety/common/errors';\nimport { UrlSafetyDefaults } from '@/modules/network/utilities/url-safety/common/constants';\n\n/** The largest body a call accepts when it names no `maxBytes` of its own. */\nconst DEFAULT_MAX_BYTES = UrlSafetyDefaults.MAX_BYTES;\n\n/** A cap on a body, for a stream piped onward or a body read into memory. Browser-pure: streams and typed arrays only. */\nexport class BodyLimit {\n /** The one refusal of a body over the cap; `detail` says how it was found (declared, received, a client's own words). */\n static refuse(opts: { detail: string }): ApplicationError {\n return getError({\n error: UrlSafetyErrors.URL_REFUSED,\n message: `[fetch] Body exceeds the cap | ${opts.detail}`,\n });\n }\n\n /** Enforces `maxBytes` on a stream nothing reads into this process: the cap fails the stream the moment the bytes cross it. */\n static capStream(opts: {\n source: ReadableStream<Uint8Array>;\n maxBytes?: number;\n }): ReadableStream<Uint8Array> {\n const { source } = opts;\n const maxBytes = opts.maxBytes ?? DEFAULT_MAX_BYTES;\n let received = 0;\n\n return source.pipeThrough(\n new TransformStream<Uint8Array, Uint8Array>({\n transform(chunk, controller) {\n received += chunk.byteLength;\n\n if (received > maxBytes) {\n controller.error(\n BodyLimit.refuse({ detail: `received: ${received} | max: ${maxBytes}` }),\n );\n\n return;\n }\n\n controller.enqueue(chunk);\n },\n }),\n );\n }\n\n /** The size a response declares, or `0` when it declares none or an unreadable one. */\n static readDeclaredLength(opts: { headers: Headers }): number {\n const declared = Number(opts.headers.get(HTTP.Headers.CONTENT_LENGTH) ?? 0);\n\n return Number.isFinite(declared) ? declared : 0;\n }\n\n /** At most `maxBytes` of the body, then the rest released; a body that fails halfway answers what arrived. Never throws on size: a refused status must still say what it was. */\n static async readPrefix(opts: { response: Response; maxBytes: number }): Promise<Uint8Array> {\n const { response, maxBytes } = opts;\n const reader = response.body?.getReader();\n const chunks: Uint8Array[] = [];\n let received = 0;\n\n if (!reader) {\n return new Uint8Array();\n }\n\n try {\n while (received < maxBytes) {\n const { done, value } = await reader.read();\n\n if (done) {\n break;\n }\n\n chunks.push(value.subarray(0, maxBytes - received));\n received += chunks[chunks.length - 1].length;\n }\n // eslint-disable-next-line venizia/no-silent-catch -- the status is the answer; a body that broke off is reported as the shorter body it was\n } catch {\n // The chunks that arrived stand.\n }\n\n try {\n await reader.cancel();\n // eslint-disable-next-line venizia/no-silent-catch -- the stream is released as far as it can be; nothing is left to report\n } catch {\n // Already closed or errored.\n }\n\n const bytes = new Uint8Array(received);\n let offset = 0;\n\n for (const chunk of chunks) {\n bytes.set(chunk, offset);\n offset += chunk.length;\n }\n\n return bytes;\n }\n\n /** `readBytes`, decoded as UTF-8 text. */\n static async readText(opts: { response: Response; maxBytes?: number }): Promise<string> {\n const bytes = await BodyLimit.readBytes(opts);\n\n return new TextDecoder().decode(bytes);\n }\n\n /**\n * Reads a body that must not exceed `maxBytes`, cancelling the moment it does. `content-length` is checked first\n * because it is free, and counted anyway because it may be absent or lie.\n */\n static async readBytes(opts: { response: Response; maxBytes?: number }): Promise<Uint8Array> {\n const { response } = opts;\n const maxBytes = opts.maxBytes ?? DEFAULT_MAX_BYTES;\n const declaredLength = BodyLimit.readDeclaredLength({ headers: response.headers });\n\n if (declaredLength > maxBytes) {\n await response.body?.cancel();\n throw BodyLimit.refuse({ detail: `declared: ${declaredLength} | max: ${maxBytes}` });\n }\n\n const reader = response.body?.getReader();\n\n if (!reader) {\n throw getError({ message: '[readBytes] Response carried no body' });\n }\n\n const chunks: Uint8Array[] = [];\n let received = 0;\n\n for (;;) {\n const { done, value } = await reader.read();\n\n if (done) {\n break;\n }\n\n received += value.length;\n\n if (received > maxBytes) {\n await reader.cancel();\n throw BodyLimit.refuse({ detail: `received: ${received} | max: ${maxBytes}` });\n }\n\n chunks.push(value);\n }\n\n const bytes = new Uint8Array(received);\n let offset = 0;\n\n for (const chunk of chunks) {\n bytes.set(chunk, offset);\n offset += chunk.length;\n }\n\n return bytes;\n }\n}\n"]}
|
|
@@ -0,0 +1,40 @@
|
|
|
1
|
+
import type { TRegisterErrors } from '@venizia/ignis-inversion';
|
|
2
|
+
import { ApplicationError } from '@venizia/ignis-inversion';
|
|
3
|
+
/** Errors a fetcher raises that are not a refusal of the url guard. */
|
|
4
|
+
declare const FetchErrors: {
|
|
5
|
+
readonly SCHEMA_MISMATCH: {
|
|
6
|
+
readonly message: {
|
|
7
|
+
readonly text: "The upstream answered something else than the schema describes";
|
|
8
|
+
readonly code: "core.fetch.schema_mismatch";
|
|
9
|
+
};
|
|
10
|
+
readonly statusCode: 502;
|
|
11
|
+
readonly category: "integration";
|
|
12
|
+
};
|
|
13
|
+
};
|
|
14
|
+
/** One place a body failed its schema: where, and which rule. Never the value found there. */
|
|
15
|
+
export interface IFetchSchemaIssue {
|
|
16
|
+
path: Array<string | number>;
|
|
17
|
+
code: string;
|
|
18
|
+
}
|
|
19
|
+
/**
|
|
20
|
+
* The body parsed, but it is not what the schema says: the upstream answered something else (502). The message and the
|
|
21
|
+
* issues name paths and rules only, so no part of the body leaves with the error.
|
|
22
|
+
*/
|
|
23
|
+
export declare class FetchSchemaError extends ApplicationError {
|
|
24
|
+
/** The status the upstream answered with. */
|
|
25
|
+
readonly status: number;
|
|
26
|
+
readonly url: string;
|
|
27
|
+
readonly issues: IFetchSchemaIssue[];
|
|
28
|
+
constructor(opts: {
|
|
29
|
+
status: number;
|
|
30
|
+
url: string;
|
|
31
|
+
issues: IFetchSchemaIssue[];
|
|
32
|
+
});
|
|
33
|
+
static is(error: unknown): error is FetchSchemaError;
|
|
34
|
+
}
|
|
35
|
+
declare module '@venizia/ignis-inversion' {
|
|
36
|
+
interface IErrorKeyRegistry extends TRegisterErrors<typeof FetchErrors> {
|
|
37
|
+
}
|
|
38
|
+
}
|
|
39
|
+
export {};
|
|
40
|
+
//# sourceMappingURL=errors.d.ts.map
|
|
@@ -0,0 +1,37 @@
|
|
|
1
|
+
import { HTTP } from '../../../../../common/constants/index.js';
|
|
2
|
+
import { ApplicationError, ErrorScopes } from '@venizia/ignis-inversion';
|
|
3
|
+
/** Errors a fetcher raises that are not a refusal of the url guard. */
|
|
4
|
+
const FetchErrors = {
|
|
5
|
+
SCHEMA_MISMATCH: {
|
|
6
|
+
message: {
|
|
7
|
+
text: 'The upstream answered something else than the schema describes',
|
|
8
|
+
code: 'core.fetch.schema_mismatch',
|
|
9
|
+
},
|
|
10
|
+
statusCode: HTTP.ResultCodes.RS_5.BadGateway,
|
|
11
|
+
category: ErrorScopes.INTEGRATION,
|
|
12
|
+
},
|
|
13
|
+
};
|
|
14
|
+
/**
|
|
15
|
+
* The body parsed, but it is not what the schema says: the upstream answered something else (502). The message and the
|
|
16
|
+
* issues name paths and rules only, so no part of the body leaves with the error.
|
|
17
|
+
*/
|
|
18
|
+
export class FetchSchemaError extends ApplicationError {
|
|
19
|
+
constructor(opts) {
|
|
20
|
+
const where = opts.issues
|
|
21
|
+
.slice(0, 5)
|
|
22
|
+
.map((issue) => `${issue.path.join('.') || '(body)'}: ${issue.code}`)
|
|
23
|
+
.join(', ');
|
|
24
|
+
super({
|
|
25
|
+
error: FetchErrors.SCHEMA_MISMATCH,
|
|
26
|
+
message: `[fetch] The response does not match the schema | status: ${opts.status} | url: ${opts.url} | issues: ${where}`,
|
|
27
|
+
});
|
|
28
|
+
this.name = 'FetchSchemaError';
|
|
29
|
+
this.status = opts.status;
|
|
30
|
+
this.url = opts.url;
|
|
31
|
+
this.issues = opts.issues;
|
|
32
|
+
}
|
|
33
|
+
static is(error) {
|
|
34
|
+
return error instanceof FetchSchemaError;
|
|
35
|
+
}
|
|
36
|
+
}
|
|
37
|
+
//# sourceMappingURL=errors.js.map
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"errors.js","sourceRoot":"","sources":["../../../../../../../src/modules/network/http-request/fetcher/common/errors.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,IAAI,EAAE,MAAM,oBAAoB,CAAC;AAE1C,OAAO,EAAE,gBAAgB,EAAE,WAAW,EAAE,MAAM,0BAA0B,CAAC;AAEzE,uEAAuE;AACvE,MAAM,WAAW,GAAG;IAClB,eAAe,EAAE;QACf,OAAO,EAAE;YACP,IAAI,EAAE,gEAAgE;YACtE,IAAI,EAAE,4BAA4B;SACnC;QACD,UAAU,EAAE,IAAI,CAAC,WAAW,CAAC,IAAI,CAAC,UAAU;QAC5C,QAAQ,EAAE,WAAW,CAAC,WAAW;KAClC;CACkD,CAAC;AAQtD;;;GAGG;AACH,MAAM,OAAO,gBAAiB,SAAQ,gBAAgB;IAMpD,YAAY,IAAkE;QAC5E,MAAM,KAAK,GAAG,IAAI,CAAC,MAAM;aACtB,KAAK,CAAC,CAAC,EAAE,CAAC,CAAC;aACX,GAAG,CAAC,CAAC,KAAK,EAAE,EAAE,CAAC,GAAG,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,GAAG,CAAC,IAAI,QAAQ,KAAK,KAAK,CAAC,IAAI,EAAE,CAAC;aACpE,IAAI,CAAC,IAAI,CAAC,CAAC;QAEd,KAAK,CAAC;YACJ,KAAK,EAAE,WAAW,CAAC,eAAe;YAClC,OAAO,EAAE,4DAA4D,IAAI,CAAC,MAAM,WAAW,IAAI,CAAC,GAAG,cAAc,KAAK,EAAE;SACzH,CAAC,CAAC;QAEH,IAAI,CAAC,IAAI,GAAG,kBAAkB,CAAC;QAC/B,IAAI,CAAC,MAAM,GAAG,IAAI,CAAC,MAAM,CAAC;QAC1B,IAAI,CAAC,GAAG,GAAG,IAAI,CAAC,GAAG,CAAC;QACpB,IAAI,CAAC,MAAM,GAAG,IAAI,CAAC,MAAM,CAAC;IAC5B,CAAC;IAED,MAAM,CAAC,EAAE,CAAC,KAAc;QACtB,OAAO,KAAK,YAAY,gBAAgB,CAAC;IAC3C,CAAC;CACF","sourcesContent":["import { HTTP } from '@/common/constants';\nimport type { TErrorDefinition, TRegisterErrors } from '@venizia/ignis-inversion';\nimport { ApplicationError, ErrorScopes } from '@venizia/ignis-inversion';\n\n/** Errors a fetcher raises that are not a refusal of the url guard. */\nconst FetchErrors = {\n SCHEMA_MISMATCH: {\n message: {\n text: 'The upstream answered something else than the schema describes',\n code: 'core.fetch.schema_mismatch',\n },\n statusCode: HTTP.ResultCodes.RS_5.BadGateway,\n category: ErrorScopes.INTEGRATION,\n },\n} as const satisfies Record<string, TErrorDefinition>;\n\n/** One place a body failed its schema: where, and which rule. Never the value found there. */\nexport interface IFetchSchemaIssue {\n path: Array<string | number>;\n code: string;\n}\n\n/**\n * The body parsed, but it is not what the schema says: the upstream answered something else (502). The message and the\n * issues name paths and rules only, so no part of the body leaves with the error.\n */\nexport class FetchSchemaError extends ApplicationError {\n /** The status the upstream answered with. */\n readonly status: number;\n readonly url: string;\n readonly issues: IFetchSchemaIssue[];\n\n constructor(opts: { status: number; url: string; issues: IFetchSchemaIssue[] }) {\n const where = opts.issues\n .slice(0, 5)\n .map((issue) => `${issue.path.join('.') || '(body)'}: ${issue.code}`)\n .join(', ');\n\n super({\n error: FetchErrors.SCHEMA_MISMATCH,\n message: `[fetch] The response does not match the schema | status: ${opts.status} | url: ${opts.url} | issues: ${where}`,\n });\n\n this.name = 'FetchSchemaError';\n this.status = opts.status;\n this.url = opts.url;\n this.issues = opts.issues;\n }\n\n static is(error: unknown): error is FetchSchemaError {\n return error instanceof FetchSchemaError;\n }\n}\n\ndeclare module '@venizia/ignis-inversion' {\n interface IErrorKeyRegistry extends TRegisterErrors<typeof FetchErrors> {}\n}\n"]}
|
|
@@ -0,0 +1,27 @@
|
|
|
1
|
+
import type { IUrlSafetyPolicy } from '../../../utilities/url-safety/common/types.js';
|
|
2
|
+
/** One hop the guard vetted: the url to send to, and the addresses to connect to (empty: connect as the client would). */
|
|
3
|
+
export interface IFetchGuardHop {
|
|
4
|
+
url: URL;
|
|
5
|
+
addresses: string[];
|
|
6
|
+
/** The name an https connection to `addresses` verifies the certificate for; unset for a literal address or http. */
|
|
7
|
+
tlsServerName?: string;
|
|
8
|
+
}
|
|
9
|
+
/** A guarded call: vets the first url and every redirect target, one hop at a time. */
|
|
10
|
+
export interface IFetchGuardRoute {
|
|
11
|
+
/** The policy's `timeout` in milliseconds, when it names one: the guard owns the duration units, so a browser bundle does not carry them. */
|
|
12
|
+
readonly timeoutMs?: number;
|
|
13
|
+
vet(opts: {
|
|
14
|
+
url: string;
|
|
15
|
+
signal?: AbortSignal;
|
|
16
|
+
}): Promise<IFetchGuardHop>;
|
|
17
|
+
}
|
|
18
|
+
/**
|
|
19
|
+
* The seam between a fetcher, which is browser-pure, and the url guard, which resolves names with `node:dns`. The server
|
|
20
|
+
* half is `UrlGuard`; a fetcher is handed it as `guardEngine`, so a browser bundle never reaches the resolver.
|
|
21
|
+
*/
|
|
22
|
+
export interface IFetchGuard {
|
|
23
|
+
createRoute(opts: {
|
|
24
|
+
policy: IUrlSafetyPolicy;
|
|
25
|
+
}): IFetchGuardRoute;
|
|
26
|
+
}
|
|
27
|
+
//# sourceMappingURL=guard.d.ts.map
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"guard.js","sourceRoot":"","sources":["../../../../../../../src/modules/network/http-request/fetcher/common/guard.ts"],"names":[],"mappings":"","sourcesContent":["import type { IUrlSafetyPolicy } from '@/modules/network/utilities/url-safety/common/types';\n\n/** One hop the guard vetted: the url to send to, and the addresses to connect to (empty: connect as the client would). */\nexport interface IFetchGuardHop {\n url: URL;\n addresses: string[];\n /** The name an https connection to `addresses` verifies the certificate for; unset for a literal address or http. */\n tlsServerName?: string;\n}\n\n/** A guarded call: vets the first url and every redirect target, one hop at a time. */\nexport interface IFetchGuardRoute {\n /** The policy's `timeout` in milliseconds, when it names one: the guard owns the duration units, so a browser bundle does not carry them. */\n readonly timeoutMs?: number;\n vet(opts: { url: string; signal?: AbortSignal }): Promise<IFetchGuardHop>;\n}\n\n/**\n * The seam between a fetcher, which is browser-pure, and the url guard, which resolves names with `node:dns`. The server\n * half is `UrlGuard`; a fetcher is handed it as `guardEngine`, so a browser bundle never reaches the resolver.\n */\nexport interface IFetchGuard {\n createRoute(opts: { policy: IUrlSafetyPolicy }): IFetchGuardRoute;\n}\n"]}
|
|
@@ -1,2 +1,8 @@
|
|
|
1
|
+
export * from './body-limit.js';
|
|
2
|
+
export * from './errors.js';
|
|
3
|
+
export * from './guard.js';
|
|
4
|
+
export * from './request-context.js';
|
|
5
|
+
export * from './response-reader.js';
|
|
1
6
|
export * from './types.js';
|
|
7
|
+
export * from './utilities.js';
|
|
2
8
|
//# sourceMappingURL=index.d.ts.map
|
|
@@ -1,2 +1,8 @@
|
|
|
1
|
+
export * from './body-limit.js';
|
|
2
|
+
export * from './errors.js';
|
|
3
|
+
export * from './guard.js';
|
|
4
|
+
export * from './request-context.js';
|
|
5
|
+
export * from './response-reader.js';
|
|
1
6
|
export * from './types.js';
|
|
7
|
+
export * from './utilities.js';
|
|
2
8
|
//# sourceMappingURL=index.js.map
|
|
@@ -1 +1 @@
|
|
|
1
|
-
{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../../../../../src/modules/network/http-request/fetcher/common/index.ts"],"names":[],"mappings":"AAAA,cAAc,SAAS,CAAC","sourcesContent":["export * from './types';\n"]}
|
|
1
|
+
{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../../../../../src/modules/network/http-request/fetcher/common/index.ts"],"names":[],"mappings":"AAAA,cAAc,cAAc,CAAC;AAC7B,cAAc,UAAU,CAAC;AACzB,cAAc,SAAS,CAAC;AACxB,cAAc,mBAAmB,CAAC;AAClC,cAAc,mBAAmB,CAAC;AAClC,cAAc,SAAS,CAAC;AACxB,cAAc,aAAa,CAAC","sourcesContent":["export * from './body-limit';\nexport * from './errors';\nexport * from './guard';\nexport * from './request-context';\nexport * from './response-reader';\nexport * from './types';\nexport * from './utilities';\n"]}
|
|
@@ -0,0 +1,15 @@
|
|
|
1
|
+
import type { IFetchRequestContext } from './types.js';
|
|
2
|
+
/** The request a hook sees, frozen so that its url, method and attempt cannot be assigned: only the headers are for the hook to change. */
|
|
3
|
+
export declare class FetchRequestContext implements IFetchRequestContext {
|
|
4
|
+
readonly method: string;
|
|
5
|
+
readonly url: string;
|
|
6
|
+
readonly headers: Headers;
|
|
7
|
+
readonly attempt: number;
|
|
8
|
+
constructor(opts: {
|
|
9
|
+
method: string;
|
|
10
|
+
url: string;
|
|
11
|
+
headers: Headers;
|
|
12
|
+
attempt: number;
|
|
13
|
+
});
|
|
14
|
+
}
|
|
15
|
+
//# sourceMappingURL=request-context.d.ts.map
|
|
@@ -0,0 +1,11 @@
|
|
|
1
|
+
/** The request a hook sees, frozen so that its url, method and attempt cannot be assigned: only the headers are for the hook to change. */
|
|
2
|
+
export class FetchRequestContext {
|
|
3
|
+
constructor(opts) {
|
|
4
|
+
this.method = opts.method;
|
|
5
|
+
this.url = opts.url;
|
|
6
|
+
this.headers = opts.headers;
|
|
7
|
+
this.attempt = opts.attempt;
|
|
8
|
+
Object.freeze(this);
|
|
9
|
+
}
|
|
10
|
+
}
|
|
11
|
+
//# sourceMappingURL=request-context.js.map
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"request-context.js","sourceRoot":"","sources":["../../../../../../../src/modules/network/http-request/fetcher/common/request-context.ts"],"names":[],"mappings":"AAEA,2IAA2I;AAC3I,MAAM,OAAO,mBAAmB;IAM9B,YAAY,IAAwE;QAClF,IAAI,CAAC,MAAM,GAAG,IAAI,CAAC,MAAM,CAAC;QAC1B,IAAI,CAAC,GAAG,GAAG,IAAI,CAAC,GAAG,CAAC;QACpB,IAAI,CAAC,OAAO,GAAG,IAAI,CAAC,OAAO,CAAC;QAC5B,IAAI,CAAC,OAAO,GAAG,IAAI,CAAC,OAAO,CAAC;QAE5B,MAAM,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC;IACtB,CAAC;CACF","sourcesContent":["import type { IFetchRequestContext } from './types';\n\n/** The request a hook sees, frozen so that its url, method and attempt cannot be assigned: only the headers are for the hook to change. */\nexport class FetchRequestContext implements IFetchRequestContext {\n readonly method: string;\n readonly url: string;\n readonly headers: Headers;\n readonly attempt: number;\n\n constructor(opts: { method: string; url: string; headers: Headers; attempt: number }) {\n this.method = opts.method;\n this.url = opts.url;\n this.headers = opts.headers;\n this.attempt = opts.attempt;\n\n Object.freeze(this);\n }\n}\n"]}
|
|
@@ -0,0 +1,133 @@
|
|
|
1
|
+
import type { TJsonValue } from '../../../../../common/types/index.js';
|
|
2
|
+
import type { ApplicationError, TResponsedError } from '../../../../error/index.js';
|
|
3
|
+
import type { UrlFetchError } from '../../../utilities/url-safety/common/errors.js';
|
|
4
|
+
/**
|
|
5
|
+
* What an IGNIS server answers - `Content-Range`, the error envelope - read once, here, for every
|
|
6
|
+
* client of that server: the http connector, and a client that reads it without the connector.
|
|
7
|
+
*/
|
|
8
|
+
export declare class HttpResponseReader {
|
|
9
|
+
/** A content type that names JSON: `application/json`, `application/problem+json`, `application/ld+json`. */
|
|
10
|
+
static readonly JSON_CONTENT_TYPE_PATTERN: RegExp;
|
|
11
|
+
/** An empty string reads as absent, so a fallback still applies. */
|
|
12
|
+
private static toText;
|
|
13
|
+
/**
|
|
14
|
+
* A `Content-Range` header as the IGNIS server writes it: `records 0-24/137` -> skip 0, total 137;
|
|
15
|
+
* an empty page, `records *\/137` -> total 137. Anything else, including an absent header or an
|
|
16
|
+
* unknown total, is `undefined`.
|
|
17
|
+
*/
|
|
18
|
+
static parseContentRange(opts: {
|
|
19
|
+
header?: string | null;
|
|
20
|
+
}): {
|
|
21
|
+
skip?: number;
|
|
22
|
+
total: number;
|
|
23
|
+
} | undefined;
|
|
24
|
+
/**
|
|
25
|
+
* The IGNIS error envelope - `{ message, statusCode, normalized: { text, code, args }, requestId,
|
|
26
|
+
* extra, details }` - read off a parsed response body. A server configured with `error.rootKey`
|
|
27
|
+
* wraps it under that key; pass the same `rootKey` to unwrap it. A body without that key, or with a
|
|
28
|
+
* non-object under it (a proxy's `{ error: 'Bad Gateway' }`), is read as it stands.
|
|
29
|
+
*
|
|
30
|
+
* A body that is not a plain object yields `{}`; any other body yields its known fields, each
|
|
31
|
+
* `undefined` when absent or mistyped. An empty string reads as absent.
|
|
32
|
+
*/
|
|
33
|
+
static readErrorEnvelope(opts: {
|
|
34
|
+
body: unknown;
|
|
35
|
+
rootKey?: string;
|
|
36
|
+
}): TResponsedError;
|
|
37
|
+
/** A failed response's envelope. A body that is not JSON yields `{}`, and the status alone still describes it. */
|
|
38
|
+
static readError(opts: {
|
|
39
|
+
response: Response;
|
|
40
|
+
rootKey?: string;
|
|
41
|
+
}): Promise<TResponsedError>;
|
|
42
|
+
/**
|
|
43
|
+
* A failed response as the error the server threw: its status, code, args and text, and its
|
|
44
|
+
* `extra` with the `requestId` added. `message` is `context` plus the server's text, for logs; without
|
|
45
|
+
* `context` it is the server's text alone (`HTTP <status>` when it sent none), for a client that shows
|
|
46
|
+
* `message` to users. `normalized.text` is the server's either way - `HTTP <status>` when none.
|
|
47
|
+
* `cause` is the server's `details.cause` - a 422's per-field issues, `{ path, message, code }`.
|
|
48
|
+
*
|
|
49
|
+
* `requestId` names the request this client made. A relaying server's `extra` carries the id of
|
|
50
|
+
* the request it made upstream: it joins `upstreamRequestIds`, nearest first, at every hop.
|
|
51
|
+
*/
|
|
52
|
+
static toApplicationError(opts: {
|
|
53
|
+
response: Response;
|
|
54
|
+
/** Where it failed, for logs - e.g. `[HttpDataSource][read] 404 | /tickets`. Left out, `message` is the server's text. */
|
|
55
|
+
context?: string;
|
|
56
|
+
rootKey?: string;
|
|
57
|
+
}): Promise<ApplicationError>;
|
|
58
|
+
/**
|
|
59
|
+
* `toApplicationError` for a fetcher's refused answer: it reads the body the `UrlFetchError` kept (the first 64 KiB),
|
|
60
|
+
* and an error that carries none is described by its status alone.
|
|
61
|
+
*/
|
|
62
|
+
static fromFetchError(opts: {
|
|
63
|
+
error: UrlFetchError<Response>;
|
|
64
|
+
context?: string;
|
|
65
|
+
rootKey?: string;
|
|
66
|
+
}): Promise<ApplicationError>;
|
|
67
|
+
/** The body as text: `''` for a 204, an empty body or no body; with `maxBytes` the read stops and fails at the cap. */
|
|
68
|
+
static readText(opts: {
|
|
69
|
+
response: Response;
|
|
70
|
+
maxBytes?: number;
|
|
71
|
+
}): Promise<string>;
|
|
72
|
+
/**
|
|
73
|
+
* The body of a success answer, by what it says it is: `null` for a 204 or an empty body, the parsed
|
|
74
|
+
* value when the content type names JSON (`application/json`, `application/problem+json`), the text itself
|
|
75
|
+
* for any other type (`text/plain`, `text/csv`). A body that claims JSON and is not is a `502` that names
|
|
76
|
+
* `context` (where it happened, e.g. `[Client][read] 200 | /tickets`), its size and its content type; its
|
|
77
|
+
* content stays out of the message, which a relaying server may pass to its own clients.
|
|
78
|
+
*/
|
|
79
|
+
static readBody(opts: {
|
|
80
|
+
response: Response;
|
|
81
|
+
context: string;
|
|
82
|
+
}): Promise<TJsonValue>;
|
|
83
|
+
/**
|
|
84
|
+
* A download as a file: its `blob`, the `filename` of its `Content-Disposition` (`filename*` first) and its `contentType`.
|
|
85
|
+
* A non-2xx answer throws what `toApplicationError({ response })` throws, so an error page is never saved as a file.
|
|
86
|
+
*/
|
|
87
|
+
static readFile(opts: {
|
|
88
|
+
response: Response;
|
|
89
|
+
}): Promise<{
|
|
90
|
+
blob: Blob;
|
|
91
|
+
filename?: string;
|
|
92
|
+
contentType?: string;
|
|
93
|
+
}>;
|
|
94
|
+
/**
|
|
95
|
+
* The body as JSON whatever its content type says, `null` for a 204 or an empty body: for a route that
|
|
96
|
+
* answers JSON under a type a proxy rewrote. Errors as `readBody` does.
|
|
97
|
+
*/
|
|
98
|
+
static readJson(opts: {
|
|
99
|
+
response: Response;
|
|
100
|
+
context: string;
|
|
101
|
+
}): Promise<TJsonValue>;
|
|
102
|
+
private static parseJson;
|
|
103
|
+
/**
|
|
104
|
+
* A body the server marked with `x-response-extra` carries `extra` beside its rows. `body` is what
|
|
105
|
+
* the route answers without extras: the `{ count, data }` envelope when the count was asked for in
|
|
106
|
+
* the body, the rows otherwise. Any other body is returned as it stands - an unmarked object is
|
|
107
|
+
* never unwrapped, so a row that has `data` and `extra` columns of its own is never misread.
|
|
108
|
+
*/
|
|
109
|
+
static readExtra(opts: {
|
|
110
|
+
body: unknown;
|
|
111
|
+
headers: Pick<Headers, 'has'>;
|
|
112
|
+
}): {
|
|
113
|
+
body: unknown;
|
|
114
|
+
extra?: Record<string, unknown>;
|
|
115
|
+
};
|
|
116
|
+
/**
|
|
117
|
+
* Reads a filename out of a `Content-Disposition` value.
|
|
118
|
+
*
|
|
119
|
+
* Three forms, in the order the RFC gives them precedence: `filename*=UTF-8''...` (percent-encoded,
|
|
120
|
+
* and the one hand-rolled parsers miss), a quoted `filename="..."`, and a bare `filename=...`.
|
|
121
|
+
* Splitting on `filename=` alone returns the percent-encoded bytes for any non-ASCII name, which in
|
|
122
|
+
* a product with non-English filenames is most of them.
|
|
123
|
+
*
|
|
124
|
+
* The pair of `RequestUtility.buildContentDispositionHeader`: one writes the header, this one reads it.
|
|
125
|
+
*/
|
|
126
|
+
static parseContentDisposition(opts: {
|
|
127
|
+
header: string | null | undefined;
|
|
128
|
+
}): {
|
|
129
|
+
type?: string;
|
|
130
|
+
filename?: string;
|
|
131
|
+
};
|
|
132
|
+
}
|
|
133
|
+
//# sourceMappingURL=response-reader.d.ts.map
|