@sdflc/backend-helpers 1.0.139 → 1.0.140
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/README.md +176 -20
- package/build/EmergencyAlerter.d.ts +140 -0
- package/build/EmergencyAlerter.js +465 -0
- package/build/esm/EmergencyAlerter.d.ts +140 -0
- package/build/esm/EmergencyAlerter.js +454 -0
- package/build/esm/gateways/BaseExternalApiGateway.d.ts +94 -0
- package/build/esm/gateways/BaseExternalApiGateway.js +319 -0
- package/build/esm/gateways/DiscordWebhookGw.d.ts +50 -0
- package/build/esm/gateways/DiscordWebhookGw.js +70 -0
- package/build/esm/gateways/HttpWebhookGw.d.ts +43 -0
- package/build/esm/gateways/HttpWebhookGw.js +131 -0
- package/build/esm/gateways/SendGridGw.d.ts +41 -0
- package/build/esm/gateways/SendGridGw.js +116 -0
- package/build/esm/gateways/SlackWebhookGw.d.ts +23 -0
- package/build/esm/gateways/SlackWebhookGw.js +59 -0
- package/build/esm/gateways/TelegramGw.d.ts +45 -0
- package/build/esm/gateways/TelegramGw.js +110 -0
- package/build/esm/gateways/TwilioGw.d.ts +33 -0
- package/build/esm/gateways/TwilioGw.js +107 -0
- package/build/esm/gateways/externalUrl.d.ts +16 -0
- package/build/esm/gateways/externalUrl.js +116 -0
- package/build/esm/gateways/guardedFetch.d.ts +15 -0
- package/build/esm/gateways/guardedFetch.js +133 -0
- package/build/esm/gateways/index.d.ts +9 -0
- package/build/esm/gateways/index.js +9 -0
- package/build/esm/index.d.ts +2 -1
- package/build/esm/index.js +2 -1
- package/build/esm/interfaces/BaseExternalApiGatewayPropsInterface.d.ts +16 -2
- package/build/gateways/BaseExternalApiGateway.d.ts +94 -0
- package/build/gateways/BaseExternalApiGateway.js +326 -0
- package/build/gateways/DiscordWebhookGw.d.ts +50 -0
- package/build/gateways/DiscordWebhookGw.js +73 -0
- package/build/gateways/HttpWebhookGw.d.ts +43 -0
- package/build/gateways/HttpWebhookGw.js +135 -0
- package/build/gateways/SendGridGw.d.ts +41 -0
- package/build/gateways/SendGridGw.js +119 -0
- package/build/gateways/SlackWebhookGw.d.ts +23 -0
- package/build/gateways/SlackWebhookGw.js +62 -0
- package/build/gateways/TelegramGw.d.ts +45 -0
- package/build/gateways/TelegramGw.js +115 -0
- package/build/gateways/TwilioGw.d.ts +33 -0
- package/build/gateways/TwilioGw.js +110 -0
- package/build/gateways/externalUrl.d.ts +16 -0
- package/build/gateways/externalUrl.js +121 -0
- package/build/gateways/guardedFetch.d.ts +15 -0
- package/build/gateways/guardedFetch.js +141 -0
- package/build/gateways/index.d.ts +9 -0
- package/build/gateways/index.js +25 -0
- package/build/index.d.ts +2 -1
- package/build/index.js +2 -1
- package/build/interfaces/BaseExternalApiGatewayPropsInterface.d.ts +16 -2
- package/package.json +2 -1
- package/build/BaseExternalApiGateway.d.ts +0 -16
- package/build/BaseExternalApiGateway.js +0 -54
- package/build/esm/BaseExternalApiGateway.d.ts +0 -16
- package/build/esm/BaseExternalApiGateway.js +0 -48
|
@@ -0,0 +1,133 @@
|
|
|
1
|
+
// ./src/gateways/guardedFetch.ts
|
|
2
|
+
//
|
|
3
|
+
// A `fetch` for URLs a USER gave us (webhooks) that refuses a forbidden address AT THE MOMENT OF CONNECTING.
|
|
4
|
+
//
|
|
5
|
+
// ⚠ WHY NOT JUST CHECK THE URL FIRST: `checkExternalUrl` resolves the host name once; the platform fetch then resolves it
|
|
6
|
+
// AGAIN, on every attempt. A DNS server that answers a public address to the first lookup and 169.254.169.254 to the
|
|
7
|
+
// second (DNS rebinding) walks straight past a check made beforehand. Here the address the socket actually connects
|
|
8
|
+
// to is the one checked: Node's `http(s).request` takes the lookup, and this lookup refuses a blocked address.
|
|
9
|
+
// ⚠ An IP written in the URL is never looked up — it is checked here directly.
|
|
10
|
+
// ⚠ Redirects are never followed (http.request does not), the reply is capped at MAX_REPLY_BYTES, and the request ends at
|
|
11
|
+
// its signal (the gateway's timeout).
|
|
12
|
+
import http from 'http';
|
|
13
|
+
import https from 'https';
|
|
14
|
+
import { Buffer } from 'buffer';
|
|
15
|
+
import { isIP } from 'net';
|
|
16
|
+
import { lookup as dnsLookup } from 'dns';
|
|
17
|
+
import { MAX_REPLY_BYTES } from './BaseExternalApiGateway';
|
|
18
|
+
import { isBlockedAddress } from './externalUrl';
|
|
19
|
+
/** The error a refused address raises — the gateway reports it as VALIDATION_FAILED, never retried. */
|
|
20
|
+
const blockedError = (address) => Object.assign(new Error(`The address ${address} is not allowed`), { code: 'EBLOCKED' });
|
|
21
|
+
/**
|
|
22
|
+
* A `dns.lookup` that refuses when ANY address the name resolves to is blocked (a name with one private address among
|
|
23
|
+
* public ones is refused, whichever the socket would have picked).
|
|
24
|
+
*/
|
|
25
|
+
export const guardedLookup = (opts = {}) => (hostname, options, callback) => {
|
|
26
|
+
const resolve = opts.dnsLookup ?? dnsLookup;
|
|
27
|
+
const isBlocked = opts.isBlocked ?? isBlockedAddress;
|
|
28
|
+
const wantsAll = typeof options === 'object' && options?.all === true;
|
|
29
|
+
resolve(hostname, { ...(typeof options === 'object' ? options : {}), all: true }, (err, addresses) => {
|
|
30
|
+
if (err) {
|
|
31
|
+
callback(err);
|
|
32
|
+
return;
|
|
33
|
+
}
|
|
34
|
+
const list = Array.isArray(addresses) ? addresses : [];
|
|
35
|
+
const refused = list.find((one) => isBlocked(String(one?.address)));
|
|
36
|
+
if (refused || list.length === 0) {
|
|
37
|
+
callback(refused
|
|
38
|
+
? blockedError(String(refused.address))
|
|
39
|
+
: Object.assign(new Error(`${hostname} did not resolve`), { code: 'ENOTFOUND' }));
|
|
40
|
+
return;
|
|
41
|
+
}
|
|
42
|
+
if (wantsAll) {
|
|
43
|
+
callback(null, list);
|
|
44
|
+
}
|
|
45
|
+
else {
|
|
46
|
+
callback(null, list[0].address, list[0].family);
|
|
47
|
+
}
|
|
48
|
+
});
|
|
49
|
+
};
|
|
50
|
+
/** A fetch whose every connection goes through `guardedLookup`. The answer has `status`, `headers` and `text()`. */
|
|
51
|
+
export const createGuardedFetch = (opts = {}) => {
|
|
52
|
+
const isBlocked = opts.isBlocked ?? isBlockedAddress;
|
|
53
|
+
return (url, init = {}) => new Promise((resolve, reject) => {
|
|
54
|
+
let target;
|
|
55
|
+
try {
|
|
56
|
+
target = new URL(url);
|
|
57
|
+
}
|
|
58
|
+
catch {
|
|
59
|
+
reject(new TypeError('Invalid URL'));
|
|
60
|
+
return;
|
|
61
|
+
}
|
|
62
|
+
const literal = target.hostname.replace(/^\[|\]$/g, '');
|
|
63
|
+
if (isIP(literal) && isBlocked(literal)) {
|
|
64
|
+
reject(blockedError(literal));
|
|
65
|
+
return;
|
|
66
|
+
}
|
|
67
|
+
const signal = init.signal;
|
|
68
|
+
if (signal?.aborted) {
|
|
69
|
+
reject(signal.reason);
|
|
70
|
+
return;
|
|
71
|
+
}
|
|
72
|
+
const transport = target.protocol === 'https:' ? https : target.protocol === 'http:' ? http : null;
|
|
73
|
+
if (!transport) {
|
|
74
|
+
reject(new TypeError(`Unsupported protocol ${target.protocol}`));
|
|
75
|
+
return;
|
|
76
|
+
}
|
|
77
|
+
let req;
|
|
78
|
+
try {
|
|
79
|
+
req = transport.request(target, {
|
|
80
|
+
method: init.method ?? 'GET',
|
|
81
|
+
headers: init.headers ?? {},
|
|
82
|
+
lookup: guardedLookup(opts),
|
|
83
|
+
});
|
|
84
|
+
}
|
|
85
|
+
catch (e) {
|
|
86
|
+
// A malformed header is refused synchronously.
|
|
87
|
+
reject(e instanceof TypeError ? e : new TypeError(String(e?.message ?? e)));
|
|
88
|
+
return;
|
|
89
|
+
}
|
|
90
|
+
const onAbort = () => req.destroy(signal?.reason);
|
|
91
|
+
signal?.addEventListener('abort', onAbort, { once: true });
|
|
92
|
+
req.on('error', (e) => {
|
|
93
|
+
signal?.removeEventListener('abort', onAbort);
|
|
94
|
+
reject(e);
|
|
95
|
+
});
|
|
96
|
+
req.on('response', (res) => {
|
|
97
|
+
const chunks = [];
|
|
98
|
+
let size = 0;
|
|
99
|
+
let settled = false;
|
|
100
|
+
const finish = () => {
|
|
101
|
+
if (settled) {
|
|
102
|
+
return;
|
|
103
|
+
}
|
|
104
|
+
settled = true;
|
|
105
|
+
signal?.removeEventListener('abort', onAbort);
|
|
106
|
+
const text = Buffer.concat(chunks).toString('utf8');
|
|
107
|
+
resolve({ status: res.statusCode ?? 0, headers: { ...res.headers }, text: async () => text });
|
|
108
|
+
};
|
|
109
|
+
res.on('data', (chunk) => {
|
|
110
|
+
if (size + chunk.length > MAX_REPLY_BYTES) {
|
|
111
|
+
chunks.push(chunk.subarray(0, MAX_REPLY_BYTES - size));
|
|
112
|
+
size = MAX_REPLY_BYTES;
|
|
113
|
+
finish();
|
|
114
|
+
res.destroy();
|
|
115
|
+
return;
|
|
116
|
+
}
|
|
117
|
+
chunks.push(chunk);
|
|
118
|
+
size += chunk.length;
|
|
119
|
+
});
|
|
120
|
+
res.on('end', finish);
|
|
121
|
+
res.on('error', (e) => {
|
|
122
|
+
if (!settled) {
|
|
123
|
+
settled = true;
|
|
124
|
+
reject(e);
|
|
125
|
+
}
|
|
126
|
+
});
|
|
127
|
+
});
|
|
128
|
+
if (init.body !== undefined && init.body !== null) {
|
|
129
|
+
req.write(typeof init.body === 'string' ? init.body : String(init.body));
|
|
130
|
+
}
|
|
131
|
+
req.end();
|
|
132
|
+
});
|
|
133
|
+
};
|
|
@@ -0,0 +1,9 @@
|
|
|
1
|
+
export * from './BaseExternalApiGateway';
|
|
2
|
+
export * from './externalUrl';
|
|
3
|
+
export * from './SendGridGw';
|
|
4
|
+
export * from './TelegramGw';
|
|
5
|
+
export * from './TwilioGw';
|
|
6
|
+
export * from './SlackWebhookGw';
|
|
7
|
+
export * from './DiscordWebhookGw';
|
|
8
|
+
export * from './HttpWebhookGw';
|
|
9
|
+
export * from './guardedFetch';
|
|
@@ -0,0 +1,9 @@
|
|
|
1
|
+
export * from './BaseExternalApiGateway';
|
|
2
|
+
export * from './externalUrl';
|
|
3
|
+
export * from './SendGridGw';
|
|
4
|
+
export * from './TelegramGw';
|
|
5
|
+
export * from './TwilioGw';
|
|
6
|
+
export * from './SlackWebhookGw';
|
|
7
|
+
export * from './DiscordWebhookGw';
|
|
8
|
+
export * from './HttpWebhookGw';
|
|
9
|
+
export * from './guardedFetch';
|
package/build/esm/index.d.ts
CHANGED
|
@@ -21,6 +21,7 @@ export * from './commonValidators';
|
|
|
21
21
|
export * from './downloadHelpers';
|
|
22
22
|
export * from './resolveClientIp';
|
|
23
23
|
export * from './BaseRestApiCrudController';
|
|
24
|
-
export * from './
|
|
24
|
+
export * from './gateways';
|
|
25
25
|
export * from './IpRateLimiter';
|
|
26
26
|
export * from './uuidHelpers';
|
|
27
|
+
export * from './EmergencyAlerter';
|
package/build/esm/index.js
CHANGED
|
@@ -21,6 +21,7 @@ export * from './commonValidators';
|
|
|
21
21
|
export * from './downloadHelpers';
|
|
22
22
|
export * from './resolveClientIp';
|
|
23
23
|
export * from './BaseRestApiCrudController';
|
|
24
|
-
export * from './
|
|
24
|
+
export * from './gateways';
|
|
25
25
|
export * from './IpRateLimiter';
|
|
26
26
|
export * from './uuidHelpers';
|
|
27
|
+
export * from './EmergencyAlerter';
|
|
@@ -1,8 +1,16 @@
|
|
|
1
|
-
|
|
1
|
+
/** The HTTP client a gateway calls — the platform `fetch` unless a test passes its own. */
|
|
2
|
+
export type ExternalApiFetch = (url: string, init: any) => Promise<any>;
|
|
3
|
+
export interface BaseExternalApiGatewayPropsInterface<TSettings extends Record<string, any> = Record<string, any>> {
|
|
4
|
+
/**
|
|
5
|
+
* Optional settings to start with — the same as calling `configure(settings)` right after construction.
|
|
6
|
+
* A gateway is usually created ONCE and configured (and re-configured) at run time.
|
|
7
|
+
*/
|
|
8
|
+
settings?: TSettings;
|
|
2
9
|
/**
|
|
3
10
|
* Optional credentials — a plain API key string or a structured object
|
|
4
11
|
* with whatever keys the external service requires.
|
|
5
12
|
* Can also be set later via setCredentials() once resolved at runtime.
|
|
13
|
+
* ⓘ Kept for gateways written before `configure()`; a new gateway takes its credentials in its settings.
|
|
6
14
|
*/
|
|
7
15
|
credentials?: string | Record<string, any>;
|
|
8
16
|
/**
|
|
@@ -11,9 +19,15 @@ export interface BaseExternalApiGatewayPropsInterface {
|
|
|
11
19
|
*/
|
|
12
20
|
baseUrl?: string;
|
|
13
21
|
/**
|
|
14
|
-
* Timeout in milliseconds for outbound
|
|
22
|
+
* Timeout in milliseconds for one outbound request.
|
|
15
23
|
* Defaults to 10000.
|
|
16
24
|
*/
|
|
17
25
|
timeoutMs?: number;
|
|
26
|
+
/** Attempts AFTER the first one, for failures worth retrying (network, timeout, 429, 5xx). Defaults to 2. */
|
|
27
|
+
retries?: number;
|
|
28
|
+
/** The waits between attempts, in milliseconds (the last one repeats). Defaults to [1000, 2000]. */
|
|
29
|
+
retryDelaysMs?: number[];
|
|
30
|
+
/** The HTTP client. Defaults to the platform `fetch`. */
|
|
31
|
+
fetch?: ExternalApiFetch;
|
|
18
32
|
logger?: any;
|
|
19
33
|
}
|
|
@@ -0,0 +1,94 @@
|
|
|
1
|
+
import { OpResult } from '@sdflc/api-helpers';
|
|
2
|
+
import { Logger } from '@sdflc/utils';
|
|
3
|
+
import { BaseExternalApiGatewayPropsInterface, ExternalApiFetch } from '../interfaces';
|
|
4
|
+
/** One outbound HTTP request. */
|
|
5
|
+
export interface ExternalApiRequest {
|
|
6
|
+
url: string;
|
|
7
|
+
method?: string;
|
|
8
|
+
headers?: Record<string, string>;
|
|
9
|
+
/** Sent as JSON (with the JSON content type) unless `body` is given. */
|
|
10
|
+
json?: unknown;
|
|
11
|
+
/** Sent as is (a string, or URLSearchParams for a form). */
|
|
12
|
+
body?: string | URLSearchParams;
|
|
13
|
+
/** Overrides the gateway's timeout for this request. */
|
|
14
|
+
timeoutMs?: number;
|
|
15
|
+
/** Values to scrub out of what this request returns, besides the gateway's own (per-request credentials). */
|
|
16
|
+
secrets?: string[];
|
|
17
|
+
}
|
|
18
|
+
/**
|
|
19
|
+
* What a request answered — the `data` of the OpResult a request returns (on success AND on an HTTP refusal).
|
|
20
|
+
* ⚠ SCRUBBED: every secret of the gateway (and of the request) is replaced by `***` in the body and the headers, and
|
|
21
|
+
* `set-cookie` is dropped — the reply travels outward in the OpResult, and a service can echo a key back.
|
|
22
|
+
*/
|
|
23
|
+
export interface ExternalApiReply {
|
|
24
|
+
status: number;
|
|
25
|
+
headers: Record<string, string>;
|
|
26
|
+
/** The parsed JSON body, else the text, else null — at most 64 KB of it. */
|
|
27
|
+
body: any;
|
|
28
|
+
}
|
|
29
|
+
/** The most of a reply that is read: a hostile receiver must not be able to stream until memory runs out. */
|
|
30
|
+
export declare const MAX_REPLY_BYTES: number;
|
|
31
|
+
/** The longest wait a `Retry-After` may ask for and still be retried — longer, and the failure is returned at once. */
|
|
32
|
+
export declare const MAX_RETRY_WAIT_MS = 10000;
|
|
33
|
+
/** The standard OpResult code for an HTTP status that is not a success. Pure. */
|
|
34
|
+
export declare const opResultCodeOfHttpStatus: (status: number) => number;
|
|
35
|
+
declare abstract class BaseExternalApiGateway<TSettings extends Record<string, any> = Record<string, any>> {
|
|
36
|
+
protected logger: Logger;
|
|
37
|
+
protected baseUrl: string;
|
|
38
|
+
protected timeoutMs: number;
|
|
39
|
+
protected retries: number;
|
|
40
|
+
protected retryDelaysMs: number[];
|
|
41
|
+
protected fetchImpl: ExternalApiFetch;
|
|
42
|
+
private _settings;
|
|
43
|
+
private _credentials;
|
|
44
|
+
private _credentialsSet;
|
|
45
|
+
constructor(props?: BaseExternalApiGatewayPropsInterface<TSettings>);
|
|
46
|
+
/**
|
|
47
|
+
* Sets the gateway up. REPLACES whatever was set before (never merges), so re-pointing a shared instance at another
|
|
48
|
+
* tenant keeps nothing of the last one. Never throws: a setting that is missing or malformed is reported by
|
|
49
|
+
* `getConfigProblems()`, and every operation refuses with VALIDATION_FAILED until it is fixed.
|
|
50
|
+
*/
|
|
51
|
+
configure(settings: TSettings): this;
|
|
52
|
+
/** What is missing or malformed in the settings, in words — never a value. Empty when the gateway can be used. */
|
|
53
|
+
getConfigProblems(): string[];
|
|
54
|
+
/** True when the settings are complete and well-formed. */
|
|
55
|
+
isConfigured(): boolean;
|
|
56
|
+
/** The current settings. ⚠ They hold secrets: for the gateway itself, never to be logged or returned. */
|
|
57
|
+
protected get settings(): Readonly<Partial<TSettings>>;
|
|
58
|
+
/** What is wrong with these settings (override per gateway). */
|
|
59
|
+
protected validateSettings(_settings: Partial<TSettings>): string[];
|
|
60
|
+
/** The values to scrub out of every error message (override per gateway: keys, tokens, secret URLs). */
|
|
61
|
+
protected secretValues(): string[];
|
|
62
|
+
/** Called after every `configure` (override to rebuild an SDK client). */
|
|
63
|
+
protected onConfigured(): void;
|
|
64
|
+
/** The refusal every operation answers while the gateway is not set up. */
|
|
65
|
+
protected notConfigured(): OpResult;
|
|
66
|
+
/** `text` with every secret of this gateway (and `extra`) replaced by `***`. */
|
|
67
|
+
protected scrub(text: string, extra?: string[]): string;
|
|
68
|
+
/** `value` (a string, or anything JSON) with every secret replaced by `***`. */
|
|
69
|
+
protected scrubValue(value: any, extra?: string[]): any;
|
|
70
|
+
/** The words of a refusal, from the service's answer (override per gateway for its error shape). */
|
|
71
|
+
protected errorMessageOf(reply: ExternalApiReply): string;
|
|
72
|
+
/** Whether a failed attempt is worth repeating (override per gateway to refuse the hopeless ones). */
|
|
73
|
+
protected shouldRetry(result: OpResult): boolean;
|
|
74
|
+
/** How long the service asked us to wait before trying again, in ms (its `Retry-After`), or null. */
|
|
75
|
+
protected retryAfterMs(result: OpResult): number | null;
|
|
76
|
+
/**
|
|
77
|
+
* ONE attempt. OK with `{status, headers, body}` for a 2xx; else the standard code for the status (with the same data,
|
|
78
|
+
* so a gateway can read the service's own error), NETWORK_ERROR or TIMEOUT when nothing answered, VALIDATION_FAILED
|
|
79
|
+
* when the request itself could not be made (a malformed header). The reply is scrubbed and capped. Never throws.
|
|
80
|
+
* Redirects are not followed.
|
|
81
|
+
*/
|
|
82
|
+
protected request(req: ExternalApiRequest): Promise<OpResult>;
|
|
83
|
+
/**
|
|
84
|
+
* `request`, repeated while `shouldRetry` says a failure is worth it — after the service's `Retry-After` when it gave
|
|
85
|
+
* one (and not at all when it asks for longer than MAX_RETRY_WAIT_MS), else after the configured waits. Never throws.
|
|
86
|
+
*/
|
|
87
|
+
protected requestWithRetries(req: ExternalApiRequest): Promise<OpResult>;
|
|
88
|
+
setCredentials(credentials: string | Record<string, any>): this;
|
|
89
|
+
hasCredentials(): boolean;
|
|
90
|
+
protected get credentials(): string | Record<string, any>;
|
|
91
|
+
protected assertCredentials(): void;
|
|
92
|
+
protected onCredentialsSet(): void;
|
|
93
|
+
}
|
|
94
|
+
export { BaseExternalApiGateway };
|
|
@@ -0,0 +1,326 @@
|
|
|
1
|
+
"use strict";
|
|
2
|
+
var __importDefault = (this && this.__importDefault) || function (mod) {
|
|
3
|
+
return (mod && mod.__esModule) ? mod : { "default": mod };
|
|
4
|
+
};
|
|
5
|
+
Object.defineProperty(exports, "__esModule", { value: true });
|
|
6
|
+
exports.BaseExternalApiGateway = exports.opResultCodeOfHttpStatus = exports.MAX_RETRY_WAIT_MS = exports.MAX_REPLY_BYTES = void 0;
|
|
7
|
+
// ./src/gateways/BaseExternalApiGateway.ts
|
|
8
|
+
//
|
|
9
|
+
// The base of every gateway to an outside service (SendGrid, Telegram, Twilio, Slack, Discord, an HTTP webhook, Stripe…).
|
|
10
|
+
//
|
|
11
|
+
// ONE way to set a gateway up: `configure(settings)`. A gateway is created ONCE and configured — and re-configured — at
|
|
12
|
+
// run time: per brand, per tenant, per request. `configure` REPLACES the settings (never merges), so a gateway
|
|
13
|
+
// re-pointed at another tenant never keeps a value of the last one.
|
|
14
|
+
//
|
|
15
|
+
// ONE way to answer: every public operation returns an `OpResult` and never throws. An HTTP refusal maps onto the
|
|
16
|
+
// standard codes (401 → UNAUTHORIZED, 404 → NOT_FOUND, 429 → TOO_MANY_REQUESTS, 5xx → FAILED, no answer →
|
|
17
|
+
// NETWORK_ERROR / TIMEOUT), so `result.isRetryableError()` and friends mean the same thing for every gateway.
|
|
18
|
+
//
|
|
19
|
+
// ⚠ Secrets (API keys, bot tokens, webhook URLs) never leave in an error: every message is scrubbed of the values the
|
|
20
|
+
// gateway names in `secretValues()`.
|
|
21
|
+
const check_types_1 = __importDefault(require("check-types"));
|
|
22
|
+
const buffer_1 = require("buffer");
|
|
23
|
+
const promises_1 = require("timers/promises");
|
|
24
|
+
const api_helpers_1 = require("@sdflc/api-helpers");
|
|
25
|
+
const utils_1 = require("@sdflc/utils");
|
|
26
|
+
const DEFAULT_TIMEOUT_MS = 10_000;
|
|
27
|
+
const DEFAULT_RETRY_DELAYS_MS = [1000, 2000];
|
|
28
|
+
/** The most of a reply that is read: a hostile receiver must not be able to stream until memory runs out. */
|
|
29
|
+
exports.MAX_REPLY_BYTES = 64 * 1024;
|
|
30
|
+
/** The longest wait a `Retry-After` may ask for and still be retried — longer, and the failure is returned at once. */
|
|
31
|
+
exports.MAX_RETRY_WAIT_MS = 10_000;
|
|
32
|
+
/** A secret shorter than this is not scrubbed (it would garble ordinary words). */
|
|
33
|
+
const MIN_SECRET_LENGTH = 4;
|
|
34
|
+
/** The standard OpResult code for an HTTP status that is not a success. Pure. */
|
|
35
|
+
const opResultCodeOfHttpStatus = (status) => {
|
|
36
|
+
if (status === 401) {
|
|
37
|
+
return api_helpers_1.OP_RESULT_CODES.UNAUTHORIZED;
|
|
38
|
+
}
|
|
39
|
+
if (status === 403) {
|
|
40
|
+
return api_helpers_1.OP_RESULT_CODES.FORBIDDEN;
|
|
41
|
+
}
|
|
42
|
+
if (status === 404) {
|
|
43
|
+
return api_helpers_1.OP_RESULT_CODES.NOT_FOUND;
|
|
44
|
+
}
|
|
45
|
+
if (status === 408) {
|
|
46
|
+
return api_helpers_1.OP_RESULT_CODES.TIMEOUT;
|
|
47
|
+
}
|
|
48
|
+
if (status === 409) {
|
|
49
|
+
return api_helpers_1.OP_RESULT_CODES.CONFLICT;
|
|
50
|
+
}
|
|
51
|
+
if (status === 429) {
|
|
52
|
+
return api_helpers_1.OP_RESULT_CODES.TOO_MANY_REQUESTS;
|
|
53
|
+
}
|
|
54
|
+
if (status >= 500) {
|
|
55
|
+
return api_helpers_1.OP_RESULT_CODES.FAILED;
|
|
56
|
+
}
|
|
57
|
+
// Any other refusal (400, 405, 413, 422 …, or a redirect that was not followed) is about the request itself.
|
|
58
|
+
return api_helpers_1.OP_RESULT_CODES.VALIDATION_FAILED;
|
|
59
|
+
};
|
|
60
|
+
exports.opResultCodeOfHttpStatus = opResultCodeOfHttpStatus;
|
|
61
|
+
class BaseExternalApiGateway {
|
|
62
|
+
logger;
|
|
63
|
+
baseUrl;
|
|
64
|
+
timeoutMs;
|
|
65
|
+
retries;
|
|
66
|
+
retryDelaysMs;
|
|
67
|
+
fetchImpl;
|
|
68
|
+
_settings = {};
|
|
69
|
+
_credentials = null;
|
|
70
|
+
_credentialsSet = false;
|
|
71
|
+
constructor(props) {
|
|
72
|
+
const { settings, credentials, baseUrl, timeoutMs, retries, retryDelaysMs, fetch, logger } = props || {};
|
|
73
|
+
this.baseUrl = baseUrl ?? '';
|
|
74
|
+
this.timeoutMs = timeoutMs ?? DEFAULT_TIMEOUT_MS;
|
|
75
|
+
this.retries = Math.max(0, retries ?? 2);
|
|
76
|
+
this.retryDelaysMs = retryDelaysMs?.length ? retryDelaysMs : DEFAULT_RETRY_DELAYS_MS;
|
|
77
|
+
this.fetchImpl = fetch ?? ((url, init) => globalThis.fetch(url, init));
|
|
78
|
+
this.logger = (0, utils_1.isLogger)(logger) ? logger : new utils_1.Logger({ level: utils_1.LoggerLevels.ERROR });
|
|
79
|
+
if (credentials !== undefined) {
|
|
80
|
+
this.setCredentials(credentials);
|
|
81
|
+
}
|
|
82
|
+
if (settings !== undefined) {
|
|
83
|
+
this.configure(settings);
|
|
84
|
+
}
|
|
85
|
+
}
|
|
86
|
+
// ─── Settings ──────────────────────────────────────────────────────────────
|
|
87
|
+
/**
|
|
88
|
+
* Sets the gateway up. REPLACES whatever was set before (never merges), so re-pointing a shared instance at another
|
|
89
|
+
* tenant keeps nothing of the last one. Never throws: a setting that is missing or malformed is reported by
|
|
90
|
+
* `getConfigProblems()`, and every operation refuses with VALIDATION_FAILED until it is fixed.
|
|
91
|
+
*/
|
|
92
|
+
configure(settings) {
|
|
93
|
+
this._settings = { ...(settings ?? {}) };
|
|
94
|
+
this.onConfigured();
|
|
95
|
+
return this;
|
|
96
|
+
}
|
|
97
|
+
/** What is missing or malformed in the settings, in words — never a value. Empty when the gateway can be used. */
|
|
98
|
+
getConfigProblems() {
|
|
99
|
+
return this.validateSettings(this._settings);
|
|
100
|
+
}
|
|
101
|
+
/** True when the settings are complete and well-formed. */
|
|
102
|
+
isConfigured() {
|
|
103
|
+
return this.getConfigProblems().length === 0;
|
|
104
|
+
}
|
|
105
|
+
/** The current settings. ⚠ They hold secrets: for the gateway itself, never to be logged or returned. */
|
|
106
|
+
get settings() {
|
|
107
|
+
return this._settings;
|
|
108
|
+
}
|
|
109
|
+
/** What is wrong with these settings (override per gateway). */
|
|
110
|
+
validateSettings(_settings) {
|
|
111
|
+
return [];
|
|
112
|
+
}
|
|
113
|
+
/** The values to scrub out of every error message (override per gateway: keys, tokens, secret URLs). */
|
|
114
|
+
secretValues() {
|
|
115
|
+
return [];
|
|
116
|
+
}
|
|
117
|
+
/** Called after every `configure` (override to rebuild an SDK client). */
|
|
118
|
+
onConfigured() {
|
|
119
|
+
// no-op
|
|
120
|
+
}
|
|
121
|
+
/** The refusal every operation answers while the gateway is not set up. */
|
|
122
|
+
notConfigured() {
|
|
123
|
+
return api_helpers_1.OpResult.fail(api_helpers_1.OP_RESULT_CODES.VALIDATION_FAILED, null, `${this.constructor.name} is not configured: ${this.getConfigProblems().join('; ')}`);
|
|
124
|
+
}
|
|
125
|
+
// ─── Requests ──────────────────────────────────────────────────────────────
|
|
126
|
+
/** `text` with every secret of this gateway (and `extra`) replaced by `***`. */
|
|
127
|
+
scrub(text, extra = []) {
|
|
128
|
+
let out = String(text ?? '');
|
|
129
|
+
// Longest first: a secret that contains another must be replaced whole.
|
|
130
|
+
const secrets = [...this.secretValues(), ...extra]
|
|
131
|
+
.map((one) => String(one ?? ''))
|
|
132
|
+
.filter((one) => one.length >= MIN_SECRET_LENGTH)
|
|
133
|
+
.sort((a, b) => b.length - a.length);
|
|
134
|
+
for (const secret of secrets) {
|
|
135
|
+
out = out.split(secret).join('***');
|
|
136
|
+
}
|
|
137
|
+
return out;
|
|
138
|
+
}
|
|
139
|
+
/** `value` (a string, or anything JSON) with every secret replaced by `***`. */
|
|
140
|
+
scrubValue(value, extra = []) {
|
|
141
|
+
if (value === null || value === undefined) {
|
|
142
|
+
return value;
|
|
143
|
+
}
|
|
144
|
+
if (typeof value === 'string') {
|
|
145
|
+
return this.scrub(value, extra);
|
|
146
|
+
}
|
|
147
|
+
try {
|
|
148
|
+
return JSON.parse(this.scrub(JSON.stringify(value), extra));
|
|
149
|
+
}
|
|
150
|
+
catch {
|
|
151
|
+
return null;
|
|
152
|
+
}
|
|
153
|
+
}
|
|
154
|
+
/** The words of a refusal, from the service's answer (override per gateway for its error shape). */
|
|
155
|
+
errorMessageOf(reply) {
|
|
156
|
+
const body = reply.body;
|
|
157
|
+
if (typeof body === 'string') {
|
|
158
|
+
return body.slice(0, 500);
|
|
159
|
+
}
|
|
160
|
+
return String(body?.message ?? body?.error ?? body?.description ?? `HTTP ${reply.status}`).slice(0, 500);
|
|
161
|
+
}
|
|
162
|
+
/** Whether a failed attempt is worth repeating (override per gateway to refuse the hopeless ones). */
|
|
163
|
+
shouldRetry(result) {
|
|
164
|
+
return result.isRetryableError() || result.getCode() === api_helpers_1.OP_RESULT_CODES.TOO_MANY_REQUESTS;
|
|
165
|
+
}
|
|
166
|
+
/** How long the service asked us to wait before trying again, in ms (its `Retry-After`), or null. */
|
|
167
|
+
retryAfterMs(result) {
|
|
168
|
+
const raw = String(result.getDataFirst()?.headers?.['retry-after'] ?? '').trim();
|
|
169
|
+
if (!raw) {
|
|
170
|
+
return null;
|
|
171
|
+
}
|
|
172
|
+
if (/^\d+$/.test(raw)) {
|
|
173
|
+
return Number(raw) * 1000;
|
|
174
|
+
}
|
|
175
|
+
const at = Date.parse(raw);
|
|
176
|
+
return Number.isFinite(at) ? Math.max(0, at - Date.now()) : null;
|
|
177
|
+
}
|
|
178
|
+
/**
|
|
179
|
+
* ONE attempt. OK with `{status, headers, body}` for a 2xx; else the standard code for the status (with the same data,
|
|
180
|
+
* so a gateway can read the service's own error), NETWORK_ERROR or TIMEOUT when nothing answered, VALIDATION_FAILED
|
|
181
|
+
* when the request itself could not be made (a malformed header). The reply is scrubbed and capped. Never throws.
|
|
182
|
+
* Redirects are not followed.
|
|
183
|
+
*/
|
|
184
|
+
async request(req) {
|
|
185
|
+
const extra = req.secrets ?? [];
|
|
186
|
+
const headers = { ...(req.headers ?? {}) };
|
|
187
|
+
const hasHeader = (name) => Object.keys(headers).some((key) => key.toLowerCase() === name);
|
|
188
|
+
let body = req.body;
|
|
189
|
+
if (body === undefined && req.json !== undefined) {
|
|
190
|
+
body = JSON.stringify(req.json);
|
|
191
|
+
if (!hasHeader('content-type')) {
|
|
192
|
+
headers['Content-Type'] = 'application/json';
|
|
193
|
+
}
|
|
194
|
+
}
|
|
195
|
+
try {
|
|
196
|
+
const response = await this.fetchImpl(req.url, {
|
|
197
|
+
method: req.method ?? 'POST',
|
|
198
|
+
headers,
|
|
199
|
+
body,
|
|
200
|
+
// ⚠ Not followed: a redirect is where an allowed address hands the request to one that is not.
|
|
201
|
+
redirect: 'manual',
|
|
202
|
+
signal: AbortSignal.timeout(req.timeoutMs ?? this.timeoutMs),
|
|
203
|
+
});
|
|
204
|
+
const text = await readCapped(response, exports.MAX_REPLY_BYTES).catch(() => '');
|
|
205
|
+
let parsed = text || null;
|
|
206
|
+
try {
|
|
207
|
+
parsed = text ? JSON.parse(text) : null;
|
|
208
|
+
}
|
|
209
|
+
catch {
|
|
210
|
+
// Not JSON: keep the text.
|
|
211
|
+
}
|
|
212
|
+
const replyHeaders = headersOf(response.headers);
|
|
213
|
+
delete replyHeaders['set-cookie'];
|
|
214
|
+
const reply = {
|
|
215
|
+
status: Number(response.status),
|
|
216
|
+
headers: this.scrubValue(replyHeaders, extra) ?? {},
|
|
217
|
+
body: this.scrubValue(parsed, extra),
|
|
218
|
+
};
|
|
219
|
+
if (reply.status >= 200 && reply.status < 300) {
|
|
220
|
+
return api_helpers_1.OpResult.ok([reply]);
|
|
221
|
+
}
|
|
222
|
+
return api_helpers_1.OpResult.fail((0, exports.opResultCodeOfHttpStatus)(reply.status), [reply], this.scrub(`[${reply.status}] ${this.errorMessageOf(reply)}`, extra));
|
|
223
|
+
}
|
|
224
|
+
catch (e) {
|
|
225
|
+
const timedOut = e?.name === 'TimeoutError' || e?.name === 'AbortError';
|
|
226
|
+
// A request that could not even be made (a malformed header, a refused address) will not be fixed by a retry.
|
|
227
|
+
const malformed = e?.code === 'EBLOCKED' || (e instanceof TypeError && e.message !== 'fetch failed');
|
|
228
|
+
const why = timedOut
|
|
229
|
+
? `no answer within ${req.timeoutMs ?? this.timeoutMs} ms`
|
|
230
|
+
: String(e?.cause?.message ?? e?.message ?? e);
|
|
231
|
+
const code = timedOut
|
|
232
|
+
? api_helpers_1.OP_RESULT_CODES.TIMEOUT
|
|
233
|
+
: malformed
|
|
234
|
+
? api_helpers_1.OP_RESULT_CODES.VALIDATION_FAILED
|
|
235
|
+
: api_helpers_1.OP_RESULT_CODES.NETWORK_ERROR;
|
|
236
|
+
return api_helpers_1.OpResult.fail(code, null, this.scrub(why, extra).slice(0, 500));
|
|
237
|
+
}
|
|
238
|
+
}
|
|
239
|
+
/**
|
|
240
|
+
* `request`, repeated while `shouldRetry` says a failure is worth it — after the service's `Retry-After` when it gave
|
|
241
|
+
* one (and not at all when it asks for longer than MAX_RETRY_WAIT_MS), else after the configured waits. Never throws.
|
|
242
|
+
*/
|
|
243
|
+
async requestWithRetries(req) {
|
|
244
|
+
let result = await this.request(req);
|
|
245
|
+
for (let attempt = 1; attempt <= this.retries && result.didFail() && this.shouldRetry(result); attempt++) {
|
|
246
|
+
const asked = this.retryAfterMs(result);
|
|
247
|
+
if (asked !== null && asked > exports.MAX_RETRY_WAIT_MS) {
|
|
248
|
+
break;
|
|
249
|
+
}
|
|
250
|
+
this.logger.debug(`${this.constructor.name}: attempt ${attempt} failed (${result.getErrorSummary('')}), retrying`);
|
|
251
|
+
await (0, promises_1.setTimeout)(asked ?? this.retryDelaysMs[Math.min(attempt - 1, this.retryDelaysMs.length - 1)]);
|
|
252
|
+
result = await this.request(req);
|
|
253
|
+
}
|
|
254
|
+
return result;
|
|
255
|
+
}
|
|
256
|
+
// ─── Credentials (kept for gateways written before configure()) ───────────
|
|
257
|
+
setCredentials(credentials) {
|
|
258
|
+
if (!check_types_1.default.string(credentials) && !check_types_1.default.object(credentials)) {
|
|
259
|
+
throw new Error(`${this.constructor.name}.setCredentials: credentials must be a string or an object`);
|
|
260
|
+
}
|
|
261
|
+
if (check_types_1.default.string(credentials) && !credentials.trim()) {
|
|
262
|
+
throw new Error(`${this.constructor.name}.setCredentials: credentials string must not be empty`);
|
|
263
|
+
}
|
|
264
|
+
this._credentials = credentials;
|
|
265
|
+
this._credentialsSet = true;
|
|
266
|
+
this.onCredentialsSet();
|
|
267
|
+
return this;
|
|
268
|
+
}
|
|
269
|
+
hasCredentials() {
|
|
270
|
+
return this._credentialsSet;
|
|
271
|
+
}
|
|
272
|
+
get credentials() {
|
|
273
|
+
return this._credentials;
|
|
274
|
+
}
|
|
275
|
+
assertCredentials() {
|
|
276
|
+
if (!this._credentialsSet) {
|
|
277
|
+
throw new Error(`${this.constructor.name}: credentials have not been set. ` + `Call setCredentials() before making API calls.`);
|
|
278
|
+
}
|
|
279
|
+
}
|
|
280
|
+
onCredentialsSet() {
|
|
281
|
+
// no-op — override in subclass to initialise SDK clients etc.
|
|
282
|
+
}
|
|
283
|
+
}
|
|
284
|
+
exports.BaseExternalApiGateway = BaseExternalApiGateway;
|
|
285
|
+
/**
|
|
286
|
+
* A reply's text, at most `max` bytes: read through the stream and cancelled at the cap (a body without a stream is read
|
|
287
|
+
* whole and cut).
|
|
288
|
+
*/
|
|
289
|
+
const readCapped = async (response, max) => {
|
|
290
|
+
const reader = response?.body?.getReader?.();
|
|
291
|
+
if (!reader) {
|
|
292
|
+
return String((await response.text()) ?? '').slice(0, max);
|
|
293
|
+
}
|
|
294
|
+
const chunks = [];
|
|
295
|
+
let size = 0;
|
|
296
|
+
for (;;) {
|
|
297
|
+
const { done, value } = await reader.read();
|
|
298
|
+
if (done) {
|
|
299
|
+
break;
|
|
300
|
+
}
|
|
301
|
+
const chunk = buffer_1.Buffer.from(value);
|
|
302
|
+
if (size + chunk.length > max) {
|
|
303
|
+
chunks.push(chunk.subarray(0, max - size));
|
|
304
|
+
await reader.cancel().catch(() => null);
|
|
305
|
+
break;
|
|
306
|
+
}
|
|
307
|
+
chunks.push(chunk);
|
|
308
|
+
size += chunk.length;
|
|
309
|
+
}
|
|
310
|
+
return buffer_1.Buffer.concat(chunks).toString('utf8');
|
|
311
|
+
};
|
|
312
|
+
/** A fetch Headers object (or a plain one) as a lower-cased record. */
|
|
313
|
+
const headersOf = (headers) => {
|
|
314
|
+
const out = {};
|
|
315
|
+
if (headers && typeof headers.forEach === 'function') {
|
|
316
|
+
headers.forEach((value, key) => {
|
|
317
|
+
out[String(key).toLowerCase()] = String(value);
|
|
318
|
+
});
|
|
319
|
+
}
|
|
320
|
+
else if (headers && typeof headers === 'object') {
|
|
321
|
+
for (const [key, value] of Object.entries(headers)) {
|
|
322
|
+
out[key.toLowerCase()] = String(value);
|
|
323
|
+
}
|
|
324
|
+
}
|
|
325
|
+
return out;
|
|
326
|
+
};
|