@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/AI.md +189 -51
- package/README.md +49 -47
- package/dist/compilers.d.ts +9 -0
- package/dist/compilers.js +58 -0
- package/dist/dependency.d.ts +4 -0
- package/dist/dependency.js +14 -0
- package/dist/errors.d.ts +40 -0
- package/dist/errors.js +106 -0
- package/dist/extension.d.ts +95 -0
- package/dist/extension.js +52 -0
- package/dist/index.d.ts +22 -6
- package/dist/index.js +725 -306
- package/dist/install.d.ts +25 -0
- package/dist/install.js +23 -0
- package/dist/options.d.ts +19 -0
- package/dist/options.js +92 -0
- package/dist/points.d.ts +53 -0
- package/dist/points.js +5 -0
- package/dist/responses.d.ts +80 -0
- package/dist/responses.js +246 -0
- package/dist/seal.d.ts +10 -9
- package/dist/seal.js +23 -53
- package/options.schema.json +53 -17
- package/package.json +43 -13
- package/templates/extension.ts +14 -0
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
|
-
/**
|
|
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
|
|
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
|
|
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
|
|
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
|
|
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
|
|
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
|
-
/**
|
|
194
|
-
|
|
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
|
|
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
|
|
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
|
|
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
|
|
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:
|
|
265
|
+
error: diagnostics.describeError(error),
|
|
296
266
|
...(repeated ? { repeated } : {}),
|
|
297
267
|
});
|
|
298
268
|
reply.code(500).header('content-type', 'application/json; charset=utf-8');
|
package/options.schema.json
CHANGED
|
@@ -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
|
-
"
|
|
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
|
-
"
|
|
45
|
+
"deprecated": true,
|
|
46
|
+
"description": "Deprecated name of requestTimeoutMs; use that key."
|
|
29
47
|
},
|
|
30
48
|
"healthRoutes": {
|
|
31
|
-
"
|
|
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": "
|
|
59
|
+
"pattern": "^\\/[^?#\\s]{0,2047}$",
|
|
46
60
|
"default": "/health/live"
|
|
47
61
|
},
|
|
48
62
|
"ready": {
|
|
49
63
|
"type": "string",
|
|
50
|
-
"pattern": "
|
|
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": "
|
|
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.
|
|
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.
|
|
48
|
+
"@dokebi/core": "^0.4.0"
|
|
33
49
|
},
|
|
34
50
|
"devDependencies": {
|
|
35
|
-
"@dokebi/health": "0.
|
|
51
|
+
"@dokebi/health": "0.4.0"
|
|
36
52
|
},
|
|
37
53
|
"dokebi": {
|
|
38
54
|
"schemaVersion": 2,
|
|
39
55
|
"id": "dokebi-web",
|
|
40
|
-
"core": "^0.
|
|
56
|
+
"core": "^0.4.0",
|
|
41
57
|
"dependencies": [
|
|
42
58
|
{
|
|
43
59
|
"name": "dokebi-health",
|
|
44
|
-
"version": "^0.
|
|
60
|
+
"version": "^0.4.0",
|
|
45
61
|
"optional": true
|
|
46
62
|
}
|
|
47
63
|
],
|
|
48
|
-
"
|
|
49
|
-
"
|
|
50
|
-
|
|
51
|
-
|
|
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 {}
|