expediate 1.0.1 → 1.0.3

package/dist/misc.js

@@ -0,0 +1,549 @@
+/* Copyright 2021 Fabien Bavent
+ *
+ * Permission is hereby granted, free of charge, to any person obtaining a
+ * copy of this software and associated documentation files (the "Software"),
+ * to deal in the Software without restriction, including without limitation
+ * the rights to use, copy, modify, merge, publish, distribute, sublicense,
+ * and/or sell copies of the Software, and to permit persons to whom the
+ * Software is furnished to do so, subject to the following conditions:
+ *
+ * The above copyright notice and this permission notice shall be included
+ * in all copies or substantial portions of the Software.
+ *
+ * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS
+ * OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+ * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL
+ * THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+ * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
+ * FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER
+ * DEALINGS IN THE SOFTWARE.
+ */
+'use strict';
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.json = json;
+exports.formData = formData;
+exports.parseBody = parseBody;
+exports.logger = logger;
+const zlib_1 = __importDefault(require("zlib"));
+// ---------------------------------------------------------------------------
+// Decompression algorithm registry
+// ---------------------------------------------------------------------------
+/**
+ * Maps a supported `Content-Encoding` value to its corresponding `zlib`
+ * decompression function.  Only `gzip` and `deflate` are supported.
+ */
+const DECOMPRESS_ALGO = {
+    gzip: zlib_1.default.gunzip,
+    deflate: zlib_1.default.inflate,
+};
+// ---------------------------------------------------------------------------
+// Internal utilities
+// ---------------------------------------------------------------------------
+/**
+ * Parse a human-readable byte-size string into a number of bytes.
+ *
+ * Supported suffixes (case-insensitive): `b`, `kb`, `mb`, `gb`.
+ * The suffix is optional; a bare number is treated as bytes.
+ *
+ * @param value - The size string to parse (e.g. `'100kb'`, `'2.5mb'`).
+ * @returns The size in bytes, or `0` if the input cannot be parsed.
+ *
+ * @example
+ * ```ts
+ * readSize('100kb')  // 102400
+ * readSize('2mb')    // 2097152
+ * readSize('1024')   // 1024
+ * readSize('bad')    // 0
+ * ```
+ */
+function readSize(value) {
+    if (typeof value === 'number')
+        return value;
+    const fmt = /^(\d+(\.\d+)?)([kmg]?b?)?$/i.exec(value);
+    if (!fmt)
+        return 0;
+    const num = parseFloat(fmt[1] ?? '0');
+    const sfx = (fmt[3] ?? 'b').toLowerCase();
+    if (sfx[0] === 'k')
+        return num * 1024;
+    if (sfx[0] === 'm')
+        return num * 1024 * 1024;
+    if (sfx[0] === 'g')
+        return num * 1024 * 1024 * 1024;
+    return num;
+}
+/**
+ * Split a `Buffer` on every occurrence of a `delimiter` buffer, returning an
+ * array of sub-buffers between delimiters (the delimiters themselves are not
+ * included in the output).
+ *
+ * Behaves like `String.prototype.split` but operates on raw binary data,
+ * making it safe for multipart bodies that may contain arbitrary byte
+ * sequences.
+ *
+ * @param buffer    - The source buffer to split.
+ * @param delimiter - The byte sequence to split on.
+ * @returns An array of buffer slices; always contains at least one element.
+ */
+function splitBuffer(buffer, delimiter) {
+    const result = [];
+    let start = 0;
+    let index;
+    while ((index = buffer.indexOf(delimiter, start)) !== -1) {
+        result.push(buffer.slice(start, index));
+        start = index + delimiter.length;
+    }
+    result.push(buffer.slice(start));
+    return result;
+}
+/**
+ * Extract the `charset` parameter from a `Content-Type` header value.
+ *
+ * Handles optional whitespace around the semicolon-separated parameters.
+ * Falls back to `'utf8'` when no `charset` parameter is found.
+ *
+ * @param contentType - The raw `Content-Type` header value
+ *                      (e.g. `'text/plain; charset=iso-8859-1'`).
+ * @returns A Node.js-compatible encoding name (e.g. `'utf8'`, `'iso-8859-1'`).
+ */
+function extractCharset(contentType) {
+    // BUG FIX: the original regex `'s+$` was a literal quote followed by `s+$`
+    // instead of `\s+$`. The trim therefore left leading/trailing whitespace on
+    // every parameter, breaking charset detection. Corrected to `\s+$`.
+    const param = contentType
+        .split(';')
+        .map((s) => s.replace(/^\s+|\s+$/g, ''))
+        .find((s) => s.startsWith('charset='));
+    return param ? param.substring('charset='.length) : 'utf8';
+}
+// ---------------------------------------------------------------------------
+// Body collection
+// ---------------------------------------------------------------------------
+/**
+ * Collect the full request body into a single `Buffer`, enforce size limits,
+ * optionally decompress, and validate the `Content-Type` against an expected
+ * MIME type.
+ *
+ * When the body is successfully collected and validated, `callback` is invoked
+ * with the raw `Content-Type` header value and the (possibly decompressed)
+ * body buffer.  In all error cases the appropriate HTTP error response is sent
+ * and `callback` is never called.
+ *
+ * Callers that need to pass control to the next middleware when there is no
+ * body should rely on the `next()` call that this function makes when
+ * `Content-Length` is `0` or absent.
+ *
+ * @param req       - The incoming request.
+ * @param res       - The outgoing response.
+ * @param opts      - Resolved body-parsing options.
+ * @param mimetype  - Expected MIME type (e.g. `'application/json'`), or `null`
+ *                    to accept any content type.
+ * @param next      - The next middleware callback; called when the body is
+ *                    empty or absent.
+ * @param callback  - Invoked with `(contentType, body)` on success.
+ */
+function readBody(req, res, opts, mimetype, next, callback) {
+    // BUG FIX: HTTP/1.1 header names are always lowercased by Node.js.
+    // The original code used mixed-case keys ('Content-Length', 'Content-Encoding',
+    // 'Content-Type') which always evaluated to undefined.
+    const length = parseInt(req.headers['content-length'] ?? '0', 10);
+    // No body declared — skip to next middleware.
+    if (!length || length === 0)
+        return next();
+    const maxLength = readSize(opts.limit) || 102_400;
+    if (length > maxLength)
+        return void res.status(413).send('Content Too Large');
+    // Compression handling.
+    const encoding = req.headers['content-encoding'];
+    if (encoding && (opts.inflate === false || !DECOMPRESS_ALGO[encoding]))
+        return void res.status(415).send('Unsupported Media Type: Wrong Content-Encoding');
+    // eslint-disable-next-line @typescript-eslint/ban-types
+    const decompress = (encoding ? DECOMPRESS_ALGO[encoding] : undefined) ?? ((d, c) => c(null, d));
+    // Content-Type validation.
+    const contentType = req.headers['content-type'] ?? '';
+    if (mimetype && contentType.split(';')[0].trim() !== mimetype)
+        return void res.status(415).send('Unsupported Media Type: Wrong Content-Type');
+    // Stream collection.
+    let data = Buffer.alloc(0);
+    req.on('data', (chunk) => {
+        if (data === null)
+            return; // already aborted
+        // BUG FIX: the size check must happen AFTER concatenating the new chunk,
+        // not before. Checking before allowed a stream of (maxLength-1)-byte chunks
+        // to bypass the limit entirely.
+        // BUG FIX: the original code referenced `chink` (typo) instead of `chunk`.
+        const next_ = Buffer.concat([data, chunk]);
+        if (next_.length > maxLength) {
+            data = null;
+            res.status(413).send('Content Too Large');
+            return;
+        }
+        data = next_;
+    });
+    req.on('end', () => {
+        if (data === null)
+            return; // aborted during streaming
+        // zlib types require NonSharedBuffer; Buffer satisfies this at runtime.
+        // eslint-disable-next-line @typescript-eslint/no-explicit-any
+        decompress(data, (err, decompressed) => {
+            if (err)
+                return void res.status(500).send(err.message);
+            callback(contentType, decompressed);
+        });
+    });
+}
+// ---------------------------------------------------------------------------
+// Body parsers
+// ---------------------------------------------------------------------------
+/**
+ * Parse a collected body buffer as plain text, decode it using the charset
+ * declared in `contentType`, and assign the result to `req.body`.
+ *
+ * On success, calls `next()`.  On failure, sends a 500 Internal Server Error.
+ *
+ * @param req         - The incoming request (mutated: `req.body` is set).
+ * @param res         - The outgoing response.
+ * @param next        - Called on successful parsing.
+ * @param contentType - The raw `Content-Type` header value.
+ * @param data        - The raw body buffer.
+ */
+function readBodyAsPlainText(req, res, next, contentType, data) {
+    const charset = extractCharset(contentType);
+    try {
+        req.body = data.toString(charset);
+        next();
+    }
+    catch (ex) {
+        res.status(500).send(ex.message);
+    }
+}
+/**
+ * Parse a collected body buffer as JSON, decode it using the charset declared
+ * in `contentType`, apply an optional `reviver`, and assign the result to
+ * `req.body`.
+ *
+ * On success, calls `next()`.  On failure (invalid JSON or unsupported charset),
+ * sends a 500 Internal Server Error.
+ *
+ * @param req         - The incoming request (mutated: `req.body` is set).
+ * @param res         - The outgoing response.
+ * @param next        - Called on successful parsing.
+ * @param opts        - Resolved options; `opts.reviver` is passed to `JSON.parse`.
+ * @param contentType - The raw `Content-Type` header value.
+ * @param data        - The raw body buffer.
+ */
+function readBodyAsJson(req, res, next, opts, contentType, data) {
+    const charset = extractCharset(contentType);
+    try {
+        req.body = JSON.parse(data.toString(charset), opts.reviver ?? undefined);
+        next();
+    }
+    catch (ex) {
+        res.status(500).send(ex.message);
+    }
+}
+/**
+ * Parse a collected body buffer as `multipart/form-data`, split it on the
+ * boundary declared in `contentType`, parse each part's headers, and assign
+ * an array of {@link FormPart} objects to `req.body`.
+ *
+ * On success, calls `next()`.  On failure (missing boundary, malformed parts),
+ * sends a 500 Internal Server Error.
+ *
+ * **Multipart wire format recap:**
+ * ```
+ * --boundary\r\n
+ * Header: value\r\n
+ * \r\n
+ * <binary content>
+ * --boundary\r\n
+ * ...
+ * --boundary--\r\n
+ * ```
+ * The boundary string in `Content-Type` does **not** include the leading `--`;
+ * actual part delimiters on the wire are `\r\n--boundary`.
+ *
+ * @param req         - The incoming request (mutated: `req.body` is set).
+ * @param res         - The outgoing response.
+ * @param next        - Called on successful parsing.
+ * @param contentType - The raw `Content-Type` header value (must include
+ *                      `boundary=<value>`).
+ * @param data        - The raw body buffer.
+ */
+function readBodyAsFormData(req, res, next, contentType, data) {
+    // BUG FIX: the original regex used `'s+$` (literal quote) instead of `\s+$`.
+    const boundary = contentType
+        .split(';')
+        .map((s) => s.replace(/^\s+|\s+$/g, ''))
+        .find((s) => s.startsWith('boundary='))
+        ?.substring('boundary='.length);
+    if (!boundary)
+        return void res.status(400).send('Bad Request: missing multipart boundary');
+    try {
+        // Wire-level delimiter: each part (after the preamble) is preceded by
+        // \r\n--boundary.  We split on this sequence so every resulting slice is
+        // the raw content of one part (headers + blank line + body), without any
+        // leading delimiter bytes.
+        // BUG FIX: the original code passed `buffer` (undefined) instead of `data`.
+        const delimiter = Buffer.from(`\r\n--${boundary}`);
+        // Prepend \r\n so the very first part is also cleanly split.
+        const normalized = Buffer.concat([Buffer.from('\r\n'), data]);
+        const rawParts = splitBuffer(normalized, delimiter);
+        const parts = [];
+        for (const part of rawParts) {
+            // The closing delimiter ends with '--'; skip it.
+            // BUG FIX: the original check `buf.length == 2 && buf.toString() == '--'`
+            // was incorrect. After splitting on \r\n--boundary, the terminal entry
+            // is '--\r\n' (or just '--'), not a 2-byte '--'. Use startsWith.
+            if (part.toString('utf8', 0, 2) === '--')
+                continue;
+            // Each part begins with \r\n (from after the delimiter), then headers,
+            // then \r\n\r\n (blank line), then content.
+            // Skip the leading \r\n.
+            const partContent = part.slice(2);
+            const blankLine = Buffer.from('\r\n\r\n');
+            const blankIdx = partContent.indexOf(blankLine);
+            if (blankIdx === -1)
+                continue; // malformed part — skip
+            const headerSection = partContent.slice(0, blankIdx).toString('utf8');
+            const content = partContent.slice(blankIdx + blankLine.length);
+            const headers = {};
+            for (const line of headerSection.split('\r\n')) {
+                if (!line)
+                    continue;
+                const colonIdx = line.indexOf(':');
+                if (colonIdx === -1)
+                    continue;
+                const key = line.substring(0, colonIdx).replace(/^\s+|\s+$/g, '').toLowerCase();
+                const value = line.substring(colonIdx + 1).replace(/^\s+|\s+$/g, '');
+                headers[key] = value;
+            }
+            parts.push({ headers, content });
+        }
+        req.body = parts;
+        next();
+    }
+    catch (ex) {
+        res.status(500).send(ex.message);
+    }
+}
+/**
+ * Dispatch table mapping a MIME type to its body-parser function.
+ * Used by {@link parseBody} to select the appropriate parser at runtime.
+ */
+const BODY_READERS = {
+    'multipart/form-data': (req, res, next, _opts, ct, data) => readBodyAsFormData(req, res, next, ct, data),
+    'application/json': (req, res, next, opts, ct, data) => readBodyAsJson(req, res, next, opts, ct, data),
+    'text/plain': (req, res, next, _opts, ct, data) => readBodyAsPlainText(req, res, next, ct, data),
+};
+// ---------------------------------------------------------------------------
+// Public middleware factories
+// ---------------------------------------------------------------------------
+/**
+ * Middleware factory that parses a `application/json` request body and
+ * assigns the parsed value to `req.body`.
+ *
+ * Also attaches a `res.json(data)` helper to the response object so that
+ * handlers can send JSON responses conveniently:
+ * ```ts
+ * res.json({ ok: true });
+ * ```
+ *
+ * Behaviour:
+ * - Requests without a body (`Content-Length: 0` or absent) are passed
+ *   through to `next()` without touching `req.body`.
+ * - Bodies larger than `opts.limit` receive **413 Content Too Large**.
+ * - Bodies with an unsupported `Content-Encoding` receive
+ *   **415 Unsupported Media Type**.
+ * - Bodies whose `Content-Type` is not `application/json` receive
+ *   **415 Unsupported Media Type**.
+ * - Parse errors receive **500 Internal Server Error**.
+ *
+ * @param opts - Optional configuration (see {@link BodyOptions}).
+ * @returns An Express-compatible middleware function.
+ */
+function json(opts) {
+    const resolved = {
+        inflate: true,
+        limit: '100kb',
+        reviver: null,
+        strict: true,
+        ...opts,
+    };
+    return (req, res, next) => {
+        // Attach a JSON response helper so handlers can call res.json(data).
+        res.json = (data) => {
+            res.write(JSON.stringify(data));
+            res.end();
+        };
+        readBody(req, res, resolved, 'application/json', next, (contentType, body) => {
+            readBodyAsJson(req, res, next, resolved, contentType, body);
+        });
+    };
+}
+/**
+ * Middleware factory that parses a `multipart/form-data` request body and
+ * assigns an array of {@link FormPart} objects to `req.body`.
+ *
+ * Each element in `req.body` exposes:
+ * - `headers` — the part's MIME headers (e.g. `Content-Disposition`).
+ * - `content` — the raw binary content of the part as a `Buffer`.
+ *
+ * Behaviour:
+ * - Requests without a body are passed through to `next()`.
+ * - Bodies larger than `opts.limit` receive **413 Content Too Large**.
+ * - Bodies with a missing or malformed `boundary` parameter receive
+ *   **400 Bad Request**.
+ * - Parse errors receive **500 Internal Server Error**.
+ *
+ * @param opts - Optional configuration (see {@link BodyOptions}).
+ * @returns An Express-compatible middleware function.
+ */
+function formData(opts) {
+    const resolved = {
+        inflate: true,
+        limit: '100kb',
+        reviver: null,
+        strict: true,
+        ...opts,
+    };
+    return (req, res, next) => {
+        readBody(req, res, resolved, 'multipart/form-data', next, (contentType, body) => {
+            readBodyAsFormData(req, res, next, contentType, body);
+        });
+    };
+}
+/**
+ * Middleware factory that auto-detects the `Content-Type` of the request body
+ * and parses it using the appropriate parser.
+ *
+ * Supported MIME types:
+ * - `application/json`    → parsed as JSON; result is a JS value.
+ * - `multipart/form-data` → parsed as multipart; result is `FormPart[]`.
+ * - `text/plain`          → decoded as text; result is a string.
+ *
+ * Requests with an unsupported MIME type receive **415 Unsupported Media Type**.
+ * All other error conditions behave identically to {@link json} and
+ * {@link formData}.
+ *
+ * @param opts - Optional configuration (see {@link BodyOptions}).
+ * @returns An Express-compatible middleware function.
+ */
+function parseBody(opts) {
+    const resolved = {
+        inflate: true,
+        limit: '100kb',
+        reviver: null,
+        strict: true,
+        ...opts,
+    };
+    return (req, res, next) => {
+        readBody(req, res, resolved, null, next, (contentType, body) => {
+            const mimetype = contentType.split(';')[0].trim();
+            if (!BODY_READERS[mimetype])
+                return res.status(415).send('Unsupported Media Type');
+            BODY_READERS[mimetype](req, res, next, resolved, contentType, body);
+        });
+    };
+}
+// ---------------------------------------------------------------------------
+// Logger middleware
+// ---------------------------------------------------------------------------
+/**
+ * ANSI terminal colour codes indexed by HTTP status class (1xx–5xx).
+ *
+ * Index 0 is unused (no HTTP 0xx class).
+ * - 1xx → yellow  (`\x1b[33m`)
+ * - 2xx → green   (`\x1b[32m`)
+ * - 3xx → yellow  (`\x1b[33m`)
+ * - 4xx → red     (`\x1b[31m`)
+ * - 5xx → bright red (`\x1b[91m`)
+ */
+const STATUS_COLORS = [
+    '\x1b[0m', // 0 — fallback / unknown
+    '\x1b[33m', // 1xx — informational (yellow)
+    '\x1b[32m', // 2xx — success (green)
+    '\x1b[33m', // 3xx — redirection (yellow)
+    '\x1b[31m', // 4xx — client error (red)
+    '\x1b[91m', // 5xx — server error (bright red)
+];
+/** ANSI reset escape sequence. */
+const ANSI_RESET = '\x1b[0m';
+/**
+ * Middleware factory that logs one line per completed HTTP request to the
+ * console (or a custom logger function).
+ *
+ * Each log line contains:
+ * - Timestamp (formatted with `Intl.DateTimeFormat`).
+ * - HTTP status code (ANSI-coloured by status class).
+ * - HTTP method and request path.
+ * - Client IP address (honours `X-Forwarded-For`).
+ * - User identity (from `opts.user` or `'-'`).
+ * - Elapsed time in milliseconds.
+ * - Response `Content-Length` (or `'-'` when absent).
+ *
+ * **Lost-request tracking:** when `opts.track` is `true`, a timer is started
+ * for each request.  If the response is not finished within `opts.trackTimeout`
+ * milliseconds, a `LOST` warning line is emitted.  This is useful in
+ * development to surface handlers that never call `res.end()`.
+ *
+ * @param opts - Optional configuration (see {@link LoggerOptions}).
+ * @returns An Express-compatible middleware function.
+ *
+ * @example
+ * ```ts
+ * app.use('/', logger({
+ *   track:        true,
+ *   trackTimeout: 30_000,
+ *   user:         (req) => (req as any).authUser ?? '-',
+ *   locale:       'en-US',
+ *   logger:       (msg) => process.stderr.write(msg + '\n'),
+ * }));
+ * ```
+ */
+function logger(opts) {
+    const options = opts ?? {};
+    const log = options.logger ?? console.log;
+    const formatter = new Intl.DateTimeFormat(options.locale ?? 'en-GB', options.dateFormat ?? {
+        month: 'short',
+        day: '2-digit',
+        hour: '2-digit',
+        minute: '2-digit',
+    });
+    return (req, res, next) => {
+        // Capture timestamp and path at request-arrival time so they are stable
+        // even if later middleware mutates req.path (e.g. prefix stripping).
+        const timestamp = formatter.format(new Date());
+        const requestPath = req.path ?? req.url ?? '/';
+        const ip = req.headers['x-forwarded-for']
+            ?? req.socket?.remoteAddress
+            ?? '-';
+        const user = options.user?.(req) ?? '-';
+        const receivedAt = Date.now();
+        // Lost-request tracking.
+        const tracker = options.track === true
+            ? setTimeout(() => {
+                log(`${timestamp} LOST ${req.method} ${requestPath} ${ip} <${user}>`);
+            }, options.trackTimeout ?? 30_000)
+            : null;
+        res.on('finish', () => {
+            if (tracker !== null)
+                clearTimeout(tracker);
+            const elapsed = Date.now() - receivedAt;
+            // BUG FIX: Math.floor is more explicit and correct than parseInt for
+            // integer division. Both work, but parseInt(200/100) has a subtle
+            // coercion to string first. Math.floor is semantically clearer.
+            const statusClass = Math.floor(res.statusCode / 100);
+            const colour = STATUS_COLORS[statusClass] ?? STATUS_COLORS[0];
+            const statusStr = `${colour}${res.statusCode}${ANSI_RESET}`;
+            const contentLen = res.getHeader('content-length') ?? '-';
+            log(`${timestamp} ${statusStr} ${req.method} ${requestPath} ${ip} <${user}> ${elapsed}ms (${contentLen})`);
+        });
+        next();
+    };
+}
+exports.default = { json, formData, parseBody, logger };
+//# sourceMappingURL=misc.js.map