@dokebi/web 0.2.0 → 0.4.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/dist/seal.js CHANGED
@@ -1,7 +1,7 @@
1
+ import { diagnostics } from '@dokebi/core/libraries';
2
+ import { WebError } from './errors.js';
1
3
  /** Response header naming the path a sealed response was sealed with (after a redirect it is the final one). */
2
4
  export const SEALED_PATH_HEADER = 'x-dokebi-sealed-path';
3
- const PATH = /^\/[^?#\s]{0,2047}$/;
4
- const REPEAT_INTERVAL_MS = 10_000;
5
5
  const JSON_TYPE = /^application\/(?:[a-z0-9.+-]+\+)?json$/;
6
6
  /** The media type of a Content-Type value: lower case, without parameters. */
7
7
  export function mediaType(value) {
@@ -30,40 +30,14 @@ function withoutPort(host) {
30
30
  const colon = raw.lastIndexOf(':');
31
31
  return colon === -1 ? raw : raw.slice(0, colon);
32
32
  }
33
- /** Validates `sealExclude`: path prefixes, matched at a segment boundary. */
33
+ /** `sealExclude` (validated by the options): prefixes without trailing slashes, unique. */
34
34
  export function sealExclude(input) {
35
- if (input === undefined)
36
- return Object.freeze([]);
37
- if (!Array.isArray(input) ||
38
- input.length > 64 ||
39
- !input.every((item) => typeof item === 'string' && PATH.test(item)))
40
- return undefined;
41
35
  return Object.freeze([...new Set(input.map((item) => item.replace(/(.)\/+$/, '$1')))]);
42
36
  }
43
37
  export function checkSealSetting(value) {
44
38
  if (value === undefined || typeof value === 'boolean' || typeof value === 'function')
45
39
  return value;
46
- throw new TypeError('Route seal must be a boolean or a function of the request');
47
- }
48
- class Repeats {
49
- #keys = new Map();
50
- take(key, now = Date.now()) {
51
- const entry = this.#keys.get(key);
52
- if (entry && now < entry.until) {
53
- entry.repeated++;
54
- return undefined;
55
- }
56
- if (!entry && this.#keys.size >= 256)
57
- this.#keys.clear();
58
- this.#keys.set(key, { until: now + REPEAT_INTERVAL_MS, repeated: 0 });
59
- return entry?.repeated ?? 0;
60
- }
61
- }
62
- function coded(message, code, statusCode, cause) {
63
- return Object.assign(new Error(message, cause === undefined ? undefined : { cause }), {
64
- code,
65
- statusCode,
66
- });
40
+ throw new WebError('INVALID_ROUTE', 'Route seal must be a boolean or a function of the request');
67
41
  }
68
42
  /**
69
43
  * The seal slot of one web server. Requests are sealed by their route (`seal`) or by a
@@ -75,7 +49,6 @@ export class WebSealing {
75
49
  logger;
76
50
  options;
77
51
  requestHost;
78
- errorText;
79
52
  #provider;
80
53
  #predicates = [];
81
54
  /** Routes that may seal (`seal: true` or a function): they need a provider. */
@@ -84,14 +57,11 @@ export class WebSealing {
84
57
  #decided = new WeakMap();
85
58
  /** Replies this layer answered itself (415, refused body): sent plain so any client can read them. */
86
59
  #plain = new WeakSet();
87
- #repeats = new Repeats();
88
- constructor(logger, options, requestHost,
89
- /** The full text of a caught value for the `error` log field (D-0047). */
90
- errorText) {
60
+ #repeats = new diagnostics.Repeats();
61
+ constructor(logger, options, requestHost) {
91
62
  this.logger = logger;
92
63
  this.options = options;
93
64
  this.requestHost = requestHost;
94
- this.errorText = errorText;
95
65
  }
96
66
  get provider() {
97
67
  return this.#provider;
@@ -102,15 +72,13 @@ export class WebSealing {
102
72
  }
103
73
  setProvider(provider) {
104
74
  if (this.#provider)
105
- throw new TypeError('A seal codec is already registered');
75
+ throw new WebError('SEAL_PROVIDER_INVALID', 'A seal codec is already registered');
106
76
  if (provider === null ||
107
77
  typeof provider !== 'object' ||
108
78
  typeof provider.forRequest !== 'function' ||
109
79
  typeof provider.contentType !== 'string' ||
110
80
  !/^[a-z]+\/[a-z0-9.+-]{1,100}$/.test(provider.contentType))
111
- throw Object.assign(new TypeError('Invalid seal codec provider'), {
112
- code: 'SEAL_PROVIDER_INVALID',
113
- });
81
+ throw new WebError('SEAL_PROVIDER_INVALID', 'Invalid seal codec provider');
114
82
  this.#provider = provider;
115
83
  this.logger.log('debug', 'Web seal codec registered', {
116
84
  contentType: provider.contentType,
@@ -120,7 +88,7 @@ export class WebSealing {
120
88
  }
121
89
  addPredicate(predicate) {
122
90
  if (typeof predicate !== 'function')
123
- throw new TypeError('Seal predicate must be a function');
91
+ throw new WebError('INVALID_ARGUMENT', 'Seal predicate must be a function');
124
92
  this.#predicates.push(predicate);
125
93
  this.logger.log('debug', 'Web seal predicate registered', {
126
94
  predicates: this.#predicates.length,
@@ -140,7 +108,7 @@ export class WebSealing {
140
108
  exclude: this.options.exclude.length,
141
109
  });
142
110
  if (this.wanted && !this.#provider)
143
- throw Object.assign(new Error('Requests are sealed (a seal host or a route with seal) but no seal codec is registered; register the dokebi-seal plugin'), { code: 'SEAL_PROVIDER_MISSING' });
111
+ throw new WebError('SEAL_PROVIDER_MISSING', 'Requests are sealed (a seal host or a route with seal) but no seal codec is registered; register the dokebi-seal plugin');
144
112
  }
145
113
  #sealedRequest(request) {
146
114
  const config = (request.routeOptions?.config ?? {});
@@ -190,8 +158,12 @@ export class WebSealing {
190
158
  this.#decided.set(request, sealer);
191
159
  return sealer ?? undefined;
192
160
  }
193
- /** onRequest: decides the request and refuses a plain body on a sealed one (415). */
194
- async onRequest(request, reply) {
161
+ /**
162
+ * onRequest: decides the request and refuses a plain body on a sealed one: the 415 error to
163
+ * answer with (sent plain), or undefined. Synchronous: dokebi-web calls it from its
164
+ * callback-style hook and passes the error to `done`, so the error mapping answers it.
165
+ */
166
+ refusePlain(request) {
195
167
  const sealer = this.sealOf(request);
196
168
  const debug = this.logger.isEnabled('debug');
197
169
  if (!sealer)
@@ -221,11 +193,7 @@ export class WebSealing {
221
193
  ...(repeated ? { repeated } : {}),
222
194
  });
223
195
  this.#plain.add(request);
224
- return reply
225
- .code(415)
226
- .type('application/json; charset=utf-8')
227
- .send({
228
- error: 'SEAL_REQUIRED',
196
+ return new WebError('SEAL_REQUIRED', 'A sealed route got a plain request body', {
229
197
  fix: `This route is sealed (a seal host): send the body sealed as ${provider.contentType} with @dokebi/seal (sealedFetch, or the Inertia bridge sealInertia). File uploads use multipart/form-data; webhooks and server-to-server routes set seal: false or are listed in dokebi-web sealExclude.`,
230
198
  });
231
199
  }
@@ -251,7 +219,7 @@ export class WebSealing {
251
219
  ...(repeated ? { repeated } : {}),
252
220
  });
253
221
  this.#plain.add(request);
254
- throw coded('Sealed request body refused', 'SEAL_BODY_REFUSED', 400, error);
222
+ throw new WebError('SEAL_BODY_REFUSED', 'Sealed request body refused', { cause: error });
255
223
  }
256
224
  if (plain === '')
257
225
  return undefined;
@@ -259,7 +227,9 @@ export class WebSealing {
259
227
  return JSON.parse(plain);
260
228
  }
261
229
  catch (error) {
262
- throw coded('Sealed request body is not JSON', 'SEAL_BODY_NOT_JSON', 400, error);
230
+ throw new WebError('SEAL_BODY_NOT_JSON', 'Sealed request body is not JSON', {
231
+ cause: error,
232
+ });
263
233
  }
264
234
  }
265
235
  /** onSend: seals the JSON response of a sealed request (other types pass unchanged). */
@@ -277,7 +247,7 @@ export class WebSealing {
277
247
  else if (Buffer.isBuffer(payload))
278
248
  text = payload.toString('utf8');
279
249
  else
280
- throw coded('A streamed JSON response cannot be sealed', 'SEAL_STREAM_UNSUPPORTED', 500);
250
+ throw new WebError('SEAL_STREAM_UNSUPPORTED', 'A streamed JSON response cannot be sealed');
281
251
  const sealed = sealer.encode(text);
282
252
  reply.header('content-type', provider.contentType);
283
253
  reply.header(SEALED_PATH_HEADER, sealer.path);
@@ -292,7 +262,7 @@ export class WebSealing {
292
262
  code: error.code ?? 'SEAL_ENCODE_FAILED',
293
263
  method: request.method,
294
264
  route,
295
- error: this.errorText(error),
265
+ error: diagnostics.describeError(error),
296
266
  ...(repeated ? { repeated } : {}),
297
267
  });
298
268
  reply.code(500).header('content-type', 'application/json; charset=utf-8');
@@ -7,32 +7,46 @@
7
7
  "type": "string",
8
8
  "minLength": 1,
9
9
  "maxLength": 253,
10
- "default": "127.0.0.1"
10
+ "default": "127.0.0.1",
11
+ "description": "Address to listen on; 0.0.0.0 accepts other machines (put a proxy in front)."
11
12
  },
12
13
  "port": {
13
14
  "type": "integer",
14
15
  "minimum": 0,
15
16
  "maximum": 65535,
16
- "default": 0
17
+ "default": 0,
18
+ "description": "Port to listen on; 0 picks a free one."
19
+ },
20
+ "maxBodyBytes": {
21
+ "type": "integer",
22
+ "minimum": 1,
23
+ "maximum": 67108864,
24
+ "default": 1048576,
25
+ "description": "Largest request body in bytes."
17
26
  },
18
27
  "bodyLimit": {
19
28
  "type": "integer",
20
29
  "minimum": 1,
21
30
  "maximum": 67108864,
22
- "default": 1048576
31
+ "deprecated": true,
32
+ "description": "Deprecated name of maxBodyBytes; use that key."
33
+ },
34
+ "requestTimeoutMs": {
35
+ "type": "integer",
36
+ "minimum": 1,
37
+ "maximum": 2147483647,
38
+ "default": 30000,
39
+ "description": "Time to receive a whole request in ms (not a limit on the work it starts)."
23
40
  },
24
41
  "requestTimeout": {
25
42
  "type": "integer",
26
43
  "minimum": 1,
27
44
  "maximum": 2147483647,
28
- "default": 30000
45
+ "deprecated": true,
46
+ "description": "Deprecated name of requestTimeoutMs; use that key."
29
47
  },
30
48
  "healthRoutes": {
31
- "default": {
32
- "live": "/health/live",
33
- "ready": "/health/ready"
34
- },
35
- "oneOf": [
49
+ "anyOf": [
36
50
  {
37
51
  "const": false
38
52
  },
@@ -42,28 +56,33 @@
42
56
  "properties": {
43
57
  "live": {
44
58
  "type": "string",
45
- "pattern": "^/[^?#\\s]{0,2047}$",
59
+ "pattern": "^\\/[^?#\\s]{0,2047}$",
46
60
  "default": "/health/live"
47
61
  },
48
62
  "ready": {
49
63
  "type": "string",
50
- "pattern": "^/[^?#\\s]{0,2047}$",
64
+ "pattern": "^\\/[^?#\\s]{0,2047}$",
51
65
  "default": "/health/ready"
52
66
  }
53
67
  }
54
68
  }
55
- ]
69
+ ],
70
+ "default": {
71
+ "live": "/health/live",
72
+ "ready": "/health/ready"
73
+ },
74
+ "description": "Liveness and readiness routes (answered before ready and while draining); false registers none."
56
75
  },
57
76
  "trustProxy": {
58
77
  "type": "array",
59
- "maxItems": 64,
60
- "uniqueItems": true,
61
78
  "items": {
62
79
  "type": "string",
63
80
  "minLength": 2,
64
81
  "maxLength": 45,
65
82
  "description": "IPv4 or IPv6 address"
66
83
  },
84
+ "maxItems": 64,
85
+ "uniqueItems": true,
67
86
  "default": [],
68
87
  "description": "Proxy addresses whose X-Forwarded-Host/For/Proto are trusted, e.g. [127.0.0.1, ::1] for a local tunnel"
69
88
  },
@@ -76,14 +95,31 @@
76
95
  },
77
96
  "sealExclude": {
78
97
  "type": "array",
79
- "maxItems": 64,
80
- "uniqueItems": true,
81
98
  "items": {
82
99
  "type": "string",
83
- "pattern": "^/[^?#\\s]{0,2047}$"
100
+ "pattern": "^\\/[^?#\\s]{0,2047}$"
84
101
  },
102
+ "maxItems": 64,
103
+ "uniqueItems": true,
85
104
  "default": [],
86
105
  "description": "Seal hosts (D-0062): path prefixes that stay plain (webhooks, server-to-server), matched at a / boundary"
106
+ },
107
+ "formBody": {
108
+ "type": "boolean",
109
+ "default": false,
110
+ "description": "Parse HTML form bodies (application/x-www-form-urlencoded) into request.body (D-0068). Off: such a request gets 415 FORM_BODY_DISABLED. Seal hosts still refuse them (415 SEAL_REQUIRED)"
111
+ },
112
+ "formMaxFields": {
113
+ "type": "integer",
114
+ "minimum": 1,
115
+ "maximum": 10000,
116
+ "default": 1000,
117
+ "description": "Most fields one form body may carry; more is 413 FORM_BODY_TOO_MANY_FIELDS (maxBodyBytes also applies)"
118
+ },
119
+ "developmentErrors": {
120
+ "type": "boolean",
121
+ "default": true,
122
+ "description": "Outside production (NODE_ENV is not production) error bodies also carry fix and details (D-0063). false: never, as in production. hint and data are always sent."
87
123
  }
88
124
  }
89
125
  }
package/package.json CHANGED
@@ -1,6 +1,14 @@
1
1
  {
2
2
  "name": "@dokebi/web",
3
- "version": "0.2.0",
3
+ "version": "0.4.0",
4
+ "description": "Fastify 5 HTTP server owned by a Dokebi app: 503 before ready, health routes, drain and cluster handover.",
5
+ "keywords": [
6
+ "dokebi",
7
+ "dokebi-plugin",
8
+ "web",
9
+ "http",
10
+ "fastify"
11
+ ],
4
12
  "private": false,
5
13
  "type": "module",
6
14
  "license": "MIT",
@@ -10,6 +18,14 @@
10
18
  ".": {
11
19
  "types": "./dist/index.d.ts",
12
20
  "import": "./dist/index.js"
21
+ },
22
+ "./points": {
23
+ "types": "./dist/points.d.ts",
24
+ "import": "./dist/points.js"
25
+ },
26
+ "./dependency": {
27
+ "types": "./dist/dependency.d.ts",
28
+ "import": "./dist/dependency.js"
13
29
  }
14
30
  },
15
31
  "files": [
@@ -24,36 +40,50 @@
24
40
  "node": ">=24.0.0"
25
41
  },
26
42
  "scripts": {
27
- "build": "tsc -p tsconfig.json",
43
+ "build": "tsc -p tsconfig.json && node -e \"import('./dist/options.js').then(async (m) => { const { renderOptionsSchema } = await import('@dokebi/core'); process.stdout.write(renderOptionsSchema(m.options)); })\" > options.schema.json",
28
44
  "typecheck": "tsc -p tsconfig.test.json --noEmit",
29
- "test": "tsc -p tsconfig.test.json && node --test .tmp/tests/tests/*.test.js"
45
+ "test": "node -e \"require('node:fs').rmSync('.tmp/tests',{recursive:true,force:true})\" && tsc -p tsconfig.test.json && node --test .tmp/tests/tests/*.test.js"
30
46
  },
31
47
  "peerDependencies": {
32
- "@dokebi/core": "^0.2.0"
48
+ "@dokebi/core": "^0.4.0"
33
49
  },
34
50
  "devDependencies": {
35
- "@dokebi/health": "0.1.2"
51
+ "@dokebi/health": "0.4.0"
36
52
  },
37
53
  "dokebi": {
38
54
  "schemaVersion": 2,
39
55
  "id": "dokebi-web",
40
- "core": "^0.2.0",
56
+ "core": "^0.4.0",
41
57
  "dependencies": [
42
58
  {
43
59
  "name": "dokebi-health",
44
- "version": "^0.1.0",
60
+ "version": "^0.4.0",
45
61
  "optional": true
46
62
  }
47
63
  ],
48
- "install": {
49
- "entry": {
50
- "source": "templates/web.ts",
51
- "target": "src/infra/web/requires.ts"
52
- }
53
- },
64
+ "contributes": [
65
+ "dokebi-testing:inject"
66
+ ],
67
+ "installModule": "dist/install.js",
54
68
  "optionsSchema": "options.schema.json",
55
69
  "documentation": "AI.md"
56
70
  },
71
+ "dokebiCatalog": {
72
+ "kind": "plugin",
73
+ "summary": "Fastify 5 HTTP server (503 before ready, health paths, drain, zero-downtime cluster replacement)",
74
+ "maturity": "preview",
75
+ "provides": [
76
+ "web.http"
77
+ ],
78
+ "doesNot": [
79
+ "No built-in authentication, rate limit, CORS or security headers",
80
+ "No file upload (multipart)"
81
+ ],
82
+ "recipes": [
83
+ "api",
84
+ "blog"
85
+ ]
86
+ },
57
87
  "dependencies": {
58
88
  "fastify": "5.12.7"
59
89
  },
@@ -0,0 +1,14 @@
1
+ // dokebi-web entry file (src/infra/web/extension.ts): user code. Left as it is, it keeps the
2
+ // default behavior (D-0064).
3
+ //
4
+ // requires: Dokebi plugins (instances or dependency descriptors) that a Fastify onClose hook
5
+ // still uses, so they are cleaned up after the web server has closed. Most projects leave it empty.
6
+ //
7
+ // AppWeb: the only hooks you can change are fastifyOptions(defaults), errorBody(error, context)
8
+ // and unavailable(context). Override only what you need with `protected override`. Do not add
9
+ // constructor arguments. Left empty, it adds no cost per request.
10
+ import { WebExtension } from '@dokebi/web';
11
+
12
+ export const requires = [] as const;
13
+
14
+ export default class AppWeb extends WebExtension {}