@dokebi/web 0.4.1 → 0.4.3
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 +248 -38
- package/README.md +32 -11
- 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 +26 -2
- package/dist/forms.d.ts +27 -10
- package/dist/forms.js +75 -17
- package/dist/index.d.ts +134 -4
- package/dist/index.js +1518 -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 +261 -20
- 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,19 @@ 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
|
+
});
|
|
208
416
|
const lazySchemas = restoreDefaultCompilers(this.server, created.schemaController, schemaController);
|
|
209
417
|
const owner = this;
|
|
210
418
|
logger.log('debug', 'Web server configured', {
|
|
211
419
|
host: options.host,
|
|
212
420
|
port: options.port,
|
|
213
421
|
bodyLimit: options.maxBodyBytes,
|
|
422
|
+
maxRouteBodyBytes: options.maxRouteBodyBytes,
|
|
423
|
+
binaryBody: options.binaryBody,
|
|
214
424
|
requestTimeout: options.requestTimeoutMs,
|
|
215
425
|
healthRoutes: options.healthRoutes ? { ...options.healthRoutes } : false,
|
|
216
426
|
trustProxy: options.trustProxy.length,
|
|
@@ -218,8 +428,18 @@ class WebOwner {
|
|
|
218
428
|
sealExclude: options.sealExclude.length,
|
|
219
429
|
formBody: options.formBody,
|
|
220
430
|
formMaxFields: options.formMaxFields,
|
|
431
|
+
unknownFields: options.unknownFields,
|
|
432
|
+
transientLog: {
|
|
433
|
+
windowMs: options.transientLogWindowMs,
|
|
434
|
+
maxKeys: options.transientLogMaxKeys,
|
|
435
|
+
level: options.transientLogLevel,
|
|
436
|
+
},
|
|
437
|
+
compression: options.compression.enabled
|
|
438
|
+
? { ...options.compression, encodings: [...options.compression.encodings] }
|
|
439
|
+
: false,
|
|
221
440
|
errorBodies: this.#production ? 'production' : 'development',
|
|
222
441
|
health: health !== undefined,
|
|
442
|
+
requestLog: logging?.requests === true,
|
|
223
443
|
// `lazy`: Fastify's default compilers, loaded on the first schema route (D-0070 §5).
|
|
224
444
|
schemaCompilers: lazySchemas ? 'lazy' : 'extension',
|
|
225
445
|
role: runtime.role,
|
|
@@ -227,14 +447,54 @@ class WebOwner {
|
|
|
227
447
|
extension: [...this.#overridden],
|
|
228
448
|
...(created === defaults ? {} : { fastifyOptions: Object.keys(created).sort() }),
|
|
229
449
|
});
|
|
230
|
-
|
|
450
|
+
this.#translators = checkTranslators(context.collect(errorTranslators));
|
|
451
|
+
if (this.#translators.length)
|
|
452
|
+
logger.log('debug', 'Web error translators collected', {
|
|
453
|
+
translators: this.#translators.map((item) => item.plugin),
|
|
454
|
+
});
|
|
455
|
+
const failures = new Repeats({ intervalMs: options.logRepeatWindowMs });
|
|
456
|
+
// With @dokebi/logger's request log Fastify writes its own records (D-0151), among them the
|
|
457
|
+
// error of a handler that failed after its answer was sent; without it web says so itself.
|
|
458
|
+
const fastifyLogs = logging?.requests === true;
|
|
231
459
|
this.server.setErrorHandler((error, request, reply) => this.#fail(error, request, reply, failures));
|
|
460
|
+
// An error raised while web sends its own error answer (an async onSend step: the session's
|
|
461
|
+
// save in a Redis outage) goes to the next handler of Fastify's chain, its default one, which
|
|
462
|
+
// answers in Fastify's own shape (audit r4 step 2). web keeps the chain on itself for that
|
|
463
|
+
// second error, then on a last step that ends the connection (lib/error-handler.js).
|
|
464
|
+
const { kErrorHandler, kReplyNextErrorHandler } = errorHandlerSymbols();
|
|
465
|
+
const own = this.server[kErrorHandler];
|
|
466
|
+
const last = Object.assign(Object.create(Object.getPrototypeOf(own)), {
|
|
467
|
+
func: (error, request, reply) => this.#answerFailed(error, request, reply, failures),
|
|
468
|
+
});
|
|
469
|
+
this.#nextHandler = (reply, pass) => {
|
|
470
|
+
reply[kReplyNextErrorHandler] =
|
|
471
|
+
pass === 1 ? own : last;
|
|
472
|
+
};
|
|
232
473
|
// An unknown route answers like any other error (D-0074): the same body, format and
|
|
233
474
|
// responders (an app's errors/404.ejs), not Fastify's own `{ message, error, statusCode }`.
|
|
234
475
|
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
476
|
// D-0062: the seal slot. Its hook steps do nothing until something asks for sealing.
|
|
236
|
-
const sealing = new WebSealing(logger, {
|
|
477
|
+
const sealing = new WebSealing(logger, {
|
|
478
|
+
driftMs: options.sealDriftMs,
|
|
479
|
+
exclude: options.sealExclude,
|
|
480
|
+
formBody: options.formBody,
|
|
481
|
+
formMaxFields: options.formMaxFields,
|
|
482
|
+
retryAfterMs: options.sealRetryAfterMs,
|
|
483
|
+
logRepeatWindowMs: options.logRepeatWindowMs,
|
|
484
|
+
}, (request) => this.api.requestHost(request));
|
|
237
485
|
this.#sealing = sealing;
|
|
486
|
+
/** D-0181: what tells a request's app (dokebi-app), asked by appOf. */
|
|
487
|
+
const appResolvers = [];
|
|
488
|
+
const security = new SecurityHeaders(options.securityHeaders);
|
|
489
|
+
this.#security = security;
|
|
490
|
+
// D-0125: the last onSend step of every route (added in onRoute below) and of 404 answers.
|
|
491
|
+
const compression = options.compression.enabled
|
|
492
|
+
? new ResponseCompression(options.compression, logger, {
|
|
493
|
+
draining: () => this.#draining,
|
|
494
|
+
// A sealed body is a ciphertext: compressing it gains nothing.
|
|
495
|
+
sealType: () => sealing.provider?.contentType,
|
|
496
|
+
}, options.logRepeatWindowMs)
|
|
497
|
+
: undefined;
|
|
238
498
|
// A request is held from here until its response closes (D-0068): one counter and one shared
|
|
239
499
|
// listener, no Promise or closure per request. Callback style: no Promise per hook either.
|
|
240
500
|
const closed = function () {
|
|
@@ -282,47 +542,133 @@ class WebOwner {
|
|
|
282
542
|
});
|
|
283
543
|
}
|
|
284
544
|
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
|
-
|
|
545
|
+
const state = context.app.state;
|
|
546
|
+
// The running state is decided without the route: `request.routeOptions` builds a new
|
|
547
|
+
// object on every read, so it is read only while requests may be turned away. A health
|
|
548
|
+
// request of the running state is held like any other (it ends at once).
|
|
549
|
+
if (this.#draining || state !== 'running' || (health && !health.ready)) {
|
|
550
|
+
const config = request.routeOptions.config;
|
|
551
|
+
// Health routes answer before ready and while draining, untracked.
|
|
552
|
+
if (config.dokebiHealth === true)
|
|
553
|
+
return done();
|
|
554
|
+
// The app is stopping once its drain began, also while the plugins that depend on web
|
|
555
|
+
// (sse, websocket) drain before web's own drain starts (audit r4 step 2: those requests
|
|
556
|
+
// were refused as STARTING, on a cluster worker that still listened).
|
|
557
|
+
const stopping = this.#draining || state === 'stopping' || state === 'cleaning';
|
|
558
|
+
// A draining node:cluster worker no longer listens; a request still arriving on one of
|
|
559
|
+
// its open keep-alive connections is served and that connection then closes, so the
|
|
560
|
+
// client's next request goes to another worker instead of seeing 503 (D-0036).
|
|
561
|
+
if (stopping && worker) {
|
|
562
|
+
if (http1(request))
|
|
563
|
+
reply.header('connection', 'close');
|
|
564
|
+
}
|
|
565
|
+
else if (config.readiness === false &&
|
|
566
|
+
(state === 'running' || state === 'stopping') &&
|
|
567
|
+
!context.signal.aborted) {
|
|
568
|
+
// M51: a metrics or status route also while a dependency is down (NOT_READY) or the
|
|
569
|
+
// app drains; tracked like any request, so the drain waits for it. Core keeps the state
|
|
570
|
+
// `stopping` through the cleanup of a stop and aborts context.signal as it begins: the
|
|
571
|
+
// plugins behind the route (metrics, a database) are going away then (audit r5 step 2).
|
|
572
|
+
}
|
|
573
|
+
else {
|
|
574
|
+
this.#refuse(request, reply, stopping ? 'DRAINING' : state !== 'running' ? 'STARTING' : 'NOT_READY');
|
|
575
|
+
return;
|
|
576
|
+
}
|
|
305
577
|
}
|
|
578
|
+
// D-0150: one field read while calm; the route only while the server sheds load.
|
|
579
|
+
if (this.#pressure !== undefined && this.#shed(request, reply))
|
|
580
|
+
return;
|
|
306
581
|
const raw = reply.raw;
|
|
307
582
|
this.#inflight++;
|
|
308
583
|
raw[REPLY] = reply;
|
|
309
584
|
raw.on('close', closed);
|
|
585
|
+
// A route with `completed` observers (metrics) is told from the close above, without a
|
|
586
|
+
// Fastify onResponse hook (its response listeners and hook runner on every request).
|
|
587
|
+
if (this.#routeHooks.completing) {
|
|
588
|
+
const context = reply[ROUTE_CONTEXT];
|
|
589
|
+
const completed = context?.config?.[COMPLETED];
|
|
590
|
+
if (completed !== undefined && completed.length > 0) {
|
|
591
|
+
raw[COMPLETING] = completed;
|
|
592
|
+
raw[STARTED] = performance.now();
|
|
593
|
+
}
|
|
594
|
+
}
|
|
595
|
+
// requestTimeoutMs bounds the body: one timer while a body is arriving, so the answer is
|
|
596
|
+
// web's 408 REQUEST_TIMEOUT on time (Node's own check runs every 30 s and is set past
|
|
597
|
+
// every body time at start, see #nodeTimeouts; HTTP/2 has none at all).
|
|
598
|
+
if (!request.raw.complete && bodyFollows(request))
|
|
599
|
+
owner.#timeBody(request, reply, options.requestTimeoutMs);
|
|
600
|
+
// A sealed form marker on a body that is not sealed (or multipart) is refused before any
|
|
601
|
+
// parser too (D-0092 §1.3): the marker promises a body of the urlencoded shape.
|
|
602
|
+
if (request.headers[FORM_SUBMISSION_HEADER] !== undefined) {
|
|
603
|
+
const refused = formMarkerRefusal(request.headers, sealing.provider?.contentType, bodyFollows(request));
|
|
604
|
+
if (refused) {
|
|
605
|
+
done(refused);
|
|
606
|
+
return;
|
|
607
|
+
}
|
|
608
|
+
}
|
|
310
609
|
// A sealed request with a plain body is answered 415 here, before any parser (D-0062).
|
|
311
610
|
done(sealing.provider ? sealing.refusePlain(request) : undefined);
|
|
312
611
|
});
|
|
612
|
+
this.#overload(options.overload);
|
|
313
613
|
this.server.addHook('onSend', (request, reply, payload, done) => {
|
|
314
614
|
reply.raw[SENDING] = true;
|
|
315
|
-
|
|
316
|
-
|
|
317
|
-
|
|
615
|
+
if (!http1(request)) {
|
|
616
|
+
// HTTP/2 has no connection header (RFC 9113 §8.2.2): one set by Fastify (its 413 and
|
|
617
|
+
// every body parse error) or a plugin would only be dropped by Node with a process
|
|
618
|
+
// warning on stderr. The stream ends; GOAWAY ends a session.
|
|
619
|
+
if (reply.hasHeader('connection'))
|
|
620
|
+
reply.removeHeader('connection');
|
|
621
|
+
}
|
|
622
|
+
else if (this.#draining && worker) {
|
|
623
|
+
// Responses already under way when a cluster worker starts draining close their
|
|
624
|
+
// connection too, instead of leaving it idle for the client to reuse (D-0036).
|
|
625
|
+
reply.header('connection', 'close');
|
|
626
|
+
}
|
|
627
|
+
// An answer sent before the request body was read to its end (413 from Content-Length, a
|
|
628
|
+
// 415 or 403 refused before any parser) closes the connection: the unread body is still on
|
|
629
|
+
// the socket, so a kept-alive connection would not answer the client's next request there
|
|
630
|
+
// (AI-M42: the next request waited for a timeout, then ECONNRESET).
|
|
631
|
+
if (!request.raw.complete && hasBody(request.headers) && http1(request)) {
|
|
318
632
|
reply.header('connection', 'close');
|
|
319
|
-
|
|
633
|
+
// Lingering close: the client may still be sending that body; closing at once resets the
|
|
634
|
+
// connection under it and it never reads this answer (AI-M47: ECONNRESET in a test). Not
|
|
635
|
+
// for a body that stalled (408): that client is not sending.
|
|
636
|
+
if (request.raw[TIMED_OUT] === undefined)
|
|
637
|
+
lingerOnClose(request.raw, options.linger, this.context.logger);
|
|
638
|
+
}
|
|
639
|
+
const status = reply.statusCode;
|
|
640
|
+
// A redirect of a sealed form (D-0092 §1.2) is told, not followed: the forms module's fetch
|
|
641
|
+
// would follow it itself — rendering the next page (and taking its flash) for nothing, and
|
|
642
|
+
// failing on another origin — so the answer is 204 with the target in x-dokebi-location.
|
|
643
|
+
if (status >= 300 &&
|
|
644
|
+
status < 400 &&
|
|
645
|
+
request.headers[FORM_SUBMISSION_HEADER] === '1' &&
|
|
646
|
+
reply.hasHeader('location')) {
|
|
647
|
+
done(null, sealedFormRedirect(request, reply, logger, payload));
|
|
648
|
+
return;
|
|
649
|
+
}
|
|
650
|
+
const sent = sealing.provider ? sealing.onSend(request, reply, payload) : payload;
|
|
651
|
+
// D-0149: an unknown route has no route-level hooks; its answer gets the default headers.
|
|
652
|
+
if (security.enabled && request.is404)
|
|
653
|
+
security.apply(security.defaults, request, reply);
|
|
654
|
+
// An unknown route has no route-level hooks: its answer (an app's 404 page) is compressed
|
|
655
|
+
// here. Every matched route compresses in its own last onSend step (onRoute).
|
|
656
|
+
if (compression !== undefined && request.is404)
|
|
657
|
+
compression.hook(request, reply, sent, done);
|
|
658
|
+
else
|
|
659
|
+
done(null, sent);
|
|
320
660
|
});
|
|
321
661
|
this.#formBody(options);
|
|
662
|
+
this.#binaryBody(options);
|
|
322
663
|
this.server.addHook('onRoute', (route) => {
|
|
664
|
+
// D-0122: a route's own body limit, within maxRouteBodyBytes (Fastify answers 413 from
|
|
665
|
+
// Content-Length before reading, or as soon as a streamed body passes it).
|
|
666
|
+
owner.#checkBodyLimit(route.method, route.url, route.bodyLimit);
|
|
323
667
|
// `seal` on a route given to Fastify directly (a register() scope, @dokebi/router mount)
|
|
324
668
|
// becomes `config.dokebiSeal` too, so every way of adding a route can opt out (D-0062).
|
|
325
669
|
const options = route;
|
|
670
|
+
// D-0132: `app` becomes the host constraint of app routes (before anything reads it).
|
|
671
|
+
owner.#appRoutes.route(options);
|
|
326
672
|
if (options.seal !== undefined) {
|
|
327
673
|
options.config = {
|
|
328
674
|
...route.config,
|
|
@@ -331,9 +677,66 @@ class WebOwner {
|
|
|
331
677
|
delete options.seal;
|
|
332
678
|
}
|
|
333
679
|
const config = route.config;
|
|
680
|
+
owner.#routeConfig.record(route.method, route.url, config);
|
|
681
|
+
owner.#routeTable.record(route.method, route.url, config, route.constraints, route.schema);
|
|
334
682
|
sealing.route(checkSealSetting(config?.dokebiSeal));
|
|
335
683
|
if (config?.dokebiHealth === true)
|
|
336
684
|
return;
|
|
685
|
+
// D-0149: the security headers are a route-level onSend step too (built at the first answer
|
|
686
|
+
// after the start); `securityHeaders: false` routes get none. D-0125: compression is the
|
|
687
|
+
// route's own last onSend step, so it runs after every scope hook (seal, session, i18n, an
|
|
688
|
+
// app's own) and sees the final body; `compress: false` routes get none. Both in one step
|
|
689
|
+
// when a route has both: each onSend step costs every request a turn of Fastify's runner.
|
|
690
|
+
const routeSecurity = config?.securityHeaders;
|
|
691
|
+
const policy = security.enabled && routeSecurity !== false ? security.route(routeSecurity) : undefined;
|
|
692
|
+
const compress = compression !== undefined &&
|
|
693
|
+
config?.compress !== false
|
|
694
|
+
? compression.hook
|
|
695
|
+
: undefined;
|
|
696
|
+
const last = policy === undefined
|
|
697
|
+
? compress
|
|
698
|
+
: compress === undefined
|
|
699
|
+
? (request, reply, payload, done) => {
|
|
700
|
+
security.apply(policy, request, reply);
|
|
701
|
+
done(null, payload);
|
|
702
|
+
}
|
|
703
|
+
: (request, reply, payload, done) => {
|
|
704
|
+
security.apply(policy, request, reply);
|
|
705
|
+
compress(request, reply, payload, done);
|
|
706
|
+
};
|
|
707
|
+
if (last !== undefined) {
|
|
708
|
+
// A new array: Fastify's HEAD twin keeps the GET's own list.
|
|
709
|
+
const fields = route;
|
|
710
|
+
const own = fields.onSend;
|
|
711
|
+
fields.onSend =
|
|
712
|
+
own === undefined || own === null
|
|
713
|
+
? [last]
|
|
714
|
+
: Array.isArray(own)
|
|
715
|
+
? [...own, last]
|
|
716
|
+
: [own, last];
|
|
717
|
+
}
|
|
718
|
+
// A route's own requestTimeoutMs (an upload route): its first onRequest step times the body
|
|
719
|
+
// again with it (the global hook ran first, with the dokebi-web option). Checked at start.
|
|
720
|
+
const bodyMs = config?.requestTimeoutMs;
|
|
721
|
+
if (typeof bodyMs === 'number' && Number.isSafeInteger(bodyMs) && bodyMs >= 1) {
|
|
722
|
+
// Node's own request timeout is set past the longest body time at start.
|
|
723
|
+
if (bodyMs <= MAX_TIMEOUT_MS)
|
|
724
|
+
owner.#longestBodyMs = Math.max(owner.#longestBodyMs, bodyMs);
|
|
725
|
+
const retime = (request, reply, done) => {
|
|
726
|
+
if (request.raw[BODY_TIMER] !== undefined)
|
|
727
|
+
owner.#timeBody(request, reply, bodyMs);
|
|
728
|
+
done();
|
|
729
|
+
};
|
|
730
|
+
const fields = route;
|
|
731
|
+
const own = fields.onRequest;
|
|
732
|
+
fields.onRequest =
|
|
733
|
+
own === undefined || own === null
|
|
734
|
+
? [retime]
|
|
735
|
+
: Array.isArray(own)
|
|
736
|
+
? [retime, ...own]
|
|
737
|
+
: [retime, own];
|
|
738
|
+
}
|
|
739
|
+
owner.#routeHooks.offer(route);
|
|
337
740
|
const original = route.handler;
|
|
338
741
|
// The handler is held until its Promise settles, also after an early reply.send() and
|
|
339
742
|
// after the client left (D-0023). The request itself is already held by onRequest, so
|
|
@@ -344,7 +747,13 @@ class WebOwner {
|
|
|
344
747
|
raw[HANDLER] = result;
|
|
345
748
|
if (thenable(result)) {
|
|
346
749
|
owner.#inflight++;
|
|
347
|
-
result.then(owner.#release,
|
|
750
|
+
result.then(owner.#release, (error) => {
|
|
751
|
+
owner.#release();
|
|
752
|
+
// Runs right before Fastify's own reaction, which sees the same `reply.sent`: an
|
|
753
|
+
// error after the answer went out (or was hijacked) is not answered, only logged.
|
|
754
|
+
if (reply.sent && !fastifyLogs)
|
|
755
|
+
owner.#failedAfterSend(request, reply, error, failures);
|
|
756
|
+
});
|
|
348
757
|
}
|
|
349
758
|
raw[ABORTED]?.handler(result);
|
|
350
759
|
return result;
|
|
@@ -365,15 +774,58 @@ class WebOwner {
|
|
|
365
774
|
};
|
|
366
775
|
const routes = options.healthRoutes;
|
|
367
776
|
if (routes) {
|
|
368
|
-
|
|
777
|
+
// D-0142: the health routes have ids like every route (`web.healthLive`, `web.healthReady`).
|
|
778
|
+
const ids = pluginRouteIds('dokebi-web', ['healthLive', 'healthReady'], options.routeIds);
|
|
779
|
+
const live = { config: ids.config('healthLive', { dokebiHealth: true }) };
|
|
780
|
+
this.server.get(routes.live, live, async (_request, reply) => {
|
|
369
781
|
const live = health ? health.live : !['failed', 'stopped'].includes(context.app.state);
|
|
370
782
|
return reply.code(live ? 200 : 503).send({ live });
|
|
371
783
|
});
|
|
372
|
-
|
|
373
|
-
|
|
374
|
-
|
|
784
|
+
const ready = { config: ids.config('healthReady', { dokebiHealth: true }) };
|
|
785
|
+
const local = () => ({
|
|
786
|
+
ready: !this.#draining && context.app.state === 'running' && (!health || health.ready),
|
|
787
|
+
draining: this.#draining || context.app.state === 'stopping' || context.app.state === 'cleaning',
|
|
788
|
+
});
|
|
789
|
+
// D-0164: a @dokebi/cluster worker answers for every worker (they share the port).
|
|
790
|
+
const bridge = readyBridge();
|
|
791
|
+
const cluster = bridge
|
|
792
|
+
? new ClusterReadiness(bridge, local, logger, options.logRepeatWindowMs)
|
|
793
|
+
: undefined;
|
|
794
|
+
if (cluster)
|
|
795
|
+
context.defer(cluster.stop);
|
|
796
|
+
this.server.get(routes.ready, ready, async (_request, reply) => {
|
|
797
|
+
const own = local().ready;
|
|
798
|
+
if (!own || !cluster)
|
|
799
|
+
return reply.code(own ? 200 : 503).send({ ready: own });
|
|
800
|
+
const body = await cluster.ready();
|
|
801
|
+
// This worker may have turned unready or begun to drain while the others answered.
|
|
802
|
+
if (!local().ready)
|
|
803
|
+
return reply.code(503).send({ ready: false });
|
|
804
|
+
return reply.code(body.ready ? 200 : 503).send(body);
|
|
375
805
|
});
|
|
376
806
|
}
|
|
807
|
+
// A tunnel or proxy on this machine or network (cloudflared with its HTTP Host Header set to
|
|
808
|
+
// localhost, nginx) sends the browser's host in X-Forwarded-Host. Without its address in
|
|
809
|
+
// trustProxy that header is ignored and requestHost() is the Host it wrote (`localhost`):
|
|
810
|
+
// app domains miss and seal keys differ from the browser's (2026-10-28). Said once per
|
|
811
|
+
// window and peer, only for loopback and private peers (a public client may send anything).
|
|
812
|
+
const ignoredForwarded = new Repeats({ intervalMs: options.logRepeatWindowMs });
|
|
813
|
+
const forwardedIgnored = (remote, forwarded, host) => {
|
|
814
|
+
const peer = plainAddress(remote);
|
|
815
|
+
if (!LOCAL_PEERS.check(peer, peer.includes(':') ? 'ipv6' : 'ipv4'))
|
|
816
|
+
return;
|
|
817
|
+
const repeated = ignoredForwarded.take(peer);
|
|
818
|
+
if (repeated === undefined)
|
|
819
|
+
return;
|
|
820
|
+
logger.log('warn', 'X-Forwarded-Host ignored: the proxy is not in trustProxy', {
|
|
821
|
+
code: 'WEB_FORWARDED_HOST_IGNORED',
|
|
822
|
+
remote: peer,
|
|
823
|
+
forwardedHost: String(forwarded).slice(0, 253),
|
|
824
|
+
host: String(host ?? '').slice(0, 253),
|
|
825
|
+
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.`,
|
|
826
|
+
...(repeated ? { repeated } : {}),
|
|
827
|
+
});
|
|
828
|
+
};
|
|
377
829
|
this.api = Object.freeze({
|
|
378
830
|
get address() {
|
|
379
831
|
return owner.#address;
|
|
@@ -381,13 +833,28 @@ class WebOwner {
|
|
|
381
833
|
route: (route) => {
|
|
382
834
|
this.#assertMutable();
|
|
383
835
|
const { seal, ...rest } = route;
|
|
384
|
-
|
|
385
|
-
|
|
386
|
-
|
|
387
|
-
this.server.route({
|
|
836
|
+
const options = seal === undefined
|
|
837
|
+
? rest
|
|
838
|
+
: {
|
|
388
839
|
...rest,
|
|
389
|
-
config: {
|
|
390
|
-
|
|
840
|
+
config: {
|
|
841
|
+
...rest.config,
|
|
842
|
+
dokebiSeal: checkSealSetting(seal),
|
|
843
|
+
},
|
|
844
|
+
};
|
|
845
|
+
if (rest.app === undefined) {
|
|
846
|
+
this.server.route(options);
|
|
847
|
+
return;
|
|
848
|
+
}
|
|
849
|
+
// D-0132: a route bound to apps is added at boot, once @dokebi/app has registered the
|
|
850
|
+
// routing whatever the plugin order. The value is checked now; the names at boot.
|
|
851
|
+
appNames(rest.app, `Route ${String(rest.method)} ${rest.url}`);
|
|
852
|
+
const bind = async (scope) => {
|
|
853
|
+
scope.route(options);
|
|
854
|
+
};
|
|
855
|
+
// In the root context (no encapsulation), like a route added directly.
|
|
856
|
+
bind[Symbol.for('skip-override')] = true;
|
|
857
|
+
this.server.register(bind);
|
|
391
858
|
},
|
|
392
859
|
register: (plugin, options) => {
|
|
393
860
|
this.#assertMutable();
|
|
@@ -402,11 +869,20 @@ class WebOwner {
|
|
|
402
869
|
const raw = request.raw ?? request;
|
|
403
870
|
const remote = raw.socket?.remoteAddress;
|
|
404
871
|
const forwarded = raw.headers['x-forwarded-host'];
|
|
405
|
-
|
|
872
|
+
// The last entry: only the socket peer is trusted, and a proxy that appends writes its
|
|
873
|
+
// value last; earlier entries come from whoever sent the request (as Fastify's request.host).
|
|
874
|
+
const trusted = forwarded !== undefined &&
|
|
406
875
|
remote !== undefined &&
|
|
407
|
-
options.trustProxy.includes(plainAddress(remote))
|
|
408
|
-
|
|
409
|
-
: raw.headers.host;
|
|
876
|
+
options.trustProxy.includes(plainAddress(remote));
|
|
877
|
+
if (forwarded !== undefined && remote !== undefined && !trusted)
|
|
878
|
+
forwardedIgnored(remote, forwarded, raw.headers[':authority'] ?? raw.headers.host);
|
|
879
|
+
const value = trusted
|
|
880
|
+
? String(Array.isArray(forwarded) ? forwarded.at(-1) : forwarded)
|
|
881
|
+
.split(',')
|
|
882
|
+
.at(-1)
|
|
883
|
+
: // HTTP/2 names the host in `:authority`; a Host header is optional there (RFC 9113
|
|
884
|
+
// §8.3.1). HTTP/1 cannot send a pseudo-header, so it always reads Host.
|
|
885
|
+
(raw.headers[':authority'] ?? raw.headers.host);
|
|
410
886
|
return String(value ?? '')
|
|
411
887
|
.trim()
|
|
412
888
|
.toLowerCase();
|
|
@@ -422,9 +898,33 @@ class WebOwner {
|
|
|
422
898
|
sealing.addPredicate(predicate);
|
|
423
899
|
},
|
|
424
900
|
sealOf: (request) => sealing.sealOf(request),
|
|
901
|
+
requestApps: (resolver) => {
|
|
902
|
+
this.#assertMutable();
|
|
903
|
+
if (typeof resolver !== 'function')
|
|
904
|
+
throw new TypeError('requestApps takes a function');
|
|
905
|
+
appResolvers.push(resolver);
|
|
906
|
+
},
|
|
907
|
+
appOf: (request) => {
|
|
908
|
+
for (const resolver of appResolvers) {
|
|
909
|
+
const name = resolver(request);
|
|
910
|
+
if (name !== undefined)
|
|
911
|
+
return name;
|
|
912
|
+
}
|
|
913
|
+
return undefined;
|
|
914
|
+
},
|
|
915
|
+
get resolvesApps() {
|
|
916
|
+
return appResolvers.length > 0;
|
|
917
|
+
},
|
|
425
918
|
get sealing() {
|
|
426
919
|
return sealing.provider !== undefined;
|
|
427
920
|
},
|
|
921
|
+
get sealWanted() {
|
|
922
|
+
return sealing.wanted;
|
|
923
|
+
},
|
|
924
|
+
formLimits: Object.freeze({
|
|
925
|
+
oldInputMaxChars: options.formOldInputMaxChars,
|
|
926
|
+
refererMaxLength: options.formRefererMaxLength,
|
|
927
|
+
}),
|
|
428
928
|
errorResponder: (responder) => {
|
|
429
929
|
this.#assertMutable();
|
|
430
930
|
if (typeof responder !== 'function')
|
|
@@ -436,20 +936,126 @@ class WebOwner {
|
|
|
436
936
|
responders: this.#responders.length,
|
|
437
937
|
});
|
|
438
938
|
},
|
|
939
|
+
routeConfig: (definition) => {
|
|
940
|
+
this.#assertMutable();
|
|
941
|
+
this.#routeConfig.add(definition);
|
|
942
|
+
logger.log('debug', 'Web route config key registered', {
|
|
943
|
+
key: definition.key,
|
|
944
|
+
plugin: definition.plugin,
|
|
945
|
+
});
|
|
946
|
+
},
|
|
947
|
+
routeHook: (definition) => {
|
|
948
|
+
this.#assertMutable();
|
|
949
|
+
const offered = this.#routeHooks.add(definition);
|
|
950
|
+
logger.log('debug', 'Web route hook registered', {
|
|
951
|
+
plugin: definition.plugin,
|
|
952
|
+
earlierRoutes: offered,
|
|
953
|
+
});
|
|
954
|
+
},
|
|
955
|
+
contentSecurityPolicy: (contribution) => {
|
|
956
|
+
this.#assertMutable();
|
|
957
|
+
const problem = contributionProblem(contribution);
|
|
958
|
+
if (problem)
|
|
959
|
+
throw new WebError('INVALID_ARGUMENT', `Invalid Content-Security-Policy sources: ${problem}`, {
|
|
960
|
+
fix: "Pass { plugin: 'dokebi-…', directives: { 'connect-src': ['ws://*:5173'] } }.",
|
|
961
|
+
});
|
|
962
|
+
this.#security.contribute(contribution);
|
|
963
|
+
logger.log('debug', 'Content-Security-Policy sources added', {
|
|
964
|
+
plugin: contribution.plugin,
|
|
965
|
+
directives: Object.keys(contribution.directives),
|
|
966
|
+
});
|
|
967
|
+
},
|
|
968
|
+
routes: () => this.#routeTable.routes(),
|
|
969
|
+
appRouting: (routing) => {
|
|
970
|
+
this.#assertMutable();
|
|
971
|
+
this.#appRoutes.set(routing);
|
|
972
|
+
},
|
|
973
|
+
get apps() {
|
|
974
|
+
return owner.#appRoutes.routing;
|
|
975
|
+
},
|
|
439
976
|
});
|
|
440
977
|
}
|
|
441
978
|
#assertMutable() {
|
|
442
979
|
if (this.#frozen || this.#closed)
|
|
443
980
|
throw new WebError('FROZEN');
|
|
444
981
|
}
|
|
982
|
+
/**
|
|
983
|
+
* The end of a draining worker's idle wait (D-0036): the keep-alive connections still idle are
|
|
984
|
+
* closed (`closeIdleConnections` leaves a connection whose next request has begun to arrive),
|
|
985
|
+
* once per drain, so later only the ending response's own connection is looked at (D-0107 §1).
|
|
986
|
+
*/
|
|
987
|
+
#closeIdle(open) {
|
|
988
|
+
if (this.#idleClosed)
|
|
989
|
+
return;
|
|
990
|
+
this.#idleClosed = true;
|
|
991
|
+
// An h2c server has no closeIdleConnections; HTTP/2 sessions were told to go away already.
|
|
992
|
+
const server = this.server.server;
|
|
993
|
+
server.closeIdleConnections?.();
|
|
994
|
+
this.context.logger.log('debug', 'Web drain closed idle connections', {
|
|
995
|
+
pending: this.#inflight,
|
|
996
|
+
open,
|
|
997
|
+
idleMs: this.#drainIdleMs,
|
|
998
|
+
});
|
|
999
|
+
}
|
|
1000
|
+
/**
|
|
1001
|
+
* A draining node:cluster worker, after its idle wait: a response that went out without
|
|
1002
|
+
* `Connection: close` (its head was out before the drain) ends its connection once it has
|
|
1003
|
+
* ended, unless a newer request of that connection is under way. During the idle wait the
|
|
1004
|
+
* connection is left open: the client's next request on it is served with `Connection: close`.
|
|
1005
|
+
*/
|
|
1006
|
+
#closeAfterResponse(response) {
|
|
1007
|
+
if (!this.#idleClosed)
|
|
1008
|
+
return;
|
|
1009
|
+
const logger = this.context.logger;
|
|
1010
|
+
// No newer request of the connection under way (marked from the server's 'request').
|
|
1011
|
+
const socket = this.#connections.endIfIdle(response);
|
|
1012
|
+
if (socket === undefined)
|
|
1013
|
+
return;
|
|
1014
|
+
if (logger.isEnabled('debug'))
|
|
1015
|
+
logger.log('debug', 'Web drain closed an idle connection', {
|
|
1016
|
+
remote: `${socket.remoteAddress ?? '?'}:${socket.remotePort ?? '?'}`,
|
|
1017
|
+
pending: this.#inflight,
|
|
1018
|
+
});
|
|
1019
|
+
}
|
|
445
1020
|
/** The shared 'close' listener of every held response (`this` is the response). */
|
|
1021
|
+
/** The route's `completed` observers, once its response was written (route-hooks.ts). */
|
|
1022
|
+
#completed(response, reply) {
|
|
1023
|
+
const elapsedMs = performance.now() - response[STARTED];
|
|
1024
|
+
for (const observe of response[COMPLETING]) {
|
|
1025
|
+
try {
|
|
1026
|
+
observe(reply.request, reply, elapsedMs);
|
|
1027
|
+
}
|
|
1028
|
+
catch (error) {
|
|
1029
|
+
this.#responseHookFailures ??= new Repeats({ intervalMs: this.options.logRepeatWindowMs });
|
|
1030
|
+
const route = reply.request.routeOptions.url ?? 'unmatched';
|
|
1031
|
+
const repeated = this.#responseHookFailures.take(route);
|
|
1032
|
+
if (repeated !== undefined)
|
|
1033
|
+
this.context.logger.log('error', 'HTTP response hook failed', {
|
|
1034
|
+
code: 'WEB_RESPONSE_HOOK_FAILED',
|
|
1035
|
+
route,
|
|
1036
|
+
repeated,
|
|
1037
|
+
error: describeError(error),
|
|
1038
|
+
});
|
|
1039
|
+
}
|
|
1040
|
+
}
|
|
1041
|
+
}
|
|
446
1042
|
#responseClosed(response) {
|
|
1043
|
+
const incoming = response.req;
|
|
1044
|
+
if (incoming?.[BODY_TIMER] !== undefined)
|
|
1045
|
+
clearBodyTimer.call(incoming);
|
|
1046
|
+
// A 408 went out for a stalled body. Node forgets a request once its response finished, so
|
|
1047
|
+
// the request stream never ends or errors when the connection closes: a reader still waiting
|
|
1048
|
+
// (a multipart file stream, a storage upload) would hold the drain until its deadline.
|
|
1049
|
+
if (incoming?.[TIMED_OUT] !== undefined && !incoming.complete && !incoming.destroyed)
|
|
1050
|
+
incoming.destroy(bodyTimeout(incoming[TIMED_OUT]));
|
|
447
1051
|
// 'close' fires once per response, so the listener is not removed (one call saved).
|
|
448
1052
|
if (this.#draining && this.#worker)
|
|
449
|
-
this
|
|
1053
|
+
this.#closeAfterResponse(response);
|
|
450
1054
|
const reply = response[REPLY];
|
|
451
1055
|
// Written (finished, or at least its head: the rest needs no user code) or hijacked: done.
|
|
452
1056
|
if (response.writableFinished || response.headersSent || reply === undefined || reply.sent) {
|
|
1057
|
+
if (response[COMPLETING] !== undefined && response.writableFinished && reply !== undefined)
|
|
1058
|
+
this.#completed(response, reply);
|
|
453
1059
|
this.#release();
|
|
454
1060
|
return;
|
|
455
1061
|
}
|
|
@@ -473,6 +1079,49 @@ class WebOwner {
|
|
|
473
1079
|
this.#release();
|
|
474
1080
|
});
|
|
475
1081
|
}
|
|
1082
|
+
/** The timer of a body that is arriving: `ms` from now (re-armed by a route's own setting). */
|
|
1083
|
+
#timeBody(request, reply, ms) {
|
|
1084
|
+
const raw = request.raw;
|
|
1085
|
+
if (raw[BODY_TIMER] === undefined)
|
|
1086
|
+
raw.once('end', clearBodyTimer);
|
|
1087
|
+
else
|
|
1088
|
+
clearTimeout(raw[BODY_TIMER]);
|
|
1089
|
+
const timer = setTimeout(this.#bodyTimedOut, ms, request, reply, ms);
|
|
1090
|
+
timer.unref();
|
|
1091
|
+
raw[BODY_TIMER] = timer;
|
|
1092
|
+
}
|
|
1093
|
+
/**
|
|
1094
|
+
* The body did not arrive within its time: 408 REQUEST_TIMEOUT when no answer has started (the
|
|
1095
|
+
* connection then closes), else the connection is cut. The parser or handler still waiting for
|
|
1096
|
+
* the body then fails as the connection ends; that is not logged as a server failure.
|
|
1097
|
+
*/
|
|
1098
|
+
#bodyTimedOut = (request, reply, ms) => {
|
|
1099
|
+
const raw = request.raw;
|
|
1100
|
+
raw[BODY_TIMER] = undefined;
|
|
1101
|
+
if (raw.complete || raw.destroyed)
|
|
1102
|
+
return;
|
|
1103
|
+
raw[TIMED_OUT] = ms;
|
|
1104
|
+
const answered = reply.sent || reply.raw.headersSent;
|
|
1105
|
+
if (this.context.logger.isEnabled('debug'))
|
|
1106
|
+
this.context.logger.log('debug', 'HTTP request body timed out', {
|
|
1107
|
+
code: 'WEB_REQUEST_TIMEOUT',
|
|
1108
|
+
method: request.method,
|
|
1109
|
+
route: request.routeOptions.url ?? 'unmatched',
|
|
1110
|
+
timeoutMs: ms,
|
|
1111
|
+
answered,
|
|
1112
|
+
});
|
|
1113
|
+
if (answered) {
|
|
1114
|
+
// HTTP/2: only this stream (NGHTTP2_CANCEL), never the session other streams share.
|
|
1115
|
+
if (http1(request))
|
|
1116
|
+
raw.socket?.destroy();
|
|
1117
|
+
else
|
|
1118
|
+
request.raw.stream?.close(8);
|
|
1119
|
+
return;
|
|
1120
|
+
}
|
|
1121
|
+
if (!http1(request))
|
|
1122
|
+
endStreamAfterAnswer(request.raw, ms);
|
|
1123
|
+
reply.send(bodyTimeout(ms));
|
|
1124
|
+
};
|
|
476
1125
|
track(work) {
|
|
477
1126
|
if (this.#closed)
|
|
478
1127
|
return Promise.reject(new WebError('CLOSED'));
|
|
@@ -507,6 +1156,53 @@ class WebOwner {
|
|
|
507
1156
|
if (!RESPONSE_HOOKS.has(name))
|
|
508
1157
|
return fn;
|
|
509
1158
|
const owner = this;
|
|
1159
|
+
if (name === 'onResponse') {
|
|
1160
|
+
// Response observers commonly call done synchronously (metrics). Keep the same drain
|
|
1161
|
+
// hold without turning that callback into a chain of Promises/microtasks. Async hooks
|
|
1162
|
+
// still hold the counter until their returned promise settles.
|
|
1163
|
+
this.#responseHookFailures ??= new Repeats({ intervalMs: this.options.logRepeatWindowMs });
|
|
1164
|
+
const failures = this.#responseHookFailures;
|
|
1165
|
+
const wrapped = function (request, reply, done) {
|
|
1166
|
+
if (owner.#closed) {
|
|
1167
|
+
done(new WebError('CLOSED'));
|
|
1168
|
+
return;
|
|
1169
|
+
}
|
|
1170
|
+
owner.#inflight++;
|
|
1171
|
+
let settled = false;
|
|
1172
|
+
const finish = (error) => {
|
|
1173
|
+
if (error) {
|
|
1174
|
+
const route = request.routeOptions.url ?? 'unmatched';
|
|
1175
|
+
const repeated = failures.take(route);
|
|
1176
|
+
if (repeated !== undefined)
|
|
1177
|
+
owner.context.logger.log('error', 'HTTP response hook failed', {
|
|
1178
|
+
code: 'WEB_RESPONSE_HOOK_FAILED',
|
|
1179
|
+
route,
|
|
1180
|
+
repeated,
|
|
1181
|
+
error: describeError(error),
|
|
1182
|
+
});
|
|
1183
|
+
}
|
|
1184
|
+
if (settled)
|
|
1185
|
+
return;
|
|
1186
|
+
settled = true;
|
|
1187
|
+
try {
|
|
1188
|
+
done(error);
|
|
1189
|
+
}
|
|
1190
|
+
finally {
|
|
1191
|
+
owner.#release();
|
|
1192
|
+
}
|
|
1193
|
+
};
|
|
1194
|
+
try {
|
|
1195
|
+
const result = fn.call(this, request, reply, finish);
|
|
1196
|
+
if (result && typeof result.then === 'function')
|
|
1197
|
+
void Promise.resolve(result).then(() => finish(), (error) => finish(error || new Error('HTTP response hook rejected without an error')));
|
|
1198
|
+
}
|
|
1199
|
+
catch (error) {
|
|
1200
|
+
finish(error || new Error('HTTP response hook threw without an error'));
|
|
1201
|
+
}
|
|
1202
|
+
};
|
|
1203
|
+
this.#wrapped.add(wrapped);
|
|
1204
|
+
return wrapped;
|
|
1205
|
+
}
|
|
510
1206
|
function invoke(instance, args) {
|
|
511
1207
|
return owner.track(() => new Promise((resolve, reject) => {
|
|
512
1208
|
const reply = name === 'onRequestAbort' ? undefined : args[1];
|
|
@@ -558,6 +1254,31 @@ class WebOwner {
|
|
|
558
1254
|
this.#wrapped.add(wrapped);
|
|
559
1255
|
return wrapped;
|
|
560
1256
|
}
|
|
1257
|
+
/**
|
|
1258
|
+
* D-0122: `binaryBody` parses application/octet-stream into a Buffer. Fastify's raw-body reader
|
|
1259
|
+
* enforces the route's `bodyLimit` (else maxBodyBytes): Content-Length over it is 413 before a
|
|
1260
|
+
* byte is read, a longer streamed body stops at the limit, so at most the limit is buffered.
|
|
1261
|
+
*/
|
|
1262
|
+
#binaryBody(options) {
|
|
1263
|
+
if (!options.binaryBody)
|
|
1264
|
+
return;
|
|
1265
|
+
this.server.addContentTypeParser(BINARY_TYPE, { parseAs: 'buffer', bodyLimit: options.maxBodyBytes }, (_request, body, done) => done(null, body));
|
|
1266
|
+
}
|
|
1267
|
+
/** D-0122: a route `bodyLimit` must be whole bytes from 1 to `maxRouteBodyBytes`. */
|
|
1268
|
+
#checkBodyLimit(method, url, limit) {
|
|
1269
|
+
if (limit === undefined)
|
|
1270
|
+
return;
|
|
1271
|
+
const most = this.options.maxRouteBodyBytes;
|
|
1272
|
+
if (typeof limit === 'number' && Number.isSafeInteger(limit) && limit >= 1 && limit <= most) {
|
|
1273
|
+
if (this.context.logger.isEnabled('debug'))
|
|
1274
|
+
this.context.logger.log('debug', 'Web route body limit', { method, url, bodyLimit: limit });
|
|
1275
|
+
return;
|
|
1276
|
+
}
|
|
1277
|
+
throw new WebError('INVALID_ROUTE', `The route ${String(method)} ${url} has bodyLimit ${String(limit)}; it must be whole bytes from 1 to maxRouteBodyBytes (${most})`, {
|
|
1278
|
+
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).`,
|
|
1279
|
+
data: { method, url, bodyLimit: limit, maxRouteBodyBytes: most },
|
|
1280
|
+
});
|
|
1281
|
+
}
|
|
561
1282
|
/** The urlencoded body parser, or its refusal when `formBody` is off (D-0068). */
|
|
562
1283
|
#formBody(options) {
|
|
563
1284
|
if (!options.formBody) {
|
|
@@ -582,12 +1303,79 @@ class WebOwner {
|
|
|
582
1303
|
done(null, parseQuery(text, '&', '=', { maxKeys: 0 }));
|
|
583
1304
|
});
|
|
584
1305
|
}
|
|
1306
|
+
/** Every route's config values for the declared keys, and likely typos (D-0076 §5). */
|
|
1307
|
+
#checkRouteConfig() {
|
|
1308
|
+
const keys = this.#routeConfig.size;
|
|
1309
|
+
const problems = this.#routeConfig.check();
|
|
1310
|
+
if (problems.length === 0) {
|
|
1311
|
+
if (keys > 0)
|
|
1312
|
+
this.context.logger.log('debug', 'Web route config checked', { keys });
|
|
1313
|
+
return;
|
|
1314
|
+
}
|
|
1315
|
+
this.context.logger.log('error', 'Web route config refused', {
|
|
1316
|
+
code: 'WEB_ROUTE_CONFIG_INVALID',
|
|
1317
|
+
problems: problems.slice(0, 20),
|
|
1318
|
+
more: Math.max(0, problems.length - 20),
|
|
1319
|
+
});
|
|
1320
|
+
throw new WebError('INVALID_ROUTE_CONFIG', `Route config refused: ${problems[0]}${problems.length > 1 ? ` (and ${problems.length - 1} more)` : ''}`, { details: { problems } });
|
|
1321
|
+
}
|
|
1322
|
+
/**
|
|
1323
|
+
* Describe mode (D-0077 B): every route once Fastify is ready (routes of plugin scopes too),
|
|
1324
|
+
* without listening. Called by the `core:describe` describer, after every setup.
|
|
1325
|
+
*/
|
|
1326
|
+
async describeRoutes() {
|
|
1327
|
+
this.#frozen = true;
|
|
1328
|
+
await this.server.ready();
|
|
1329
|
+
return describeRoutes(this.#routeTable);
|
|
1330
|
+
}
|
|
1331
|
+
/** A route id on two routes of one app fails the start (D-0077 A). */
|
|
1332
|
+
#checkRouteIds() {
|
|
1333
|
+
const duplicates = this.#routeTable.duplicateIds();
|
|
1334
|
+
const logger = this.context.logger;
|
|
1335
|
+
if (duplicates.length === 0) {
|
|
1336
|
+
if (logger.isEnabled('debug'))
|
|
1337
|
+
logger.log('debug', 'Web route ids checked', {
|
|
1338
|
+
routes: this.#routeTable.routes().length,
|
|
1339
|
+
ids: this.#routeTable.routes().filter((route) => route.id !== undefined).length,
|
|
1340
|
+
});
|
|
1341
|
+
return;
|
|
1342
|
+
}
|
|
1343
|
+
logger.log('error', 'Web route ids refused', {
|
|
1344
|
+
code: 'WEB_ROUTE_ID_DUPLICATE',
|
|
1345
|
+
duplicates: duplicates.slice(0, 20),
|
|
1346
|
+
more: Math.max(0, duplicates.length - 20),
|
|
1347
|
+
});
|
|
1348
|
+
const [first] = duplicates;
|
|
1349
|
+
// D-0142: when a plugin's own route is one of them, say which option renames it.
|
|
1350
|
+
const owned = first.owners?.map((owner) => {
|
|
1351
|
+
const [plugin, key] = owner.split(' ');
|
|
1352
|
+
return `options.${plugin}.${key}`;
|
|
1353
|
+
});
|
|
1354
|
+
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)` : ''}`, {
|
|
1355
|
+
details: { duplicates },
|
|
1356
|
+
...(owned?.length
|
|
1357
|
+
? {
|
|
1358
|
+
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' : ''}.`,
|
|
1359
|
+
}
|
|
1360
|
+
: {}),
|
|
1361
|
+
});
|
|
1362
|
+
}
|
|
585
1363
|
async start() {
|
|
586
1364
|
this.#frozen = true;
|
|
587
1365
|
const started = performance.now();
|
|
588
1366
|
await this.server.ready();
|
|
589
1367
|
// After every setup (routes and the seal provider are all known): fail closed (D-0062).
|
|
590
1368
|
this.#sealing.check();
|
|
1369
|
+
this.#checkRouteConfig();
|
|
1370
|
+
this.#checkRouteIds();
|
|
1371
|
+
this.#routeHooks.close();
|
|
1372
|
+
this.#security.freeze();
|
|
1373
|
+
this.#nodeTimeouts();
|
|
1374
|
+
const shedding = this.#shedding;
|
|
1375
|
+
if (shedding) {
|
|
1376
|
+
this.#sampler = setInterval(() => this.#sample(), shedding.settings.sampleIntervalMs);
|
|
1377
|
+
this.#sampler.unref();
|
|
1378
|
+
}
|
|
591
1379
|
this.context.logger.log('debug', 'Web routes frozen', {
|
|
592
1380
|
ms: Math.round(performance.now() - started),
|
|
593
1381
|
});
|
|
@@ -598,6 +1386,34 @@ class WebOwner {
|
|
|
598
1386
|
if (!this.#worker)
|
|
599
1387
|
await this.listen();
|
|
600
1388
|
}
|
|
1389
|
+
/**
|
|
1390
|
+
* Node's own timeouts of an HTTP/1 server, once every route is known. Node bounds the head by
|
|
1391
|
+
* the smaller of `headersTimeout` and `requestTimeout` and the whole request by the larger (it
|
|
1392
|
+
* swaps them), checked every 30 s, and answers past it with a bare 408 of Fastify's that no log
|
|
1393
|
+
* records. Left as Fastify set them (requestTimeout = requestTimeoutMs, headersTimeout Node's
|
|
1394
|
+
* 60 s), every request was cut at 60 s: an upload route's own `config.requestTimeoutMs`
|
|
1395
|
+
* (600000 for large files) never got past a minute. The head keeps its bound; the whole
|
|
1396
|
+
* request gets the longest body time plus that, so web's own timer (408 REQUEST_TIMEOUT,
|
|
1397
|
+
* started once the head has arrived) always ends a body first.
|
|
1398
|
+
*/
|
|
1399
|
+
#nodeTimeouts() {
|
|
1400
|
+
const server = this.server.server;
|
|
1401
|
+
const request = server.requestTimeout;
|
|
1402
|
+
const headers = server.headersTimeout;
|
|
1403
|
+
// An HTTP/2 server has neither (HTTP/2 bodies have only web's timer); a serverFactory's own
|
|
1404
|
+
// server keeps what it set.
|
|
1405
|
+
if (typeof request !== 'number' || typeof headers !== 'number' || request === 0)
|
|
1406
|
+
return;
|
|
1407
|
+
const head = headers > 0 ? Math.min(headers, request) : request;
|
|
1408
|
+
const whole = Math.min(MAX_TIMEOUT_MS, Math.max(request, this.#longestBodyMs) + head);
|
|
1409
|
+
server.headersTimeout = head;
|
|
1410
|
+
server.requestTimeout = whole;
|
|
1411
|
+
this.context.logger.log('debug', 'Web request timeouts', {
|
|
1412
|
+
headersTimeoutMs: head,
|
|
1413
|
+
requestTimeoutMs: whole,
|
|
1414
|
+
longestBodyMs: this.#longestBodyMs,
|
|
1415
|
+
});
|
|
1416
|
+
}
|
|
601
1417
|
/** Listens unless this process does not serve (`runtime.serving` false, D-0063 §4). */
|
|
602
1418
|
async listen() {
|
|
603
1419
|
if (this.#address !== undefined)
|
|
@@ -627,7 +1443,7 @@ class WebOwner {
|
|
|
627
1443
|
ms: Math.round(performance.now() - started),
|
|
628
1444
|
});
|
|
629
1445
|
}
|
|
630
|
-
async drain(signal) {
|
|
1446
|
+
async drain(signal, deadline) {
|
|
631
1447
|
this.#draining = true;
|
|
632
1448
|
this.#frozen = true;
|
|
633
1449
|
const started = performance.now();
|
|
@@ -643,15 +1459,15 @@ class WebOwner {
|
|
|
643
1459
|
// The primary may already be handing this worker a connection when it learns the server
|
|
644
1460
|
// closed; the worker answers "not accepted" and the primary passes it on, but only if the
|
|
645
1461
|
// 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
|
|
1462
|
+
// primary never hears back), so a draining worker stays at least `drainGraceMs` (D-0036, D-0114).
|
|
647
1463
|
// Only the listening socket closes (net level): http's close() would also drop idle
|
|
648
1464
|
// keep-alive connections at once, racing clients that are just reusing them. Those
|
|
649
1465
|
// connections stay; their next request is served with `Connection: close`.
|
|
650
1466
|
let grace;
|
|
651
1467
|
if (this.#worker && this.server.server.listening) {
|
|
652
1468
|
Server.prototype.close.call(this.server.server);
|
|
653
|
-
grace = delay(
|
|
654
|
-
logger.log('debug', 'Web worker stopped listening', { graceMs:
|
|
1469
|
+
grace = delay(this.#drainGraceMs);
|
|
1470
|
+
logger.log('debug', 'Web worker stopped listening', { graceMs: this.#drainGraceMs });
|
|
655
1471
|
}
|
|
656
1472
|
const listening = new AbortController();
|
|
657
1473
|
const aborted = new Promise((resolve) => {
|
|
@@ -660,16 +1476,54 @@ class WebOwner {
|
|
|
660
1476
|
else
|
|
661
1477
|
signal.addEventListener('abort', () => resolve(), { once: true, signal: listening.signal });
|
|
662
1478
|
});
|
|
1479
|
+
let idleTimer;
|
|
663
1480
|
try {
|
|
664
|
-
|
|
665
|
-
|
|
1481
|
+
if (this.#worker) {
|
|
1482
|
+
// HTTP/2 can say it: GOAWAY, streams under way finish, no new ones (D-0036).
|
|
1483
|
+
const sessions = this.#connections.goAway();
|
|
1484
|
+
if (sessions)
|
|
1485
|
+
logger.log('debug', 'Web drain told HTTP/2 sessions to go away', { sessions });
|
|
1486
|
+
// HTTP/1 cannot: a keep-alive connection told `Keep-Alive: timeout=…` may carry the
|
|
1487
|
+
// client's next request at any moment, and closing it then loses that request
|
|
1488
|
+
// (ECONNRESET; a POST is never resent). So the connections stay open up to drainIdleMs:
|
|
1489
|
+
// a request on one is served with `Connection: close` and the client moves to another
|
|
1490
|
+
// worker; the drain goes on as soon as none is left (M50 review).
|
|
1491
|
+
let open = this.#connections.size;
|
|
1492
|
+
// Never past the drain deadline (core counts a drain still running then as
|
|
1493
|
+
// DRAIN_TIMEOUT): end DEADLINE_MARGIN_MS before it, the time to close the idle ones,
|
|
1494
|
+
// finish the answers under way and return.
|
|
1495
|
+
const idleMs = Math.min(this.#drainIdleMs, deadline === undefined
|
|
1496
|
+
? Number.POSITIVE_INFINITY
|
|
1497
|
+
: deadline - started - DEADLINE_MARGIN_MS);
|
|
1498
|
+
if (open > 0 && idleMs > 0) {
|
|
1499
|
+
let waited = false;
|
|
1500
|
+
// One timer for the whole wait, cleared when the drain ends (finally below).
|
|
1501
|
+
const idle = new Promise((resolve) => {
|
|
1502
|
+
idleTimer = setTimeout(() => {
|
|
1503
|
+
waited = true;
|
|
1504
|
+
resolve();
|
|
1505
|
+
}, idleMs);
|
|
1506
|
+
});
|
|
1507
|
+
while (open > 0 && !waited && !signal.aborted) {
|
|
1508
|
+
await Promise.race([this.#connections.changed(), idle, aborted]);
|
|
1509
|
+
open = this.#connections.size;
|
|
1510
|
+
}
|
|
1511
|
+
}
|
|
1512
|
+
if (!signal.aborted)
|
|
1513
|
+
this.#closeIdle(open);
|
|
1514
|
+
}
|
|
1515
|
+
while (this.#inflight > 0 || signal.aborted) {
|
|
1516
|
+
if (!signal.aborted)
|
|
1517
|
+
await Promise.race([this.#whenIdle(), aborted]);
|
|
666
1518
|
if (signal.aborted) {
|
|
667
|
-
// Deadline or forced stop: cut
|
|
1519
|
+
// Deadline or forced stop: cut every connection but upgraded ones (an HTTP/2 server
|
|
1520
|
+
// has no closeAllConnections); core records the timeout.
|
|
1521
|
+
const cut = this.#connections.cut();
|
|
668
1522
|
logger.log('debug', 'Web drain cut connections', {
|
|
669
1523
|
pending: this.#inflight,
|
|
1524
|
+
cut,
|
|
670
1525
|
ms: Math.round(performance.now() - started),
|
|
671
1526
|
});
|
|
672
|
-
this.server.server.closeAllConnections();
|
|
673
1527
|
return;
|
|
674
1528
|
}
|
|
675
1529
|
// Fastify starts the next step of a request (the next hook, onResponse after 'finish')
|
|
@@ -681,6 +1535,7 @@ class WebOwner {
|
|
|
681
1535
|
logger.log('debug', 'Web drain finished', { ms: Math.round(performance.now() - started) });
|
|
682
1536
|
}
|
|
683
1537
|
finally {
|
|
1538
|
+
clearTimeout(idleTimer);
|
|
684
1539
|
listening.abort();
|
|
685
1540
|
}
|
|
686
1541
|
}
|
|
@@ -706,29 +1561,121 @@ class WebOwner {
|
|
|
706
1561
|
fix: `Return { ...defaults, … } from fastifyOptions() in ${EXTENSION_FILE}, synchronously; return503OnClosing and forceCloseConnections belong to the drain contract.`,
|
|
707
1562
|
data: { hook: 'fastifyOptions', ...(changed.length ? { pinned: changed } : {}) },
|
|
708
1563
|
});
|
|
709
|
-
|
|
1564
|
+
const created = { ...fields, ...PINNED };
|
|
1565
|
+
// h2c: Fastify refuses `idle` (an Http2Server has no closeIdleConnections, the server failed
|
|
1566
|
+
// to start). Node closes HTTP/2 sessions itself in server.close(), and WebConnections ends
|
|
1567
|
+
// the connections that would hold it.
|
|
1568
|
+
if (created.http2 === true && !created.https)
|
|
1569
|
+
return { ...created, forceCloseConnections: false };
|
|
1570
|
+
return created;
|
|
710
1571
|
}
|
|
711
1572
|
/**
|
|
712
1573
|
* The error handler: D-0063 §1 mapping, the `errorBody` hook, logging, then the error responders
|
|
713
1574
|
* or the built-in JSON or HTML answer (D-0074). Synchronous while no responder is registered.
|
|
714
1575
|
*/
|
|
715
|
-
#fail(
|
|
1576
|
+
#fail(thrown, request, reply, failures) {
|
|
716
1577
|
const logger = this.context.logger;
|
|
717
1578
|
const production = this.#production;
|
|
1579
|
+
// The first error answer of this response, or the answer to an error raised while sending it.
|
|
1580
|
+
const raw = reply.raw;
|
|
1581
|
+
const pass = (raw[ERROR_PASS] ?? 0) + 1;
|
|
1582
|
+
raw[ERROR_PASS] = pass;
|
|
1583
|
+
this.#nextHandler(reply, pass);
|
|
1584
|
+
if (pass > 1) {
|
|
1585
|
+
if (logger.isEnabled('debug'))
|
|
1586
|
+
logger.log('debug', 'HTTP error raised while sending an error answer', {
|
|
1587
|
+
method: request.method,
|
|
1588
|
+
route: request.routeOptions.url ?? 'unmatched',
|
|
1589
|
+
status: reply.statusCode,
|
|
1590
|
+
errorCode: thrown?.code ?? null,
|
|
1591
|
+
});
|
|
1592
|
+
// The first answer's Retry-After told when that error ends; this answer sets its own, if
|
|
1593
|
+
// any (audit r5: a 500 went out with the Retry-After of the 503 before it).
|
|
1594
|
+
reply.removeHeader('retry-after');
|
|
1595
|
+
}
|
|
1596
|
+
// The route pattern, not the requested URL: no query values in the log (D-0047). D-0142: and
|
|
1597
|
+
// the route id, so a refusal of a plugin's own route (403 of /mcp) is named like an app's.
|
|
1598
|
+
const matched = request.routeOptions;
|
|
1599
|
+
const route = matched.url ?? 'unmatched';
|
|
1600
|
+
const routeId = typeof matched.config?.id === 'string' ? matched.config.id : null;
|
|
1601
|
+
// D-0093: an error that would answer 500 is offered to the translators first; a coded result
|
|
1602
|
+
// is answered (and logged) in its place. Besides uncoded errors that is a Dokebi error
|
|
1603
|
+
// answering 500 around a cause, thrown in a handler or a hook: a plugin's coded failure (a
|
|
1604
|
+
// failed auth hook, a session store) over a driver error, which only a 5xx translation (a
|
|
1605
|
+
// database that timed out, is busy or unavailable) replaces.
|
|
1606
|
+
const offer = this.#translators.length ? translatable(thrown) : 'no';
|
|
1607
|
+
const translated = offer === 'no'
|
|
1608
|
+
? undefined
|
|
1609
|
+
: this.#translate(thrown, request, route, failures, offer === 'server-only');
|
|
1610
|
+
const error = translated?.error ?? thrown;
|
|
718
1611
|
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
1612
|
const own = error?.code;
|
|
722
1613
|
const code = typeof own === 'string' ? own : answer.body.error;
|
|
723
|
-
if (
|
|
1614
|
+
if (translated) {
|
|
1615
|
+
const retryAfterMs = translated.error.data?.retryAfterMs;
|
|
1616
|
+
if (typeof retryAfterMs === 'number' && Number.isFinite(retryAfterMs) && retryAfterMs > 0)
|
|
1617
|
+
reply.header('retry-after', String(Math.ceil(retryAfterMs / 1000)));
|
|
1618
|
+
// D-0113: a translated 503 (a busy, slow or unavailable store) is a retryable refusal; a
|
|
1619
|
+
// burst of it logs the first of each code and route per window, the rest are counted.
|
|
1620
|
+
const transient = answer.status === 503;
|
|
1621
|
+
const repeated = transient
|
|
1622
|
+
? this.#transientFirst(request.method, route, answer.status, code, translated.plugin)
|
|
1623
|
+
? 0
|
|
1624
|
+
: undefined
|
|
1625
|
+
: failures.take(`translated ${request.method} ${route} ${code}`);
|
|
1626
|
+
if (repeated !== undefined)
|
|
1627
|
+
logger.log(transient ? this.#transient.level : 'error', 'HTTP request error translated', {
|
|
1628
|
+
code: 'WEB_ERROR_TRANSLATED',
|
|
1629
|
+
requestId: request.id,
|
|
1630
|
+
method: request.method,
|
|
1631
|
+
route,
|
|
1632
|
+
routeId,
|
|
1633
|
+
status: answer.status,
|
|
1634
|
+
errorCode: code,
|
|
1635
|
+
translator: translated.plugin,
|
|
1636
|
+
// The translated error with the thrown value as its cause: the whole driver error.
|
|
1637
|
+
error: describeError(error),
|
|
1638
|
+
...(repeated ? { repeated } : {}),
|
|
1639
|
+
});
|
|
1640
|
+
}
|
|
1641
|
+
else if (answer.status >= 500) {
|
|
1642
|
+
// A retryable 503 (the seal provider's nonce store, D-0096; a shared rate-limit store, an
|
|
1643
|
+
// app error, D-0102) says when to retry: `data.retryAfterMs` of a coded error.
|
|
1644
|
+
const retryAfterMs = answer.status === 503 ? dokebiError(error)?.data?.retryAfterMs : undefined;
|
|
1645
|
+
const transient = typeof retryAfterMs === 'number' && Number.isFinite(retryAfterMs) && retryAfterMs > 0;
|
|
1646
|
+
if (transient)
|
|
1647
|
+
reply.header('retry-after', String(Math.ceil(retryAfterMs / 1000)));
|
|
1648
|
+
// D-0113: such a 503 is counted like a translated one; every other 5xx keeps the D-0047
|
|
1649
|
+
// rule (in full, the same route and error once per 10 seconds with `repeated`).
|
|
724
1650
|
const name = error instanceof Error ? error.name : typeof error;
|
|
725
|
-
|
|
1651
|
+
// A refusal the app declared intended (defineErrors `intended: true`) is the app working as
|
|
1652
|
+
// designed: warn, counted like the other retryable 503s, never error.
|
|
1653
|
+
const intended = answer.status === 503 &&
|
|
1654
|
+
error?.[INTENDED_REFUSAL] === true;
|
|
1655
|
+
// A seal refusal its layer already recorded (SEAL_NONCES_LOST: the warn
|
|
1656
|
+
// SEAL_BODY_REFUSED once per window): no second record of the same event.
|
|
1657
|
+
const recorded = error?.[RECORDED] === true;
|
|
1658
|
+
if (recorded && logger.isEnabled('debug'))
|
|
1659
|
+
logger.log('debug', 'HTTP request refused: the seal layer recorded it', {
|
|
1660
|
+
method: request.method,
|
|
1661
|
+
route,
|
|
1662
|
+
status: answer.status,
|
|
1663
|
+
errorCode: code,
|
|
1664
|
+
});
|
|
1665
|
+
const repeated = recorded
|
|
1666
|
+
? undefined
|
|
1667
|
+
: transient || intended
|
|
1668
|
+
? this.#transientFirst(request.method, route, answer.status, code, undefined, intended ? 'warn' : undefined)
|
|
1669
|
+
? 0
|
|
1670
|
+
: undefined
|
|
1671
|
+
: failures.take(`${request.method} ${route} ${name} ${code}`);
|
|
726
1672
|
if (repeated !== undefined)
|
|
727
|
-
logger.log('error', 'HTTP request failed', {
|
|
1673
|
+
logger.log(intended ? 'warn' : transient ? this.#transient.level : 'error', 'HTTP request failed', {
|
|
728
1674
|
code: 'WEB_REQUEST_FAILED',
|
|
729
1675
|
requestId: request.id,
|
|
730
1676
|
method: request.method,
|
|
731
1677
|
route,
|
|
1678
|
+
routeId,
|
|
732
1679
|
status: answer.status,
|
|
733
1680
|
errorCode: code,
|
|
734
1681
|
error: describeError(error),
|
|
@@ -743,6 +1690,7 @@ class WebOwner {
|
|
|
743
1690
|
code: error.code,
|
|
744
1691
|
method: request.method,
|
|
745
1692
|
route,
|
|
1693
|
+
routeId,
|
|
746
1694
|
fix: error.fix,
|
|
747
1695
|
...(repeated ? { repeated } : {}),
|
|
748
1696
|
});
|
|
@@ -752,9 +1700,12 @@ class WebOwner {
|
|
|
752
1700
|
status: answer.status,
|
|
753
1701
|
method: request.method,
|
|
754
1702
|
route,
|
|
1703
|
+
routeId,
|
|
755
1704
|
error: describeError(error),
|
|
756
1705
|
errorCode: code,
|
|
757
1706
|
});
|
|
1707
|
+
// The words of the answer are web's own (fixed English) unless the errorBody hook wrote them.
|
|
1708
|
+
let ownWords = true;
|
|
758
1709
|
if (this.#hooks && this.#overridden.has('errorBody')) {
|
|
759
1710
|
try {
|
|
760
1711
|
const changed = this.#hooks.errorBody(error, { request, answer, production });
|
|
@@ -763,6 +1714,7 @@ class WebOwner {
|
|
|
763
1714
|
data: { hook: 'errorBody' },
|
|
764
1715
|
});
|
|
765
1716
|
answer = changed;
|
|
1717
|
+
ownWords = false;
|
|
766
1718
|
}
|
|
767
1719
|
catch (failure) {
|
|
768
1720
|
const repeated = failures.take(`errorBody ${route}`);
|
|
@@ -781,24 +1733,354 @@ class WebOwner {
|
|
|
781
1733
|
// D-0074 §1: JSON for scripts (Inertia, fetch, XHR, APIs, sealed requests), a small page for
|
|
782
1734
|
// a browser navigation or an HTML form post.
|
|
783
1735
|
const sealed = this.#sealing.sealOf(request) !== undefined;
|
|
784
|
-
const format =
|
|
1736
|
+
const format = requestErrorFormat(request, sealed);
|
|
1737
|
+
clearResourceHeaders(reply, answer.status);
|
|
785
1738
|
reply.code(answer.status);
|
|
786
1739
|
if (!this.#responders.length) {
|
|
787
|
-
this.#send(reply, answer.status, body, format);
|
|
1740
|
+
this.#send(reply, answer.status, body, format, ownWords);
|
|
788
1741
|
return undefined;
|
|
789
1742
|
}
|
|
790
|
-
|
|
1743
|
+
const responding = this.#respond({ request, reply, error, status: answer.status, body, format, production, sealed }, route, failures, ownWords);
|
|
1744
|
+
// Held until the responders end: once the client has left, nothing else holds an error view
|
|
1745
|
+
// that is still rendering (D-0023). The same promise goes to Fastify, which sees a rejection.
|
|
1746
|
+
this.#inflight++;
|
|
1747
|
+
responding.then(this.#release, this.#release);
|
|
1748
|
+
return responding;
|
|
1749
|
+
}
|
|
1750
|
+
/**
|
|
1751
|
+
* D-0150: @fastify/under-pressure samples the event loop delay, its utilization and memory every
|
|
1752
|
+
* sampleIntervalMs (its own timer, `server.memoryUsage()`). Registered without limits it adds
|
|
1753
|
+
* no hook of its own (its hook reads `request.routeOptions` on every request); dokebi-web reads
|
|
1754
|
+
* the sample on the same period and keeps one field, which its onRequest hook checks. Above a
|
|
1755
|
+
* limit the answer is 503 OVERLOADED with Retry-After before any handler runs (a small page for
|
|
1756
|
+
* a browser navigation, the error shape otherwise); health routes and `config.overload: false`
|
|
1757
|
+
* routes are served. Logged like the other retryable 503s (D-0113): the first of each route
|
|
1758
|
+
* per window in full, the rest counted; the start and end of each overload at debug.
|
|
1759
|
+
*/
|
|
1760
|
+
#overload(settings) {
|
|
1761
|
+
const logger = this.context.logger;
|
|
1762
|
+
const limits = {
|
|
1763
|
+
eventLoopDelay: settings.maxEventLoopDelayMs,
|
|
1764
|
+
eventLoopUtilization: settings.maxEventLoopUtilization,
|
|
1765
|
+
heapUsedBytes: settings.maxHeapUsedBytes,
|
|
1766
|
+
rssBytes: settings.maxRssBytes,
|
|
1767
|
+
};
|
|
1768
|
+
const checked = Object.values(limits).some((value) => value > 0);
|
|
1769
|
+
if (!settings.enabled || !checked) {
|
|
1770
|
+
logger.log('debug', 'Web overload protection off', {
|
|
1771
|
+
enabled: settings.enabled,
|
|
1772
|
+
limits: checked,
|
|
1773
|
+
});
|
|
1774
|
+
return;
|
|
1775
|
+
}
|
|
1776
|
+
// The sampler starts with the server (start) and stops when it closes.
|
|
1777
|
+
this.server.addHook('onClose', (_instance, done) => {
|
|
1778
|
+
if (this.#sampler)
|
|
1779
|
+
clearInterval(this.#sampler);
|
|
1780
|
+
done();
|
|
1781
|
+
});
|
|
1782
|
+
this.server.register(underPressure, {
|
|
1783
|
+
sampleInterval: settings.sampleIntervalMs,
|
|
1784
|
+
// Each sample on its own (the default, 'cumulative', averages since the process started).
|
|
1785
|
+
eventLoopUtilizationMode: 'interval',
|
|
1786
|
+
});
|
|
1787
|
+
const answers = new Map();
|
|
1788
|
+
this.#shedding = {
|
|
1789
|
+
settings,
|
|
1790
|
+
limits,
|
|
1791
|
+
seconds: String(Math.ceil(settings.retryAfterMs / 1000)),
|
|
1792
|
+
answer: (reason) => {
|
|
1793
|
+
let answer = answers.get(reason);
|
|
1794
|
+
if (!answer) {
|
|
1795
|
+
const error = new WebError('OVERLOADED', 'The server is overloaded; try again later', {
|
|
1796
|
+
data: { reason, retryAfterMs: settings.retryAfterMs },
|
|
1797
|
+
});
|
|
1798
|
+
answer = errorAnswer(error, this.#production, (details) => this.#details(details));
|
|
1799
|
+
answers.set(reason, answer);
|
|
1800
|
+
}
|
|
1801
|
+
return answer;
|
|
1802
|
+
},
|
|
1803
|
+
};
|
|
1804
|
+
logger.log('debug', 'Web overload protection on', {
|
|
1805
|
+
...limits,
|
|
1806
|
+
sampleIntervalMs: settings.sampleIntervalMs,
|
|
1807
|
+
retryAfterMs: settings.retryAfterMs,
|
|
1808
|
+
});
|
|
1809
|
+
}
|
|
1810
|
+
/**
|
|
1811
|
+
* D-0154: the reloadable options of dokebi-web (securityHeaders but `enabled`, the overload
|
|
1812
|
+
* limits and retryAfterMs, developmentErrors, the transient log, drainGraceMs). Built here,
|
|
1813
|
+
* switched in `apply` for the next request. Overload limits cannot turn protection on when it
|
|
1814
|
+
* was off at start (its sampler was never registered): that needs a restart.
|
|
1815
|
+
*/
|
|
1816
|
+
prepareReload(next) {
|
|
1817
|
+
const shedding = this.#shedding;
|
|
1818
|
+
const limits = {
|
|
1819
|
+
eventLoopDelay: next.overload.maxEventLoopDelayMs,
|
|
1820
|
+
eventLoopUtilization: next.overload.maxEventLoopUtilization,
|
|
1821
|
+
heapUsedBytes: next.overload.maxHeapUsedBytes,
|
|
1822
|
+
rssBytes: next.overload.maxRssBytes,
|
|
1823
|
+
};
|
|
1824
|
+
if (!shedding && Object.values(limits).some((value) => value > 0))
|
|
1825
|
+
throw new DokebiError('OVERLOAD_RESTART_REQUIRED', 'Overload protection was off at start; turning it on needs a restart', {
|
|
1826
|
+
plugin: 'dokebi-web',
|
|
1827
|
+
fix: 'Restart the app to turn on overload protection (its sampler starts with the server).',
|
|
1828
|
+
});
|
|
1829
|
+
const production = process.env.NODE_ENV === 'production' || !next.developmentErrors;
|
|
1830
|
+
const transient = new TransientLog({
|
|
1831
|
+
logger: this.context.logger,
|
|
1832
|
+
windowMs: next.transientLogWindowMs,
|
|
1833
|
+
maxKeys: next.transientLogMaxKeys,
|
|
1834
|
+
level: next.transientLogLevel,
|
|
1835
|
+
});
|
|
1836
|
+
const answers = new Map();
|
|
1837
|
+
const overload = next.overload;
|
|
1838
|
+
const nextShedding = shedding && {
|
|
1839
|
+
settings: overload,
|
|
1840
|
+
limits,
|
|
1841
|
+
seconds: String(Math.ceil(overload.retryAfterMs / 1000)),
|
|
1842
|
+
answer: (reason) => {
|
|
1843
|
+
let answer = answers.get(reason);
|
|
1844
|
+
if (!answer) {
|
|
1845
|
+
const error = new WebError('OVERLOADED', 'The server is overloaded; try again later', {
|
|
1846
|
+
data: { reason, retryAfterMs: overload.retryAfterMs },
|
|
1847
|
+
});
|
|
1848
|
+
answer = errorAnswer(error, production, (details) => this.#details(details));
|
|
1849
|
+
answers.set(reason, answer);
|
|
1850
|
+
}
|
|
1851
|
+
return answer;
|
|
1852
|
+
},
|
|
1853
|
+
};
|
|
1854
|
+
return {
|
|
1855
|
+
apply: () => {
|
|
1856
|
+
this.#security.update(next.securityHeaders);
|
|
1857
|
+
if (nextShedding)
|
|
1858
|
+
this.#shedding = nextShedding;
|
|
1859
|
+
this.#production = production;
|
|
1860
|
+
this.#drainGraceMs = next.drainGraceMs;
|
|
1861
|
+
this.#drainIdleMs = next.drainIdleMs;
|
|
1862
|
+
this.#unavailableRetryAfter = String(Math.ceil(next.unavailableRetryAfterMs / 1000));
|
|
1863
|
+
// The counts of the old window are written, not lost (D-0113).
|
|
1864
|
+
this.#transient.flush();
|
|
1865
|
+
this.#transient = transient;
|
|
1866
|
+
this.context.logger.log('debug', 'Web options reloaded', {
|
|
1867
|
+
code: 'WEB_RELOADED',
|
|
1868
|
+
errorBodies: production ? 'production' : 'development',
|
|
1869
|
+
overload: nextShedding ? limits : false,
|
|
1870
|
+
securityHeaders: this.#security.enabled,
|
|
1871
|
+
});
|
|
1872
|
+
},
|
|
1873
|
+
};
|
|
791
1874
|
}
|
|
792
|
-
/**
|
|
793
|
-
#
|
|
1875
|
+
/** Reads the last sample of @fastify/under-pressure: the reason of an overload, or none. */
|
|
1876
|
+
#sample() {
|
|
1877
|
+
const shedding = this.#shedding;
|
|
1878
|
+
if (!shedding)
|
|
1879
|
+
return;
|
|
1880
|
+
const usage = this.server.memoryUsage();
|
|
1881
|
+
const { limits } = shedding;
|
|
1882
|
+
// under-pressure says Infinity when its delay histogram took no sample in an interval: the
|
|
1883
|
+
// loop did not run for about that long (a block, the process descheduled). The delay was at
|
|
1884
|
+
// least one interval, not more than every limit: kept, an Infinity shed every request
|
|
1885
|
+
// whatever maxEventLoopDelayMs said (600000 too) and logged its value as null.
|
|
1886
|
+
const delay = Number.isFinite(usage.eventLoopDelay)
|
|
1887
|
+
? usage.eventLoopDelay
|
|
1888
|
+
: shedding.settings.sampleIntervalMs;
|
|
1889
|
+
const values = [
|
|
1890
|
+
['eventLoopDelay', delay],
|
|
1891
|
+
['eventLoopUtilization', usage.eventLoopUtilized],
|
|
1892
|
+
['heapUsedBytes', usage.heapUsed],
|
|
1893
|
+
['rssBytes', usage.rssBytes],
|
|
1894
|
+
];
|
|
1895
|
+
const over = values.find(([reason, value]) => (limits[reason] ?? 0) > 0 && value > (limits[reason] ?? 0));
|
|
1896
|
+
const before = this.#pressure;
|
|
1897
|
+
this.#pressure = over ? { reason: over[0], value: over[1] } : undefined;
|
|
1898
|
+
const logger = this.context.logger;
|
|
1899
|
+
if (over && !before)
|
|
1900
|
+
logger.log('debug', 'Web overload: requests are refused', {
|
|
1901
|
+
reason: over[0],
|
|
1902
|
+
value: Math.round(over[1] * 1000) / 1000,
|
|
1903
|
+
limit: limits[over[0]],
|
|
1904
|
+
});
|
|
1905
|
+
else if (!over && before)
|
|
1906
|
+
logger.log('debug', 'Web overload over: requests are served again', {
|
|
1907
|
+
reason: before.reason,
|
|
1908
|
+
});
|
|
1909
|
+
}
|
|
1910
|
+
/** Answers a request 503 OVERLOADED, unless its route is served under pressure (true: answered). */
|
|
1911
|
+
#shed(request, reply) {
|
|
1912
|
+
const pressure = this.#pressure;
|
|
1913
|
+
const shedding = this.#shedding;
|
|
1914
|
+
if (!pressure || !shedding)
|
|
1915
|
+
return false;
|
|
1916
|
+
// Read only while shedding: `request.routeOptions` builds a new object on every read.
|
|
1917
|
+
const options = request.routeOptions;
|
|
1918
|
+
const config = options.config;
|
|
1919
|
+
if (config.dokebiHealth === true || config.overload === false)
|
|
1920
|
+
return false;
|
|
1921
|
+
const route = options.url ?? 'unmatched';
|
|
1922
|
+
if (this.#transientFirst(request.method, route, 503, 'OVERLOADED'))
|
|
1923
|
+
this.context.logger.log(this.#transient.level, 'HTTP request refused: the server is overloaded', {
|
|
1924
|
+
code: 'WEB_OVERLOADED',
|
|
1925
|
+
method: request.method,
|
|
1926
|
+
route,
|
|
1927
|
+
routeId: typeof config.id === 'string' ? config.id : null,
|
|
1928
|
+
reason: pressure.reason,
|
|
1929
|
+
value: Math.round(pressure.value * 1000) / 1000,
|
|
1930
|
+
limit: shedding.limits[pressure.reason] ?? null,
|
|
1931
|
+
fix: 'Add capacity, find what blocks the event loop, or raise options.dokebi-web.overload',
|
|
1932
|
+
});
|
|
1933
|
+
const answer = shedding.answer(pressure.reason);
|
|
1934
|
+
reply
|
|
1935
|
+
.code(503)
|
|
1936
|
+
.header('retry-after', shedding.seconds)
|
|
1937
|
+
.header('cache-control', 'no-store')
|
|
1938
|
+
.header('content-language', 'en');
|
|
1939
|
+
const body = this.#production ? productionBody(answer.body) : answer.body;
|
|
1940
|
+
if (requestErrorFormat(request, this.#sealing.sealOf(request) !== undefined) === 'html')
|
|
1941
|
+
reply.type('text/html; charset=utf-8').send(errorPage(503, body));
|
|
1942
|
+
else
|
|
1943
|
+
reply.send(body);
|
|
1944
|
+
return true;
|
|
1945
|
+
}
|
|
1946
|
+
/** True for the first retryable 503 of its code and route in the window (D-0113). */
|
|
1947
|
+
#transientFirst(method, route, status, errorCode, translator, level) {
|
|
1948
|
+
return this.#transient.first(`${status} ${errorCode} ${method} ${route}`, () => ({
|
|
1949
|
+
method,
|
|
1950
|
+
route,
|
|
1951
|
+
status,
|
|
1952
|
+
errorCode,
|
|
1953
|
+
...(translator === undefined ? {} : { translator }),
|
|
1954
|
+
}), level);
|
|
1955
|
+
}
|
|
1956
|
+
/**
|
|
1957
|
+
* The first coded error a translator returns for `error` (D-0093), with its plugin; a
|
|
1958
|
+
* translator that throws or returns something else is logged and skipped. For a coded error
|
|
1959
|
+
* (`serverOnly`) only a translation answering 5xx counts: a 4xx would blame the client for a
|
|
1960
|
+
* failure the plugin or app already called its own.
|
|
1961
|
+
*/
|
|
1962
|
+
#translate(error, request, route, failures, serverOnly) {
|
|
1963
|
+
for (const { plugin, value } of this.#translators) {
|
|
1964
|
+
let result;
|
|
1965
|
+
try {
|
|
1966
|
+
result = value.translate(error, request);
|
|
1967
|
+
if (result === undefined)
|
|
1968
|
+
continue;
|
|
1969
|
+
const known = dokebiError(result);
|
|
1970
|
+
if (known && serverOnly && (known.status ?? 500) < 500) {
|
|
1971
|
+
if (this.context.logger.isEnabled('debug'))
|
|
1972
|
+
this.context.logger.log('debug', 'Web error translation kept the coded error', {
|
|
1973
|
+
route,
|
|
1974
|
+
translator: plugin,
|
|
1975
|
+
errorCode: error.code,
|
|
1976
|
+
translatedCode: known.code,
|
|
1977
|
+
});
|
|
1978
|
+
continue;
|
|
1979
|
+
}
|
|
1980
|
+
if (known)
|
|
1981
|
+
return { error: known, plugin };
|
|
1982
|
+
throw new WebError('INVALID_ERROR_TRANSLATOR', 'An error translator returned something other than a Dokebi error or undefined', { data: { translator: plugin } });
|
|
1983
|
+
}
|
|
1984
|
+
catch (failure) {
|
|
1985
|
+
// Logged, then the next translator (finally the 500 answer) takes the error.
|
|
1986
|
+
const repeated = failures.take(`translator ${plugin} ${route}`);
|
|
1987
|
+
if (repeated !== undefined)
|
|
1988
|
+
this.context.logger.log('error', 'Web error translator failed', {
|
|
1989
|
+
code: 'WEB_ERROR_TRANSLATOR_FAILED',
|
|
1990
|
+
method: request.method,
|
|
1991
|
+
route,
|
|
1992
|
+
translator: plugin,
|
|
1993
|
+
fix: `Return a DokebiError or undefined from the dokebi-web:error-translator of ${plugin}, synchronously, without throwing.`,
|
|
1994
|
+
error: describeError(failure),
|
|
1995
|
+
...(repeated ? { repeated } : {}),
|
|
1996
|
+
});
|
|
1997
|
+
}
|
|
1998
|
+
}
|
|
1999
|
+
return undefined;
|
|
2000
|
+
}
|
|
2001
|
+
/**
|
|
2002
|
+
* The answer to an error raised while sending web's own error answer failed as well: nothing
|
|
2003
|
+
* is left to answer with, so the connection ends (an HTTP/2 stream only), logged once per route
|
|
2004
|
+
* and window. Never throws: Fastify would answer in its own shape then.
|
|
2005
|
+
*/
|
|
2006
|
+
#answerFailed(error, request, reply, failures) {
|
|
2007
|
+
const route = request.routeOptions.url ?? 'unmatched';
|
|
2008
|
+
const repeated = failures.take(`answer-failed ${request.method} ${route}`);
|
|
2009
|
+
if (repeated !== undefined)
|
|
2010
|
+
this.context.logger.log('error', 'HTTP error answer failed; the connection is ended', {
|
|
2011
|
+
code: 'WEB_ERROR_ANSWER_FAILED',
|
|
2012
|
+
requestId: request.id,
|
|
2013
|
+
method: request.method,
|
|
2014
|
+
route,
|
|
2015
|
+
status: reply.statusCode,
|
|
2016
|
+
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.',
|
|
2017
|
+
error: describeError(error),
|
|
2018
|
+
...(repeated ? { repeated } : {}),
|
|
2019
|
+
});
|
|
2020
|
+
// Ended on purpose: the response's close releases the request at once (it would otherwise be
|
|
2021
|
+
// held as one whose client left, waiting for an answer that is never sent).
|
|
2022
|
+
delete reply.raw[REPLY];
|
|
2023
|
+
if (http1(request))
|
|
2024
|
+
reply.raw.socket?.destroy();
|
|
2025
|
+
else
|
|
2026
|
+
request.raw.stream?.close(2);
|
|
2027
|
+
return undefined;
|
|
2028
|
+
}
|
|
2029
|
+
/**
|
|
2030
|
+
* D-0047: a handler whose Promise rejected after its answer was sent (work it awaited after
|
|
2031
|
+
* `reply.send`, a hijacked stream). Fastify cannot answer it any more and only tells its own
|
|
2032
|
+
* logger, which is off without @dokebi/logger's request log. Once per route and error per
|
|
2033
|
+
* `logRepeatWindowMs`, with `repeated`.
|
|
2034
|
+
*/
|
|
2035
|
+
#failedAfterSend(request, reply, error, failures) {
|
|
2036
|
+
const matched = request.routeOptions;
|
|
2037
|
+
const route = matched.url ?? 'unmatched';
|
|
2038
|
+
// The body stalled and was answered 408: the handler then fails reading it, as expected.
|
|
2039
|
+
if (request.raw[TIMED_OUT] !== undefined) {
|
|
2040
|
+
if (this.context.logger.isEnabled('debug'))
|
|
2041
|
+
this.context.logger.log('debug', 'HTTP handler ended after its body timed out', {
|
|
2042
|
+
method: request.method,
|
|
2043
|
+
route,
|
|
2044
|
+
error: describeError(error),
|
|
2045
|
+
});
|
|
2046
|
+
return;
|
|
2047
|
+
}
|
|
2048
|
+
const name = error instanceof Error ? error.name : typeof error;
|
|
2049
|
+
const own = error?.code;
|
|
2050
|
+
const repeated = failures.take(`after-send ${request.method} ${route} ${name} ${String(own)}`);
|
|
2051
|
+
if (repeated === undefined)
|
|
2052
|
+
return;
|
|
2053
|
+
this.context.logger.log('error', 'HTTP handler failed after its answer was sent', {
|
|
2054
|
+
code: 'WEB_HANDLER_FAILED_AFTER_SEND',
|
|
2055
|
+
requestId: request.id,
|
|
2056
|
+
method: request.method,
|
|
2057
|
+
route,
|
|
2058
|
+
routeId: typeof matched.config?.id === 'string' ? matched.config.id : null,
|
|
2059
|
+
status: reply.statusCode,
|
|
2060
|
+
...(typeof own === 'string' ? { errorCode: own } : {}),
|
|
2061
|
+
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).',
|
|
2062
|
+
error: describeError(error),
|
|
2063
|
+
...(repeated ? { repeated } : {}),
|
|
2064
|
+
});
|
|
2065
|
+
}
|
|
2066
|
+
/**
|
|
2067
|
+
* The built-in answer: the body as JSON, or its small HTML page. `own`: its words are web's
|
|
2068
|
+
* fixed English (`<html lang="en">`, the messages of coded errors), so it says
|
|
2069
|
+
* `Content-Language: en` — not the language a plugin negotiated for the request before
|
|
2070
|
+
* (@dokebi/i18n sets that in onRequest). A body the errorBody hook wrote, and an app's error
|
|
2071
|
+
* view sent by a responder, keep whatever header they have.
|
|
2072
|
+
*/
|
|
2073
|
+
#send(reply, status, body, format, own) {
|
|
794
2074
|
reply.code(status);
|
|
2075
|
+
if (own)
|
|
2076
|
+
reply.header('content-language', 'en');
|
|
795
2077
|
if (format === 'html')
|
|
796
2078
|
reply.type('text/html; charset=utf-8').send(errorPage(status, body));
|
|
797
2079
|
else
|
|
798
2080
|
reply.type('application/json; charset=utf-8').send(body);
|
|
799
2081
|
}
|
|
800
2082
|
/** Asks the error responders (D-0074); the built-in answer when none wrote one or one failed. */
|
|
801
|
-
async #respond(response, route, failures) {
|
|
2083
|
+
async #respond(response, route, failures, own) {
|
|
802
2084
|
const { request, reply } = response;
|
|
803
2085
|
const logger = this.context.logger;
|
|
804
2086
|
// `reply.sent` stays false until the response has ended (async onSend hooks such as the
|
|
@@ -839,7 +2121,7 @@ class WebOwner {
|
|
|
839
2121
|
}
|
|
840
2122
|
}
|
|
841
2123
|
// 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);
|
|
2124
|
+
this.#send(reply, response.status, response.body, response.format, own);
|
|
843
2125
|
return reply;
|
|
844
2126
|
}
|
|
845
2127
|
/** `details` for a development body; one that is not JSON (a cycle, a BigInt) is left out. */
|
|
@@ -866,11 +2148,16 @@ class WebOwner {
|
|
|
866
2148
|
method: request.method,
|
|
867
2149
|
url: request.url.split('?', 1)[0]?.slice(0, 200),
|
|
868
2150
|
});
|
|
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 =
|
|
2151
|
+
// D-0074 §1: a browser navigation gets a small page, every script JSON; other sealed
|
|
2152
|
+
// requests stay JSON (the route is known in onRequest, so the seal decision is too).
|
|
2153
|
+
const html = requestErrorFormat(request, this.#sealing.sealOf(request) !== undefined) === 'html';
|
|
2154
|
+
// Like every retryable 503 of the stack (a Redis outage, overload): when to try again. The
|
|
2155
|
+
// connection still closes, so the retry may reach another worker or instance.
|
|
2156
|
+
const retryAfter = this.#unavailableRetryAfter;
|
|
872
2157
|
if (!this.#hooks || !this.#overridden.has('unavailable')) {
|
|
873
|
-
reply.code(503).header('
|
|
2158
|
+
reply.code(503).header('content-language', 'en').header('retry-after', retryAfter);
|
|
2159
|
+
if (http1(request))
|
|
2160
|
+
reply.header('connection', 'close');
|
|
874
2161
|
if (html)
|
|
875
2162
|
reply
|
|
876
2163
|
.type('text/html; charset=utf-8')
|
|
@@ -881,6 +2168,7 @@ class WebOwner {
|
|
|
881
2168
|
}
|
|
882
2169
|
const answer = {
|
|
883
2170
|
status: 503,
|
|
2171
|
+
headers: { 'retry-after': retryAfter },
|
|
884
2172
|
body: { error: 'SERVICE_UNAVAILABLE', reason },
|
|
885
2173
|
};
|
|
886
2174
|
let chosen = answer;
|
|
@@ -890,6 +2178,12 @@ class WebOwner {
|
|
|
890
2178
|
throw new WebError('INVALID_EXTENSION_RESULT', 'unavailable() returned no answer', {
|
|
891
2179
|
data: { hook: 'unavailable' },
|
|
892
2180
|
});
|
|
2181
|
+
// Node's own rules (ERR_INVALID_HTTP_TOKEN, ERR_INVALID_CHAR): a value with a line break
|
|
2182
|
+
// otherwise failed the refusal at writeHead into Fastify's own 500 body.
|
|
2183
|
+
for (const [name, value] of Object.entries(result.headers ?? {})) {
|
|
2184
|
+
validateHeaderName(name);
|
|
2185
|
+
validateHeaderValue(name, value);
|
|
2186
|
+
}
|
|
893
2187
|
chosen = result;
|
|
894
2188
|
}
|
|
895
2189
|
catch (failure) {
|
|
@@ -904,7 +2198,8 @@ class WebOwner {
|
|
|
904
2198
|
for (const [name, value] of Object.entries(chosen.headers ?? {}))
|
|
905
2199
|
reply.header(name, value);
|
|
906
2200
|
// The request is refused either way: the connection closes, as without the hook.
|
|
907
|
-
|
|
2201
|
+
if (http1(request))
|
|
2202
|
+
reply.header('connection', 'close');
|
|
908
2203
|
const body = chosen.body;
|
|
909
2204
|
// A page only for a body of the error shape; anything else the hook chose stays JSON.
|
|
910
2205
|
if (html && body !== null && typeof body === 'object' && typeof body.error === 'string')
|
|
@@ -936,9 +2231,17 @@ class WebOwner {
|
|
|
936
2231
|
async close() {
|
|
937
2232
|
this.#closed = true;
|
|
938
2233
|
const started = performance.now();
|
|
939
|
-
|
|
2234
|
+
const { ended } = this.#connections.close();
|
|
2235
|
+
try {
|
|
2236
|
+
await this.server.close();
|
|
2237
|
+
}
|
|
2238
|
+
finally {
|
|
2239
|
+
// The counts of a burst that ends with the server are written, not lost (D-0113).
|
|
2240
|
+
this.#transient.flush();
|
|
2241
|
+
}
|
|
940
2242
|
this.context.logger.log('debug', 'Web server closed', {
|
|
941
2243
|
ms: Math.round(performance.now() - started),
|
|
2244
|
+
endedConnections: ended,
|
|
942
2245
|
});
|
|
943
2246
|
}
|
|
944
2247
|
}
|
|
@@ -946,8 +2249,30 @@ const NO_EXTENSION = Object.freeze({
|
|
|
946
2249
|
hooks: undefined,
|
|
947
2250
|
overridden: new Set(),
|
|
948
2251
|
});
|
|
2252
|
+
/**
|
|
2253
|
+
* Ajv's logger (its `logger` option) on the plugin's logger: Ajv reports schema problems of strict
|
|
2254
|
+
* mode (`strictTypes`, unknown formats) while a route's schema compiles, with console otherwise.
|
|
2255
|
+
*/
|
|
2256
|
+
function schemaLogger(logger) {
|
|
2257
|
+
const text = (parts) => parts.map(String).join(' ');
|
|
2258
|
+
return {
|
|
2259
|
+
log: (...parts) => {
|
|
2260
|
+
if (logger.isEnabled('debug'))
|
|
2261
|
+
logger.log('debug', 'Schema compiler message', {
|
|
2262
|
+
code: 'WEB_SCHEMA_MESSAGE',
|
|
2263
|
+
message: text(parts),
|
|
2264
|
+
});
|
|
2265
|
+
},
|
|
2266
|
+
warn: (...parts) => logger.log('warn', 'Route schema warning', {
|
|
2267
|
+
code: 'WEB_SCHEMA_WARNING',
|
|
2268
|
+
warning: text(parts),
|
|
2269
|
+
}),
|
|
2270
|
+
error: (...parts) => logger.log('error', 'Route schema error', { code: 'WEB_SCHEMA_ERROR', error: text(parts) }),
|
|
2271
|
+
};
|
|
2272
|
+
}
|
|
949
2273
|
const HEALTH = 'dokebi-health';
|
|
950
2274
|
const health = optionalDependency({ name: HEALTH, version: '^0.4.0' });
|
|
2275
|
+
const logging = optionalDependency({ name: 'dokebi-logger', version: '^0.1.0' });
|
|
951
2276
|
function invalidEntry(message, fix) {
|
|
952
2277
|
return new WebError('INVALID_ENTRY', message, fix === undefined ? {} : { fix });
|
|
953
2278
|
}
|
|
@@ -1044,13 +2369,42 @@ class WebRuntime {
|
|
|
1044
2369
|
this.health = health;
|
|
1045
2370
|
}
|
|
1046
2371
|
setup(context) {
|
|
1047
|
-
const owner = new WebOwner(context, this.options, this.extension, context.getOptionalDependency(this.health));
|
|
2372
|
+
const owner = new WebOwner(context, this.options, this.extension, context.getOptionalDependency(this.health), context.getOptionalDependency(logging));
|
|
1048
2373
|
this.#owner = owner;
|
|
1049
2374
|
context.defer(() => owner.close());
|
|
1050
2375
|
// D-0063 §7: `inject` of @dokebi/core/testing goes through this server, without a socket.
|
|
1051
2376
|
context.contribute(injectPoint, Object.freeze({
|
|
1052
2377
|
inject: (request) => owner.inject(request),
|
|
1053
2378
|
}));
|
|
2379
|
+
// D-0077 B: only `dokebi describe` (runtime.describing) asks; a normal start adds nothing.
|
|
2380
|
+
if (context.runtime.describing) {
|
|
2381
|
+
const options = this.options;
|
|
2382
|
+
context.contribute(describePoint, {
|
|
2383
|
+
section: 'routes',
|
|
2384
|
+
describe: () => owner.describeRoutes(),
|
|
2385
|
+
});
|
|
2386
|
+
context.contribute(describePoint, {
|
|
2387
|
+
section: 'web',
|
|
2388
|
+
describe: () => ({
|
|
2389
|
+
host: options.host,
|
|
2390
|
+
port: options.port,
|
|
2391
|
+
healthRoutes: options.healthRoutes ? { ...options.healthRoutes } : false,
|
|
2392
|
+
formBody: options.formBody,
|
|
2393
|
+
maxBodyBytes: options.maxBodyBytes,
|
|
2394
|
+
trustProxy: options.trustProxy.length,
|
|
2395
|
+
sealExclude: [...options.sealExclude],
|
|
2396
|
+
compression: options.compression.enabled
|
|
2397
|
+
? { ...options.compression, encodings: [...options.compression.encodings] }
|
|
2398
|
+
: false,
|
|
2399
|
+
}),
|
|
2400
|
+
});
|
|
2401
|
+
context.contribute(describePoint, {
|
|
2402
|
+
section: 'env',
|
|
2403
|
+
describe: () => [
|
|
2404
|
+
{ name: 'NODE_ENV', purpose: 'production: error bodies without fix and details' },
|
|
2405
|
+
],
|
|
2406
|
+
});
|
|
2407
|
+
}
|
|
1054
2408
|
return owner.api;
|
|
1055
2409
|
}
|
|
1056
2410
|
start() {
|
|
@@ -1060,27 +2414,100 @@ class WebRuntime {
|
|
|
1060
2414
|
return this.#owner?.worker ? this.#owner.listen() : undefined;
|
|
1061
2415
|
}
|
|
1062
2416
|
drain(context) {
|
|
1063
|
-
|
|
2417
|
+
// core 0.4.2: drainDeadline (an older core has none: the idle wait is drainIdleMs alone).
|
|
2418
|
+
return this.#owner?.drain(context.drainSignal, context.drainDeadline);
|
|
2419
|
+
}
|
|
2420
|
+
/** D-0154: the reloadable options (see WebOwner.prepareReload). */
|
|
2421
|
+
reload({ options }) {
|
|
2422
|
+
return this.#owner?.prepareReload(settings(options));
|
|
1064
2423
|
}
|
|
1065
2424
|
}
|
|
1066
2425
|
export const createPlugin = definePlugin({
|
|
1067
2426
|
name: 'dokebi-web',
|
|
1068
|
-
version: '0.4.
|
|
1069
|
-
core: '^0.4.
|
|
2427
|
+
version: '0.4.3',
|
|
2428
|
+
core: '^0.4.2',
|
|
1070
2429
|
options: declaration,
|
|
1071
2430
|
entry: (input) => new WebEntryInput(input),
|
|
1072
|
-
contributes: [injectPoint],
|
|
2431
|
+
contributes: [injectPoint, describePoint],
|
|
2432
|
+
collects: [errorTranslators],
|
|
1073
2433
|
// A required dokebi-health in entry.requires replaces the optional link.
|
|
1074
2434
|
dependencies: ({ entry }) => {
|
|
1075
2435
|
// The extension is created here, once: a broken subclass fails the factory call.
|
|
1076
2436
|
entry?.extension();
|
|
1077
2437
|
const requires = entry?.requires ?? [];
|
|
1078
|
-
|
|
2438
|
+
const linked = requires.some((dependency) => dependency.name === HEALTH)
|
|
1079
2439
|
? requires
|
|
1080
2440
|
: [...requires, health];
|
|
2441
|
+
return linked.some((dependency) => dependency.name === logging.name)
|
|
2442
|
+
? linked
|
|
2443
|
+
: [...linked, logging];
|
|
1081
2444
|
},
|
|
1082
2445
|
instance: ({ options, entry, dependencies }) => new WebRuntime(settings(options), entry?.extension() ?? NO_EXTENSION, (dependencies.find((dependency) => dependency.name === HEALTH) ??
|
|
1083
2446
|
health)),
|
|
1084
2447
|
});
|
|
1085
2448
|
/** Declares dokebi-web as a required provider (also `@dokebi/web/dependency`, D-0063 §6). */
|
|
1086
2449
|
export { dependency } from './dependency.js';
|
|
2450
|
+
const LINGERING = Symbol('dokebi.web.lingering');
|
|
2451
|
+
/**
|
|
2452
|
+
* Lingering close (as nginx's lingering_close): when Node closes the connection after an answer
|
|
2453
|
+
* sent before the request body was read, it first sends FIN only, keeps reading and dropping what
|
|
2454
|
+
* the client still sends — up to `linger.maxBytes`, for at most `linger.ms` — and closes once the
|
|
2455
|
+
* client has sent it all. The client then reads the answer instead of a connection reset.
|
|
2456
|
+
*/
|
|
2457
|
+
function lingerOnClose(request, linger, logger) {
|
|
2458
|
+
const { ms, maxBytes } = linger;
|
|
2459
|
+
const socket = request.socket;
|
|
2460
|
+
// An injected request (light-my-request) has no real socket to linger on.
|
|
2461
|
+
if (ms === 0 || !socket || typeof socket.destroySoon !== 'function' || socket[LINGERING])
|
|
2462
|
+
return;
|
|
2463
|
+
socket[LINGERING] = true;
|
|
2464
|
+
const destroySoon = socket.destroySoon.bind(socket);
|
|
2465
|
+
socket.destroySoon = () => {
|
|
2466
|
+
if (socket.destroyed)
|
|
2467
|
+
return;
|
|
2468
|
+
let read = 0;
|
|
2469
|
+
const close = (reason) => {
|
|
2470
|
+
clearTimeout(timer);
|
|
2471
|
+
if (logger.isEnabled('debug'))
|
|
2472
|
+
logger.log('debug', 'Early-answered connection closed after lingering', {
|
|
2473
|
+
code: 'WEB_LINGER_CLOSED',
|
|
2474
|
+
reason,
|
|
2475
|
+
bytes: read,
|
|
2476
|
+
});
|
|
2477
|
+
if (!socket.destroyed)
|
|
2478
|
+
socket.destroy();
|
|
2479
|
+
};
|
|
2480
|
+
const timer = setTimeout(() => close('time'), ms);
|
|
2481
|
+
timer.unref();
|
|
2482
|
+
socket.once('close', () => clearTimeout(timer));
|
|
2483
|
+
request.on('data', (chunk) => {
|
|
2484
|
+
read += chunk.length;
|
|
2485
|
+
if (read > maxBytes)
|
|
2486
|
+
close('size');
|
|
2487
|
+
});
|
|
2488
|
+
request.once('end', () => close('end'));
|
|
2489
|
+
// The client read the answer and closed its side (most stop sending at our FIN).
|
|
2490
|
+
socket.once('end', () => close('client'));
|
|
2491
|
+
// A client that resets the connection while it lingers ends it; nothing is left to answer.
|
|
2492
|
+
request.once('error', (error) => {
|
|
2493
|
+
if (logger.isEnabled('debug'))
|
|
2494
|
+
logger.log('debug', 'Early-answered connection ended by the client while lingering', {
|
|
2495
|
+
code: 'WEB_LINGER_CLOSED',
|
|
2496
|
+
reason: 'error',
|
|
2497
|
+
error: diagnostics.describeError(error),
|
|
2498
|
+
});
|
|
2499
|
+
close('error');
|
|
2500
|
+
});
|
|
2501
|
+
try {
|
|
2502
|
+
socket.end();
|
|
2503
|
+
request.resume();
|
|
2504
|
+
}
|
|
2505
|
+
catch (error) {
|
|
2506
|
+
logger.log('error', 'Lingering close failed; closing the connection now', {
|
|
2507
|
+
code: 'WEB_LINGER_FAILED',
|
|
2508
|
+
error: diagnostics.describeError(error),
|
|
2509
|
+
});
|
|
2510
|
+
destroySoon();
|
|
2511
|
+
}
|
|
2512
|
+
};
|
|
2513
|
+
}
|