tr-apisrv 1.0.0 → 3.0.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/README.md +416 -62
- package/index.js +974 -91
- package/package.json +1 -1
- package/test/test.js +1570 -10
package/README.md
CHANGED
|
@@ -1,98 +1,452 @@
|
|
|
1
|
-
API Server
|
|
2
|
-
==========
|
|
1
|
+
# API Server
|
|
3
2
|
|
|
4
|
-
|
|
5
|
-
|
|
6
|
-
|
|
3
|
+
`tr-apisrv` is a lightweight JSON-oriented HTTP(S) server that focuses on fast
|
|
4
|
+
configuration and predictable request handling rules. It supports declarative
|
|
5
|
+
handler registration, request parameter validation, and pluggable
|
|
6
|
+
authentication, making it easy to bootstrap small services or mock APIs.
|
|
7
7
|
|
|
8
|
-
Requires Node.js 18 or newer
|
|
8
|
+
Requires **Node.js 18 or newer**.
|
|
9
9
|
|
|
10
|
+
## Installation
|
|
11
|
+
|
|
12
|
+
```bash
|
|
13
|
+
npm install tr-apisrv
|
|
10
14
|
```
|
|
15
|
+
|
|
16
|
+
## Quick start
|
|
17
|
+
|
|
18
|
+
```javascript
|
|
11
19
|
const ApiSrv = require('tr-apisrv');
|
|
12
20
|
|
|
13
|
-
|
|
14
|
-
|
|
15
|
-
|
|
16
|
-
|
|
17
|
-
prettyPrintJsonResponses: true,
|
|
18
|
-
bodyReadTimeoutMs: 5000,
|
|
19
|
-
maxBodySize: 1024 * 1024,
|
|
20
|
-
debug: true });
|
|
21
|
+
async function authenticate(request) {
|
|
22
|
+
// return false to reject the request
|
|
23
|
+
return request.headers.authorization === 'Bearer secret-token';
|
|
24
|
+
}
|
|
21
25
|
|
|
22
|
-
async function
|
|
23
|
-
|
|
26
|
+
async function listUsers(request) {
|
|
27
|
+
// Access individual parameter sources or the merged view
|
|
28
|
+
return request.jsonResponse({
|
|
29
|
+
params: request.params,
|
|
30
|
+
path: request.pathParams,
|
|
31
|
+
query: request.urlParams,
|
|
32
|
+
body: request.bodyParams
|
|
33
|
+
});
|
|
24
34
|
}
|
|
25
35
|
|
|
26
|
-
async function
|
|
27
|
-
|
|
36
|
+
async function fallback(request) {
|
|
37
|
+
return request.jsonResponse({ message: 'Fallback handler invoked' });
|
|
28
38
|
}
|
|
39
|
+
|
|
40
|
+
const server = new ApiSrv({
|
|
41
|
+
port: 8808,
|
|
42
|
+
address: '127.0.0.1',
|
|
43
|
+
authCallback: authenticate,
|
|
44
|
+
callback: fallback,
|
|
45
|
+
requestHandlers: {
|
|
46
|
+
GET: {
|
|
47
|
+
'/users': listUsers,
|
|
48
|
+
'/users/{userId}': listUsers,
|
|
49
|
+
'/files/[path]': {
|
|
50
|
+
callback: listUsers,
|
|
51
|
+
options: {
|
|
52
|
+
paramsValidator: (params) => ({ ...params, validated: true })
|
|
53
|
+
}
|
|
54
|
+
}
|
|
55
|
+
}
|
|
56
|
+
}
|
|
57
|
+
});
|
|
29
58
|
```
|
|
30
59
|
|
|
31
|
-
|
|
32
|
-
|
|
60
|
+
Requests are matched against `requestHandlers` first. When no handler matches,
|
|
61
|
+
the optional top-level `callback` is used as a fallback. If neither resolves the
|
|
62
|
+
request, `tr-apisrv` returns a canonical JSON error such as
|
|
63
|
+
`{"code":404,"message":"Not Found"}`.
|
|
64
|
+
|
|
65
|
+
## Configuration reference
|
|
66
|
+
|
|
67
|
+
| Option | Type | Default | Description |
|
|
68
|
+
| --- | --- | --- | --- |
|
|
69
|
+
| `port` | number | **required** | TCP port to listen on (1–65535). |
|
|
70
|
+
| `address` | string | `undefined` | Local address to bind. Leave undefined to listen on all interfaces. |
|
|
71
|
+
| `key` / `cert` | string | Buffer | `undefined` | Provide both to enable HTTPS. Supplying only one throws an error. |
|
|
72
|
+
| `callback` | function | `undefined` | Fallback handler when no `requestHandlers` entry matches. |
|
|
73
|
+
| `requestHandlers` | object | `undefined` | Declarative handler map, keyed by HTTP method. Details below. |
|
|
74
|
+
| `authCallback` | function | `() => true` | Runs before any parameters are parsed. Return truthy to continue; falsy lets you reject (e.g. send 401). Parameter fields are `undefined` during this callback. |
|
|
75
|
+
| `upgradeCallback` | function | `undefined` | Optional `upgrade` (e.g. WebSocket) handler invoked after authentication. |
|
|
76
|
+
| `prettyPrintJsonResponses` | boolean | `false` | When true, `jsonResponse` pretty-prints JSON with trailing newline. |
|
|
77
|
+
| `rejectDangerousPaths` | boolean | `true` | Reject paths containing empty, `.` or `..` segments with HTTP 400. |
|
|
78
|
+
| `bodyReadTimeoutMs` | number | `2000` | Milliseconds allowed to fully read the request body. Applies to upgrade as well. |
|
|
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. |
|
|
84
|
+
| `debug` | boolean | `false` | Enables verbose logging for authentication failures and handler completion. |
|
|
85
|
+
|
|
86
|
+
The server accepts only `GET`, `POST`, `PUT`, and `DELETE` requests. Other
|
|
87
|
+
methods receive `405 Method Not Allowed`.
|
|
88
|
+
|
|
89
|
+
## Request handler definitions
|
|
90
|
+
|
|
91
|
+
Each HTTP method in `requestHandlers` maps path templates to either a callback
|
|
92
|
+
function or an object of the shape `{ callback, options }`. Callbacks receive the
|
|
93
|
+
request wrapper described in [Request object](#request-object).
|
|
94
|
+
|
|
95
|
+
### Resolution order
|
|
96
|
+
|
|
97
|
+
1. Match the request method and path against `requestHandlers`.
|
|
98
|
+
2. If no handler matches and a top-level `callback` exists, it handles the request.
|
|
99
|
+
3. When neither resolves the request, `tr-apisrv` returns a JSON error. A `405 Method Not Allowed`
|
|
100
|
+
response is used when another method is registered for the same path; otherwise
|
|
101
|
+
the response is `404 Not Found`.
|
|
102
|
+
|
|
103
|
+
### Path templates
|
|
104
|
+
|
|
105
|
+
Path templates determine which requests reach a handler and how parameters are
|
|
106
|
+
extracted. All templates must start with `/`.
|
|
107
|
+
Method keys in `requestHandlers` should be uppercase (`GET`, `POST`, `PUT`, `DELETE`).
|
|
108
|
+
|
|
109
|
+
* **Literal segments** – `/users/list` matches exactly that path.
|
|
110
|
+
* **Single-segment captures** – `{name}` captures one path component and makes it
|
|
111
|
+
available as a string. Capture names must match the regular expression
|
|
112
|
+
`/^[A-Za-z_][A-Za-z0-9_]*$/`. Example: `/users/{userId}` matches `/users/123`
|
|
113
|
+
and sets `request.pathParams.userId === '123'`.
|
|
114
|
+
* **Multi-segment captures** – `[name]` captures one or more consecutive
|
|
115
|
+
segments and exposes them as an array of strings. Names follow the same
|
|
116
|
+
pattern restriction as `{name}`. Arrays match 1–32 segments by default, and
|
|
117
|
+
you can provide explicit bounds with `[name:min]` (exact length) or
|
|
118
|
+
`[name:min:max]` (inclusive range). Examples:
|
|
119
|
+
* `/example/path/[MyArray]` matches 1 to 32 segments.
|
|
120
|
+
* `/example/path/[MyArray:4]` matches exactly four segments.
|
|
121
|
+
* `/example/path/[MyArray:2:12]` matches two to twelve segments.
|
|
122
|
+
* `/example/path/[MyArray:10:50]` matches ten to fifty segments, allowing
|
|
123
|
+
larger maxima than the default. The upper bound is always finite—either the
|
|
124
|
+
default 32 or the explicit maximum you declare.
|
|
125
|
+
* Captures can be combined with literals, e.g. `/{cmd}/[args]/{tail}`. When
|
|
126
|
+
combined, `[args]` consumes all necessary segments so the remaining template
|
|
127
|
+
still matches.
|
|
128
|
+
|
|
129
|
+
Trailing slashes are significant only when they appear in the template:
|
|
130
|
+
|
|
131
|
+
* `/users/` matches `/users/` but not `/users`.
|
|
132
|
+
* `/users` matches both `/users` and `/users/`.
|
|
133
|
+
|
|
134
|
+
All captured values are URL-decoded. If decoding fails, the request is rejected
|
|
135
|
+
with HTTP 400.
|
|
136
|
+
|
|
137
|
+
### Handler options
|
|
33
138
|
|
|
34
|
-
|
|
35
|
-
|
|
139
|
+
`options` fine-tune validation and query-string handling. Every option is
|
|
140
|
+
optional; validators may be synchronous or asynchronous and must return the
|
|
141
|
+
processed object. Throwing from a validator results in `400 Bad Request`. Returning
|
|
142
|
+
anything other than an object causes a `500` response noting the validator must
|
|
143
|
+
return an object.
|
|
144
|
+
|
|
145
|
+
| Option | Description |
|
|
146
|
+
| --- | --- |
|
|
147
|
+
| `pathParamsValidator` | Validates and can transform `request.pathParams`. |
|
|
148
|
+
| `urlParamsValidator` | Validates and can transform `request.urlParams`. Not called when `ignoreUrlParams` is `true`. |
|
|
149
|
+
| `bodyParamsValidator` | Validates and can transform `request.bodyParams`. |
|
|
150
|
+
| `paramsValidator` | Validates the merged `request.params` object. |
|
|
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()`. |
|
|
154
|
+
|
|
155
|
+
#### Validator example
|
|
36
156
|
|
|
37
157
|
```javascript
|
|
38
|
-
|
|
39
|
-
|
|
40
|
-
|
|
41
|
-
|
|
42
|
-
|
|
43
|
-
|
|
44
|
-
|
|
45
|
-
|
|
46
|
-
|
|
158
|
+
server.requestHandleAdd('GET', '/reports/{id}', fetchReport, {
|
|
159
|
+
pathParamsValidator: (params) => ({ id: Number(params.id) }),
|
|
160
|
+
urlParamsValidator: async (query) => ({ ...query, limit: Number(query.limit ?? 10) }),
|
|
161
|
+
paramsValidator: (params) => ({ ...params, filtered: true })
|
|
162
|
+
});
|
|
163
|
+
```
|
|
164
|
+
|
|
165
|
+
Validators can perform type coercion or enforce business rules before the
|
|
166
|
+
handler runs. Throwing inside any validator (including asynchronous ones)
|
|
167
|
+
returns `400 Bad Request` with the error message appended in parentheses.
|
|
168
|
+
|
|
169
|
+
Use `ignoreUrlParams` to opt out of query-string parsing entirely:
|
|
170
|
+
|
|
171
|
+
```javascript
|
|
172
|
+
server.requestHandleAdd('POST', '/import', importHandler, {
|
|
173
|
+
ignoreUrlParams: true,
|
|
174
|
+
bodyParamsValidator: validateImportPayload
|
|
175
|
+
});
|
|
176
|
+
```
|
|
177
|
+
|
|
178
|
+
You can supply the same `options` when adding handlers at runtime with
|
|
179
|
+
`requestHandleAdd(method, path, callback, options)`.
|
|
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;
|
|
47
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
|
+
|
|
200
|
+
### Runtime updates
|
|
201
|
+
|
|
202
|
+
Handlers may be added, replaced, or removed without restarting the process:
|
|
203
|
+
|
|
204
|
+
```javascript
|
|
205
|
+
server.requestHandleAdd('GET', '/status', statusHandler);
|
|
206
|
+
server.requestHandleAdd('POST', '/status', statusHandler, {
|
|
207
|
+
bodyParamsValidator: (body) => ({ ...body, updatedAt: Date.now() })
|
|
208
|
+
});
|
|
209
|
+
|
|
210
|
+
// Remove a single method
|
|
211
|
+
server.requestHandleDelete('POST', '/status');
|
|
212
|
+
|
|
213
|
+
// Remove all methods for a path
|
|
214
|
+
server.requestHandleDelete('*', '/status');
|
|
215
|
+
```
|
|
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);
|
|
48
224
|
}
|
|
49
225
|
```
|
|
50
226
|
|
|
51
|
-
|
|
52
|
-
|
|
227
|
+
## Request object
|
|
228
|
+
|
|
229
|
+
Handlers receive an object that wraps the underlying `http.IncomingMessage` and
|
|
230
|
+
`http.ServerResponse`.
|
|
231
|
+
|
|
232
|
+
| Property | Description |
|
|
233
|
+
| --- | --- |
|
|
234
|
+
| `method` | Uppercase HTTP method. |
|
|
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`. |
|
|
239
|
+
| `req` | The raw `http.IncomingMessage`. |
|
|
240
|
+
| `res` | The raw `http.ServerResponse`. |
|
|
241
|
+
| `headers` | Request headers as received. |
|
|
242
|
+
| `jsonResponse(data, statusCode?, excludeNoCacheHeaders?)` | Serializes JSON responses and sets default no-cache headers unless `excludeNoCacheHeaders` is `true`. |
|
|
243
|
+
| `errorResponse(statusCode, detail?)` | Sends a JSON error using canonical HTTP status text. For `400 Bad Request`, the optional detail is appended in parentheses. |
|
|
244
|
+
| `params` | Merged view of all parameters (body < query < path precedence). |
|
|
245
|
+
| `pathParams` | Parameters parsed from the matched path template. |
|
|
246
|
+
| `urlParams` | Parsed query parameters (unless suppressed). Arrays are preserved when the query repeats a key. |
|
|
247
|
+
| `bodyParams` | Parsed request body, when provided. |
|
|
248
|
+
|
|
249
|
+
During `authCallback`, the server has not parsed any parameters. At that point
|
|
250
|
+
`request.params`, `request.pathParams`, `request.urlParams`, and
|
|
251
|
+
`request.bodyParams` are all `undefined`. They are populated only after
|
|
252
|
+
authentication succeeds and before the handler runs.
|
|
253
|
+
|
|
254
|
+
All parameter collections are plain objects (or arrays for multi-segment
|
|
255
|
+
captures). Parameters are merged in the following order: body → query string →
|
|
256
|
+
path. Later sources override earlier ones in `request.params`. When this occurs,
|
|
257
|
+
`tr-apisrv` logs a warning naming both sources.
|
|
258
|
+
|
|
259
|
+
## Body parsing and limits
|
|
260
|
+
|
|
261
|
+
* `POST` and `PUT` bodies must use `application/json` or
|
|
262
|
+
`application/x-www-form-urlencoded`. Other types result in
|
|
263
|
+
`400 Bad Request (POST or PUT body must be in JSON or www-form-urlencoded format.)`.
|
|
264
|
+
* `GET` and `DELETE` requests must not include a body.
|
|
265
|
+
* Bodies larger than `maxBodySize` yield `413 Payload Too Large`.
|
|
266
|
+
* Slow clients that exceed `bodyReadTimeoutMs` cause `408 Request Timeout`.
|
|
267
|
+
|
|
268
|
+
## Path rewriting
|
|
269
|
+
|
|
270
|
+
`pathRewrite` receives the request path (without the query string) and returns
|
|
271
|
+
the path to use for matching handlers. Return `undefined` to keep the path as
|
|
272
|
+
it is. It is the place to strip a deployment prefix, so that one handler table
|
|
273
|
+
serves the same routes under several mount points:
|
|
53
274
|
|
|
54
275
|
```javascript
|
|
55
|
-
|
|
56
|
-
|
|
57
|
-
|
|
58
|
-
|
|
59
|
-
|
|
60
|
-
|
|
61
|
-
|
|
62
|
-
|
|
276
|
+
const server = new ApiSrv({
|
|
277
|
+
port: 8808,
|
|
278
|
+
// /api/v1/users, /v1/users and /users all reach the '/users' handler
|
|
279
|
+
pathRewrite: (path) => path.replace(/^\/(api\/)?(v1\/)?/, '/'),
|
|
280
|
+
requestHandlers: { GET: { '/users': listUsers } }
|
|
281
|
+
});
|
|
282
|
+
```
|
|
283
|
+
|
|
284
|
+
The function must be synchronous and must return a string that starts with
|
|
285
|
+
`/`; anything else, or a thrown error, results in HTTP 500. The dangerous path
|
|
286
|
+
check applies both to the path as received and to the rewritten one.
|
|
287
|
+
`request.url` holds the rewritten path and `request.originalUrl` the original.
|
|
288
|
+
Upgrade requests are rewritten in the same way.
|
|
289
|
+
|
|
290
|
+
## Authentication and upgrades
|
|
291
|
+
|
|
292
|
+
Before a handler runs, `authCallback` is awaited with the request object. During
|
|
293
|
+
this phase the parameter properties remain `undefined`; they are parsed only
|
|
294
|
+
after authentication succeeds. Returning a falsy value lets you send your own
|
|
295
|
+
response (for example, `401 Unauthorized`) and skips the handler. The callback
|
|
296
|
+
can still mutate the request object, such as attaching user information for the
|
|
297
|
+
handler to consume.
|
|
298
|
+
|
|
299
|
+
When `upgradeCallback` is provided, upgrade requests (e.g. WebSocket handshakes)
|
|
300
|
+
follow the same sequence: authentication runs first with the parameter
|
|
301
|
+
properties unset. Once the callback allows the upgrade, query parameters are
|
|
302
|
+
parsed and provided alongside `req`, `s`, and `head` before invoking the upgrade
|
|
303
|
+
handler.
|
|
304
|
+
|
|
305
|
+
## Error handling
|
|
306
|
+
|
|
307
|
+
Errors generated by `tr-apisrv` itself always use JSON with canonical HTTP
|
|
308
|
+
status text in the `message` property, for example:
|
|
309
|
+
|
|
310
|
+
```json
|
|
311
|
+
{ "code": 404, "message": "Not Found" }
|
|
312
|
+
```
|
|
313
|
+
|
|
314
|
+
Additional context is appended in parentheses for 400-series validation errors,
|
|
315
|
+
matching the format `"Bad Request (detailed reason)"`.
|
|
316
|
+
|
|
317
|
+
### Custom error responses
|
|
318
|
+
|
|
319
|
+
Set `errorCallback` to answer these errors in your own format. It is called
|
|
320
|
+
with one object for every error response that `tr-apisrv` generates itself:
|
|
321
|
+
|
|
322
|
+
| Property | Description |
|
|
323
|
+
| --- | --- |
|
|
324
|
+
| `code` | The HTTP status the server would answer with. |
|
|
325
|
+
| `message` | The message of the default response, e.g. `Bad Request (detailed reason)`. |
|
|
326
|
+
| `detail` | The detail alone, when there is one. |
|
|
327
|
+
| `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). |
|
|
328
|
+
| `stage` | For `validator`: which validator, e.g. `request parameters`. |
|
|
329
|
+
| `cause` | For `validator` and `handler`: the error that was thrown. A validator can attach anything to it, such as a list of problems. |
|
|
330
|
+
| `req`, `res` | The raw request and response. |
|
|
331
|
+
| `request` | The request wrapper. Depending on how far the request got, some of its properties are not set yet. |
|
|
332
|
+
|
|
333
|
+
Send the response and return a truthy value. Return a falsy value to let the
|
|
334
|
+
server send its default response; it does that too when the callback throws
|
|
335
|
+
or leaves the response unsent.
|
|
336
|
+
|
|
337
|
+
```javascript
|
|
338
|
+
const server = new ApiSrv({
|
|
339
|
+
port: 8808,
|
|
340
|
+
errorCallback: (error) => {
|
|
341
|
+
const body = { status: 'error', code: error.code, message: error.message };
|
|
342
|
+
if (error.source === 'validator' && error.cause && error.cause.problems) {
|
|
343
|
+
body.problems = error.cause.problems;
|
|
344
|
+
}
|
|
345
|
+
error.res.writeHead(error.code, { 'Content-Type': 'application/json; charset=utf-8' });
|
|
346
|
+
error.res.end(JSON.stringify(body));
|
|
347
|
+
return true;
|
|
348
|
+
},
|
|
349
|
+
requestHandlers: {
|
|
350
|
+
POST: {
|
|
351
|
+
'/items': {
|
|
352
|
+
callback: createItem,
|
|
353
|
+
options: {
|
|
354
|
+
paramsValidator: (params) => {
|
|
355
|
+
const problems = checkItem(params);
|
|
356
|
+
if (problems.length > 0) {
|
|
357
|
+
const err = new Error('Invalid item');
|
|
358
|
+
err.problems = problems;
|
|
359
|
+
throw err;
|
|
360
|
+
}
|
|
361
|
+
return params;
|
|
362
|
+
}
|
|
63
363
|
}
|
|
364
|
+
}
|
|
64
365
|
}
|
|
65
|
-
}
|
|
366
|
+
}
|
|
367
|
+
});
|
|
66
368
|
```
|
|
67
369
|
|
|
68
|
-
|
|
69
|
-
|
|
370
|
+
The callback may be asynchronous. For errors raised while the request is still
|
|
371
|
+
being read (`limit`, and some of `request`) the connection is closed right
|
|
372
|
+
after the error, so respond synchronously for those. Responses that a handler
|
|
373
|
+
sends with `request.errorResponse()` or `request.jsonResponse()` do not go
|
|
374
|
+
through the callback.
|
|
70
375
|
|
|
71
|
-
|
|
72
|
-
The
|
|
376
|
+
Handlers remain free to craft any response, including non-JSON payloads, by using
|
|
377
|
+
`request.res` directly. The convenience method `jsonResponse` is suitable for
|
|
378
|
+
most use cases:
|
|
73
379
|
|
|
74
380
|
```javascript
|
|
75
|
-
async function
|
|
76
|
-
|
|
77
|
-
r.res.writeHead(200, { 'Content-Type': 'text/plain' });
|
|
78
|
-
r.res.end('ok');
|
|
79
|
-
return;
|
|
80
|
-
}
|
|
81
|
-
// default JSON response
|
|
82
|
-
return r.jsonResponse({ ok: true });
|
|
381
|
+
async function ping(request) {
|
|
382
|
+
return request.jsonResponse({ ok: true });
|
|
83
383
|
}
|
|
84
384
|
```
|
|
85
385
|
|
|
86
|
-
|
|
87
|
-
|
|
386
|
+
## Safety features
|
|
387
|
+
|
|
388
|
+
When `rejectDangerousPaths` is `true` (the default), the server rejects paths
|
|
389
|
+
containing empty segments (`//`) or dot segments (`/.`, `/..`) before running
|
|
390
|
+
authentication or handlers. Disable the check only when you know that upstream
|
|
391
|
+
routing has already sanitized paths:
|
|
392
|
+
|
|
393
|
+
```javascript
|
|
394
|
+
const srv = new ApiSrv({
|
|
395
|
+
port: 8808,
|
|
396
|
+
rejectDangerousPaths: false,
|
|
397
|
+
callback: handler
|
|
398
|
+
});
|
|
399
|
+
```
|
|
400
|
+
|
|
401
|
+
### Parameter names
|
|
402
|
+
|
|
403
|
+
A parameter named `__proto__` is an ordinary own property of
|
|
404
|
+
`request.params`; it never replaces the prototype of the object. A JSON body
|
|
405
|
+
can nevertheless carry keys such as `__proto__` or `constructor` at any depth,
|
|
406
|
+
and code that later copies such objects with `Object.assign` or a recursive
|
|
407
|
+
merge can be tricked by them. If your API has no use for those names, reject
|
|
408
|
+
them outright:
|
|
409
|
+
|
|
410
|
+
```javascript
|
|
411
|
+
const srv = new ApiSrv({
|
|
412
|
+
port: 8808,
|
|
413
|
+
rejectDangerousParamNames: true, // 400 for __proto__, constructor, prototype keys
|
|
414
|
+
requireObjectBody: true, // 400 for a JSON array as the body
|
|
415
|
+
callback: handler
|
|
416
|
+
});
|
|
417
|
+
```
|
|
418
|
+
|
|
419
|
+
Without `requireObjectBody`, the items of a JSON array body become the
|
|
420
|
+
parameters `"0"`, `"1"` and so on.
|
|
421
|
+
|
|
422
|
+
### Response headers
|
|
423
|
+
|
|
424
|
+
JSON responses, including errors, carry `X-Content-Type-Options: nosniff`.
|
|
425
|
+
|
|
426
|
+
## Changes in 3.0.0
|
|
427
|
+
|
|
428
|
+
Version 3.0.0 is backwards compatible with 2.1.0: every existing option,
|
|
429
|
+
method and default behaves as before. New:
|
|
88
430
|
|
|
89
|
-
|
|
90
|
-
|
|
431
|
+
* `errorCallback`, for answering server-generated errors in your own format.
|
|
432
|
+
* `pathRewrite`, and `request.originalUrl`.
|
|
433
|
+
* Handler options `authCallback` and `meta`, and `request.handler`.
|
|
434
|
+
* `requestHandlerList()`.
|
|
435
|
+
* `requireObjectBody` and `rejectDangerousParamNames`.
|
|
91
436
|
|
|
92
|
-
|
|
437
|
+
Fixes and hardening that apply without any configuration:
|
|
93
438
|
|
|
439
|
+
* A parameter named `__proto__` in a JSON body used to become the prototype of
|
|
440
|
+
`request.params`, so that its contents appeared as parameters that were not
|
|
441
|
+
own properties. It is now an own property like any other.
|
|
442
|
+
* `__proto__` is rejected as a path template parameter name.
|
|
443
|
+
* A request target that is not a path (for example an absolute URL, when
|
|
444
|
+
`rejectDangerousPaths` is off) matched against `requestHandlers` used to
|
|
445
|
+
end in HTTP 500. It now matches nothing: 404, or the fallback `callback`.
|
|
446
|
+
* JSON responses carry `X-Content-Type-Options: nosniff`.
|
|
447
|
+
* The request body is assembled once instead of being copied for every chunk
|
|
448
|
+
received.
|
|
94
449
|
|
|
95
|
-
License
|
|
96
|
-
=======
|
|
450
|
+
## License
|
|
97
451
|
|
|
98
|
-
MIT
|
|
452
|
+
MIT
|