@dokebi/web 0.4.2 → 0.4.4
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/AI.md +250 -39
- package/README.md +31 -10
- package/dist/app-routes.d.ts +20 -0
- package/dist/app-routes.js +137 -0
- package/dist/before-hijack.d.ts +24 -0
- package/dist/before-hijack.js +73 -0
- package/dist/body.d.ts +14 -0
- package/dist/body.js +30 -0
- package/dist/cluster-ready.d.ts +67 -0
- package/dist/cluster-ready.js +123 -0
- package/dist/compilers.d.ts +16 -0
- package/dist/compilers.js +25 -0
- package/dist/compression.d.ts +40 -0
- package/dist/compression.js +435 -0
- package/dist/connections.d.ts +44 -0
- package/dist/connections.js +282 -0
- package/dist/define-errors.d.ts +76 -0
- package/dist/define-errors.js +161 -0
- package/dist/describe.d.ts +37 -0
- package/dist/describe.js +96 -0
- package/dist/errors.d.ts +1 -1
- package/dist/errors.js +24 -3
- package/dist/forms.d.ts +23 -7
- package/dist/forms.js +53 -13
- package/dist/index.d.ts +134 -4
- package/dist/index.js +1552 -91
- package/dist/options.d.ts +56 -0
- package/dist/options.js +320 -1
- package/dist/points.d.ts +159 -0
- package/dist/points.js +162 -1
- package/dist/responses.d.ts +31 -6
- package/dist/responses.js +68 -6
- package/dist/route-config.d.ts +38 -0
- package/dist/route-config.js +222 -0
- package/dist/route-hooks.d.ts +75 -0
- package/dist/route-hooks.js +118 -0
- package/dist/route-table.d.ts +55 -0
- package/dist/route-table.js +142 -0
- package/dist/seal.d.ts +49 -1
- package/dist/seal.js +259 -24
- package/dist/security-headers.d.ts +121 -0
- package/dist/security-headers.js +298 -0
- package/dist/transient-log.d.ts +42 -0
- package/dist/transient-log.js +95 -0
- package/options.schema.json +488 -1
- package/package.json +22 -9
package/dist/index.js
CHANGED
|
@@ -1,23 +1,43 @@
|
|
|
1
1
|
import { createHmac } from 'node:crypto';
|
|
2
|
-
import { Server } from 'node:net';
|
|
2
|
+
import { BlockList, Server } from 'node:net';
|
|
3
3
|
import { parse as parseQuery } from 'node:querystring';
|
|
4
4
|
import { setTimeout as delay, setImmediate as immediate } from 'node:timers/promises';
|
|
5
5
|
import { types } from 'node:util';
|
|
6
|
-
import { createExtension, definePlugin, definePoint, dependencyOf, EXTENSION_BRAND, optionalDependency, } from '@dokebi/core';
|
|
6
|
+
import { createExtension, DokebiError, definePlugin, definePoint, dependencyOf, EXTENSION_BRAND, optionalDependency, } from '@dokebi/core';
|
|
7
7
|
import { diagnostics } from '@dokebi/core/libraries';
|
|
8
|
+
import underPressure from '@fastify/under-pressure';
|
|
8
9
|
import Fastify, {} from 'fastify';
|
|
9
|
-
import {
|
|
10
|
+
import { AppRoutes, appNames } from './app-routes.js';
|
|
11
|
+
import { bodyFollows, hasBody, http1 } from './body.js';
|
|
12
|
+
import { ClusterReadiness, readyBridge } from './cluster-ready.js';
|
|
13
|
+
import { errorHandlerSymbols, lazyCompilers, restoreDefaultCompilers, routeContextSymbol, } from './compilers.js';
|
|
14
|
+
import { ResponseCompression } from './compression.js';
|
|
15
|
+
import { WebConnections } from './connections.js';
|
|
16
|
+
import { INTENDED_REFUSAL } from './define-errors.js';
|
|
17
|
+
import { describePoint, describeRoutes } from './describe.js';
|
|
10
18
|
import { WebError } from './errors.js';
|
|
11
19
|
import { WebExtension, webHooks, } from './extension.js';
|
|
12
20
|
import { options as declaration } from './options.js';
|
|
13
|
-
import {
|
|
14
|
-
import {
|
|
21
|
+
import { errorTranslators, pluginRouteIds, } from './points.js';
|
|
22
|
+
import { clientStatus, dokebiError, errorAnswer, errorPage, FORM_SUBMISSION_HEADER, productionBody, requestErrorFormat, sendableDetails, validAnswer, } from './responses.js';
|
|
23
|
+
import { MAX_TIMEOUT_MS, RouteConfigKeys } from './route-config.js';
|
|
24
|
+
import { COMPLETED, RouteHooks, } from './route-hooks.js';
|
|
25
|
+
import { RouteTable } from './route-table.js';
|
|
26
|
+
import { checkSealSetting, formMarkerRefusal, RECORDED, sealExclude, sealedFormRedirect, WebSealing, } from './seal.js';
|
|
27
|
+
import { contributionProblem, SecurityHeaders, } from './security-headers.js';
|
|
28
|
+
import { TransientLog } from './transient-log.js';
|
|
29
|
+
export { appNames } from './app-routes.js';
|
|
30
|
+
export { BEFORE_HIJACK, beforeHijackSteps, runBeforeHijack, } from './before-hijack.js';
|
|
31
|
+
export { skipCompression, } from './compression.js';
|
|
32
|
+
export { defineErrors, ERROR_CATALOG, errorCatalog, INTENDED_REFUSAL, } from './define-errors.js';
|
|
15
33
|
export { validationError, WebError, WebValidationError, } from './errors.js';
|
|
16
34
|
export { WebExtension, } from './extension.js';
|
|
17
35
|
export { formBackTarget, formFieldErrors, formOldInput, isFormSubmission, } from './forms.js';
|
|
18
36
|
export { options } from './options.js';
|
|
19
|
-
export {
|
|
20
|
-
export {
|
|
37
|
+
export { APP_NAME, APP_NAMES_MAX, appOption, appUrlMatch, pluginRouteIds, ROUTE_ID, ROUTE_OWNER, routeIdsOption, routeNamespace, } from './points.js';
|
|
38
|
+
export { errorFormat, FORM_SUBMISSION_HEADER, requestErrorFormat, SEALED_FETCH_HEADER, } from './responses.js';
|
|
39
|
+
export { SEALED_LOCATION_HEADER, SEALED_PATH_HEADER, } from './seal.js';
|
|
40
|
+
export { DEFAULT_DIRECTIVES, } from './security-headers.js';
|
|
21
41
|
/** Set by `dokebi verify` on the app it starts (D-0065 §11); the header echoes it. */
|
|
22
42
|
const VERIFY_TOKEN_ENV = 'DOKEBI_VERIFY_TOKEN';
|
|
23
43
|
const VERIFY_HEADER = 'x-dokebi-verify';
|
|
@@ -31,9 +51,28 @@ const INSTANCE_HEADER = 'x-dokebi-instance';
|
|
|
31
51
|
const INSTANCE_TOKEN = /^[A-Za-z0-9_-]{16,128}$/;
|
|
32
52
|
const INSTANCE_CHALLENGE = /^[A-Za-z0-9_-]{16,128}$/;
|
|
33
53
|
const { describeError, Repeats } = diagnostics;
|
|
54
|
+
// Not `import … from 'node:http'` for values: its ESM facade loads undici (responses.ts).
|
|
55
|
+
const { validateHeaderName, validateHeaderValue } = process.getBuiltinModule('node:http');
|
|
34
56
|
const EXTENSION_FILE = 'src/infra/web/extension.ts';
|
|
35
57
|
/** IPv4-mapped IPv6 (`::ffff:127.0.0.1`) compares as plain IPv4. */
|
|
36
58
|
const plainAddress = (address) => address.replace(/^::ffff:(?=\d+\.\d+\.\d+\.\d+$)/, '');
|
|
59
|
+
/** Loopback, private and link-local peers: where a tunnel or proxy of this deployment connects from. */
|
|
60
|
+
const LOCAL_PEERS = new BlockList();
|
|
61
|
+
for (const [address, prefix] of [
|
|
62
|
+
['127.0.0.0', 8],
|
|
63
|
+
['10.0.0.0', 8],
|
|
64
|
+
['172.16.0.0', 12],
|
|
65
|
+
['192.168.0.0', 16],
|
|
66
|
+
['169.254.0.0', 16],
|
|
67
|
+
['100.64.0.0', 10],
|
|
68
|
+
])
|
|
69
|
+
LOCAL_PEERS.addSubnet(address, prefix, 'ipv4');
|
|
70
|
+
for (const [address, prefix] of [
|
|
71
|
+
['::1', 128],
|
|
72
|
+
['fc00::', 7],
|
|
73
|
+
['fe80::', 10],
|
|
74
|
+
])
|
|
75
|
+
LOCAL_PEERS.addSubnet(address, prefix, 'ipv6');
|
|
37
76
|
function settings(parsed) {
|
|
38
77
|
return Object.freeze({
|
|
39
78
|
...parsed,
|
|
@@ -41,14 +80,20 @@ function settings(parsed) {
|
|
|
41
80
|
sealExclude: sealExclude(parsed.sealExclude),
|
|
42
81
|
});
|
|
43
82
|
}
|
|
44
|
-
/** Fastify creation options that belong to the drain contract (D-0023, D-0036). */
|
|
45
|
-
const PINNED = Object.freeze({ return503OnClosing: true, forceCloseConnections: 'idle' });
|
|
46
|
-
const FORM_TYPE = 'application/x-www-form-urlencoded';
|
|
47
83
|
/**
|
|
48
|
-
* How long a draining
|
|
49
|
-
*
|
|
84
|
+
* How long before the drain deadline a draining worker's idle wait ends (D-0036): closing the
|
|
85
|
+
* idle connections is one synchronous sweep, then the drain returns once the answers under way
|
|
86
|
+
* have ended. 100 ms leaves that a few event loop turns even on a loaded machine, and is a small
|
|
87
|
+
* part of any useful deadline (the default is 20 s).
|
|
50
88
|
*/
|
|
51
|
-
const
|
|
89
|
+
const DEADLINE_MARGIN_MS = 100;
|
|
90
|
+
// `http1`: HTTP/2 has no connection-specific headers (RFC 9113 §8.2.2): Node drops a `connection`
|
|
91
|
+
// header there with a process warning on stderr, past the logger, and a session ends by GOAWAY,
|
|
92
|
+
// never by a closed socket under one stream. `bodyFollows`: one rule for HTTP/1 and HTTP/2.
|
|
93
|
+
const PINNED = Object.freeze({ return503OnClosing: true, forceCloseConnections: 'idle' });
|
|
94
|
+
const FORM_TYPE = 'application/x-www-form-urlencoded';
|
|
95
|
+
/** D-0122: the raw binary body `binaryBody` parses. */
|
|
96
|
+
const BINARY_TYPE = 'application/octet-stream';
|
|
52
97
|
const injectPoint = definePoint('dokebi-testing:inject');
|
|
53
98
|
const hooks = new Map([
|
|
54
99
|
['onRequest', 2],
|
|
@@ -73,6 +118,54 @@ const REPLY = Symbol('dokebi.web.reply');
|
|
|
73
118
|
const HANDLER = Symbol('dokebi.web.handler');
|
|
74
119
|
const SENDING = Symbol('dokebi.web.sending');
|
|
75
120
|
const ABORTED = Symbol('dokebi.web.aborted');
|
|
121
|
+
/** The `completed` observers of a request's route, and when its first onRequest step ran. */
|
|
122
|
+
const COMPLETING = Symbol('dokebi.web.completing');
|
|
123
|
+
const STARTED = Symbol('dokebi.web.started');
|
|
124
|
+
const ROUTE_CONTEXT = routeContextSymbol();
|
|
125
|
+
/** How many times web's error handler ran for this response (its own answer may fail too). */
|
|
126
|
+
const ERROR_PASS = Symbol('dokebi.web.errorPass');
|
|
127
|
+
/** On the raw request whose body is still arriving: its requestTimeoutMs timer. */
|
|
128
|
+
const BODY_TIMER = Symbol('dokebi.web.bodyTimer');
|
|
129
|
+
/** On the raw request whose body did not arrive in time (answered 408 or cut). */
|
|
130
|
+
const TIMED_OUT = Symbol('dokebi.web.timedOut');
|
|
131
|
+
/** The error of a body that did not arrive in time: the 408 answer, and what its reader gets. */
|
|
132
|
+
function bodyTimeout(ms) {
|
|
133
|
+
return new WebError('REQUEST_TIMEOUT', `The request body did not arrive within ${ms} ms`, {
|
|
134
|
+
data: { timeoutMs: ms },
|
|
135
|
+
});
|
|
136
|
+
}
|
|
137
|
+
/**
|
|
138
|
+
* HTTP/2 after a 408: the server's half of the stream ends with the answer, the client's stays
|
|
139
|
+
* open while the stalled client neither sends nor ends it — and with it the request, its reader
|
|
140
|
+
* and the drain (until the drain deadline: DRAIN_FAILED). Once the answer is written the reader
|
|
141
|
+
* of the body fails, as over HTTP/1 when the connection closes (a stream that simply ended would
|
|
142
|
+
* read as a complete, truncated body), and the stream ends with RST_STREAM NO_ERROR, the way RFC
|
|
143
|
+
* 9113 §8.1 gives a server to stop a request body after a complete answer.
|
|
144
|
+
*/
|
|
145
|
+
function endStreamAfterAnswer(request, ms) {
|
|
146
|
+
const stream = request.stream;
|
|
147
|
+
if (stream === undefined)
|
|
148
|
+
return;
|
|
149
|
+
const end = () => {
|
|
150
|
+
// A plain Readable emits its error whether or not anyone listens (an IncomingMessage only
|
|
151
|
+
// to listeners): without a reader there is nothing to tell, and no uncaught 'error'.
|
|
152
|
+
if (!request.destroyed && !request.readableEnded)
|
|
153
|
+
request.destroy(request.listenerCount('error') > 0 ? bodyTimeout(ms) : undefined);
|
|
154
|
+
if (!stream.closed)
|
|
155
|
+
stream.close(0);
|
|
156
|
+
};
|
|
157
|
+
if (stream.writableFinished)
|
|
158
|
+
end();
|
|
159
|
+
else
|
|
160
|
+
stream.once('finish', end);
|
|
161
|
+
}
|
|
162
|
+
/** The shared 'end' listener of a request whose body is timed (`this` is the raw request). */
|
|
163
|
+
function clearBodyTimer() {
|
|
164
|
+
if (this[BODY_TIMER] !== undefined) {
|
|
165
|
+
clearTimeout(this[BODY_TIMER]);
|
|
166
|
+
this[BODY_TIMER] = undefined;
|
|
167
|
+
}
|
|
168
|
+
}
|
|
76
169
|
function thenable(value) {
|
|
77
170
|
return (value !== null &&
|
|
78
171
|
(typeof value === 'object' || typeof value === 'function') &&
|
|
@@ -137,6 +230,30 @@ const UNAVAILABLE = {
|
|
|
137
230
|
NOT_READY: 'The application is not ready. Try again in a moment.',
|
|
138
231
|
DRAINING: 'The application is restarting. Try again in a moment.',
|
|
139
232
|
};
|
|
233
|
+
/**
|
|
234
|
+
* The headers that describe the resource a handler was about to send. An error answer is not that
|
|
235
|
+
* resource: kept, a 404 would go out cached for a year as immutable, with the resource's ETag (a
|
|
236
|
+
* later If-None-Match answers 304 to the error), or as a download.
|
|
237
|
+
*/
|
|
238
|
+
const RESOURCE_HEADERS = [
|
|
239
|
+
'etag',
|
|
240
|
+
'last-modified',
|
|
241
|
+
'expires',
|
|
242
|
+
'content-disposition',
|
|
243
|
+
'accept-ranges',
|
|
244
|
+
'content-range',
|
|
245
|
+
];
|
|
246
|
+
/**
|
|
247
|
+
* Clears the resource headers off an error answer and makes it `no-store`; a 416 keeps its
|
|
248
|
+
* `Content-Range: bytes *` + `/size` (RFC 9110 §15.5.17). Error responders run after and may set
|
|
249
|
+
* their own.
|
|
250
|
+
*/
|
|
251
|
+
function clearResourceHeaders(reply, status) {
|
|
252
|
+
for (const name of RESOURCE_HEADERS)
|
|
253
|
+
if ((name !== 'content-range' || status !== 416) && reply.hasHeader(name))
|
|
254
|
+
reply.removeHeader(name);
|
|
255
|
+
reply.header('cache-control', 'no-store');
|
|
256
|
+
}
|
|
140
257
|
/** A usable `unavailable` result: a 4xx/5xx status, string headers, synchronous. */
|
|
141
258
|
function validRefusal(value) {
|
|
142
259
|
if (value === null || typeof value !== 'object' || 'then' in value)
|
|
@@ -151,6 +268,28 @@ function validRefusal(value) {
|
|
|
151
268
|
typeof headers === 'object' &&
|
|
152
269
|
Object.values(headers).every((item) => typeof item === 'string'))));
|
|
153
270
|
}
|
|
271
|
+
/**
|
|
272
|
+
* Whether a thrown value goes to the error translators (D-0093): `any` for an uncoded error that
|
|
273
|
+
* would answer 500 (no Fastify 4xx), `server-only` for a Dokebi error answering 500 (only a 5xx
|
|
274
|
+
* translation replaces it): a plugin's coded failure around a cause, or a plugin's own error that
|
|
275
|
+
* its translator knows (a Redis QUEUE_FULL, D-0102); `no` otherwise.
|
|
276
|
+
*/
|
|
277
|
+
function translatable(thrown) {
|
|
278
|
+
const known = dokebiError(thrown);
|
|
279
|
+
if (known === undefined)
|
|
280
|
+
return clientStatus(thrown) ? 'no' : 'any';
|
|
281
|
+
return (known.status ?? clientStatus(thrown) ?? 500) === 500 ? 'server-only' : 'no';
|
|
282
|
+
}
|
|
283
|
+
/**
|
|
284
|
+
* The contributions of `dokebi-web:error-translator` (D-0093), checked once at setup: each must
|
|
285
|
+
* be `{ translate(error, request) }`, or the setup fails with INVALID_ERROR_TRANSLATOR.
|
|
286
|
+
*/
|
|
287
|
+
function checkTranslators(contributions) {
|
|
288
|
+
for (const { plugin, value } of contributions)
|
|
289
|
+
if (typeof value?.translate !== 'function')
|
|
290
|
+
throw new WebError('INVALID_ERROR_TRANSLATOR', `${plugin} contributed an invalid error translator`, { data: { translator: plugin } });
|
|
291
|
+
return Object.freeze([...contributions]);
|
|
292
|
+
}
|
|
154
293
|
class WebOwner {
|
|
155
294
|
context;
|
|
156
295
|
options;
|
|
@@ -167,37 +306,101 @@ class WebOwner {
|
|
|
167
306
|
}
|
|
168
307
|
};
|
|
169
308
|
#wrapped = new WeakSet();
|
|
309
|
+
#responseHookFailures;
|
|
310
|
+
/** Retryable 503s: the first of a window in full, the rest counted (D-0113). */
|
|
311
|
+
#transient;
|
|
170
312
|
#closed = false;
|
|
313
|
+
/** The server's connections: what close, a worker's drain and the deadline end (D-0023). */
|
|
314
|
+
#connections;
|
|
171
315
|
#frozen = false;
|
|
172
316
|
#draining = false;
|
|
317
|
+
/** A draining worker's idle wait ended and it closed the connections still idle (D-0036). */
|
|
318
|
+
#idleClosed = false;
|
|
173
319
|
#address;
|
|
174
320
|
#sealing;
|
|
321
|
+
/** D-0149: the security headers of every answer. */
|
|
322
|
+
#security;
|
|
323
|
+
/** D-0150: the overload limits and answers; undefined when protection is off. */
|
|
324
|
+
#shedding;
|
|
325
|
+
#sampler;
|
|
326
|
+
/** The reason the last sample was over a limit, read by onRequest. */
|
|
327
|
+
#pressure;
|
|
175
328
|
/** Error responders, the last added first (D-0074). */
|
|
176
329
|
#responders = [];
|
|
330
|
+
/** Contributions of `dokebi-web:error-translator` in setup order (D-0093). */
|
|
331
|
+
#translators;
|
|
332
|
+
/** Route config keys of other plugins, checked at start (D-0076 §5). */
|
|
333
|
+
#routeConfig = new RouteConfigKeys();
|
|
334
|
+
/** Routes bound to apps and the app routing of @dokebi/app (D-0132). */
|
|
335
|
+
#appRoutes;
|
|
336
|
+
/** Per-route hooks of other plugins (D-0076 §3.8). */
|
|
337
|
+
#routeHooks = new RouteHooks((hook) => this.#hook('onResponse', hook));
|
|
338
|
+
/**
|
|
339
|
+
* Every route with its id (D-0077 A): `routes()`, and the duplicate id check at start. In
|
|
340
|
+
* describe mode it also keeps each route's schema and config values (D-0077 B).
|
|
341
|
+
*/
|
|
342
|
+
#routeTable;
|
|
177
343
|
api;
|
|
178
344
|
/** A node:cluster worker (D-0063 `context.runtime`): it listens from `ready` and drains first. */
|
|
179
345
|
#worker;
|
|
180
346
|
/** Error bodies without `fix`, `details` and 5xx messages (D-0063 §1). */
|
|
181
347
|
#production;
|
|
348
|
+
/** How long a draining worker stays after it stopped listening (D-0154: reloadable). */
|
|
349
|
+
#drainGraceMs;
|
|
350
|
+
/** How long a draining worker keeps idle keep-alive connections for a next request (D-0036). */
|
|
351
|
+
#drainIdleMs;
|
|
352
|
+
/** `Retry-After` (seconds, as text) of the 503 refusals while starting, unready or draining. */
|
|
353
|
+
#unavailableRetryAfter;
|
|
354
|
+
/** The longest time a body may take to arrive: requestTimeoutMs or a route's own (onRoute). */
|
|
355
|
+
#longestBodyMs;
|
|
356
|
+
/** Where the next error of a reply goes after web's pass `pass` of it (set in the constructor). */
|
|
357
|
+
#nextHandler = () => { };
|
|
182
358
|
#hooks;
|
|
183
359
|
#overridden;
|
|
184
360
|
#https;
|
|
185
|
-
constructor(context, options, extension, health) {
|
|
361
|
+
constructor(context, options, extension, health, logging) {
|
|
186
362
|
this.context = context;
|
|
187
363
|
this.options = options;
|
|
188
364
|
const logger = context.logger;
|
|
189
365
|
const runtime = context.runtime ?? context.app.runtime;
|
|
190
366
|
this.#worker = runtime.role === 'worker';
|
|
367
|
+
this.#routeTable = new RouteTable(runtime.describing === true);
|
|
368
|
+
this.#appRoutes = new AppRoutes(context);
|
|
191
369
|
this.#production = process.env.NODE_ENV === 'production' || !options.developmentErrors;
|
|
370
|
+
this.#drainGraceMs = options.drainGraceMs;
|
|
371
|
+
this.#drainIdleMs = options.drainIdleMs;
|
|
372
|
+
this.#unavailableRetryAfter = String(Math.ceil(options.unavailableRetryAfterMs / 1000));
|
|
373
|
+
this.#longestBodyMs = options.requestTimeoutMs;
|
|
374
|
+
this.#transient = new TransientLog({
|
|
375
|
+
logger,
|
|
376
|
+
windowMs: options.transientLogWindowMs,
|
|
377
|
+
maxKeys: options.transientLogMaxKeys,
|
|
378
|
+
level: options.transientLogLevel,
|
|
379
|
+
});
|
|
192
380
|
this.#hooks = extension.hooks;
|
|
193
381
|
this.#overridden = extension.overridden;
|
|
194
382
|
// Fastify's schema compilers are loaded when a route first needs one (compilers.ts).
|
|
195
383
|
const schemaController = lazyCompilers();
|
|
196
384
|
const defaults = {
|
|
197
|
-
|
|
385
|
+
// D-0151: Fastify's records through this plugin's logger when @dokebi/logger asks for them.
|
|
386
|
+
...(logging?.requests === true
|
|
387
|
+
? { loggerInstance: logging.fastifyLogger(logger) }
|
|
388
|
+
: { logger: false }),
|
|
198
389
|
bodyLimit: options.maxBodyBytes,
|
|
199
390
|
requestTimeout: options.requestTimeoutMs,
|
|
200
391
|
schemaController,
|
|
392
|
+
ajv: {
|
|
393
|
+
customOptions: {
|
|
394
|
+
// Fastify's Ajv drops the fields a schema does not allow (removeAdditional); `refuse`
|
|
395
|
+
// validates them instead: 422 VALIDATION_FAILED, `<field>` is not allowed.
|
|
396
|
+
...(options.unknownFields === 'refuse' ? { removeAdditional: false } : {}),
|
|
397
|
+
// A union type (`type: ['string', 'number']`) is valid JSON Schema; Ajv's strict mode
|
|
398
|
+
// printed a warning for it at every start (community request B2).
|
|
399
|
+
allowUnionTypes: true,
|
|
400
|
+
// D-0047: what Ajv still reports goes through this logger, not console.
|
|
401
|
+
logger: schemaLogger(logger),
|
|
402
|
+
},
|
|
403
|
+
},
|
|
201
404
|
...PINNED,
|
|
202
405
|
...(options.trustProxy.length ? { trustProxy: [...options.trustProxy] } : {}),
|
|
203
406
|
};
|
|
@@ -205,12 +408,53 @@ class WebOwner {
|
|
|
205
408
|
this.#https = Boolean(created.https);
|
|
206
409
|
// HTTPS and HTTP/2 change only the raw server type; the API is typed for the default one.
|
|
207
410
|
this.server = Fastify(created);
|
|
411
|
+
this.#connections = new WebConnections(this.server.server, {
|
|
412
|
+
secure: this.#https,
|
|
413
|
+
http2: created.http2 === true,
|
|
414
|
+
logger,
|
|
415
|
+
});
|
|
416
|
+
// A request Node's HTTP parser refuses (a malformed line, data after `Connection: close`, a
|
|
417
|
+
// header block too large, a request timeout) gets Fastify's bare 400/408/431 before any route,
|
|
418
|
+
// and Fastify records it only at trace. From a peer in trustProxy (the deployment's own
|
|
419
|
+
// proxy) that is a configuration fault to fix: a warning, once per window, peer and code.
|
|
420
|
+
// From any other peer it is debug: an internet client may send anything. The request bytes
|
|
421
|
+
// (`rawPacket`) can hold tokens and are never logged. Prepended: Fastify's own listener
|
|
422
|
+
// answers and destroys the socket, after which its peer address is gone.
|
|
423
|
+
const clientErrors = new Repeats({ intervalMs: options.logRepeatWindowMs });
|
|
424
|
+
this.server.server.prependListener('clientError', (error, socket) => {
|
|
425
|
+
if (error.code === 'ECONNRESET' || socket.destroyed)
|
|
426
|
+
return;
|
|
427
|
+
const peer = plainAddress(socket.remoteAddress ?? '?');
|
|
428
|
+
const proxy = options.trustProxy.includes(peer);
|
|
429
|
+
if (!proxy && !logger.isEnabled('debug'))
|
|
430
|
+
return;
|
|
431
|
+
const code = typeof error.code === 'string' ? error.code : 'UNKNOWN';
|
|
432
|
+
const repeated = proxy ? clientErrors.take(`${peer} ${code}`) : 0;
|
|
433
|
+
if (repeated === undefined)
|
|
434
|
+
return;
|
|
435
|
+
logger.log(proxy ? 'warn' : 'debug', 'A request was refused before any route', {
|
|
436
|
+
code: 'WEB_CLIENT_ERROR',
|
|
437
|
+
error: code,
|
|
438
|
+
...(typeof error.reason === 'string' ? { reason: error.reason.slice(0, 200) } : {}),
|
|
439
|
+
...(typeof error.bytesParsed === 'number' ? { bytesParsed: error.bytesParsed } : {}),
|
|
440
|
+
status: code === 'ERR_HTTP_REQUEST_TIMEOUT' ? 408 : code === 'HPE_HEADER_OVERFLOW' ? 431 : 400,
|
|
441
|
+
remote: peer,
|
|
442
|
+
...(proxy
|
|
443
|
+
? {
|
|
444
|
+
fix: 'The peer is your proxy (trustProxy): check what it sends upstream. HPE_CLOSED_CONNECTION: it reused a connection the app answered with close (send Connection "" upstream with keepalive, as deploy proxy --nginx writes it).',
|
|
445
|
+
}
|
|
446
|
+
: {}),
|
|
447
|
+
...(repeated ? { repeated } : {}),
|
|
448
|
+
});
|
|
449
|
+
});
|
|
208
450
|
const lazySchemas = restoreDefaultCompilers(this.server, created.schemaController, schemaController);
|
|
209
451
|
const owner = this;
|
|
210
452
|
logger.log('debug', 'Web server configured', {
|
|
211
453
|
host: options.host,
|
|
212
454
|
port: options.port,
|
|
213
455
|
bodyLimit: options.maxBodyBytes,
|
|
456
|
+
maxRouteBodyBytes: options.maxRouteBodyBytes,
|
|
457
|
+
binaryBody: options.binaryBody,
|
|
214
458
|
requestTimeout: options.requestTimeoutMs,
|
|
215
459
|
healthRoutes: options.healthRoutes ? { ...options.healthRoutes } : false,
|
|
216
460
|
trustProxy: options.trustProxy.length,
|
|
@@ -218,8 +462,18 @@ class WebOwner {
|
|
|
218
462
|
sealExclude: options.sealExclude.length,
|
|
219
463
|
formBody: options.formBody,
|
|
220
464
|
formMaxFields: options.formMaxFields,
|
|
465
|
+
unknownFields: options.unknownFields,
|
|
466
|
+
transientLog: {
|
|
467
|
+
windowMs: options.transientLogWindowMs,
|
|
468
|
+
maxKeys: options.transientLogMaxKeys,
|
|
469
|
+
level: options.transientLogLevel,
|
|
470
|
+
},
|
|
471
|
+
compression: options.compression.enabled
|
|
472
|
+
? { ...options.compression, encodings: [...options.compression.encodings] }
|
|
473
|
+
: false,
|
|
221
474
|
errorBodies: this.#production ? 'production' : 'development',
|
|
222
475
|
health: health !== undefined,
|
|
476
|
+
requestLog: logging?.requests === true,
|
|
223
477
|
// `lazy`: Fastify's default compilers, loaded on the first schema route (D-0070 §5).
|
|
224
478
|
schemaCompilers: lazySchemas ? 'lazy' : 'extension',
|
|
225
479
|
role: runtime.role,
|
|
@@ -227,14 +481,54 @@ class WebOwner {
|
|
|
227
481
|
extension: [...this.#overridden],
|
|
228
482
|
...(created === defaults ? {} : { fastifyOptions: Object.keys(created).sort() }),
|
|
229
483
|
});
|
|
230
|
-
|
|
484
|
+
this.#translators = checkTranslators(context.collect(errorTranslators));
|
|
485
|
+
if (this.#translators.length)
|
|
486
|
+
logger.log('debug', 'Web error translators collected', {
|
|
487
|
+
translators: this.#translators.map((item) => item.plugin),
|
|
488
|
+
});
|
|
489
|
+
const failures = new Repeats({ intervalMs: options.logRepeatWindowMs });
|
|
490
|
+
// With @dokebi/logger's request log Fastify writes its own records (D-0151), among them the
|
|
491
|
+
// error of a handler that failed after its answer was sent; without it web says so itself.
|
|
492
|
+
const fastifyLogs = logging?.requests === true;
|
|
231
493
|
this.server.setErrorHandler((error, request, reply) => this.#fail(error, request, reply, failures));
|
|
494
|
+
// An error raised while web sends its own error answer (an async onSend step: the session's
|
|
495
|
+
// save in a Redis outage) goes to the next handler of Fastify's chain, its default one, which
|
|
496
|
+
// answers in Fastify's own shape (audit r4 step 2). web keeps the chain on itself for that
|
|
497
|
+
// second error, then on a last step that ends the connection (lib/error-handler.js).
|
|
498
|
+
const { kErrorHandler, kReplyNextErrorHandler } = errorHandlerSymbols();
|
|
499
|
+
const own = this.server[kErrorHandler];
|
|
500
|
+
const last = Object.assign(Object.create(Object.getPrototypeOf(own)), {
|
|
501
|
+
func: (error, request, reply) => this.#answerFailed(error, request, reply, failures),
|
|
502
|
+
});
|
|
503
|
+
this.#nextHandler = (reply, pass) => {
|
|
504
|
+
reply[kReplyNextErrorHandler] =
|
|
505
|
+
pass === 1 ? own : last;
|
|
506
|
+
};
|
|
232
507
|
// An unknown route answers like any other error (D-0074): the same body, format and
|
|
233
508
|
// responders (an app's errors/404.ejs), not Fastify's own `{ message, error, statusCode }`.
|
|
234
509
|
this.server.setNotFoundHandler((request, reply) => this.#fail(new WebError('NOT_FOUND', `No route for ${request.method} ${request.url.split('?', 1)[0]?.slice(0, 200)}`), request, reply, failures));
|
|
235
510
|
// D-0062: the seal slot. Its hook steps do nothing until something asks for sealing.
|
|
236
|
-
const sealing = new WebSealing(logger, {
|
|
511
|
+
const sealing = new WebSealing(logger, {
|
|
512
|
+
driftMs: options.sealDriftMs,
|
|
513
|
+
exclude: options.sealExclude,
|
|
514
|
+
formBody: options.formBody,
|
|
515
|
+
formMaxFields: options.formMaxFields,
|
|
516
|
+
retryAfterMs: options.sealRetryAfterMs,
|
|
517
|
+
logRepeatWindowMs: options.logRepeatWindowMs,
|
|
518
|
+
}, (request) => this.api.requestHost(request));
|
|
237
519
|
this.#sealing = sealing;
|
|
520
|
+
/** D-0181: what tells a request's app (dokebi-app), asked by appOf. */
|
|
521
|
+
const appResolvers = [];
|
|
522
|
+
const security = new SecurityHeaders(options.securityHeaders);
|
|
523
|
+
this.#security = security;
|
|
524
|
+
// D-0125: the last onSend step of every route (added in onRoute below) and of 404 answers.
|
|
525
|
+
const compression = options.compression.enabled
|
|
526
|
+
? new ResponseCompression(options.compression, logger, {
|
|
527
|
+
draining: () => this.#draining,
|
|
528
|
+
// A sealed body is a ciphertext: compressing it gains nothing.
|
|
529
|
+
sealType: () => sealing.provider?.contentType,
|
|
530
|
+
}, options.logRepeatWindowMs)
|
|
531
|
+
: undefined;
|
|
238
532
|
// A request is held from here until its response closes (D-0068): one counter and one shared
|
|
239
533
|
// listener, no Promise or closure per request. Callback style: no Promise per hook either.
|
|
240
534
|
const closed = function () {
|
|
@@ -282,47 +576,133 @@ class WebOwner {
|
|
|
282
576
|
});
|
|
283
577
|
}
|
|
284
578
|
this.server.addHook('onRequest', (request, reply, done) => {
|
|
285
|
-
|
|
286
|
-
|
|
287
|
-
//
|
|
288
|
-
//
|
|
289
|
-
|
|
290
|
-
|
|
291
|
-
|
|
292
|
-
|
|
293
|
-
|
|
294
|
-
|
|
295
|
-
|
|
296
|
-
|
|
297
|
-
|
|
298
|
-
|
|
299
|
-
|
|
300
|
-
|
|
301
|
-
|
|
302
|
-
|
|
303
|
-
|
|
304
|
-
|
|
579
|
+
const state = context.app.state;
|
|
580
|
+
// The running state is decided without the route: `request.routeOptions` builds a new
|
|
581
|
+
// object on every read, so it is read only while requests may be turned away. A health
|
|
582
|
+
// request of the running state is held like any other (it ends at once).
|
|
583
|
+
if (this.#draining || state !== 'running' || (health && !health.ready)) {
|
|
584
|
+
const config = request.routeOptions.config;
|
|
585
|
+
// Health routes answer before ready and while draining, untracked.
|
|
586
|
+
if (config.dokebiHealth === true)
|
|
587
|
+
return done();
|
|
588
|
+
// The app is stopping once its drain began, also while the plugins that depend on web
|
|
589
|
+
// (sse, websocket) drain before web's own drain starts (audit r4 step 2: those requests
|
|
590
|
+
// were refused as STARTING, on a cluster worker that still listened).
|
|
591
|
+
const stopping = this.#draining || state === 'stopping' || state === 'cleaning';
|
|
592
|
+
// A draining node:cluster worker no longer listens; a request still arriving on one of
|
|
593
|
+
// its open keep-alive connections is served and that connection then closes, so the
|
|
594
|
+
// client's next request goes to another worker instead of seeing 503 (D-0036).
|
|
595
|
+
if (stopping && worker) {
|
|
596
|
+
if (http1(request))
|
|
597
|
+
reply.header('connection', 'close');
|
|
598
|
+
}
|
|
599
|
+
else if (config.readiness === false &&
|
|
600
|
+
(state === 'running' || state === 'stopping') &&
|
|
601
|
+
!context.signal.aborted) {
|
|
602
|
+
// M51: a metrics or status route also while a dependency is down (NOT_READY) or the
|
|
603
|
+
// app drains; tracked like any request, so the drain waits for it. Core keeps the state
|
|
604
|
+
// `stopping` through the cleanup of a stop and aborts context.signal as it begins: the
|
|
605
|
+
// plugins behind the route (metrics, a database) are going away then (audit r5 step 2).
|
|
606
|
+
}
|
|
607
|
+
else {
|
|
608
|
+
this.#refuse(request, reply, stopping ? 'DRAINING' : state !== 'running' ? 'STARTING' : 'NOT_READY');
|
|
609
|
+
return;
|
|
610
|
+
}
|
|
305
611
|
}
|
|
612
|
+
// D-0150: one field read while calm; the route only while the server sheds load.
|
|
613
|
+
if (this.#pressure !== undefined && this.#shed(request, reply))
|
|
614
|
+
return;
|
|
306
615
|
const raw = reply.raw;
|
|
307
616
|
this.#inflight++;
|
|
308
617
|
raw[REPLY] = reply;
|
|
309
618
|
raw.on('close', closed);
|
|
619
|
+
// A route with `completed` observers (metrics) is told from the close above, without a
|
|
620
|
+
// Fastify onResponse hook (its response listeners and hook runner on every request).
|
|
621
|
+
if (this.#routeHooks.completing) {
|
|
622
|
+
const context = reply[ROUTE_CONTEXT];
|
|
623
|
+
const completed = context?.config?.[COMPLETED];
|
|
624
|
+
if (completed !== undefined && completed.length > 0) {
|
|
625
|
+
raw[COMPLETING] = completed;
|
|
626
|
+
raw[STARTED] = performance.now();
|
|
627
|
+
}
|
|
628
|
+
}
|
|
629
|
+
// requestTimeoutMs bounds the body: one timer while a body is arriving, so the answer is
|
|
630
|
+
// web's 408 REQUEST_TIMEOUT on time (Node's own check runs every 30 s and is set past
|
|
631
|
+
// every body time at start, see #nodeTimeouts; HTTP/2 has none at all).
|
|
632
|
+
if (!request.raw.complete && bodyFollows(request))
|
|
633
|
+
owner.#timeBody(request, reply, options.requestTimeoutMs);
|
|
634
|
+
// A sealed form marker on a body that is not sealed (or multipart) is refused before any
|
|
635
|
+
// parser too (D-0092 §1.3): the marker promises a body of the urlencoded shape.
|
|
636
|
+
if (request.headers[FORM_SUBMISSION_HEADER] !== undefined) {
|
|
637
|
+
const refused = formMarkerRefusal(request.headers, sealing.provider?.contentType, bodyFollows(request));
|
|
638
|
+
if (refused) {
|
|
639
|
+
done(refused);
|
|
640
|
+
return;
|
|
641
|
+
}
|
|
642
|
+
}
|
|
310
643
|
// A sealed request with a plain body is answered 415 here, before any parser (D-0062).
|
|
311
644
|
done(sealing.provider ? sealing.refusePlain(request) : undefined);
|
|
312
645
|
});
|
|
646
|
+
this.#overload(options.overload);
|
|
313
647
|
this.server.addHook('onSend', (request, reply, payload, done) => {
|
|
314
648
|
reply.raw[SENDING] = true;
|
|
315
|
-
|
|
316
|
-
|
|
317
|
-
|
|
649
|
+
if (!http1(request)) {
|
|
650
|
+
// HTTP/2 has no connection header (RFC 9113 §8.2.2): one set by Fastify (its 413 and
|
|
651
|
+
// every body parse error) or a plugin would only be dropped by Node with a process
|
|
652
|
+
// warning on stderr. The stream ends; GOAWAY ends a session.
|
|
653
|
+
if (reply.hasHeader('connection'))
|
|
654
|
+
reply.removeHeader('connection');
|
|
655
|
+
}
|
|
656
|
+
else if (this.#draining && worker) {
|
|
657
|
+
// Responses already under way when a cluster worker starts draining close their
|
|
658
|
+
// connection too, instead of leaving it idle for the client to reuse (D-0036).
|
|
659
|
+
reply.header('connection', 'close');
|
|
660
|
+
}
|
|
661
|
+
// An answer sent before the request body was read to its end (413 from Content-Length, a
|
|
662
|
+
// 415 or 403 refused before any parser) closes the connection: the unread body is still on
|
|
663
|
+
// the socket, so a kept-alive connection would not answer the client's next request there
|
|
664
|
+
// (AI-M42: the next request waited for a timeout, then ECONNRESET).
|
|
665
|
+
if (!request.raw.complete && hasBody(request.headers) && http1(request)) {
|
|
318
666
|
reply.header('connection', 'close');
|
|
319
|
-
|
|
667
|
+
// Lingering close: the client may still be sending that body; closing at once resets the
|
|
668
|
+
// connection under it and it never reads this answer (AI-M47: ECONNRESET in a test). Not
|
|
669
|
+
// for a body that stalled (408): that client is not sending.
|
|
670
|
+
if (request.raw[TIMED_OUT] === undefined)
|
|
671
|
+
lingerOnClose(request.raw, options.linger, this.context.logger);
|
|
672
|
+
}
|
|
673
|
+
const status = reply.statusCode;
|
|
674
|
+
// A redirect of a sealed form (D-0092 §1.2) is told, not followed: the forms module's fetch
|
|
675
|
+
// would follow it itself — rendering the next page (and taking its flash) for nothing, and
|
|
676
|
+
// failing on another origin — so the answer is 204 with the target in x-dokebi-location.
|
|
677
|
+
if (status >= 300 &&
|
|
678
|
+
status < 400 &&
|
|
679
|
+
request.headers[FORM_SUBMISSION_HEADER] === '1' &&
|
|
680
|
+
reply.hasHeader('location')) {
|
|
681
|
+
done(null, sealedFormRedirect(request, reply, logger, payload));
|
|
682
|
+
return;
|
|
683
|
+
}
|
|
684
|
+
const sent = sealing.provider ? sealing.onSend(request, reply, payload) : payload;
|
|
685
|
+
// D-0149: an unknown route has no route-level hooks; its answer gets the default headers.
|
|
686
|
+
if (security.enabled && request.is404)
|
|
687
|
+
security.apply(security.defaults, request, reply);
|
|
688
|
+
// An unknown route has no route-level hooks: its answer (an app's 404 page) is compressed
|
|
689
|
+
// here. Every matched route compresses in its own last onSend step (onRoute).
|
|
690
|
+
if (compression !== undefined && request.is404)
|
|
691
|
+
compression.hook(request, reply, sent, done);
|
|
692
|
+
else
|
|
693
|
+
done(null, sent);
|
|
320
694
|
});
|
|
321
695
|
this.#formBody(options);
|
|
696
|
+
this.#binaryBody(options);
|
|
322
697
|
this.server.addHook('onRoute', (route) => {
|
|
698
|
+
// D-0122: a route's own body limit, within maxRouteBodyBytes (Fastify answers 413 from
|
|
699
|
+
// Content-Length before reading, or as soon as a streamed body passes it).
|
|
700
|
+
owner.#checkBodyLimit(route.method, route.url, route.bodyLimit);
|
|
323
701
|
// `seal` on a route given to Fastify directly (a register() scope, @dokebi/router mount)
|
|
324
702
|
// becomes `config.dokebiSeal` too, so every way of adding a route can opt out (D-0062).
|
|
325
703
|
const options = route;
|
|
704
|
+
// D-0132: `app` becomes the host constraint of app routes (before anything reads it).
|
|
705
|
+
owner.#appRoutes.route(options);
|
|
326
706
|
if (options.seal !== undefined) {
|
|
327
707
|
options.config = {
|
|
328
708
|
...route.config,
|
|
@@ -331,9 +711,66 @@ class WebOwner {
|
|
|
331
711
|
delete options.seal;
|
|
332
712
|
}
|
|
333
713
|
const config = route.config;
|
|
714
|
+
owner.#routeConfig.record(route.method, route.url, config);
|
|
715
|
+
owner.#routeTable.record(route.method, route.url, config, route.constraints, route.schema);
|
|
334
716
|
sealing.route(checkSealSetting(config?.dokebiSeal));
|
|
335
717
|
if (config?.dokebiHealth === true)
|
|
336
718
|
return;
|
|
719
|
+
// D-0149: the security headers are a route-level onSend step too (built at the first answer
|
|
720
|
+
// after the start); `securityHeaders: false` routes get none. D-0125: compression is the
|
|
721
|
+
// route's own last onSend step, so it runs after every scope hook (seal, session, i18n, an
|
|
722
|
+
// app's own) and sees the final body; `compress: false` routes get none. Both in one step
|
|
723
|
+
// when a route has both: each onSend step costs every request a turn of Fastify's runner.
|
|
724
|
+
const routeSecurity = config?.securityHeaders;
|
|
725
|
+
const policy = security.enabled && routeSecurity !== false ? security.route(routeSecurity) : undefined;
|
|
726
|
+
const compress = compression !== undefined &&
|
|
727
|
+
config?.compress !== false
|
|
728
|
+
? compression.hook
|
|
729
|
+
: undefined;
|
|
730
|
+
const last = policy === undefined
|
|
731
|
+
? compress
|
|
732
|
+
: compress === undefined
|
|
733
|
+
? (request, reply, payload, done) => {
|
|
734
|
+
security.apply(policy, request, reply);
|
|
735
|
+
done(null, payload);
|
|
736
|
+
}
|
|
737
|
+
: (request, reply, payload, done) => {
|
|
738
|
+
security.apply(policy, request, reply);
|
|
739
|
+
compress(request, reply, payload, done);
|
|
740
|
+
};
|
|
741
|
+
if (last !== undefined) {
|
|
742
|
+
// A new array: Fastify's HEAD twin keeps the GET's own list.
|
|
743
|
+
const fields = route;
|
|
744
|
+
const own = fields.onSend;
|
|
745
|
+
fields.onSend =
|
|
746
|
+
own === undefined || own === null
|
|
747
|
+
? [last]
|
|
748
|
+
: Array.isArray(own)
|
|
749
|
+
? [...own, last]
|
|
750
|
+
: [own, last];
|
|
751
|
+
}
|
|
752
|
+
// A route's own requestTimeoutMs (an upload route): its first onRequest step times the body
|
|
753
|
+
// again with it (the global hook ran first, with the dokebi-web option). Checked at start.
|
|
754
|
+
const bodyMs = config?.requestTimeoutMs;
|
|
755
|
+
if (typeof bodyMs === 'number' && Number.isSafeInteger(bodyMs) && bodyMs >= 1) {
|
|
756
|
+
// Node's own request timeout is set past the longest body time at start.
|
|
757
|
+
if (bodyMs <= MAX_TIMEOUT_MS)
|
|
758
|
+
owner.#longestBodyMs = Math.max(owner.#longestBodyMs, bodyMs);
|
|
759
|
+
const retime = (request, reply, done) => {
|
|
760
|
+
if (request.raw[BODY_TIMER] !== undefined)
|
|
761
|
+
owner.#timeBody(request, reply, bodyMs);
|
|
762
|
+
done();
|
|
763
|
+
};
|
|
764
|
+
const fields = route;
|
|
765
|
+
const own = fields.onRequest;
|
|
766
|
+
fields.onRequest =
|
|
767
|
+
own === undefined || own === null
|
|
768
|
+
? [retime]
|
|
769
|
+
: Array.isArray(own)
|
|
770
|
+
? [retime, ...own]
|
|
771
|
+
: [retime, own];
|
|
772
|
+
}
|
|
773
|
+
owner.#routeHooks.offer(route);
|
|
337
774
|
const original = route.handler;
|
|
338
775
|
// The handler is held until its Promise settles, also after an early reply.send() and
|
|
339
776
|
// after the client left (D-0023). The request itself is already held by onRequest, so
|
|
@@ -344,7 +781,13 @@ class WebOwner {
|
|
|
344
781
|
raw[HANDLER] = result;
|
|
345
782
|
if (thenable(result)) {
|
|
346
783
|
owner.#inflight++;
|
|
347
|
-
result.then(owner.#release,
|
|
784
|
+
result.then(owner.#release, (error) => {
|
|
785
|
+
owner.#release();
|
|
786
|
+
// Runs right before Fastify's own reaction, which sees the same `reply.sent`: an
|
|
787
|
+
// error after the answer went out (or was hijacked) is not answered, only logged.
|
|
788
|
+
if (reply.sent && !fastifyLogs)
|
|
789
|
+
owner.#failedAfterSend(request, reply, error, failures);
|
|
790
|
+
});
|
|
348
791
|
}
|
|
349
792
|
raw[ABORTED]?.handler(result);
|
|
350
793
|
return result;
|
|
@@ -365,15 +808,58 @@ class WebOwner {
|
|
|
365
808
|
};
|
|
366
809
|
const routes = options.healthRoutes;
|
|
367
810
|
if (routes) {
|
|
368
|
-
|
|
811
|
+
// D-0142: the health routes have ids like every route (`web.healthLive`, `web.healthReady`).
|
|
812
|
+
const ids = pluginRouteIds('dokebi-web', ['healthLive', 'healthReady'], options.routeIds);
|
|
813
|
+
const live = { config: ids.config('healthLive', { dokebiHealth: true }) };
|
|
814
|
+
this.server.get(routes.live, live, async (_request, reply) => {
|
|
369
815
|
const live = health ? health.live : !['failed', 'stopped'].includes(context.app.state);
|
|
370
816
|
return reply.code(live ? 200 : 503).send({ live });
|
|
371
817
|
});
|
|
372
|
-
|
|
373
|
-
|
|
374
|
-
|
|
818
|
+
const ready = { config: ids.config('healthReady', { dokebiHealth: true }) };
|
|
819
|
+
const local = () => ({
|
|
820
|
+
ready: !this.#draining && context.app.state === 'running' && (!health || health.ready),
|
|
821
|
+
draining: this.#draining || context.app.state === 'stopping' || context.app.state === 'cleaning',
|
|
822
|
+
});
|
|
823
|
+
// D-0164: a @dokebi/cluster worker answers for every worker (they share the port).
|
|
824
|
+
const bridge = readyBridge();
|
|
825
|
+
const cluster = bridge
|
|
826
|
+
? new ClusterReadiness(bridge, local, logger, options.logRepeatWindowMs)
|
|
827
|
+
: undefined;
|
|
828
|
+
if (cluster)
|
|
829
|
+
context.defer(cluster.stop);
|
|
830
|
+
this.server.get(routes.ready, ready, async (_request, reply) => {
|
|
831
|
+
const own = local().ready;
|
|
832
|
+
if (!own || !cluster)
|
|
833
|
+
return reply.code(own ? 200 : 503).send({ ready: own });
|
|
834
|
+
const body = await cluster.ready();
|
|
835
|
+
// This worker may have turned unready or begun to drain while the others answered.
|
|
836
|
+
if (!local().ready)
|
|
837
|
+
return reply.code(503).send({ ready: false });
|
|
838
|
+
return reply.code(body.ready ? 200 : 503).send(body);
|
|
375
839
|
});
|
|
376
840
|
}
|
|
841
|
+
// A tunnel or proxy on this machine or network (cloudflared with its HTTP Host Header set to
|
|
842
|
+
// localhost, nginx) sends the browser's host in X-Forwarded-Host. Without its address in
|
|
843
|
+
// trustProxy that header is ignored and requestHost() is the Host it wrote (`localhost`):
|
|
844
|
+
// app domains miss and seal keys differ from the browser's (2026-10-28). Said once per
|
|
845
|
+
// window and peer, only for loopback and private peers (a public client may send anything).
|
|
846
|
+
const ignoredForwarded = new Repeats({ intervalMs: options.logRepeatWindowMs });
|
|
847
|
+
const forwardedIgnored = (remote, forwarded, host) => {
|
|
848
|
+
const peer = plainAddress(remote);
|
|
849
|
+
if (!LOCAL_PEERS.check(peer, peer.includes(':') ? 'ipv6' : 'ipv4'))
|
|
850
|
+
return;
|
|
851
|
+
const repeated = ignoredForwarded.take(peer);
|
|
852
|
+
if (repeated === undefined)
|
|
853
|
+
return;
|
|
854
|
+
logger.log('warn', 'X-Forwarded-Host ignored: the proxy is not in trustProxy', {
|
|
855
|
+
code: 'WEB_FORWARDED_HOST_IGNORED',
|
|
856
|
+
remote: peer,
|
|
857
|
+
forwardedHost: String(forwarded).slice(0, 253),
|
|
858
|
+
host: String(host ?? '').slice(0, 253),
|
|
859
|
+
fix: `When ${peer} is your tunnel or proxy, add it to dokebi-web.trustProxy (a tunnel on this machine such as cloudflared: trustProxy: [127.0.0.1, ::1]); then requestHost() is the browser's host.`,
|
|
860
|
+
...(repeated ? { repeated } : {}),
|
|
861
|
+
});
|
|
862
|
+
};
|
|
377
863
|
this.api = Object.freeze({
|
|
378
864
|
get address() {
|
|
379
865
|
return owner.#address;
|
|
@@ -381,13 +867,28 @@ class WebOwner {
|
|
|
381
867
|
route: (route) => {
|
|
382
868
|
this.#assertMutable();
|
|
383
869
|
const { seal, ...rest } = route;
|
|
384
|
-
|
|
385
|
-
|
|
386
|
-
|
|
387
|
-
this.server.route({
|
|
870
|
+
const options = seal === undefined
|
|
871
|
+
? rest
|
|
872
|
+
: {
|
|
388
873
|
...rest,
|
|
389
|
-
config: {
|
|
390
|
-
|
|
874
|
+
config: {
|
|
875
|
+
...rest.config,
|
|
876
|
+
dokebiSeal: checkSealSetting(seal),
|
|
877
|
+
},
|
|
878
|
+
};
|
|
879
|
+
if (rest.app === undefined) {
|
|
880
|
+
this.server.route(options);
|
|
881
|
+
return;
|
|
882
|
+
}
|
|
883
|
+
// D-0132: a route bound to apps is added at boot, once @dokebi/app has registered the
|
|
884
|
+
// routing whatever the plugin order. The value is checked now; the names at boot.
|
|
885
|
+
appNames(rest.app, `Route ${String(rest.method)} ${rest.url}`);
|
|
886
|
+
const bind = async (scope) => {
|
|
887
|
+
scope.route(options);
|
|
888
|
+
};
|
|
889
|
+
// In the root context (no encapsulation), like a route added directly.
|
|
890
|
+
bind[Symbol.for('skip-override')] = true;
|
|
891
|
+
this.server.register(bind);
|
|
391
892
|
},
|
|
392
893
|
register: (plugin, options) => {
|
|
393
894
|
this.#assertMutable();
|
|
@@ -402,11 +903,20 @@ class WebOwner {
|
|
|
402
903
|
const raw = request.raw ?? request;
|
|
403
904
|
const remote = raw.socket?.remoteAddress;
|
|
404
905
|
const forwarded = raw.headers['x-forwarded-host'];
|
|
405
|
-
|
|
906
|
+
// The last entry: only the socket peer is trusted, and a proxy that appends writes its
|
|
907
|
+
// value last; earlier entries come from whoever sent the request (as Fastify's request.host).
|
|
908
|
+
const trusted = forwarded !== undefined &&
|
|
406
909
|
remote !== undefined &&
|
|
407
|
-
options.trustProxy.includes(plainAddress(remote))
|
|
408
|
-
|
|
409
|
-
: raw.headers.host;
|
|
910
|
+
options.trustProxy.includes(plainAddress(remote));
|
|
911
|
+
if (forwarded !== undefined && remote !== undefined && !trusted)
|
|
912
|
+
forwardedIgnored(remote, forwarded, raw.headers[':authority'] ?? raw.headers.host);
|
|
913
|
+
const value = trusted
|
|
914
|
+
? String(Array.isArray(forwarded) ? forwarded.at(-1) : forwarded)
|
|
915
|
+
.split(',')
|
|
916
|
+
.at(-1)
|
|
917
|
+
: // HTTP/2 names the host in `:authority`; a Host header is optional there (RFC 9113
|
|
918
|
+
// §8.3.1). HTTP/1 cannot send a pseudo-header, so it always reads Host.
|
|
919
|
+
(raw.headers[':authority'] ?? raw.headers.host);
|
|
410
920
|
return String(value ?? '')
|
|
411
921
|
.trim()
|
|
412
922
|
.toLowerCase();
|
|
@@ -422,9 +932,33 @@ class WebOwner {
|
|
|
422
932
|
sealing.addPredicate(predicate);
|
|
423
933
|
},
|
|
424
934
|
sealOf: (request) => sealing.sealOf(request),
|
|
935
|
+
requestApps: (resolver) => {
|
|
936
|
+
this.#assertMutable();
|
|
937
|
+
if (typeof resolver !== 'function')
|
|
938
|
+
throw new TypeError('requestApps takes a function');
|
|
939
|
+
appResolvers.push(resolver);
|
|
940
|
+
},
|
|
941
|
+
appOf: (request) => {
|
|
942
|
+
for (const resolver of appResolvers) {
|
|
943
|
+
const name = resolver(request);
|
|
944
|
+
if (name !== undefined)
|
|
945
|
+
return name;
|
|
946
|
+
}
|
|
947
|
+
return undefined;
|
|
948
|
+
},
|
|
949
|
+
get resolvesApps() {
|
|
950
|
+
return appResolvers.length > 0;
|
|
951
|
+
},
|
|
425
952
|
get sealing() {
|
|
426
953
|
return sealing.provider !== undefined;
|
|
427
954
|
},
|
|
955
|
+
get sealWanted() {
|
|
956
|
+
return sealing.wanted;
|
|
957
|
+
},
|
|
958
|
+
formLimits: Object.freeze({
|
|
959
|
+
oldInputMaxChars: options.formOldInputMaxChars,
|
|
960
|
+
refererMaxLength: options.formRefererMaxLength,
|
|
961
|
+
}),
|
|
428
962
|
errorResponder: (responder) => {
|
|
429
963
|
this.#assertMutable();
|
|
430
964
|
if (typeof responder !== 'function')
|
|
@@ -436,20 +970,126 @@ class WebOwner {
|
|
|
436
970
|
responders: this.#responders.length,
|
|
437
971
|
});
|
|
438
972
|
},
|
|
973
|
+
routeConfig: (definition) => {
|
|
974
|
+
this.#assertMutable();
|
|
975
|
+
this.#routeConfig.add(definition);
|
|
976
|
+
logger.log('debug', 'Web route config key registered', {
|
|
977
|
+
key: definition.key,
|
|
978
|
+
plugin: definition.plugin,
|
|
979
|
+
});
|
|
980
|
+
},
|
|
981
|
+
routeHook: (definition) => {
|
|
982
|
+
this.#assertMutable();
|
|
983
|
+
const offered = this.#routeHooks.add(definition);
|
|
984
|
+
logger.log('debug', 'Web route hook registered', {
|
|
985
|
+
plugin: definition.plugin,
|
|
986
|
+
earlierRoutes: offered,
|
|
987
|
+
});
|
|
988
|
+
},
|
|
989
|
+
contentSecurityPolicy: (contribution) => {
|
|
990
|
+
this.#assertMutable();
|
|
991
|
+
const problem = contributionProblem(contribution);
|
|
992
|
+
if (problem)
|
|
993
|
+
throw new WebError('INVALID_ARGUMENT', `Invalid Content-Security-Policy sources: ${problem}`, {
|
|
994
|
+
fix: "Pass { plugin: 'dokebi-…', directives: { 'connect-src': ['ws://*:5173'] } }.",
|
|
995
|
+
});
|
|
996
|
+
this.#security.contribute(contribution);
|
|
997
|
+
logger.log('debug', 'Content-Security-Policy sources added', {
|
|
998
|
+
plugin: contribution.plugin,
|
|
999
|
+
directives: Object.keys(contribution.directives),
|
|
1000
|
+
});
|
|
1001
|
+
},
|
|
1002
|
+
routes: () => this.#routeTable.routes(),
|
|
1003
|
+
appRouting: (routing) => {
|
|
1004
|
+
this.#assertMutable();
|
|
1005
|
+
this.#appRoutes.set(routing);
|
|
1006
|
+
},
|
|
1007
|
+
get apps() {
|
|
1008
|
+
return owner.#appRoutes.routing;
|
|
1009
|
+
},
|
|
439
1010
|
});
|
|
440
1011
|
}
|
|
441
1012
|
#assertMutable() {
|
|
442
1013
|
if (this.#frozen || this.#closed)
|
|
443
1014
|
throw new WebError('FROZEN');
|
|
444
1015
|
}
|
|
1016
|
+
/**
|
|
1017
|
+
* The end of a draining worker's idle wait (D-0036): the keep-alive connections still idle are
|
|
1018
|
+
* closed (`closeIdleConnections` leaves a connection whose next request has begun to arrive),
|
|
1019
|
+
* once per drain, so later only the ending response's own connection is looked at (D-0107 §1).
|
|
1020
|
+
*/
|
|
1021
|
+
#closeIdle(open) {
|
|
1022
|
+
if (this.#idleClosed)
|
|
1023
|
+
return;
|
|
1024
|
+
this.#idleClosed = true;
|
|
1025
|
+
// An h2c server has no closeIdleConnections; HTTP/2 sessions were told to go away already.
|
|
1026
|
+
const server = this.server.server;
|
|
1027
|
+
server.closeIdleConnections?.();
|
|
1028
|
+
this.context.logger.log('debug', 'Web drain closed idle connections', {
|
|
1029
|
+
pending: this.#inflight,
|
|
1030
|
+
open,
|
|
1031
|
+
idleMs: this.#drainIdleMs,
|
|
1032
|
+
});
|
|
1033
|
+
}
|
|
1034
|
+
/**
|
|
1035
|
+
* A draining node:cluster worker, after its idle wait: a response that went out without
|
|
1036
|
+
* `Connection: close` (its head was out before the drain) ends its connection once it has
|
|
1037
|
+
* ended, unless a newer request of that connection is under way. During the idle wait the
|
|
1038
|
+
* connection is left open: the client's next request on it is served with `Connection: close`.
|
|
1039
|
+
*/
|
|
1040
|
+
#closeAfterResponse(response) {
|
|
1041
|
+
if (!this.#idleClosed)
|
|
1042
|
+
return;
|
|
1043
|
+
const logger = this.context.logger;
|
|
1044
|
+
// No newer request of the connection under way (marked from the server's 'request').
|
|
1045
|
+
const socket = this.#connections.endIfIdle(response);
|
|
1046
|
+
if (socket === undefined)
|
|
1047
|
+
return;
|
|
1048
|
+
if (logger.isEnabled('debug'))
|
|
1049
|
+
logger.log('debug', 'Web drain closed an idle connection', {
|
|
1050
|
+
remote: `${socket.remoteAddress ?? '?'}:${socket.remotePort ?? '?'}`,
|
|
1051
|
+
pending: this.#inflight,
|
|
1052
|
+
});
|
|
1053
|
+
}
|
|
445
1054
|
/** The shared 'close' listener of every held response (`this` is the response). */
|
|
1055
|
+
/** The route's `completed` observers, once its response was written (route-hooks.ts). */
|
|
1056
|
+
#completed(response, reply) {
|
|
1057
|
+
const elapsedMs = performance.now() - response[STARTED];
|
|
1058
|
+
for (const observe of response[COMPLETING]) {
|
|
1059
|
+
try {
|
|
1060
|
+
observe(reply.request, reply, elapsedMs);
|
|
1061
|
+
}
|
|
1062
|
+
catch (error) {
|
|
1063
|
+
this.#responseHookFailures ??= new Repeats({ intervalMs: this.options.logRepeatWindowMs });
|
|
1064
|
+
const route = reply.request.routeOptions.url ?? 'unmatched';
|
|
1065
|
+
const repeated = this.#responseHookFailures.take(route);
|
|
1066
|
+
if (repeated !== undefined)
|
|
1067
|
+
this.context.logger.log('error', 'HTTP response hook failed', {
|
|
1068
|
+
code: 'WEB_RESPONSE_HOOK_FAILED',
|
|
1069
|
+
route,
|
|
1070
|
+
repeated,
|
|
1071
|
+
error: describeError(error),
|
|
1072
|
+
});
|
|
1073
|
+
}
|
|
1074
|
+
}
|
|
1075
|
+
}
|
|
446
1076
|
#responseClosed(response) {
|
|
1077
|
+
const incoming = response.req;
|
|
1078
|
+
if (incoming?.[BODY_TIMER] !== undefined)
|
|
1079
|
+
clearBodyTimer.call(incoming);
|
|
1080
|
+
// A 408 went out for a stalled body. Node forgets a request once its response finished, so
|
|
1081
|
+
// the request stream never ends or errors when the connection closes: a reader still waiting
|
|
1082
|
+
// (a multipart file stream, a storage upload) would hold the drain until its deadline.
|
|
1083
|
+
if (incoming?.[TIMED_OUT] !== undefined && !incoming.complete && !incoming.destroyed)
|
|
1084
|
+
incoming.destroy(bodyTimeout(incoming[TIMED_OUT]));
|
|
447
1085
|
// 'close' fires once per response, so the listener is not removed (one call saved).
|
|
448
1086
|
if (this.#draining && this.#worker)
|
|
449
|
-
this
|
|
1087
|
+
this.#closeAfterResponse(response);
|
|
450
1088
|
const reply = response[REPLY];
|
|
451
1089
|
// Written (finished, or at least its head: the rest needs no user code) or hijacked: done.
|
|
452
1090
|
if (response.writableFinished || response.headersSent || reply === undefined || reply.sent) {
|
|
1091
|
+
if (response[COMPLETING] !== undefined && response.writableFinished && reply !== undefined)
|
|
1092
|
+
this.#completed(response, reply);
|
|
453
1093
|
this.#release();
|
|
454
1094
|
return;
|
|
455
1095
|
}
|
|
@@ -473,6 +1113,49 @@ class WebOwner {
|
|
|
473
1113
|
this.#release();
|
|
474
1114
|
});
|
|
475
1115
|
}
|
|
1116
|
+
/** The timer of a body that is arriving: `ms` from now (re-armed by a route's own setting). */
|
|
1117
|
+
#timeBody(request, reply, ms) {
|
|
1118
|
+
const raw = request.raw;
|
|
1119
|
+
if (raw[BODY_TIMER] === undefined)
|
|
1120
|
+
raw.once('end', clearBodyTimer);
|
|
1121
|
+
else
|
|
1122
|
+
clearTimeout(raw[BODY_TIMER]);
|
|
1123
|
+
const timer = setTimeout(this.#bodyTimedOut, ms, request, reply, ms);
|
|
1124
|
+
timer.unref();
|
|
1125
|
+
raw[BODY_TIMER] = timer;
|
|
1126
|
+
}
|
|
1127
|
+
/**
|
|
1128
|
+
* The body did not arrive within its time: 408 REQUEST_TIMEOUT when no answer has started (the
|
|
1129
|
+
* connection then closes), else the connection is cut. The parser or handler still waiting for
|
|
1130
|
+
* the body then fails as the connection ends; that is not logged as a server failure.
|
|
1131
|
+
*/
|
|
1132
|
+
#bodyTimedOut = (request, reply, ms) => {
|
|
1133
|
+
const raw = request.raw;
|
|
1134
|
+
raw[BODY_TIMER] = undefined;
|
|
1135
|
+
if (raw.complete || raw.destroyed)
|
|
1136
|
+
return;
|
|
1137
|
+
raw[TIMED_OUT] = ms;
|
|
1138
|
+
const answered = reply.sent || reply.raw.headersSent;
|
|
1139
|
+
if (this.context.logger.isEnabled('debug'))
|
|
1140
|
+
this.context.logger.log('debug', 'HTTP request body timed out', {
|
|
1141
|
+
code: 'WEB_REQUEST_TIMEOUT',
|
|
1142
|
+
method: request.method,
|
|
1143
|
+
route: request.routeOptions.url ?? 'unmatched',
|
|
1144
|
+
timeoutMs: ms,
|
|
1145
|
+
answered,
|
|
1146
|
+
});
|
|
1147
|
+
if (answered) {
|
|
1148
|
+
// HTTP/2: only this stream (NGHTTP2_CANCEL), never the session other streams share.
|
|
1149
|
+
if (http1(request))
|
|
1150
|
+
raw.socket?.destroy();
|
|
1151
|
+
else
|
|
1152
|
+
request.raw.stream?.close(8);
|
|
1153
|
+
return;
|
|
1154
|
+
}
|
|
1155
|
+
if (!http1(request))
|
|
1156
|
+
endStreamAfterAnswer(request.raw, ms);
|
|
1157
|
+
reply.send(bodyTimeout(ms));
|
|
1158
|
+
};
|
|
476
1159
|
track(work) {
|
|
477
1160
|
if (this.#closed)
|
|
478
1161
|
return Promise.reject(new WebError('CLOSED'));
|
|
@@ -507,6 +1190,53 @@ class WebOwner {
|
|
|
507
1190
|
if (!RESPONSE_HOOKS.has(name))
|
|
508
1191
|
return fn;
|
|
509
1192
|
const owner = this;
|
|
1193
|
+
if (name === 'onResponse') {
|
|
1194
|
+
// Response observers commonly call done synchronously (metrics). Keep the same drain
|
|
1195
|
+
// hold without turning that callback into a chain of Promises/microtasks. Async hooks
|
|
1196
|
+
// still hold the counter until their returned promise settles.
|
|
1197
|
+
this.#responseHookFailures ??= new Repeats({ intervalMs: this.options.logRepeatWindowMs });
|
|
1198
|
+
const failures = this.#responseHookFailures;
|
|
1199
|
+
const wrapped = function (request, reply, done) {
|
|
1200
|
+
if (owner.#closed) {
|
|
1201
|
+
done(new WebError('CLOSED'));
|
|
1202
|
+
return;
|
|
1203
|
+
}
|
|
1204
|
+
owner.#inflight++;
|
|
1205
|
+
let settled = false;
|
|
1206
|
+
const finish = (error) => {
|
|
1207
|
+
if (error) {
|
|
1208
|
+
const route = request.routeOptions.url ?? 'unmatched';
|
|
1209
|
+
const repeated = failures.take(route);
|
|
1210
|
+
if (repeated !== undefined)
|
|
1211
|
+
owner.context.logger.log('error', 'HTTP response hook failed', {
|
|
1212
|
+
code: 'WEB_RESPONSE_HOOK_FAILED',
|
|
1213
|
+
route,
|
|
1214
|
+
repeated,
|
|
1215
|
+
error: describeError(error),
|
|
1216
|
+
});
|
|
1217
|
+
}
|
|
1218
|
+
if (settled)
|
|
1219
|
+
return;
|
|
1220
|
+
settled = true;
|
|
1221
|
+
try {
|
|
1222
|
+
done(error);
|
|
1223
|
+
}
|
|
1224
|
+
finally {
|
|
1225
|
+
owner.#release();
|
|
1226
|
+
}
|
|
1227
|
+
};
|
|
1228
|
+
try {
|
|
1229
|
+
const result = fn.call(this, request, reply, finish);
|
|
1230
|
+
if (result && typeof result.then === 'function')
|
|
1231
|
+
void Promise.resolve(result).then(() => finish(), (error) => finish(error || new Error('HTTP response hook rejected without an error')));
|
|
1232
|
+
}
|
|
1233
|
+
catch (error) {
|
|
1234
|
+
finish(error || new Error('HTTP response hook threw without an error'));
|
|
1235
|
+
}
|
|
1236
|
+
};
|
|
1237
|
+
this.#wrapped.add(wrapped);
|
|
1238
|
+
return wrapped;
|
|
1239
|
+
}
|
|
510
1240
|
function invoke(instance, args) {
|
|
511
1241
|
return owner.track(() => new Promise((resolve, reject) => {
|
|
512
1242
|
const reply = name === 'onRequestAbort' ? undefined : args[1];
|
|
@@ -558,6 +1288,31 @@ class WebOwner {
|
|
|
558
1288
|
this.#wrapped.add(wrapped);
|
|
559
1289
|
return wrapped;
|
|
560
1290
|
}
|
|
1291
|
+
/**
|
|
1292
|
+
* D-0122: `binaryBody` parses application/octet-stream into a Buffer. Fastify's raw-body reader
|
|
1293
|
+
* enforces the route's `bodyLimit` (else maxBodyBytes): Content-Length over it is 413 before a
|
|
1294
|
+
* byte is read, a longer streamed body stops at the limit, so at most the limit is buffered.
|
|
1295
|
+
*/
|
|
1296
|
+
#binaryBody(options) {
|
|
1297
|
+
if (!options.binaryBody)
|
|
1298
|
+
return;
|
|
1299
|
+
this.server.addContentTypeParser(BINARY_TYPE, { parseAs: 'buffer', bodyLimit: options.maxBodyBytes }, (_request, body, done) => done(null, body));
|
|
1300
|
+
}
|
|
1301
|
+
/** D-0122: a route `bodyLimit` must be whole bytes from 1 to `maxRouteBodyBytes`. */
|
|
1302
|
+
#checkBodyLimit(method, url, limit) {
|
|
1303
|
+
if (limit === undefined)
|
|
1304
|
+
return;
|
|
1305
|
+
const most = this.options.maxRouteBodyBytes;
|
|
1306
|
+
if (typeof limit === 'number' && Number.isSafeInteger(limit) && limit >= 1 && limit <= most) {
|
|
1307
|
+
if (this.context.logger.isEnabled('debug'))
|
|
1308
|
+
this.context.logger.log('debug', 'Web route body limit', { method, url, bodyLimit: limit });
|
|
1309
|
+
return;
|
|
1310
|
+
}
|
|
1311
|
+
throw new WebError('INVALID_ROUTE', `The route ${String(method)} ${url} has bodyLimit ${String(limit)}; it must be whole bytes from 1 to maxRouteBodyBytes (${most})`, {
|
|
1312
|
+
fix: `Lower the route's bodyLimit, or raise maxRouteBodyBytes under dokebi-web in dokebi.yaml (at most 1073741824). For larger uploads stream them (multipart receiveUpload of @dokebi/storage).`,
|
|
1313
|
+
data: { method, url, bodyLimit: limit, maxRouteBodyBytes: most },
|
|
1314
|
+
});
|
|
1315
|
+
}
|
|
561
1316
|
/** The urlencoded body parser, or its refusal when `formBody` is off (D-0068). */
|
|
562
1317
|
#formBody(options) {
|
|
563
1318
|
if (!options.formBody) {
|
|
@@ -582,12 +1337,79 @@ class WebOwner {
|
|
|
582
1337
|
done(null, parseQuery(text, '&', '=', { maxKeys: 0 }));
|
|
583
1338
|
});
|
|
584
1339
|
}
|
|
1340
|
+
/** Every route's config values for the declared keys, and likely typos (D-0076 §5). */
|
|
1341
|
+
#checkRouteConfig() {
|
|
1342
|
+
const keys = this.#routeConfig.size;
|
|
1343
|
+
const problems = this.#routeConfig.check();
|
|
1344
|
+
if (problems.length === 0) {
|
|
1345
|
+
if (keys > 0)
|
|
1346
|
+
this.context.logger.log('debug', 'Web route config checked', { keys });
|
|
1347
|
+
return;
|
|
1348
|
+
}
|
|
1349
|
+
this.context.logger.log('error', 'Web route config refused', {
|
|
1350
|
+
code: 'WEB_ROUTE_CONFIG_INVALID',
|
|
1351
|
+
problems: problems.slice(0, 20),
|
|
1352
|
+
more: Math.max(0, problems.length - 20),
|
|
1353
|
+
});
|
|
1354
|
+
throw new WebError('INVALID_ROUTE_CONFIG', `Route config refused: ${problems[0]}${problems.length > 1 ? ` (and ${problems.length - 1} more)` : ''}`, { details: { problems } });
|
|
1355
|
+
}
|
|
1356
|
+
/**
|
|
1357
|
+
* Describe mode (D-0077 B): every route once Fastify is ready (routes of plugin scopes too),
|
|
1358
|
+
* without listening. Called by the `core:describe` describer, after every setup.
|
|
1359
|
+
*/
|
|
1360
|
+
async describeRoutes() {
|
|
1361
|
+
this.#frozen = true;
|
|
1362
|
+
await this.server.ready();
|
|
1363
|
+
return describeRoutes(this.#routeTable);
|
|
1364
|
+
}
|
|
1365
|
+
/** A route id on two routes of one app fails the start (D-0077 A). */
|
|
1366
|
+
#checkRouteIds() {
|
|
1367
|
+
const duplicates = this.#routeTable.duplicateIds();
|
|
1368
|
+
const logger = this.context.logger;
|
|
1369
|
+
if (duplicates.length === 0) {
|
|
1370
|
+
if (logger.isEnabled('debug'))
|
|
1371
|
+
logger.log('debug', 'Web route ids checked', {
|
|
1372
|
+
routes: this.#routeTable.routes().length,
|
|
1373
|
+
ids: this.#routeTable.routes().filter((route) => route.id !== undefined).length,
|
|
1374
|
+
});
|
|
1375
|
+
return;
|
|
1376
|
+
}
|
|
1377
|
+
logger.log('error', 'Web route ids refused', {
|
|
1378
|
+
code: 'WEB_ROUTE_ID_DUPLICATE',
|
|
1379
|
+
duplicates: duplicates.slice(0, 20),
|
|
1380
|
+
more: Math.max(0, duplicates.length - 20),
|
|
1381
|
+
});
|
|
1382
|
+
const [first] = duplicates;
|
|
1383
|
+
// D-0142: when a plugin's own route is one of them, say which option renames it.
|
|
1384
|
+
const owned = first.owners?.map((owner) => {
|
|
1385
|
+
const [plugin, key] = owner.split(' ');
|
|
1386
|
+
return `options.${plugin}.${key}`;
|
|
1387
|
+
});
|
|
1388
|
+
throw new WebError('DUPLICATE_ROUTE_ID', `Route id ${first.id} is on more than one route: ${first.routes.join(', ')}${duplicates.length > 1 ? ` (and ${duplicates.length - 1} more ids)` : ''}`, {
|
|
1389
|
+
details: { duplicates },
|
|
1390
|
+
...(owned?.length
|
|
1391
|
+
? {
|
|
1392
|
+
fix: `Set ${owned.join(' or ')} to an id of its own${first.routes.some((route) => route.endsWith(' (application)')) ? ', or give the application route another config.id' : ''}.`,
|
|
1393
|
+
}
|
|
1394
|
+
: {}),
|
|
1395
|
+
});
|
|
1396
|
+
}
|
|
585
1397
|
async start() {
|
|
586
1398
|
this.#frozen = true;
|
|
587
1399
|
const started = performance.now();
|
|
588
1400
|
await this.server.ready();
|
|
589
1401
|
// After every setup (routes and the seal provider are all known): fail closed (D-0062).
|
|
590
1402
|
this.#sealing.check();
|
|
1403
|
+
this.#checkRouteConfig();
|
|
1404
|
+
this.#checkRouteIds();
|
|
1405
|
+
this.#routeHooks.close();
|
|
1406
|
+
this.#security.freeze();
|
|
1407
|
+
this.#nodeTimeouts();
|
|
1408
|
+
const shedding = this.#shedding;
|
|
1409
|
+
if (shedding) {
|
|
1410
|
+
this.#sampler = setInterval(() => this.#sample(), shedding.settings.sampleIntervalMs);
|
|
1411
|
+
this.#sampler.unref();
|
|
1412
|
+
}
|
|
591
1413
|
this.context.logger.log('debug', 'Web routes frozen', {
|
|
592
1414
|
ms: Math.round(performance.now() - started),
|
|
593
1415
|
});
|
|
@@ -598,6 +1420,34 @@ class WebOwner {
|
|
|
598
1420
|
if (!this.#worker)
|
|
599
1421
|
await this.listen();
|
|
600
1422
|
}
|
|
1423
|
+
/**
|
|
1424
|
+
* Node's own timeouts of an HTTP/1 server, once every route is known. Node bounds the head by
|
|
1425
|
+
* the smaller of `headersTimeout` and `requestTimeout` and the whole request by the larger (it
|
|
1426
|
+
* swaps them), checked every 30 s, and answers past it with a bare 408 of Fastify's that no log
|
|
1427
|
+
* records. Left as Fastify set them (requestTimeout = requestTimeoutMs, headersTimeout Node's
|
|
1428
|
+
* 60 s), every request was cut at 60 s: an upload route's own `config.requestTimeoutMs`
|
|
1429
|
+
* (600000 for large files) never got past a minute. The head keeps its bound; the whole
|
|
1430
|
+
* request gets the longest body time plus that, so web's own timer (408 REQUEST_TIMEOUT,
|
|
1431
|
+
* started once the head has arrived) always ends a body first.
|
|
1432
|
+
*/
|
|
1433
|
+
#nodeTimeouts() {
|
|
1434
|
+
const server = this.server.server;
|
|
1435
|
+
const request = server.requestTimeout;
|
|
1436
|
+
const headers = server.headersTimeout;
|
|
1437
|
+
// An HTTP/2 server has neither (HTTP/2 bodies have only web's timer); a serverFactory's own
|
|
1438
|
+
// server keeps what it set.
|
|
1439
|
+
if (typeof request !== 'number' || typeof headers !== 'number' || request === 0)
|
|
1440
|
+
return;
|
|
1441
|
+
const head = headers > 0 ? Math.min(headers, request) : request;
|
|
1442
|
+
const whole = Math.min(MAX_TIMEOUT_MS, Math.max(request, this.#longestBodyMs) + head);
|
|
1443
|
+
server.headersTimeout = head;
|
|
1444
|
+
server.requestTimeout = whole;
|
|
1445
|
+
this.context.logger.log('debug', 'Web request timeouts', {
|
|
1446
|
+
headersTimeoutMs: head,
|
|
1447
|
+
requestTimeoutMs: whole,
|
|
1448
|
+
longestBodyMs: this.#longestBodyMs,
|
|
1449
|
+
});
|
|
1450
|
+
}
|
|
601
1451
|
/** Listens unless this process does not serve (`runtime.serving` false, D-0063 §4). */
|
|
602
1452
|
async listen() {
|
|
603
1453
|
if (this.#address !== undefined)
|
|
@@ -627,7 +1477,7 @@ class WebOwner {
|
|
|
627
1477
|
ms: Math.round(performance.now() - started),
|
|
628
1478
|
});
|
|
629
1479
|
}
|
|
630
|
-
async drain(signal) {
|
|
1480
|
+
async drain(signal, deadline) {
|
|
631
1481
|
this.#draining = true;
|
|
632
1482
|
this.#frozen = true;
|
|
633
1483
|
const started = performance.now();
|
|
@@ -643,15 +1493,15 @@ class WebOwner {
|
|
|
643
1493
|
// The primary may already be handing this worker a connection when it learns the server
|
|
644
1494
|
// closed; the worker answers "not accepted" and the primary passes it on, but only if the
|
|
645
1495
|
// worker is still alive. A worker that exited meanwhile strands that connection (the
|
|
646
|
-
// primary never hears back), so a draining worker stays at least
|
|
1496
|
+
// primary never hears back), so a draining worker stays at least `drainGraceMs` (D-0036, D-0114).
|
|
647
1497
|
// Only the listening socket closes (net level): http's close() would also drop idle
|
|
648
1498
|
// keep-alive connections at once, racing clients that are just reusing them. Those
|
|
649
1499
|
// connections stay; their next request is served with `Connection: close`.
|
|
650
1500
|
let grace;
|
|
651
1501
|
if (this.#worker && this.server.server.listening) {
|
|
652
1502
|
Server.prototype.close.call(this.server.server);
|
|
653
|
-
grace = delay(
|
|
654
|
-
logger.log('debug', 'Web worker stopped listening', { graceMs:
|
|
1503
|
+
grace = delay(this.#drainGraceMs);
|
|
1504
|
+
logger.log('debug', 'Web worker stopped listening', { graceMs: this.#drainGraceMs });
|
|
655
1505
|
}
|
|
656
1506
|
const listening = new AbortController();
|
|
657
1507
|
const aborted = new Promise((resolve) => {
|
|
@@ -660,16 +1510,54 @@ class WebOwner {
|
|
|
660
1510
|
else
|
|
661
1511
|
signal.addEventListener('abort', () => resolve(), { once: true, signal: listening.signal });
|
|
662
1512
|
});
|
|
1513
|
+
let idleTimer;
|
|
663
1514
|
try {
|
|
664
|
-
|
|
665
|
-
|
|
1515
|
+
if (this.#worker) {
|
|
1516
|
+
// HTTP/2 can say it: GOAWAY, streams under way finish, no new ones (D-0036).
|
|
1517
|
+
const sessions = this.#connections.goAway();
|
|
1518
|
+
if (sessions)
|
|
1519
|
+
logger.log('debug', 'Web drain told HTTP/2 sessions to go away', { sessions });
|
|
1520
|
+
// HTTP/1 cannot: a keep-alive connection told `Keep-Alive: timeout=…` may carry the
|
|
1521
|
+
// client's next request at any moment, and closing it then loses that request
|
|
1522
|
+
// (ECONNRESET; a POST is never resent). So the connections stay open up to drainIdleMs:
|
|
1523
|
+
// a request on one is served with `Connection: close` and the client moves to another
|
|
1524
|
+
// worker; the drain goes on as soon as none is left (M50 review).
|
|
1525
|
+
let open = this.#connections.size;
|
|
1526
|
+
// Never past the drain deadline (core counts a drain still running then as
|
|
1527
|
+
// DRAIN_TIMEOUT): end DEADLINE_MARGIN_MS before it, the time to close the idle ones,
|
|
1528
|
+
// finish the answers under way and return.
|
|
1529
|
+
const idleMs = Math.min(this.#drainIdleMs, deadline === undefined
|
|
1530
|
+
? Number.POSITIVE_INFINITY
|
|
1531
|
+
: deadline - started - DEADLINE_MARGIN_MS);
|
|
1532
|
+
if (open > 0 && idleMs > 0) {
|
|
1533
|
+
let waited = false;
|
|
1534
|
+
// One timer for the whole wait, cleared when the drain ends (finally below).
|
|
1535
|
+
const idle = new Promise((resolve) => {
|
|
1536
|
+
idleTimer = setTimeout(() => {
|
|
1537
|
+
waited = true;
|
|
1538
|
+
resolve();
|
|
1539
|
+
}, idleMs);
|
|
1540
|
+
});
|
|
1541
|
+
while (open > 0 && !waited && !signal.aborted) {
|
|
1542
|
+
await Promise.race([this.#connections.changed(), idle, aborted]);
|
|
1543
|
+
open = this.#connections.size;
|
|
1544
|
+
}
|
|
1545
|
+
}
|
|
1546
|
+
if (!signal.aborted)
|
|
1547
|
+
this.#closeIdle(open);
|
|
1548
|
+
}
|
|
1549
|
+
while (this.#inflight > 0 || signal.aborted) {
|
|
1550
|
+
if (!signal.aborted)
|
|
1551
|
+
await Promise.race([this.#whenIdle(), aborted]);
|
|
666
1552
|
if (signal.aborted) {
|
|
667
|
-
// Deadline or forced stop: cut
|
|
1553
|
+
// Deadline or forced stop: cut every connection but upgraded ones (an HTTP/2 server
|
|
1554
|
+
// has no closeAllConnections); core records the timeout.
|
|
1555
|
+
const cut = this.#connections.cut();
|
|
668
1556
|
logger.log('debug', 'Web drain cut connections', {
|
|
669
1557
|
pending: this.#inflight,
|
|
1558
|
+
cut,
|
|
670
1559
|
ms: Math.round(performance.now() - started),
|
|
671
1560
|
});
|
|
672
|
-
this.server.server.closeAllConnections();
|
|
673
1561
|
return;
|
|
674
1562
|
}
|
|
675
1563
|
// Fastify starts the next step of a request (the next hook, onResponse after 'finish')
|
|
@@ -681,6 +1569,7 @@ class WebOwner {
|
|
|
681
1569
|
logger.log('debug', 'Web drain finished', { ms: Math.round(performance.now() - started) });
|
|
682
1570
|
}
|
|
683
1571
|
finally {
|
|
1572
|
+
clearTimeout(idleTimer);
|
|
684
1573
|
listening.abort();
|
|
685
1574
|
}
|
|
686
1575
|
}
|
|
@@ -706,29 +1595,121 @@ class WebOwner {
|
|
|
706
1595
|
fix: `Return { ...defaults, … } from fastifyOptions() in ${EXTENSION_FILE}, synchronously; return503OnClosing and forceCloseConnections belong to the drain contract.`,
|
|
707
1596
|
data: { hook: 'fastifyOptions', ...(changed.length ? { pinned: changed } : {}) },
|
|
708
1597
|
});
|
|
709
|
-
|
|
1598
|
+
const created = { ...fields, ...PINNED };
|
|
1599
|
+
// h2c: Fastify refuses `idle` (an Http2Server has no closeIdleConnections, the server failed
|
|
1600
|
+
// to start). Node closes HTTP/2 sessions itself in server.close(), and WebConnections ends
|
|
1601
|
+
// the connections that would hold it.
|
|
1602
|
+
if (created.http2 === true && !created.https)
|
|
1603
|
+
return { ...created, forceCloseConnections: false };
|
|
1604
|
+
return created;
|
|
710
1605
|
}
|
|
711
1606
|
/**
|
|
712
1607
|
* The error handler: D-0063 §1 mapping, the `errorBody` hook, logging, then the error responders
|
|
713
1608
|
* or the built-in JSON or HTML answer (D-0074). Synchronous while no responder is registered.
|
|
714
1609
|
*/
|
|
715
|
-
#fail(
|
|
1610
|
+
#fail(thrown, request, reply, failures) {
|
|
716
1611
|
const logger = this.context.logger;
|
|
717
1612
|
const production = this.#production;
|
|
1613
|
+
// The first error answer of this response, or the answer to an error raised while sending it.
|
|
1614
|
+
const raw = reply.raw;
|
|
1615
|
+
const pass = (raw[ERROR_PASS] ?? 0) + 1;
|
|
1616
|
+
raw[ERROR_PASS] = pass;
|
|
1617
|
+
this.#nextHandler(reply, pass);
|
|
1618
|
+
if (pass > 1) {
|
|
1619
|
+
if (logger.isEnabled('debug'))
|
|
1620
|
+
logger.log('debug', 'HTTP error raised while sending an error answer', {
|
|
1621
|
+
method: request.method,
|
|
1622
|
+
route: request.routeOptions.url ?? 'unmatched',
|
|
1623
|
+
status: reply.statusCode,
|
|
1624
|
+
errorCode: thrown?.code ?? null,
|
|
1625
|
+
});
|
|
1626
|
+
// The first answer's Retry-After told when that error ends; this answer sets its own, if
|
|
1627
|
+
// any (audit r5: a 500 went out with the Retry-After of the 503 before it).
|
|
1628
|
+
reply.removeHeader('retry-after');
|
|
1629
|
+
}
|
|
1630
|
+
// The route pattern, not the requested URL: no query values in the log (D-0047). D-0142: and
|
|
1631
|
+
// the route id, so a refusal of a plugin's own route (403 of /mcp) is named like an app's.
|
|
1632
|
+
const matched = request.routeOptions;
|
|
1633
|
+
const route = matched.url ?? 'unmatched';
|
|
1634
|
+
const routeId = typeof matched.config?.id === 'string' ? matched.config.id : null;
|
|
1635
|
+
// D-0093: an error that would answer 500 is offered to the translators first; a coded result
|
|
1636
|
+
// is answered (and logged) in its place. Besides uncoded errors that is a Dokebi error
|
|
1637
|
+
// answering 500 around a cause, thrown in a handler or a hook: a plugin's coded failure (a
|
|
1638
|
+
// failed auth hook, a session store) over a driver error, which only a 5xx translation (a
|
|
1639
|
+
// database that timed out, is busy or unavailable) replaces.
|
|
1640
|
+
const offer = this.#translators.length ? translatable(thrown) : 'no';
|
|
1641
|
+
const translated = offer === 'no'
|
|
1642
|
+
? undefined
|
|
1643
|
+
: this.#translate(thrown, request, route, failures, offer === 'server-only');
|
|
1644
|
+
const error = translated?.error ?? thrown;
|
|
718
1645
|
let answer = errorAnswer(error, production, (details) => this.#details(details));
|
|
719
|
-
// The route pattern, not the requested URL: no query values in the log (D-0047).
|
|
720
|
-
const route = request.routeOptions.url ?? 'unmatched';
|
|
721
1646
|
const own = error?.code;
|
|
722
1647
|
const code = typeof own === 'string' ? own : answer.body.error;
|
|
723
|
-
if (
|
|
1648
|
+
if (translated) {
|
|
1649
|
+
const retryAfterMs = translated.error.data?.retryAfterMs;
|
|
1650
|
+
if (typeof retryAfterMs === 'number' && Number.isFinite(retryAfterMs) && retryAfterMs > 0)
|
|
1651
|
+
reply.header('retry-after', String(Math.ceil(retryAfterMs / 1000)));
|
|
1652
|
+
// D-0113: a translated 503 (a busy, slow or unavailable store) is a retryable refusal; a
|
|
1653
|
+
// burst of it logs the first of each code and route per window, the rest are counted.
|
|
1654
|
+
const transient = answer.status === 503;
|
|
1655
|
+
const repeated = transient
|
|
1656
|
+
? this.#transientFirst(request.method, route, answer.status, code, translated.plugin)
|
|
1657
|
+
? 0
|
|
1658
|
+
: undefined
|
|
1659
|
+
: failures.take(`translated ${request.method} ${route} ${code}`);
|
|
1660
|
+
if (repeated !== undefined)
|
|
1661
|
+
logger.log(transient ? this.#transient.level : 'error', 'HTTP request error translated', {
|
|
1662
|
+
code: 'WEB_ERROR_TRANSLATED',
|
|
1663
|
+
requestId: request.id,
|
|
1664
|
+
method: request.method,
|
|
1665
|
+
route,
|
|
1666
|
+
routeId,
|
|
1667
|
+
status: answer.status,
|
|
1668
|
+
errorCode: code,
|
|
1669
|
+
translator: translated.plugin,
|
|
1670
|
+
// The translated error with the thrown value as its cause: the whole driver error.
|
|
1671
|
+
error: describeError(error),
|
|
1672
|
+
...(repeated ? { repeated } : {}),
|
|
1673
|
+
});
|
|
1674
|
+
}
|
|
1675
|
+
else if (answer.status >= 500) {
|
|
1676
|
+
// A retryable 503 (the seal provider's nonce store, D-0096; a shared rate-limit store, an
|
|
1677
|
+
// app error, D-0102) says when to retry: `data.retryAfterMs` of a coded error.
|
|
1678
|
+
const retryAfterMs = answer.status === 503 ? dokebiError(error)?.data?.retryAfterMs : undefined;
|
|
1679
|
+
const transient = typeof retryAfterMs === 'number' && Number.isFinite(retryAfterMs) && retryAfterMs > 0;
|
|
1680
|
+
if (transient)
|
|
1681
|
+
reply.header('retry-after', String(Math.ceil(retryAfterMs / 1000)));
|
|
1682
|
+
// D-0113: such a 503 is counted like a translated one; every other 5xx keeps the D-0047
|
|
1683
|
+
// rule (in full, the same route and error once per 10 seconds with `repeated`).
|
|
724
1684
|
const name = error instanceof Error ? error.name : typeof error;
|
|
725
|
-
|
|
1685
|
+
// A refusal the app declared intended (defineErrors `intended: true`) is the app working as
|
|
1686
|
+
// designed: warn, counted like the other retryable 503s, never error.
|
|
1687
|
+
const intended = answer.status === 503 &&
|
|
1688
|
+
error?.[INTENDED_REFUSAL] === true;
|
|
1689
|
+
// A seal refusal its layer already recorded (SEAL_NONCES_LOST: the warn
|
|
1690
|
+
// SEAL_BODY_REFUSED once per window): no second record of the same event.
|
|
1691
|
+
const recorded = error?.[RECORDED] === true;
|
|
1692
|
+
if (recorded && logger.isEnabled('debug'))
|
|
1693
|
+
logger.log('debug', 'HTTP request refused: the seal layer recorded it', {
|
|
1694
|
+
method: request.method,
|
|
1695
|
+
route,
|
|
1696
|
+
status: answer.status,
|
|
1697
|
+
errorCode: code,
|
|
1698
|
+
});
|
|
1699
|
+
const repeated = recorded
|
|
1700
|
+
? undefined
|
|
1701
|
+
: transient || intended
|
|
1702
|
+
? this.#transientFirst(request.method, route, answer.status, code, undefined, intended ? 'warn' : undefined)
|
|
1703
|
+
? 0
|
|
1704
|
+
: undefined
|
|
1705
|
+
: failures.take(`${request.method} ${route} ${name} ${code}`);
|
|
726
1706
|
if (repeated !== undefined)
|
|
727
|
-
logger.log('error', 'HTTP request failed', {
|
|
1707
|
+
logger.log(intended ? 'warn' : transient ? this.#transient.level : 'error', 'HTTP request failed', {
|
|
728
1708
|
code: 'WEB_REQUEST_FAILED',
|
|
729
1709
|
requestId: request.id,
|
|
730
1710
|
method: request.method,
|
|
731
1711
|
route,
|
|
1712
|
+
routeId,
|
|
732
1713
|
status: answer.status,
|
|
733
1714
|
errorCode: code,
|
|
734
1715
|
error: describeError(error),
|
|
@@ -743,6 +1724,7 @@ class WebOwner {
|
|
|
743
1724
|
code: error.code,
|
|
744
1725
|
method: request.method,
|
|
745
1726
|
route,
|
|
1727
|
+
routeId,
|
|
746
1728
|
fix: error.fix,
|
|
747
1729
|
...(repeated ? { repeated } : {}),
|
|
748
1730
|
});
|
|
@@ -752,9 +1734,12 @@ class WebOwner {
|
|
|
752
1734
|
status: answer.status,
|
|
753
1735
|
method: request.method,
|
|
754
1736
|
route,
|
|
1737
|
+
routeId,
|
|
755
1738
|
error: describeError(error),
|
|
756
1739
|
errorCode: code,
|
|
757
1740
|
});
|
|
1741
|
+
// The words of the answer are web's own (fixed English) unless the errorBody hook wrote them.
|
|
1742
|
+
let ownWords = true;
|
|
758
1743
|
if (this.#hooks && this.#overridden.has('errorBody')) {
|
|
759
1744
|
try {
|
|
760
1745
|
const changed = this.#hooks.errorBody(error, { request, answer, production });
|
|
@@ -763,6 +1748,7 @@ class WebOwner {
|
|
|
763
1748
|
data: { hook: 'errorBody' },
|
|
764
1749
|
});
|
|
765
1750
|
answer = changed;
|
|
1751
|
+
ownWords = false;
|
|
766
1752
|
}
|
|
767
1753
|
catch (failure) {
|
|
768
1754
|
const repeated = failures.take(`errorBody ${route}`);
|
|
@@ -781,24 +1767,354 @@ class WebOwner {
|
|
|
781
1767
|
// D-0074 §1: JSON for scripts (Inertia, fetch, XHR, APIs, sealed requests), a small page for
|
|
782
1768
|
// a browser navigation or an HTML form post.
|
|
783
1769
|
const sealed = this.#sealing.sealOf(request) !== undefined;
|
|
784
|
-
const format =
|
|
1770
|
+
const format = requestErrorFormat(request, sealed);
|
|
1771
|
+
clearResourceHeaders(reply, answer.status);
|
|
785
1772
|
reply.code(answer.status);
|
|
786
1773
|
if (!this.#responders.length) {
|
|
787
|
-
this.#send(reply, answer.status, body, format);
|
|
1774
|
+
this.#send(reply, answer.status, body, format, ownWords);
|
|
788
1775
|
return undefined;
|
|
789
1776
|
}
|
|
790
|
-
|
|
1777
|
+
const responding = this.#respond({ request, reply, error, status: answer.status, body, format, production, sealed }, route, failures, ownWords);
|
|
1778
|
+
// Held until the responders end: once the client has left, nothing else holds an error view
|
|
1779
|
+
// that is still rendering (D-0023). The same promise goes to Fastify, which sees a rejection.
|
|
1780
|
+
this.#inflight++;
|
|
1781
|
+
responding.then(this.#release, this.#release);
|
|
1782
|
+
return responding;
|
|
1783
|
+
}
|
|
1784
|
+
/**
|
|
1785
|
+
* D-0150: @fastify/under-pressure samples the event loop delay, its utilization and memory every
|
|
1786
|
+
* sampleIntervalMs (its own timer, `server.memoryUsage()`). Registered without limits it adds
|
|
1787
|
+
* no hook of its own (its hook reads `request.routeOptions` on every request); dokebi-web reads
|
|
1788
|
+
* the sample on the same period and keeps one field, which its onRequest hook checks. Above a
|
|
1789
|
+
* limit the answer is 503 OVERLOADED with Retry-After before any handler runs (a small page for
|
|
1790
|
+
* a browser navigation, the error shape otherwise); health routes and `config.overload: false`
|
|
1791
|
+
* routes are served. Logged like the other retryable 503s (D-0113): the first of each route
|
|
1792
|
+
* per window in full, the rest counted; the start and end of each overload at debug.
|
|
1793
|
+
*/
|
|
1794
|
+
#overload(settings) {
|
|
1795
|
+
const logger = this.context.logger;
|
|
1796
|
+
const limits = {
|
|
1797
|
+
eventLoopDelay: settings.maxEventLoopDelayMs,
|
|
1798
|
+
eventLoopUtilization: settings.maxEventLoopUtilization,
|
|
1799
|
+
heapUsedBytes: settings.maxHeapUsedBytes,
|
|
1800
|
+
rssBytes: settings.maxRssBytes,
|
|
1801
|
+
};
|
|
1802
|
+
const checked = Object.values(limits).some((value) => value > 0);
|
|
1803
|
+
if (!settings.enabled || !checked) {
|
|
1804
|
+
logger.log('debug', 'Web overload protection off', {
|
|
1805
|
+
enabled: settings.enabled,
|
|
1806
|
+
limits: checked,
|
|
1807
|
+
});
|
|
1808
|
+
return;
|
|
1809
|
+
}
|
|
1810
|
+
// The sampler starts with the server (start) and stops when it closes.
|
|
1811
|
+
this.server.addHook('onClose', (_instance, done) => {
|
|
1812
|
+
if (this.#sampler)
|
|
1813
|
+
clearInterval(this.#sampler);
|
|
1814
|
+
done();
|
|
1815
|
+
});
|
|
1816
|
+
this.server.register(underPressure, {
|
|
1817
|
+
sampleInterval: settings.sampleIntervalMs,
|
|
1818
|
+
// Each sample on its own (the default, 'cumulative', averages since the process started).
|
|
1819
|
+
eventLoopUtilizationMode: 'interval',
|
|
1820
|
+
});
|
|
1821
|
+
const answers = new Map();
|
|
1822
|
+
this.#shedding = {
|
|
1823
|
+
settings,
|
|
1824
|
+
limits,
|
|
1825
|
+
seconds: String(Math.ceil(settings.retryAfterMs / 1000)),
|
|
1826
|
+
answer: (reason) => {
|
|
1827
|
+
let answer = answers.get(reason);
|
|
1828
|
+
if (!answer) {
|
|
1829
|
+
const error = new WebError('OVERLOADED', 'The server is overloaded; try again later', {
|
|
1830
|
+
data: { reason, retryAfterMs: settings.retryAfterMs },
|
|
1831
|
+
});
|
|
1832
|
+
answer = errorAnswer(error, this.#production, (details) => this.#details(details));
|
|
1833
|
+
answers.set(reason, answer);
|
|
1834
|
+
}
|
|
1835
|
+
return answer;
|
|
1836
|
+
},
|
|
1837
|
+
};
|
|
1838
|
+
logger.log('debug', 'Web overload protection on', {
|
|
1839
|
+
...limits,
|
|
1840
|
+
sampleIntervalMs: settings.sampleIntervalMs,
|
|
1841
|
+
retryAfterMs: settings.retryAfterMs,
|
|
1842
|
+
});
|
|
1843
|
+
}
|
|
1844
|
+
/**
|
|
1845
|
+
* D-0154: the reloadable options of dokebi-web (securityHeaders but `enabled`, the overload
|
|
1846
|
+
* limits and retryAfterMs, developmentErrors, the transient log, drainGraceMs). Built here,
|
|
1847
|
+
* switched in `apply` for the next request. Overload limits cannot turn protection on when it
|
|
1848
|
+
* was off at start (its sampler was never registered): that needs a restart.
|
|
1849
|
+
*/
|
|
1850
|
+
prepareReload(next) {
|
|
1851
|
+
const shedding = this.#shedding;
|
|
1852
|
+
const limits = {
|
|
1853
|
+
eventLoopDelay: next.overload.maxEventLoopDelayMs,
|
|
1854
|
+
eventLoopUtilization: next.overload.maxEventLoopUtilization,
|
|
1855
|
+
heapUsedBytes: next.overload.maxHeapUsedBytes,
|
|
1856
|
+
rssBytes: next.overload.maxRssBytes,
|
|
1857
|
+
};
|
|
1858
|
+
if (!shedding && Object.values(limits).some((value) => value > 0))
|
|
1859
|
+
throw new DokebiError('OVERLOAD_RESTART_REQUIRED', 'Overload protection was off at start; turning it on needs a restart', {
|
|
1860
|
+
plugin: 'dokebi-web',
|
|
1861
|
+
fix: 'Restart the app to turn on overload protection (its sampler starts with the server).',
|
|
1862
|
+
});
|
|
1863
|
+
const production = process.env.NODE_ENV === 'production' || !next.developmentErrors;
|
|
1864
|
+
const transient = new TransientLog({
|
|
1865
|
+
logger: this.context.logger,
|
|
1866
|
+
windowMs: next.transientLogWindowMs,
|
|
1867
|
+
maxKeys: next.transientLogMaxKeys,
|
|
1868
|
+
level: next.transientLogLevel,
|
|
1869
|
+
});
|
|
1870
|
+
const answers = new Map();
|
|
1871
|
+
const overload = next.overload;
|
|
1872
|
+
const nextShedding = shedding && {
|
|
1873
|
+
settings: overload,
|
|
1874
|
+
limits,
|
|
1875
|
+
seconds: String(Math.ceil(overload.retryAfterMs / 1000)),
|
|
1876
|
+
answer: (reason) => {
|
|
1877
|
+
let answer = answers.get(reason);
|
|
1878
|
+
if (!answer) {
|
|
1879
|
+
const error = new WebError('OVERLOADED', 'The server is overloaded; try again later', {
|
|
1880
|
+
data: { reason, retryAfterMs: overload.retryAfterMs },
|
|
1881
|
+
});
|
|
1882
|
+
answer = errorAnswer(error, production, (details) => this.#details(details));
|
|
1883
|
+
answers.set(reason, answer);
|
|
1884
|
+
}
|
|
1885
|
+
return answer;
|
|
1886
|
+
},
|
|
1887
|
+
};
|
|
1888
|
+
return {
|
|
1889
|
+
apply: () => {
|
|
1890
|
+
this.#security.update(next.securityHeaders);
|
|
1891
|
+
if (nextShedding)
|
|
1892
|
+
this.#shedding = nextShedding;
|
|
1893
|
+
this.#production = production;
|
|
1894
|
+
this.#drainGraceMs = next.drainGraceMs;
|
|
1895
|
+
this.#drainIdleMs = next.drainIdleMs;
|
|
1896
|
+
this.#unavailableRetryAfter = String(Math.ceil(next.unavailableRetryAfterMs / 1000));
|
|
1897
|
+
// The counts of the old window are written, not lost (D-0113).
|
|
1898
|
+
this.#transient.flush();
|
|
1899
|
+
this.#transient = transient;
|
|
1900
|
+
this.context.logger.log('debug', 'Web options reloaded', {
|
|
1901
|
+
code: 'WEB_RELOADED',
|
|
1902
|
+
errorBodies: production ? 'production' : 'development',
|
|
1903
|
+
overload: nextShedding ? limits : false,
|
|
1904
|
+
securityHeaders: this.#security.enabled,
|
|
1905
|
+
});
|
|
1906
|
+
},
|
|
1907
|
+
};
|
|
1908
|
+
}
|
|
1909
|
+
/** Reads the last sample of @fastify/under-pressure: the reason of an overload, or none. */
|
|
1910
|
+
#sample() {
|
|
1911
|
+
const shedding = this.#shedding;
|
|
1912
|
+
if (!shedding)
|
|
1913
|
+
return;
|
|
1914
|
+
const usage = this.server.memoryUsage();
|
|
1915
|
+
const { limits } = shedding;
|
|
1916
|
+
// under-pressure says Infinity when its delay histogram took no sample in an interval: the
|
|
1917
|
+
// loop did not run for about that long (a block, the process descheduled). The delay was at
|
|
1918
|
+
// least one interval, not more than every limit: kept, an Infinity shed every request
|
|
1919
|
+
// whatever maxEventLoopDelayMs said (600000 too) and logged its value as null.
|
|
1920
|
+
const delay = Number.isFinite(usage.eventLoopDelay)
|
|
1921
|
+
? usage.eventLoopDelay
|
|
1922
|
+
: shedding.settings.sampleIntervalMs;
|
|
1923
|
+
const values = [
|
|
1924
|
+
['eventLoopDelay', delay],
|
|
1925
|
+
['eventLoopUtilization', usage.eventLoopUtilized],
|
|
1926
|
+
['heapUsedBytes', usage.heapUsed],
|
|
1927
|
+
['rssBytes', usage.rssBytes],
|
|
1928
|
+
];
|
|
1929
|
+
const over = values.find(([reason, value]) => (limits[reason] ?? 0) > 0 && value > (limits[reason] ?? 0));
|
|
1930
|
+
const before = this.#pressure;
|
|
1931
|
+
this.#pressure = over ? { reason: over[0], value: over[1] } : undefined;
|
|
1932
|
+
const logger = this.context.logger;
|
|
1933
|
+
if (over && !before)
|
|
1934
|
+
logger.log('debug', 'Web overload: requests are refused', {
|
|
1935
|
+
reason: over[0],
|
|
1936
|
+
value: Math.round(over[1] * 1000) / 1000,
|
|
1937
|
+
limit: limits[over[0]],
|
|
1938
|
+
});
|
|
1939
|
+
else if (!over && before)
|
|
1940
|
+
logger.log('debug', 'Web overload over: requests are served again', {
|
|
1941
|
+
reason: before.reason,
|
|
1942
|
+
});
|
|
1943
|
+
}
|
|
1944
|
+
/** Answers a request 503 OVERLOADED, unless its route is served under pressure (true: answered). */
|
|
1945
|
+
#shed(request, reply) {
|
|
1946
|
+
const pressure = this.#pressure;
|
|
1947
|
+
const shedding = this.#shedding;
|
|
1948
|
+
if (!pressure || !shedding)
|
|
1949
|
+
return false;
|
|
1950
|
+
// Read only while shedding: `request.routeOptions` builds a new object on every read.
|
|
1951
|
+
const options = request.routeOptions;
|
|
1952
|
+
const config = options.config;
|
|
1953
|
+
if (config.dokebiHealth === true || config.overload === false)
|
|
1954
|
+
return false;
|
|
1955
|
+
const route = options.url ?? 'unmatched';
|
|
1956
|
+
if (this.#transientFirst(request.method, route, 503, 'OVERLOADED'))
|
|
1957
|
+
this.context.logger.log(this.#transient.level, 'HTTP request refused: the server is overloaded', {
|
|
1958
|
+
code: 'WEB_OVERLOADED',
|
|
1959
|
+
method: request.method,
|
|
1960
|
+
route,
|
|
1961
|
+
routeId: typeof config.id === 'string' ? config.id : null,
|
|
1962
|
+
reason: pressure.reason,
|
|
1963
|
+
value: Math.round(pressure.value * 1000) / 1000,
|
|
1964
|
+
limit: shedding.limits[pressure.reason] ?? null,
|
|
1965
|
+
fix: 'Add capacity, find what blocks the event loop, or raise options.dokebi-web.overload',
|
|
1966
|
+
});
|
|
1967
|
+
const answer = shedding.answer(pressure.reason);
|
|
1968
|
+
reply
|
|
1969
|
+
.code(503)
|
|
1970
|
+
.header('retry-after', shedding.seconds)
|
|
1971
|
+
.header('cache-control', 'no-store')
|
|
1972
|
+
.header('content-language', 'en');
|
|
1973
|
+
const body = this.#production ? productionBody(answer.body) : answer.body;
|
|
1974
|
+
if (requestErrorFormat(request, this.#sealing.sealOf(request) !== undefined) === 'html')
|
|
1975
|
+
reply.type('text/html; charset=utf-8').send(errorPage(503, body));
|
|
1976
|
+
else
|
|
1977
|
+
reply.send(body);
|
|
1978
|
+
return true;
|
|
1979
|
+
}
|
|
1980
|
+
/** True for the first retryable 503 of its code and route in the window (D-0113). */
|
|
1981
|
+
#transientFirst(method, route, status, errorCode, translator, level) {
|
|
1982
|
+
return this.#transient.first(`${status} ${errorCode} ${method} ${route}`, () => ({
|
|
1983
|
+
method,
|
|
1984
|
+
route,
|
|
1985
|
+
status,
|
|
1986
|
+
errorCode,
|
|
1987
|
+
...(translator === undefined ? {} : { translator }),
|
|
1988
|
+
}), level);
|
|
1989
|
+
}
|
|
1990
|
+
/**
|
|
1991
|
+
* The first coded error a translator returns for `error` (D-0093), with its plugin; a
|
|
1992
|
+
* translator that throws or returns something else is logged and skipped. For a coded error
|
|
1993
|
+
* (`serverOnly`) only a translation answering 5xx counts: a 4xx would blame the client for a
|
|
1994
|
+
* failure the plugin or app already called its own.
|
|
1995
|
+
*/
|
|
1996
|
+
#translate(error, request, route, failures, serverOnly) {
|
|
1997
|
+
for (const { plugin, value } of this.#translators) {
|
|
1998
|
+
let result;
|
|
1999
|
+
try {
|
|
2000
|
+
result = value.translate(error, request);
|
|
2001
|
+
if (result === undefined)
|
|
2002
|
+
continue;
|
|
2003
|
+
const known = dokebiError(result);
|
|
2004
|
+
if (known && serverOnly && (known.status ?? 500) < 500) {
|
|
2005
|
+
if (this.context.logger.isEnabled('debug'))
|
|
2006
|
+
this.context.logger.log('debug', 'Web error translation kept the coded error', {
|
|
2007
|
+
route,
|
|
2008
|
+
translator: plugin,
|
|
2009
|
+
errorCode: error.code,
|
|
2010
|
+
translatedCode: known.code,
|
|
2011
|
+
});
|
|
2012
|
+
continue;
|
|
2013
|
+
}
|
|
2014
|
+
if (known)
|
|
2015
|
+
return { error: known, plugin };
|
|
2016
|
+
throw new WebError('INVALID_ERROR_TRANSLATOR', 'An error translator returned something other than a Dokebi error or undefined', { data: { translator: plugin } });
|
|
2017
|
+
}
|
|
2018
|
+
catch (failure) {
|
|
2019
|
+
// Logged, then the next translator (finally the 500 answer) takes the error.
|
|
2020
|
+
const repeated = failures.take(`translator ${plugin} ${route}`);
|
|
2021
|
+
if (repeated !== undefined)
|
|
2022
|
+
this.context.logger.log('error', 'Web error translator failed', {
|
|
2023
|
+
code: 'WEB_ERROR_TRANSLATOR_FAILED',
|
|
2024
|
+
method: request.method,
|
|
2025
|
+
route,
|
|
2026
|
+
translator: plugin,
|
|
2027
|
+
fix: `Return a DokebiError or undefined from the dokebi-web:error-translator of ${plugin}, synchronously, without throwing.`,
|
|
2028
|
+
error: describeError(failure),
|
|
2029
|
+
...(repeated ? { repeated } : {}),
|
|
2030
|
+
});
|
|
2031
|
+
}
|
|
2032
|
+
}
|
|
2033
|
+
return undefined;
|
|
2034
|
+
}
|
|
2035
|
+
/**
|
|
2036
|
+
* The answer to an error raised while sending web's own error answer failed as well: nothing
|
|
2037
|
+
* is left to answer with, so the connection ends (an HTTP/2 stream only), logged once per route
|
|
2038
|
+
* and window. Never throws: Fastify would answer in its own shape then.
|
|
2039
|
+
*/
|
|
2040
|
+
#answerFailed(error, request, reply, failures) {
|
|
2041
|
+
const route = request.routeOptions.url ?? 'unmatched';
|
|
2042
|
+
const repeated = failures.take(`answer-failed ${request.method} ${route}`);
|
|
2043
|
+
if (repeated !== undefined)
|
|
2044
|
+
this.context.logger.log('error', 'HTTP error answer failed; the connection is ended', {
|
|
2045
|
+
code: 'WEB_ERROR_ANSWER_FAILED',
|
|
2046
|
+
requestId: request.id,
|
|
2047
|
+
method: request.method,
|
|
2048
|
+
route,
|
|
2049
|
+
status: reply.statusCode,
|
|
2050
|
+
fix: 'An onSend step failed on the error answer and again on the answer to its own error (a session or cookie store that is down): see error.',
|
|
2051
|
+
error: describeError(error),
|
|
2052
|
+
...(repeated ? { repeated } : {}),
|
|
2053
|
+
});
|
|
2054
|
+
// Ended on purpose: the response's close releases the request at once (it would otherwise be
|
|
2055
|
+
// held as one whose client left, waiting for an answer that is never sent).
|
|
2056
|
+
delete reply.raw[REPLY];
|
|
2057
|
+
if (http1(request))
|
|
2058
|
+
reply.raw.socket?.destroy();
|
|
2059
|
+
else
|
|
2060
|
+
request.raw.stream?.close(2);
|
|
2061
|
+
return undefined;
|
|
2062
|
+
}
|
|
2063
|
+
/**
|
|
2064
|
+
* D-0047: a handler whose Promise rejected after its answer was sent (work it awaited after
|
|
2065
|
+
* `reply.send`, a hijacked stream). Fastify cannot answer it any more and only tells its own
|
|
2066
|
+
* logger, which is off without @dokebi/logger's request log. Once per route and error per
|
|
2067
|
+
* `logRepeatWindowMs`, with `repeated`.
|
|
2068
|
+
*/
|
|
2069
|
+
#failedAfterSend(request, reply, error, failures) {
|
|
2070
|
+
const matched = request.routeOptions;
|
|
2071
|
+
const route = matched.url ?? 'unmatched';
|
|
2072
|
+
// The body stalled and was answered 408: the handler then fails reading it, as expected.
|
|
2073
|
+
if (request.raw[TIMED_OUT] !== undefined) {
|
|
2074
|
+
if (this.context.logger.isEnabled('debug'))
|
|
2075
|
+
this.context.logger.log('debug', 'HTTP handler ended after its body timed out', {
|
|
2076
|
+
method: request.method,
|
|
2077
|
+
route,
|
|
2078
|
+
error: describeError(error),
|
|
2079
|
+
});
|
|
2080
|
+
return;
|
|
2081
|
+
}
|
|
2082
|
+
const name = error instanceof Error ? error.name : typeof error;
|
|
2083
|
+
const own = error?.code;
|
|
2084
|
+
const repeated = failures.take(`after-send ${request.method} ${route} ${name} ${String(own)}`);
|
|
2085
|
+
if (repeated === undefined)
|
|
2086
|
+
return;
|
|
2087
|
+
this.context.logger.log('error', 'HTTP handler failed after its answer was sent', {
|
|
2088
|
+
code: 'WEB_HANDLER_FAILED_AFTER_SEND',
|
|
2089
|
+
requestId: request.id,
|
|
2090
|
+
method: request.method,
|
|
2091
|
+
route,
|
|
2092
|
+
routeId: typeof matched.config?.id === 'string' ? matched.config.id : null,
|
|
2093
|
+
status: reply.statusCode,
|
|
2094
|
+
...(typeof own === 'string' ? { errorCode: own } : {}),
|
|
2095
|
+
fix: 'The client already has its answer: catch and handle errors of work done after reply.send() (or move it to web.track() or a job).',
|
|
2096
|
+
error: describeError(error),
|
|
2097
|
+
...(repeated ? { repeated } : {}),
|
|
2098
|
+
});
|
|
791
2099
|
}
|
|
792
|
-
/**
|
|
793
|
-
|
|
2100
|
+
/**
|
|
2101
|
+
* The built-in answer: the body as JSON, or its small HTML page. `own`: its words are web's
|
|
2102
|
+
* fixed English (`<html lang="en">`, the messages of coded errors), so it says
|
|
2103
|
+
* `Content-Language: en` — not the language a plugin negotiated for the request before
|
|
2104
|
+
* (@dokebi/i18n sets that in onRequest). A body the errorBody hook wrote, and an app's error
|
|
2105
|
+
* view sent by a responder, keep whatever header they have.
|
|
2106
|
+
*/
|
|
2107
|
+
#send(reply, status, body, format, own) {
|
|
794
2108
|
reply.code(status);
|
|
2109
|
+
if (own)
|
|
2110
|
+
reply.header('content-language', 'en');
|
|
795
2111
|
if (format === 'html')
|
|
796
2112
|
reply.type('text/html; charset=utf-8').send(errorPage(status, body));
|
|
797
2113
|
else
|
|
798
2114
|
reply.type('application/json; charset=utf-8').send(body);
|
|
799
2115
|
}
|
|
800
2116
|
/** Asks the error responders (D-0074); the built-in answer when none wrote one or one failed. */
|
|
801
|
-
async #respond(response, route, failures) {
|
|
2117
|
+
async #respond(response, route, failures, own) {
|
|
802
2118
|
const { request, reply } = response;
|
|
803
2119
|
const logger = this.context.logger;
|
|
804
2120
|
// `reply.sent` stays false until the response has ended (async onSend hooks such as the
|
|
@@ -839,7 +2155,7 @@ class WebOwner {
|
|
|
839
2155
|
}
|
|
840
2156
|
}
|
|
841
2157
|
// Headers a failed responder may have set (a view's type) are replaced by the built-in answer.
|
|
842
|
-
this.#send(reply, response.status, response.body, response.format);
|
|
2158
|
+
this.#send(reply, response.status, response.body, response.format, own);
|
|
843
2159
|
return reply;
|
|
844
2160
|
}
|
|
845
2161
|
/** `details` for a development body; one that is not JSON (a cycle, a BigInt) is left out. */
|
|
@@ -866,11 +2182,16 @@ class WebOwner {
|
|
|
866
2182
|
method: request.method,
|
|
867
2183
|
url: request.url.split('?', 1)[0]?.slice(0, 200),
|
|
868
2184
|
});
|
|
869
|
-
// D-0074 §1: a browser navigation gets a small page, every script JSON; sealed
|
|
870
|
-
// JSON (the route is known in onRequest, so the seal decision is too).
|
|
871
|
-
const html =
|
|
2185
|
+
// D-0074 §1: a browser navigation gets a small page, every script JSON; other sealed
|
|
2186
|
+
// requests stay JSON (the route is known in onRequest, so the seal decision is too).
|
|
2187
|
+
const html = requestErrorFormat(request, this.#sealing.sealOf(request) !== undefined) === 'html';
|
|
2188
|
+
// Like every retryable 503 of the stack (a Redis outage, overload): when to try again. The
|
|
2189
|
+
// connection still closes, so the retry may reach another worker or instance.
|
|
2190
|
+
const retryAfter = this.#unavailableRetryAfter;
|
|
872
2191
|
if (!this.#hooks || !this.#overridden.has('unavailable')) {
|
|
873
|
-
reply.code(503).header('
|
|
2192
|
+
reply.code(503).header('content-language', 'en').header('retry-after', retryAfter);
|
|
2193
|
+
if (http1(request))
|
|
2194
|
+
reply.header('connection', 'close');
|
|
874
2195
|
if (html)
|
|
875
2196
|
reply
|
|
876
2197
|
.type('text/html; charset=utf-8')
|
|
@@ -881,6 +2202,7 @@ class WebOwner {
|
|
|
881
2202
|
}
|
|
882
2203
|
const answer = {
|
|
883
2204
|
status: 503,
|
|
2205
|
+
headers: { 'retry-after': retryAfter },
|
|
884
2206
|
body: { error: 'SERVICE_UNAVAILABLE', reason },
|
|
885
2207
|
};
|
|
886
2208
|
let chosen = answer;
|
|
@@ -890,6 +2212,12 @@ class WebOwner {
|
|
|
890
2212
|
throw new WebError('INVALID_EXTENSION_RESULT', 'unavailable() returned no answer', {
|
|
891
2213
|
data: { hook: 'unavailable' },
|
|
892
2214
|
});
|
|
2215
|
+
// Node's own rules (ERR_INVALID_HTTP_TOKEN, ERR_INVALID_CHAR): a value with a line break
|
|
2216
|
+
// otherwise failed the refusal at writeHead into Fastify's own 500 body.
|
|
2217
|
+
for (const [name, value] of Object.entries(result.headers ?? {})) {
|
|
2218
|
+
validateHeaderName(name);
|
|
2219
|
+
validateHeaderValue(name, value);
|
|
2220
|
+
}
|
|
893
2221
|
chosen = result;
|
|
894
2222
|
}
|
|
895
2223
|
catch (failure) {
|
|
@@ -904,7 +2232,8 @@ class WebOwner {
|
|
|
904
2232
|
for (const [name, value] of Object.entries(chosen.headers ?? {}))
|
|
905
2233
|
reply.header(name, value);
|
|
906
2234
|
// The request is refused either way: the connection closes, as without the hook.
|
|
907
|
-
|
|
2235
|
+
if (http1(request))
|
|
2236
|
+
reply.header('connection', 'close');
|
|
908
2237
|
const body = chosen.body;
|
|
909
2238
|
// A page only for a body of the error shape; anything else the hook chose stays JSON.
|
|
910
2239
|
if (html && body !== null && typeof body === 'object' && typeof body.error === 'string')
|
|
@@ -936,9 +2265,17 @@ class WebOwner {
|
|
|
936
2265
|
async close() {
|
|
937
2266
|
this.#closed = true;
|
|
938
2267
|
const started = performance.now();
|
|
939
|
-
|
|
2268
|
+
const { ended } = this.#connections.close();
|
|
2269
|
+
try {
|
|
2270
|
+
await this.server.close();
|
|
2271
|
+
}
|
|
2272
|
+
finally {
|
|
2273
|
+
// The counts of a burst that ends with the server are written, not lost (D-0113).
|
|
2274
|
+
this.#transient.flush();
|
|
2275
|
+
}
|
|
940
2276
|
this.context.logger.log('debug', 'Web server closed', {
|
|
941
2277
|
ms: Math.round(performance.now() - started),
|
|
2278
|
+
endedConnections: ended,
|
|
942
2279
|
});
|
|
943
2280
|
}
|
|
944
2281
|
}
|
|
@@ -946,8 +2283,30 @@ const NO_EXTENSION = Object.freeze({
|
|
|
946
2283
|
hooks: undefined,
|
|
947
2284
|
overridden: new Set(),
|
|
948
2285
|
});
|
|
2286
|
+
/**
|
|
2287
|
+
* Ajv's logger (its `logger` option) on the plugin's logger: Ajv reports schema problems of strict
|
|
2288
|
+
* mode (`strictTypes`, unknown formats) while a route's schema compiles, with console otherwise.
|
|
2289
|
+
*/
|
|
2290
|
+
function schemaLogger(logger) {
|
|
2291
|
+
const text = (parts) => parts.map(String).join(' ');
|
|
2292
|
+
return {
|
|
2293
|
+
log: (...parts) => {
|
|
2294
|
+
if (logger.isEnabled('debug'))
|
|
2295
|
+
logger.log('debug', 'Schema compiler message', {
|
|
2296
|
+
code: 'WEB_SCHEMA_MESSAGE',
|
|
2297
|
+
message: text(parts),
|
|
2298
|
+
});
|
|
2299
|
+
},
|
|
2300
|
+
warn: (...parts) => logger.log('warn', 'Route schema warning', {
|
|
2301
|
+
code: 'WEB_SCHEMA_WARNING',
|
|
2302
|
+
warning: text(parts),
|
|
2303
|
+
}),
|
|
2304
|
+
error: (...parts) => logger.log('error', 'Route schema error', { code: 'WEB_SCHEMA_ERROR', error: text(parts) }),
|
|
2305
|
+
};
|
|
2306
|
+
}
|
|
949
2307
|
const HEALTH = 'dokebi-health';
|
|
950
2308
|
const health = optionalDependency({ name: HEALTH, version: '^0.4.0' });
|
|
2309
|
+
const logging = optionalDependency({ name: 'dokebi-logger', version: '^0.1.0' });
|
|
951
2310
|
function invalidEntry(message, fix) {
|
|
952
2311
|
return new WebError('INVALID_ENTRY', message, fix === undefined ? {} : { fix });
|
|
953
2312
|
}
|
|
@@ -1044,13 +2403,42 @@ class WebRuntime {
|
|
|
1044
2403
|
this.health = health;
|
|
1045
2404
|
}
|
|
1046
2405
|
setup(context) {
|
|
1047
|
-
const owner = new WebOwner(context, this.options, this.extension, context.getOptionalDependency(this.health));
|
|
2406
|
+
const owner = new WebOwner(context, this.options, this.extension, context.getOptionalDependency(this.health), context.getOptionalDependency(logging));
|
|
1048
2407
|
this.#owner = owner;
|
|
1049
2408
|
context.defer(() => owner.close());
|
|
1050
2409
|
// D-0063 §7: `inject` of @dokebi/core/testing goes through this server, without a socket.
|
|
1051
2410
|
context.contribute(injectPoint, Object.freeze({
|
|
1052
2411
|
inject: (request) => owner.inject(request),
|
|
1053
2412
|
}));
|
|
2413
|
+
// D-0077 B: only `dokebi describe` (runtime.describing) asks; a normal start adds nothing.
|
|
2414
|
+
if (context.runtime.describing) {
|
|
2415
|
+
const options = this.options;
|
|
2416
|
+
context.contribute(describePoint, {
|
|
2417
|
+
section: 'routes',
|
|
2418
|
+
describe: () => owner.describeRoutes(),
|
|
2419
|
+
});
|
|
2420
|
+
context.contribute(describePoint, {
|
|
2421
|
+
section: 'web',
|
|
2422
|
+
describe: () => ({
|
|
2423
|
+
host: options.host,
|
|
2424
|
+
port: options.port,
|
|
2425
|
+
healthRoutes: options.healthRoutes ? { ...options.healthRoutes } : false,
|
|
2426
|
+
formBody: options.formBody,
|
|
2427
|
+
maxBodyBytes: options.maxBodyBytes,
|
|
2428
|
+
trustProxy: options.trustProxy.length,
|
|
2429
|
+
sealExclude: [...options.sealExclude],
|
|
2430
|
+
compression: options.compression.enabled
|
|
2431
|
+
? { ...options.compression, encodings: [...options.compression.encodings] }
|
|
2432
|
+
: false,
|
|
2433
|
+
}),
|
|
2434
|
+
});
|
|
2435
|
+
context.contribute(describePoint, {
|
|
2436
|
+
section: 'env',
|
|
2437
|
+
describe: () => [
|
|
2438
|
+
{ name: 'NODE_ENV', purpose: 'production: error bodies without fix and details' },
|
|
2439
|
+
],
|
|
2440
|
+
});
|
|
2441
|
+
}
|
|
1054
2442
|
return owner.api;
|
|
1055
2443
|
}
|
|
1056
2444
|
start() {
|
|
@@ -1060,27 +2448,100 @@ class WebRuntime {
|
|
|
1060
2448
|
return this.#owner?.worker ? this.#owner.listen() : undefined;
|
|
1061
2449
|
}
|
|
1062
2450
|
drain(context) {
|
|
1063
|
-
|
|
2451
|
+
// core 0.4.2: drainDeadline (an older core has none: the idle wait is drainIdleMs alone).
|
|
2452
|
+
return this.#owner?.drain(context.drainSignal, context.drainDeadline);
|
|
2453
|
+
}
|
|
2454
|
+
/** D-0154: the reloadable options (see WebOwner.prepareReload). */
|
|
2455
|
+
reload({ options }) {
|
|
2456
|
+
return this.#owner?.prepareReload(settings(options));
|
|
1064
2457
|
}
|
|
1065
2458
|
}
|
|
1066
2459
|
export const createPlugin = definePlugin({
|
|
1067
2460
|
name: 'dokebi-web',
|
|
1068
|
-
version: '0.4.
|
|
1069
|
-
core: '^0.4.
|
|
2461
|
+
version: '0.4.4',
|
|
2462
|
+
core: '^0.4.2',
|
|
1070
2463
|
options: declaration,
|
|
1071
2464
|
entry: (input) => new WebEntryInput(input),
|
|
1072
|
-
contributes: [injectPoint],
|
|
2465
|
+
contributes: [injectPoint, describePoint],
|
|
2466
|
+
collects: [errorTranslators],
|
|
1073
2467
|
// A required dokebi-health in entry.requires replaces the optional link.
|
|
1074
2468
|
dependencies: ({ entry }) => {
|
|
1075
2469
|
// The extension is created here, once: a broken subclass fails the factory call.
|
|
1076
2470
|
entry?.extension();
|
|
1077
2471
|
const requires = entry?.requires ?? [];
|
|
1078
|
-
|
|
2472
|
+
const linked = requires.some((dependency) => dependency.name === HEALTH)
|
|
1079
2473
|
? requires
|
|
1080
2474
|
: [...requires, health];
|
|
2475
|
+
return linked.some((dependency) => dependency.name === logging.name)
|
|
2476
|
+
? linked
|
|
2477
|
+
: [...linked, logging];
|
|
1081
2478
|
},
|
|
1082
2479
|
instance: ({ options, entry, dependencies }) => new WebRuntime(settings(options), entry?.extension() ?? NO_EXTENSION, (dependencies.find((dependency) => dependency.name === HEALTH) ??
|
|
1083
2480
|
health)),
|
|
1084
2481
|
});
|
|
1085
2482
|
/** Declares dokebi-web as a required provider (also `@dokebi/web/dependency`, D-0063 §6). */
|
|
1086
2483
|
export { dependency } from './dependency.js';
|
|
2484
|
+
const LINGERING = Symbol('dokebi.web.lingering');
|
|
2485
|
+
/**
|
|
2486
|
+
* Lingering close (as nginx's lingering_close): when Node closes the connection after an answer
|
|
2487
|
+
* sent before the request body was read, it first sends FIN only, keeps reading and dropping what
|
|
2488
|
+
* the client still sends — up to `linger.maxBytes`, for at most `linger.ms` — and closes once the
|
|
2489
|
+
* client has sent it all. The client then reads the answer instead of a connection reset.
|
|
2490
|
+
*/
|
|
2491
|
+
function lingerOnClose(request, linger, logger) {
|
|
2492
|
+
const { ms, maxBytes } = linger;
|
|
2493
|
+
const socket = request.socket;
|
|
2494
|
+
// An injected request (light-my-request) has no real socket to linger on.
|
|
2495
|
+
if (ms === 0 || !socket || typeof socket.destroySoon !== 'function' || socket[LINGERING])
|
|
2496
|
+
return;
|
|
2497
|
+
socket[LINGERING] = true;
|
|
2498
|
+
const destroySoon = socket.destroySoon.bind(socket);
|
|
2499
|
+
socket.destroySoon = () => {
|
|
2500
|
+
if (socket.destroyed)
|
|
2501
|
+
return;
|
|
2502
|
+
let read = 0;
|
|
2503
|
+
const close = (reason) => {
|
|
2504
|
+
clearTimeout(timer);
|
|
2505
|
+
if (logger.isEnabled('debug'))
|
|
2506
|
+
logger.log('debug', 'Early-answered connection closed after lingering', {
|
|
2507
|
+
code: 'WEB_LINGER_CLOSED',
|
|
2508
|
+
reason,
|
|
2509
|
+
bytes: read,
|
|
2510
|
+
});
|
|
2511
|
+
if (!socket.destroyed)
|
|
2512
|
+
socket.destroy();
|
|
2513
|
+
};
|
|
2514
|
+
const timer = setTimeout(() => close('time'), ms);
|
|
2515
|
+
timer.unref();
|
|
2516
|
+
socket.once('close', () => clearTimeout(timer));
|
|
2517
|
+
request.on('data', (chunk) => {
|
|
2518
|
+
read += chunk.length;
|
|
2519
|
+
if (read > maxBytes)
|
|
2520
|
+
close('size');
|
|
2521
|
+
});
|
|
2522
|
+
request.once('end', () => close('end'));
|
|
2523
|
+
// The client read the answer and closed its side (most stop sending at our FIN).
|
|
2524
|
+
socket.once('end', () => close('client'));
|
|
2525
|
+
// A client that resets the connection while it lingers ends it; nothing is left to answer.
|
|
2526
|
+
request.once('error', (error) => {
|
|
2527
|
+
if (logger.isEnabled('debug'))
|
|
2528
|
+
logger.log('debug', 'Early-answered connection ended by the client while lingering', {
|
|
2529
|
+
code: 'WEB_LINGER_CLOSED',
|
|
2530
|
+
reason: 'error',
|
|
2531
|
+
error: diagnostics.describeError(error),
|
|
2532
|
+
});
|
|
2533
|
+
close('error');
|
|
2534
|
+
});
|
|
2535
|
+
try {
|
|
2536
|
+
socket.end();
|
|
2537
|
+
request.resume();
|
|
2538
|
+
}
|
|
2539
|
+
catch (error) {
|
|
2540
|
+
logger.log('error', 'Lingering close failed; closing the connection now', {
|
|
2541
|
+
code: 'WEB_LINGER_FAILED',
|
|
2542
|
+
error: diagnostics.describeError(error),
|
|
2543
|
+
});
|
|
2544
|
+
destroySoon();
|
|
2545
|
+
}
|
|
2546
|
+
};
|
|
2547
|
+
}
|