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.
Files changed (4) hide show
  1. package/README.md +416 -62
  2. package/index.js +974 -91
  3. package/package.json +1 -1
  4. package/test/test.js +1570 -10
package/README.md CHANGED
@@ -1,98 +1,452 @@
1
- API Server
2
- ==========
1
+ # API Server
3
2
 
4
- This is a simple API server providing with ability to easily create
5
- JSON API servers. Accepts also calls in www-form-urlencoded form
6
- and treats them identically to flat JSON key-value structure.
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
- var srv = new ApiSrv({ port: 8808,
14
- address: '127.0.0.1',
15
- callback: cb,
16
- authCallback: authCb,
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 authCb(r) {
23
- return true;
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 cb(r) {
27
- r.jsonResponse(r, 200);
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
- Examples
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
- GET handler with path parameter
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
- async function cb(r) {
39
- if (r.method === 'GET') {
40
- // Match URL like /user/123 and capture the id
41
- const m = r.url.match(/^\/user\/([^/]+)$/);
42
- if (m) {
43
- const id = m[1];
44
- // r.params contains parsed query string values
45
- return r.jsonResponse({ id, params: r.params });
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
- POST handler with JSON body
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
- async function cb(r) {
56
- if (r.method === 'POST') {
57
- // Match URL like /user/123 and capture the id
58
- const m = r.url.match(/^\/user\/([^/]+)$/);
59
- if (m) {
60
- const id = m[1];
61
- // Body is already parsed into r.params
62
- return r.jsonResponse({ id, received: r.params });
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
- Non‑JSON response
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
- Sometimes a handler may need to send a plain text or other custom response.
72
- The underlying `http.ServerResponse` is available as `r.res`:
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 cb(r) {
76
- if (r.url === '/plaintext') {
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
- `maxBodySize` limits the size of accepted request bodies in bytes. Requests exceeding
87
- the limit are terminated with HTTP status 413. The default limit is 1 MiB.
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
- Author
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
- Timo J. Rinne <tri@iki.fi>
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 License
452
+ MIT