@dokebi/web 0.4.2 → 0.4.4

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