c8e4909bf1edca17202e1ca26a3310b9d748ffb3
[squeep-api-dingus] / lib / dingus.js
1 /* eslint-disable security/detect-object-injection */
2 'use strict';
3
4 /**
5 * A very minimal API server framework.
6 * Just a self-contained router and some request glue.
7 */
8
9 require('./patches');
10 const { promises: fsPromises } = require('fs');
11 const path = require('path');
12 const querystring = require('querystring');
13 const common = require('./common');
14 const ContentNegotiation = require('./content-negotiation');
15 const Enum = require('./enum');
16 const { DingusError, ResponseError } = require('./errors');
17 const { extensionToMime } = require('./mime-helper');
18 const Router = require('./router');
19 const Template = require('./template');
20
21 // For logging.
22 const _fileScope = common.fileScope(__filename);
23
24 const defaultOptions = {
25 ignoreTrailingSlash: false,
26 proxyPrefix: '',
27 strictAccept: true,
28 selfBaseUrl: '',
29 trustProxy: true,
30 querystring,
31 };
32
33 class Dingus {
34 /**
35 * @param {Object} logger object which implements logging methods
36 * @param {Object} options
37 * @param {Boolean} options.ignoreTrailingSlash
38 * @param {string} options.proxyPrefix leading part of url path to strip
39 * @param {Boolean} options.strictAccept whether to error on unsupported Accept type
40 * @param {string} options.selfBaseUrl for constructing links
41 * @param {Boolean} options.trustProxy trust some header data to be provided by proxy
42 * @param {Object} options.querystring alternate qs parser to use
43 */
44 constructor(logger = common.nullLogger, options = {}) {
45 common.setOptions(this, defaultOptions, options);
46
47 this.router = new Router(options);
48
49 if (!this.proxyPrefix) {
50 this._stripPrefix = (p) => p;
51 }
52
53 this.responseTypes = [
54 Enum.ContentType.TextHTML,
55 Enum.ContentType.TextPlain,
56 Enum.ContentType.ApplicationJson,
57 ];
58
59 this.logger = logger;
60 common.ensureLoggerLevels(this.logger);
61 }
62
63
64 /**
65 * Resolve relative and empty paths in url
66 * @param {string} p path
67 */
68 _normalizePath(p) {
69 const pathNorm = path.normalize(p); // This isn't perfectly correct, but it's easy...
70 return this._stripPrefix(pathNorm);
71 }
72
73
74 /**
75 * Remove a leading portion of url path
76 * N.B. This method gets obliterated if there is no prefix defined at construction
77 * @param {string} p path
78 */
79 _stripPrefix(p) {
80 if (p.startsWith(this.proxyPrefix)) {
81 return p.slice(this.proxyPrefix.length);
82 }
83 return p;
84 }
85
86
87 /**
88 * Returns the path part, and querystring object, from a request url.
89 * @param {string} url
90 */
91 _splitUrl(url) {
92 const [ p, qs ] = common.splitFirst(url, '?');
93 return {
94 pathPart: this._normalizePath(p),
95 queryParams: this.querystring.parse(qs),
96 };
97 }
98
99
100 /**
101 * Insert a new path handler
102 * @param {string} method
103 * @param {string} urlPath
104 * @param {fn} handler
105 */
106 on(method, urlPath, handler) {
107 this.router.on(method, urlPath, handler);
108 }
109
110
111 /**
112 * Common header tagging for all requests.
113 * Add our own identifier, and persist any external transit identifiers.
114 * @param {http.ClientRequest} req
115 * @param {http.ServerResponse} res
116 * @param {object} ctx
117 */
118 static tagContext(req, res, ctx) {
119 const requestId = common.requestId();
120 ctx.requestId = requestId;
121 res.setHeader(Enum.Header.RequestId, requestId);
122 [Enum.Header.XRequestId, Enum.Header.XCorrelationId].forEach((h) => {
123 const v = req.getHeader(h);
124 if (v) {
125 ctx[h.replace(/-/g, '')] = v;
126 res.setHeader(h, v);
127 }
128 });
129 return requestId;
130 }
131
132
133 /**
134 *
135 * @param {http.ClientRequest} req
136 */
137 _getAddress(req) {
138 // TODO: RFC7239 Forwarded support
139 const address = (this.trustProxy && req && req.getHeader(Enum.Header.XForwardedFor)) ||
140 (this.trustProxy && req && req.getHeader(Enum.Header.XRealIP)) ||
141 (req && req.connection && req.connection.remoteAddress) ||
142 '';
143 return address.split(/\s*,\s*/u)[0];
144 }
145
146
147 /**
148 *
149 * @param {http.ClientRequest} req
150 */
151 _getProtocol(req) {
152 // TODO: RFC7239 Forwarded support
153 const protocol = (this.trustProxy && req && req.getHeader(Enum.Header.XForwardedProto)) ||
154 ((req && req.connection && req.connection.encrypted) ? 'https' : 'http');
155 return protocol.split(/\s*,\s*/u)[0];
156 }
157
158
159 /**
160 *
161 * @param {http.ClientRequest} req
162 * @param {http.ServerResponse} res
163 * @param {object} ctx
164 */
165 clientAddressContext(req, res, ctx) {
166 ctx.clientAddress = this._getAddress(req);
167 ctx.clientProtocol = this._getProtocol(req);
168 }
169
170
171 /**
172 * Called before every request handler.
173 * @param {http.ClientRequest} req
174 * @param {http.ServerResponse} res
175 * @param {object} ctx
176 */
177 async preHandler(req, res, ctx) {
178 Dingus.tagContext(req, res, ctx);
179 this.clientAddressContext(req, res, ctx);
180 }
181
182
183 /**
184 * Helper for collecting chunks as array of buffers.
185 * @param {Buffer[]} chunks
186 * @param {string|Buffer} chunk
187 * @param {string} encoding
188 */
189 static pushBufChunk(chunks, chunk, encoding = 'utf8') {
190 if (chunk) {
191 if (typeof chunk === 'string') {
192 chunk = Buffer.from(chunk, encoding);
193 }
194 chunks.push(chunk);
195 }
196 }
197
198
199 /**
200 * Sets ctx.responseBody and calls handler upon res.end().
201 * @param {http.ClientRequest} req
202 * @param {http.ServerResponse} res
203 * @param {object} ctx
204 * @param {*} handler fn(req, res, ctx)
205 */
206 static setEndBodyHandler(req, res, ctx, handler) {
207 const origWrite = res.write.bind(res);
208 const origEnd = res.end.bind(res);
209 const chunks = [];
210 res.write = function (chunk, encoding, ...rest) {
211 Dingus.pushBufChunk(chunks, chunk, encoding);
212 return origWrite(chunk, encoding, ...rest);
213 };
214 res.end = function (data, encoding, ...rest) {
215 Dingus.pushBufChunk(chunks, data, encoding);
216 ctx.responseBody = Buffer.concat(chunks);
217 handler(req, res, ctx);
218 return origEnd(data, encoding, ...rest);
219 };
220 }
221
222
223 /**
224 * Intercept writes for head requests, do not send to client,
225 * but send length, and make body available in context.
226 * @param {http.ClientRequest} req
227 * @param {http.ServerResponse} res
228 * @param {object} ctx
229 */
230 static setHeadHandler(req, res, ctx) {
231 if (req.method === 'HEAD') {
232 const origEnd = res.end.bind(res);
233 const chunks = [];
234 res.write = function (chunk, encoding) {
235 Dingus.pushBufChunk(chunks, chunk, encoding);
236 // No call to original res.write.
237 };
238 res.end = function (data, encoding, ...rest) {
239 Dingus.pushBufChunk(chunks, data, encoding);
240 ctx.responseBody = Buffer.concat(chunks);
241 res.setHeader(Enum.Header.ContentLength, Buffer.byteLength(ctx.responseBody));
242 return origEnd(undefined, encoding, ...rest);
243 };
244 }
245 }
246
247
248 /**
249 * Dispatch the handler for a request
250 * @param {http.ClientRequest} req
251 * @param {http.ServerResponse} res
252 * @param {object} ctx
253 */
254 async dispatch(req, res, ctx = {}) {
255 const _scope = _fileScope('dispatch');
256
257 const { pathPart, queryParams } = this._splitUrl(req.url);
258 ctx.queryParams = queryParams;
259
260 let handler;
261 try {
262 handler = this.router.lookup(req.method, pathPart, ctx);
263 } catch (e) {
264 if (e instanceof DingusError) {
265 switch (e.message) {
266 case 'NoPath':
267 handler = this.handlerNotFound.bind(this);
268 break;
269 case 'NoMethod':
270 handler = this.handlerMethodNotAllowed.bind(this);
271 break;
272 default:
273 this.logger.error(_scope, 'unknown dingus error', { error: e });
274 handler = this.handlerInternalServerError.bind(this);
275 }
276 } else if (e instanceof URIError) {
277 handler = this.handlerBadRequest.bind(this);
278 } else {
279 this.logger.error(_scope, 'lookup failure', { error: e });
280 handler = this.handlerInternalServerError.bind(this);
281 }
282 }
283
284 try {
285 await this.preHandler(req, res, ctx);
286 return await handler(req, res, ctx);
287 } catch (e) {
288 ctx.error = e;
289 this.sendErrorResponse(e, req, res, ctx);
290 }
291 }
292
293
294 /**
295 * Return normalized type, without any parameters.
296 * @param {http.ClientRequest} req
297 * @returns {string}
298 */
299 static getRequestContentType(req) {
300 const contentType = req.getHeader(Enum.Header.ContentType);
301 return (contentType || '').split(';')[0].trim().toLowerCase();
302 }
303
304
305 /**
306 * Parse rawBody from ctx as contentType into parsedBody.
307 * @param {string} contentType
308 * @param {object} ctx
309 */
310 parseBody(contentType, ctx) {
311 const _scope = _fileScope('parseBody');
312
313 switch (contentType) {
314 case Enum.ContentType.ApplicationForm:
315 ctx.parsedBody = this.querystring.parse(ctx.rawBody);
316 break;
317
318 case Enum.ContentType.ApplicationJson:
319 try {
320 ctx.parsedBody = JSON.parse(ctx.rawBody);
321 } catch (e) {
322 this.logger.debug(_scope, 'JSON parse failed', { requestId: ctx.requestId, error: e });
323 throw new ResponseError(Enum.ErrorResponse.BadRequest, e.message);
324 }
325 break;
326
327 default:
328 this.logger.debug(_scope, 'unhandled content-type', { requestId: ctx.requestId, contentType });
329 throw new ResponseError(Enum.ErrorResponse.UnsupportedMediaType);
330 }
331 }
332
333
334 /**
335 * Return all body data from a request.
336 * @param {http.ClientRequest} req
337 */
338 async bodyData(req) {
339 const _scope = _fileScope('bodyData');
340 return new Promise((resolve, reject) => {
341 const body = [];
342 req.on('data', (chunk) => body.push(chunk));
343 req.on('end', () => resolve(Buffer.concat(body).toString()));
344 req.on('error', (e) => {
345 this.logger.error(_scope, 'failed', { error: e });
346 reject(e);
347 });
348 });
349 }
350
351
352 /**
353 * Read and parse request body data.
354 * @param {http.ClientRequest} req
355 * @param {http.ServerResponse} res
356 * @param {object} ctx
357 */
358 async ingestBody(req, res, ctx) {
359 ctx.rawBody = await this.bodyData(req);
360 const contentType = Dingus.getRequestContentType(req);
361 this.parseBody(contentType, ctx);
362 }
363
364
365 /**
366 * Return the best matching response type.
367 * @param {string[]} responseTypes
368 * @param {http.ClientRequest} req
369 */
370 static getResponseContentType(responseTypes, req) {
371 const acceptHeader = req.getHeader(Enum.Header.Accept);
372 return ContentNegotiation.accept(responseTypes, acceptHeader);
373 }
374
375
376 /**
377 * Returns a list of the most-preferred content encodings for the response.
378 * @param {string[]} responseEncodings
379 * @param {http.ClientRequest} req
380 */
381 static getResponseEncoding(responseEncodings, req) {
382 const acceptEncodingHeader = req.getHeader(Enum.Header.AcceptEncoding);
383 return ContentNegotiation.preferred(responseEncodings, acceptEncodingHeader);
384 }
385
386
387 /**
388 * Set the best content type for the response.
389 * @param {string[]} responseTypes default first
390 * @param {http.ClientRequest} req
391 * @param {http.ServerResponse} res
392 * @param {object} ctx
393 */
394 setResponseType(responseTypes, req, res, ctx) {
395 const _scope = _fileScope('setResponseType');
396 ctx.responseType = Dingus.getResponseContentType(responseTypes, req);
397 if (!ctx.responseType) {
398 if (this.strictAccept) {
399 this.logger.debug(_scope, 'unhandled strict accept', { requestId: req.requestId });
400 throw new ResponseError(Enum.ErrorResponse.NotAcceptable);
401 } else {
402 ctx.responseType = responseTypes[0];
403 }
404 }
405 res.setHeader(Enum.Header.ContentType, ctx.responseType);
406 }
407
408
409 /**
410 * Inserts an encoding
411 * @param {http.ServerResponse} res
412 * @param {string} encoding
413 */
414 static addEncodingHeader(res, encoding) {
415 const existingEncodings = res.getHeader(Enum.Header.ContentEncoding);
416 if (existingEncodings) {
417 encoding = `${encoding}, ${existingEncodings}`;
418 }
419 res.setHeader(Enum.Header.ContentEncoding, encoding);
420 }
421
422
423 /**
424 * Attempt to fetch both data and metadata for a file.
425 * @param {string} filePath
426 */
427 async _readFileInfo(filePath) {
428 const _scope = _fileScope('_readFileInfo');
429 let result;
430 try {
431 // eslint-disable-next-line security/detect-non-literal-fs-filename
432 const stat = fsPromises.stat(filePath);
433 // eslint-disable-next-line security/detect-non-literal-fs-filename
434 const data = fsPromises.readFile(filePath);
435 result = await Promise.all([stat, data]);
436 } catch (e) {
437 if (['ENOENT', 'EACCES', 'EISDIR', 'ENAMETOOLONG', 'EINVAL'].includes(e.code)) {
438 return [null, null];
439 }
440 this.logger.error(_scope, 'fs error', { error: e, filePath });
441 throw e;
442 }
443 return result;
444 }
445
446
447 /**
448 * Serve a file from a directory, with rudimentary cache awareness.
449 * This will also serve pre-encoded variations if available and requested.
450 * @param {http.ClientRequest} req
451 * @param {http.ServerResponse} res
452 * @param {object} ctx
453 * @param {string} directory
454 * @param {string} fileName
455 */
456 async serveFile(req, res, ctx, directory, fileName) {
457 const _scope = _fileScope('serveFile');
458 this.logger.debug(_scope, 'called', { req: common.requestLogData(req), ctx });
459
460 // Normalize the supplied path, as encoded path-navigation may have been (maliciously) present.
461 fileName = path.normalize(fileName);
462
463 // We will not deal with any subdirs, nor any dot-files.
464 // (Note that we could not deal with subdirs even if we wanted, due to simple router matching scheme.)
465 if (fileName.indexOf(path.sep) >= 0
466 || fileName.charAt(0) === '.') {
467 this.logger.debug(_scope, 'rejected filename', { fileName });
468 return this.handlerNotFound(req, res, ctx);
469 }
470
471 const filePath = path.join(directory, fileName);
472
473 // File must exist, before any alternate static encodings will be considered.
474 let [stat, data] = await this._readFileInfo(filePath);
475 if (!stat) {
476 return this.handlerNotFound(req, res, ctx);
477 }
478
479 // If encodings were requested, check for static versions to serve.
480 // Update stat and data if matching version is found.
481 ctx.availableEncodings = Dingus.getResponseEncoding(Object.values(Enum.EncodingType), req);
482 if (ctx.availableEncodings.length === 0) {
483 // Identity encoding was specifically denied, and nothing else available.
484 this.logger.debug(_scope, 'no suitable encodings', { ctx });
485 return this.handlerMethodNotAllowed(req, res, ctx);
486 }
487 for (const encoding of ctx.availableEncodings) {
488 if (encoding === Enum.EncodingType.Identity) {
489 break;
490 }
491 const suffix = Enum.EncodingTypeSuffix[encoding];
492 if (suffix) {
493 const encodedFilePath = `${filePath}${suffix}`;
494 const [ encodedStat, encodedData ] = await this._readFileInfo(encodedFilePath);
495 if (encodedStat) {
496 ([ stat, data ] = [ encodedStat, encodedData ]);
497 ctx.selectedEncoding = encoding;
498 Dingus.addEncodingHeader(res, encoding);
499 res.setHeader(Enum.Header.Vary, Enum.Header.AcceptEncoding);
500 this.logger.debug(_scope, 'serving encoded version', { ctx, encodedFilePath });
501 }
502 break;
503 }
504 }
505
506 const lastModifiedDate = new Date(stat.mtimeMs);
507 res.setHeader(Enum.Header.LastModified, lastModifiedDate.toGMTString());
508
509 const eTag = common.generateETag(filePath, stat, data);
510 res.setHeader(Enum.Header.ETag, eTag);
511
512 if (common.isClientCached(req, stat.mtimeMs, eTag)) {
513 this.logger.debug(_scope, 'client cached file', { filePath });
514 res.statusCode = 304; // Not Modified
515 res.end();
516 return;
517 }
518
519 // Set the type based on extension of un-encoded filename.
520 const ext = path.extname(filePath).slice(1); // Drop the dot
521 const contentType = extensionToMime(ext);
522 res.setHeader(Enum.Header.ContentType, contentType);
523
524 // We presume static files are relatively cacheable.
525 res.setHeader(Enum.Header.CacheControl, 'public');
526
527 this.logger.debug(_scope, 'serving file', { filePath, contentType });
528 res.end(data);
529 }
530
531
532 /**
533 * Return a content-type appropriate rendering of an errorResponse object.
534 * @param {string} type content-type of response
535 * @param {object} err either an Error object, or an error response
536 * @param {number} err.statusCode
537 * @param {string} err.errorMessage
538 * @param {string|string[]} err.details
539 */
540 // eslint-disable-next-line class-methods-use-this
541 renderError(contentType, err) {
542 switch (contentType) {
543 case Enum.ContentType.ApplicationJson:
544 return JSON.stringify(err);
545
546 case Enum.ContentType.TextHTML:
547 return Template.errorHTML(err);
548
549 case Enum.ContentType.TextPlain:
550 default:
551 return [err.errorMessage, err.details].join('\r\n');
552 }
553 }
554
555
556 /**
557 * Send an error response. Terminal.
558 * Logs any non-error-response errors as such.
559 * @param {object} err either an Error object, or an error response
560 * @param {http.ClientRequest} req
561 * @param {http.ServerResponse} res
562 * @param {object} ctx
563 */
564 sendErrorResponse(err, req, res, ctx) {
565 const _scope = _fileScope('sendErrorResponse');
566 let body;
567
568 // Default to a content type if one is not yet present
569 if (!res.hasHeader(Enum.Header.ContentType)) {
570 res.setHeader(Enum.Header.ContentType, Enum.ContentType.TextPlain);
571 }
572
573 if (err && err.statusCode) {
574 res.statusCode = err.statusCode;
575 body = this.renderError(res.getHeader(Enum.Header.ContentType), err);
576 this.logger.debug(_scope, 'handler error', { err, ...common.handlerLogData(req, res, ctx) });
577 } else {
578 res.statusCode = 500;
579 body = this.renderError(res.getHeader(Enum.Header.ContentType), Enum.ErrorResponse.InternalServerError);
580 this.logger.error(_scope, 'handler exception', { err, ...common.handlerLogData(req, res, ctx) });
581 }
582 res.end(body);
583 }
584
585
586 /**
587 * @param {http.ClientRequest} req
588 * @param {http.ServerResponse} res
589 * @param {object} ctx
590 */
591 async handlerMethodNotAllowed(req, res, ctx) {
592 this.setResponseType(this.responseTypes, req, res, ctx);
593 throw new ResponseError(Enum.ErrorResponse.MethodNotAllowed);
594 }
595
596
597 /**
598 * @param {http.ClientRequest} req
599 * @param {http.ServerResponse} res
600 * @param {object} ctx
601 */
602 async handlerNotFound(req, res, ctx) {
603 this.setResponseType(this.responseTypes, req, res, ctx);
604 throw new ResponseError(Enum.ErrorResponse.NotFound);
605 }
606
607
608 /**
609 * @param {http.ClientRequest} req
610 * @param {http.ServerResponse} res
611 * @param {object} ctx
612 */
613 async handlerBadRequest(req, res, ctx) {
614 this.setResponseType(this.responseTypes, req, res, ctx);
615 throw new ResponseError(Enum.ErrorResponse.BadRequest);
616 }
617
618 /**
619 * @param {http.ClientRequest} req
620 * @param {http.ServerResponse} res
621 * @param {object} ctx
622 */
623 async handlerInternalServerError(req, res, ctx) {
624 this.setResponseType(this.responseTypes, req, res, ctx);
625 throw new ResponseError(Enum.ErrorResponse.InternalServerError);
626 }
627
628 }
629
630 module.exports = Dingus;