@dokebi/web 0.4.2 → 0.4.3

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