tr-apisrv 2.1.0 → 3.1.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/CHANGELOG.md +22 -0
- package/README.md +173 -2
- package/index.js +330 -65
- package/package.json +1 -1
- package/test/test.js +639 -0
package/CHANGELOG.md
ADDED
|
@@ -0,0 +1,22 @@
|
|
|
1
|
+
Changelog
|
|
2
|
+
=========
|
|
3
|
+
|
|
4
|
+
3.1.0
|
|
5
|
+
-----
|
|
6
|
+
|
|
7
|
+
Tested on Node.js 18, 20, 22, 24 and 26.
|
|
8
|
+
|
|
9
|
+
### Changed behaviour
|
|
10
|
+
|
|
11
|
+
- `maxBodySize: 0` now allows only empty bodies, as documented.
|
|
12
|
+
Before, 0 disabled the limit.
|
|
13
|
+
|
|
14
|
+
### Fixed
|
|
15
|
+
|
|
16
|
+
- A request rejected because of its body (413 too large, 400 longer
|
|
17
|
+
than Content-Length) had its connection destroyed right after the
|
|
18
|
+
response was queued, so clients could get a reset instead of the
|
|
19
|
+
response (seen on Node 20 and 22). The response is now sent with
|
|
20
|
+
`Connection: close` and the connection is closed only after it has
|
|
21
|
+
been written. If an `errorCallback` takes over and never responds,
|
|
22
|
+
the connection is closed after `bodyReadTimeoutMs`.
|
package/README.md
CHANGED
|
@@ -77,6 +77,10 @@ request, `tr-apisrv` returns a canonical JSON error such as
|
|
|
77
77
|
| `rejectDangerousPaths` | boolean | `true` | Reject paths containing empty, `.` or `..` segments with HTTP 400. |
|
|
78
78
|
| `bodyReadTimeoutMs` | number | `2000` | Milliseconds allowed to fully read the request body. Applies to upgrade as well. |
|
|
79
79
|
| `maxBodySize` | number | `1048576` | Maximum allowed request body size in bytes. `0` allows only empty bodies. |
|
|
80
|
+
| `errorCallback` | function | `undefined` | Called for every error response the server generates itself, so that the application can send its own. See [Custom error responses](#custom-error-responses). |
|
|
81
|
+
| `pathRewrite` | function | `undefined` | `(path) => path`, applied to the request path before handlers are matched. See [Path rewriting](#path-rewriting). |
|
|
82
|
+
| `requireObjectBody` | boolean | `false` | When true, a JSON body that is an array is rejected with HTTP 400. |
|
|
83
|
+
| `rejectDangerousParamNames` | boolean | `false` | When true, a request whose body or query string has a key named `__proto__`, `constructor` or `prototype`, at any depth, is rejected with HTTP 400. |
|
|
80
84
|
| `debug` | boolean | `false` | Enables verbose logging for authentication failures and handler completion. |
|
|
81
85
|
|
|
82
86
|
The server accepts only `GET`, `POST`, `PUT`, and `DELETE` requests. Other
|
|
@@ -145,6 +149,8 @@ return an object.
|
|
|
145
149
|
| `bodyParamsValidator` | Validates and can transform `request.bodyParams`. |
|
|
146
150
|
| `paramsValidator` | Validates the merged `request.params` object. |
|
|
147
151
|
| `ignoreUrlParams` | When `true`, the query string is ignored and `request.urlParams` is left `undefined`. |
|
|
152
|
+
| `authCallback` | Authentication for this handler only. Runs after the server's `authCallback` has accepted the request and, like it, before any parameters are parsed. Return truthy to continue; when returning falsy, send the response yourself. |
|
|
153
|
+
| `meta` | Any value you want to attach to the handler, for example a name or the scopes it needs. Available as `request.handler.meta` and from `requestHandlerList()`. |
|
|
148
154
|
|
|
149
155
|
#### Validator example
|
|
150
156
|
|
|
@@ -172,6 +178,25 @@ server.requestHandleAdd('POST', '/import', importHandler, {
|
|
|
172
178
|
You can supply the same `options` when adding handlers at runtime with
|
|
173
179
|
`requestHandleAdd(method, path, callback, options)`.
|
|
174
180
|
|
|
181
|
+
#### Per-handler authentication and metadata
|
|
182
|
+
|
|
183
|
+
```javascript
|
|
184
|
+
server.requestHandleAdd('POST', '/admin/users', createUser, {
|
|
185
|
+
meta: { name: 'create-user', scope: 'admin' },
|
|
186
|
+
authCallback: async (request) => {
|
|
187
|
+
if (await tokenHasScope(request.headers.authorization, request.handler.meta.scope)) {
|
|
188
|
+
return true;
|
|
189
|
+
}
|
|
190
|
+
request.jsonResponse({ code: 403, message: 'Forbidden' }, 403);
|
|
191
|
+
return false;
|
|
192
|
+
}
|
|
193
|
+
});
|
|
194
|
+
```
|
|
195
|
+
|
|
196
|
+
`request.handler` is `{ method, path, meta }` for a request matched by
|
|
197
|
+
`requestHandlers`, where `path` is the template that matched. It is
|
|
198
|
+
`undefined` when the fallback `callback` serves the request.
|
|
199
|
+
|
|
175
200
|
### Runtime updates
|
|
176
201
|
|
|
177
202
|
Handlers may be added, replaced, or removed without restarting the process:
|
|
@@ -189,6 +214,16 @@ server.requestHandleDelete('POST', '/status');
|
|
|
189
214
|
server.requestHandleDelete('*', '/status');
|
|
190
215
|
```
|
|
191
216
|
|
|
217
|
+
`requestHandlerList()` returns the registered handlers as
|
|
218
|
+
`{ method, path, meta }` objects, which is useful for generating
|
|
219
|
+
documentation or checking that every route has what it needs:
|
|
220
|
+
|
|
221
|
+
```javascript
|
|
222
|
+
for (const { method, path, meta } of server.requestHandlerList()) {
|
|
223
|
+
console.log(method, path, meta);
|
|
224
|
+
}
|
|
225
|
+
```
|
|
226
|
+
|
|
192
227
|
## Request object
|
|
193
228
|
|
|
194
229
|
Handlers receive an object that wraps the underlying `http.IncomingMessage` and
|
|
@@ -197,7 +232,10 @@ Handlers receive an object that wraps the underlying `http.IncomingMessage` and
|
|
|
197
232
|
| Property | Description |
|
|
198
233
|
| --- | --- |
|
|
199
234
|
| `method` | Uppercase HTTP method. |
|
|
200
|
-
| `url` | Request path without the query string. |
|
|
235
|
+
| `url` | Request path without the query string, after `pathRewrite` when one is configured. |
|
|
236
|
+
| `originalUrl` | Request path without the query string, as received. |
|
|
237
|
+
| `handler` | `{ method, path, meta }` of the matched `requestHandlers` entry, or `undefined` for the fallback `callback`. |
|
|
238
|
+
| `requestPayloadBuffer` | The request body as received, as a `Buffer`. |
|
|
201
239
|
| `req` | The raw `http.IncomingMessage`. |
|
|
202
240
|
| `res` | The raw `http.ServerResponse`. |
|
|
203
241
|
| `headers` | Request headers as received. |
|
|
@@ -224,9 +262,34 @@ path. Later sources override earlier ones in `request.params`. When this occurs,
|
|
|
224
262
|
`application/x-www-form-urlencoded`. Other types result in
|
|
225
263
|
`400 Bad Request (POST or PUT body must be in JSON or www-form-urlencoded format.)`.
|
|
226
264
|
* `GET` and `DELETE` requests must not include a body.
|
|
227
|
-
* Bodies larger than `maxBodySize` yield `413 Payload Too Large
|
|
265
|
+
* Bodies larger than `maxBodySize` yield `413 Payload Too Large`; with
|
|
266
|
+
`maxBodySize: 0` any non-empty body does. The response to a rejected
|
|
267
|
+
body is sent with `Connection: close` and the connection is closed
|
|
268
|
+
after it.
|
|
228
269
|
* Slow clients that exceed `bodyReadTimeoutMs` cause `408 Request Timeout`.
|
|
229
270
|
|
|
271
|
+
## Path rewriting
|
|
272
|
+
|
|
273
|
+
`pathRewrite` receives the request path (without the query string) and returns
|
|
274
|
+
the path to use for matching handlers. Return `undefined` to keep the path as
|
|
275
|
+
it is. It is the place to strip a deployment prefix, so that one handler table
|
|
276
|
+
serves the same routes under several mount points:
|
|
277
|
+
|
|
278
|
+
```javascript
|
|
279
|
+
const server = new ApiSrv({
|
|
280
|
+
port: 8808,
|
|
281
|
+
// /api/v1/users, /v1/users and /users all reach the '/users' handler
|
|
282
|
+
pathRewrite: (path) => path.replace(/^\/(api\/)?(v1\/)?/, '/'),
|
|
283
|
+
requestHandlers: { GET: { '/users': listUsers } }
|
|
284
|
+
});
|
|
285
|
+
```
|
|
286
|
+
|
|
287
|
+
The function must be synchronous and must return a string that starts with
|
|
288
|
+
`/`; anything else, or a thrown error, results in HTTP 500. The dangerous path
|
|
289
|
+
check applies both to the path as received and to the rewritten one.
|
|
290
|
+
`request.url` holds the rewritten path and `request.originalUrl` the original.
|
|
291
|
+
Upgrade requests are rewritten in the same way.
|
|
292
|
+
|
|
230
293
|
## Authentication and upgrades
|
|
231
294
|
|
|
232
295
|
Before a handler runs, `authCallback` is awaited with the request object. During
|
|
@@ -254,6 +317,65 @@ status text in the `message` property, for example:
|
|
|
254
317
|
Additional context is appended in parentheses for 400-series validation errors,
|
|
255
318
|
matching the format `"Bad Request (detailed reason)"`.
|
|
256
319
|
|
|
320
|
+
### Custom error responses
|
|
321
|
+
|
|
322
|
+
Set `errorCallback` to answer these errors in your own format. It is called
|
|
323
|
+
with one object for every error response that `tr-apisrv` generates itself:
|
|
324
|
+
|
|
325
|
+
| Property | Description |
|
|
326
|
+
| --- | --- |
|
|
327
|
+
| `code` | The HTTP status the server would answer with. |
|
|
328
|
+
| `message` | The message of the default response, e.g. `Bad Request (detailed reason)`. |
|
|
329
|
+
| `detail` | The detail alone, when there is one. |
|
|
330
|
+
| `source` | What produced the error: `request` (malformed request, dangerous path, unsupported method), `limit` (body too large, read timeout), `parser` (unparsable or unacceptable body or parameters), `validator` (a parameter validator threw or returned a non-object), `router` (no handler: 404 or 405, or a failing `pathRewrite`), `handler` (the handler threw). |
|
|
331
|
+
| `stage` | For `validator`: which validator, e.g. `request parameters`. |
|
|
332
|
+
| `cause` | For `validator` and `handler`: the error that was thrown. A validator can attach anything to it, such as a list of problems. |
|
|
333
|
+
| `req`, `res` | The raw request and response. |
|
|
334
|
+
| `request` | The request wrapper. Depending on how far the request got, some of its properties are not set yet. |
|
|
335
|
+
|
|
336
|
+
Send the response and return a truthy value. Return a falsy value to let the
|
|
337
|
+
server send its default response; it does that too when the callback throws
|
|
338
|
+
or leaves the response unsent.
|
|
339
|
+
|
|
340
|
+
```javascript
|
|
341
|
+
const server = new ApiSrv({
|
|
342
|
+
port: 8808,
|
|
343
|
+
errorCallback: (error) => {
|
|
344
|
+
const body = { status: 'error', code: error.code, message: error.message };
|
|
345
|
+
if (error.source === 'validator' && error.cause && error.cause.problems) {
|
|
346
|
+
body.problems = error.cause.problems;
|
|
347
|
+
}
|
|
348
|
+
error.res.writeHead(error.code, { 'Content-Type': 'application/json; charset=utf-8' });
|
|
349
|
+
error.res.end(JSON.stringify(body));
|
|
350
|
+
return true;
|
|
351
|
+
},
|
|
352
|
+
requestHandlers: {
|
|
353
|
+
POST: {
|
|
354
|
+
'/items': {
|
|
355
|
+
callback: createItem,
|
|
356
|
+
options: {
|
|
357
|
+
paramsValidator: (params) => {
|
|
358
|
+
const problems = checkItem(params);
|
|
359
|
+
if (problems.length > 0) {
|
|
360
|
+
const err = new Error('Invalid item');
|
|
361
|
+
err.problems = problems;
|
|
362
|
+
throw err;
|
|
363
|
+
}
|
|
364
|
+
return params;
|
|
365
|
+
}
|
|
366
|
+
}
|
|
367
|
+
}
|
|
368
|
+
}
|
|
369
|
+
}
|
|
370
|
+
});
|
|
371
|
+
```
|
|
372
|
+
|
|
373
|
+
The callback may be asynchronous. For errors raised while the request is still
|
|
374
|
+
being read (`limit`, and some of `request`) the connection is closed right
|
|
375
|
+
after the error, so respond synchronously for those. Responses that a handler
|
|
376
|
+
sends with `request.errorResponse()` or `request.jsonResponse()` do not go
|
|
377
|
+
through the callback.
|
|
378
|
+
|
|
257
379
|
Handlers remain free to craft any response, including non-JSON payloads, by using
|
|
258
380
|
`request.res` directly. The convenience method `jsonResponse` is suitable for
|
|
259
381
|
most use cases:
|
|
@@ -279,6 +401,55 @@ const srv = new ApiSrv({
|
|
|
279
401
|
});
|
|
280
402
|
```
|
|
281
403
|
|
|
404
|
+
### Parameter names
|
|
405
|
+
|
|
406
|
+
A parameter named `__proto__` is an ordinary own property of
|
|
407
|
+
`request.params`; it never replaces the prototype of the object. A JSON body
|
|
408
|
+
can nevertheless carry keys such as `__proto__` or `constructor` at any depth,
|
|
409
|
+
and code that later copies such objects with `Object.assign` or a recursive
|
|
410
|
+
merge can be tricked by them. If your API has no use for those names, reject
|
|
411
|
+
them outright:
|
|
412
|
+
|
|
413
|
+
```javascript
|
|
414
|
+
const srv = new ApiSrv({
|
|
415
|
+
port: 8808,
|
|
416
|
+
rejectDangerousParamNames: true, // 400 for __proto__, constructor, prototype keys
|
|
417
|
+
requireObjectBody: true, // 400 for a JSON array as the body
|
|
418
|
+
callback: handler
|
|
419
|
+
});
|
|
420
|
+
```
|
|
421
|
+
|
|
422
|
+
Without `requireObjectBody`, the items of a JSON array body become the
|
|
423
|
+
parameters `"0"`, `"1"` and so on.
|
|
424
|
+
|
|
425
|
+
### Response headers
|
|
426
|
+
|
|
427
|
+
JSON responses, including errors, carry `X-Content-Type-Options: nosniff`.
|
|
428
|
+
|
|
429
|
+
## Changes in 3.0.0
|
|
430
|
+
|
|
431
|
+
Version 3.0.0 is backwards compatible with 2.1.0: every existing option,
|
|
432
|
+
method and default behaves as before. New:
|
|
433
|
+
|
|
434
|
+
* `errorCallback`, for answering server-generated errors in your own format.
|
|
435
|
+
* `pathRewrite`, and `request.originalUrl`.
|
|
436
|
+
* Handler options `authCallback` and `meta`, and `request.handler`.
|
|
437
|
+
* `requestHandlerList()`.
|
|
438
|
+
* `requireObjectBody` and `rejectDangerousParamNames`.
|
|
439
|
+
|
|
440
|
+
Fixes and hardening that apply without any configuration:
|
|
441
|
+
|
|
442
|
+
* A parameter named `__proto__` in a JSON body used to become the prototype of
|
|
443
|
+
`request.params`, so that its contents appeared as parameters that were not
|
|
444
|
+
own properties. It is now an own property like any other.
|
|
445
|
+
* `__proto__` is rejected as a path template parameter name.
|
|
446
|
+
* A request target that is not a path (for example an absolute URL, when
|
|
447
|
+
`rejectDangerousPaths` is off) matched against `requestHandlers` used to
|
|
448
|
+
end in HTTP 500. It now matches nothing: 404, or the fallback `callback`.
|
|
449
|
+
* JSON responses carry `X-Content-Type-Options: nosniff`.
|
|
450
|
+
* The request body is assembled once instead of being copied for every chunk
|
|
451
|
+
received.
|
|
452
|
+
|
|
282
453
|
## License
|
|
283
454
|
|
|
284
455
|
MIT
|