zero-http 0.2.4 → 0.3.1

package/lib/http/response.js

@@ -3,7 +3,33 @@
  * @description Lightweight wrapper around Node's `ServerResponse`.
  *              Provides chainable helpers for status, headers, and body output.
  */
+const fs = require('fs');
+const nodePath = require('path');
 const SSEStream = require('../sse/stream');
+const log = require('../debug')('zero:http');
+
+/** HTTP status code reason phrases. */
+const STATUS_CODES = {
+    200: 'OK', 201: 'Created', 204: 'No Content', 301: 'Moved Permanently',
+    302: 'Found', 304: 'Not Modified', 400: 'Bad Request', 401: 'Unauthorized',
+    403: 'Forbidden', 404: 'Not Found', 405: 'Method Not Allowed',
+    408: 'Request Timeout', 409: 'Conflict', 413: 'Payload Too Large',
+    415: 'Unsupported Media Type', 422: 'Unprocessable Entity',
+    429: 'Too Many Requests', 500: 'Internal Server Error',
+    502: 'Bad Gateway', 503: 'Service Unavailable', 504: 'Gateway Timeout',
+};
+
+/** Extension → MIME-type for sendFile/download. */
+const MIME_MAP = {
+    '.html': 'text/html', '.htm': 'text/html', '.css': 'text/css',
+    '.js': 'application/javascript', '.mjs': 'application/javascript',
+    '.json': 'application/json', '.txt': 'text/plain', '.xml': 'application/xml',
+    '.png': 'image/png', '.jpg': 'image/jpeg', '.jpeg': 'image/jpeg',
+    '.gif': 'image/gif', '.svg': 'image/svg+xml', '.webp': 'image/webp',
+    '.ico': 'image/x-icon', '.pdf': 'application/pdf', '.zip': 'application/zip',
+    '.mp4': 'video/mp4', '.webm': 'video/webm', '.mp3': 'audio/mpeg',
+    '.woff': 'font/woff', '.woff2': 'font/woff2', '.ttf': 'font/ttf',
+};
 
 /**
  * Wrapped HTTP response.
@@ -24,6 +50,14 @@ class Response
         this._headers = {};
         /** @type {boolean} */
         this._sent = false;
+        /** Request-scoped locals store. */
+        this.locals = {};
+        /**
+         * Reference to the parent App instance.
+         * Set by `app.handle()`.
+         * @type {import('../app')|null}
+         */
+        this.app = null;
     }
 
     /**
@@ -41,7 +75,18 @@ class Response
      * @param {string} value - Header value.
      * @returns {Response} `this` for chaining.
      */
-    set(name, value) { this._headers[name] = value; return this; }
+    set(name, value)
+    {
+        // Prevent CRLF header injection
+        const sName = String(name);
+        const sValue = String(value);
+        if (/[\r\n]/.test(sName) || /[\r\n]/.test(sValue))
+        {
+            throw new Error('Header values must not contain CR or LF characters');
+        }
+        this._headers[sName] = sValue;
+        return this;
+    }
 
     /**
      * Get a previously-set response header (case-insensitive).
@@ -51,8 +96,13 @@ class Response
      */
     get(name)
     {
-        const key = Object.keys(this._headers).find(k => k.toLowerCase() === name.toLowerCase());
-        return key ? this._headers[key] : undefined;
+        const lower = name.toLowerCase();
+        const keys = Object.keys(this._headers);
+        for (let i = 0; i < keys.length; i++)
+        {
+            if (keys[i].toLowerCase() === lower) return this._headers[keys[i]];
+        }
+        return undefined;
     }
 
     /**
@@ -87,9 +137,11 @@ class Response
     send(body)
     {
         if (this._sent) return;
+        log.debug('send %d', this._status);
         const res = this.raw;
 
-        Object.entries(this._headers).forEach(([k, v]) => res.setHeader(k, v));
+        const hdrKeys = Object.keys(this._headers);
+        for (let i = 0; i < hdrKeys.length; i++) res.setHeader(hdrKeys[i], this._headers[hdrKeys[i]]);
         res.statusCode = this._status;
 
         if (body === undefined || body === null)
@@ -112,7 +164,16 @@ class Response
             if (!hasContentType)
             {
                 // Heuristic: if it looks like HTML, set text/html
-                res.setHeader('Content-Type', body.trimStart().startsWith('<') ? 'text/html' : 'text/plain');
+                // Avoid trimStart() allocation — scan for first non-whitespace char
+                let isHTML = false;
+                for (let i = 0; i < body.length; i++)
+                {
+                    const c = body.charCodeAt(i);
+                    if (c === 32 || c === 9 || c === 10 || c === 13) continue;
+                    isHTML = c === 60; // '<'
+                    break;
+                }
+                res.setHeader('Content-Type', isHTML ? 'text/html' : 'text/plain');
             }
             res.end(body);
         }
@@ -120,7 +181,17 @@ class Response
         {
             // Object / array → JSON
             if (!hasContentType) res.setHeader('Content-Type', 'application/json');
-            res.end(JSON.stringify(body));
+            let json;
+            try { json = JSON.stringify(body); }
+            catch (e)
+            {
+                log.error('JSON.stringify failed: %s', e.message);
+                res.setHeader('Content-Type', 'application/json');
+                this._status = 500;
+                res.statusCode = 500;
+                json = JSON.stringify({ error: 'Failed to serialize response body' });
+            }
+            res.end(json);
         }
         this._sent = true;
     }
@@ -146,6 +217,339 @@ class Response
      */
     html(str) { this.set('Content-Type', 'text/html'); return this.send(String(str)); }
 
+    /**
+     * Send only the status code with the standard reason phrase as body.
+     * @param {number} code - HTTP status code.
+     */
+    sendStatus(code)
+    {
+        this._status = code;
+        const body = STATUS_CODES[code] || String(code);
+        this.type('text').send(body);
+    }
+
+    /**
+     * Append a value to a header. If the header already exists,
+     * creates a comma-separated list.
+     * @param {string} name  - Header name.
+     * @param {string} value - Header value to append.
+     * @returns {Response} `this` for chaining.
+     */
+    append(name, value)
+    {
+        const sValue = String(value);
+        if (/[\r\n]/.test(sValue))
+        {
+            throw new Error('Header values must not contain CR or LF characters');
+        }
+        const existing = this.get(name);
+        if (existing)
+        {
+            this._headers[name] = existing + ', ' + sValue;
+        }
+        else
+        {
+            this._headers[name] = sValue;
+        }
+        return this;
+    }
+
+    /**
+     * Add the given field to the Vary response header.
+     * @param {string} field - Header field name to add to Vary.
+     * @returns {Response} `this` for chaining.
+     */
+    vary(field)
+    {
+        const existing = this.get('Vary') || '';
+        if (existing === '*') return this;
+        if (field === '*') { this.set('Vary', '*'); return this; }
+        const fields = existing ? existing.split(/\s*,\s*/) : [];
+        if (!fields.some(f => f.toLowerCase() === field.toLowerCase()))
+        {
+            fields.push(field);
+        }
+        this.set('Vary', fields.join(', '));
+        return this;
+    }
+
+    /**
+     * Whether headers have been sent to the client.
+     * @type {boolean}
+     */
+    get headersSent()
+    {
+        return this.raw.headersSent;
+    }
+
+    /**
+     * Send a file as the response. Streams the file with proper Content-Type.
+     * @param {string}   filePath - Path to the file.
+     * @param {object}   [opts]
+     * @param {object}   [opts.headers]   - Additional headers to set.
+     * @param {string}   [opts.root]      - Root directory for relative paths.
+     * @param {Function} [cb]             - Callback `(err) => void`.
+     */
+    sendFile(filePath, opts, cb)
+    {
+        if (this._sent) return;
+        if (typeof opts === 'function') { cb = opts; opts = {}; }
+        if (!opts) opts = {};
+
+        let fullPath = opts.root ? nodePath.resolve(opts.root, filePath) : nodePath.resolve(filePath);
+
+        // Prevent path traversal
+        if (opts.root)
+        {
+            const resolvedRoot = nodePath.resolve(opts.root);
+            if (!fullPath.startsWith(resolvedRoot + nodePath.sep) && fullPath !== resolvedRoot)
+            {
+                const err = new Error('Forbidden');
+                err.status = 403;
+                if (cb) return cb(err);
+                return this.status(403).json({ error: 'Forbidden' });
+            }
+        }
+
+        if (fullPath.indexOf('\0') !== -1)
+        {
+            const err = new Error('Bad Request');
+            err.status = 400;
+            if (cb) return cb(err);
+            return this.status(400).json({ error: 'Bad Request' });
+        }
+
+        fs.stat(fullPath, (err, stat) =>
+        {
+            if (err || !stat.isFile())
+            {
+                const e = err || new Error('Not Found');
+                e.status = 404;
+                if (cb) return cb(e);
+                return this.status(404).json({ error: 'Not Found' });
+            }
+
+            const ext = nodePath.extname(fullPath).toLowerCase();
+            const ct = MIME_MAP[ext] || 'application/octet-stream';
+
+            const raw = this.raw;
+            const hk = Object.keys(this._headers);
+            for (let i = 0; i < hk.length; i++) raw.setHeader(hk[i], this._headers[hk[i]]);
+            if (opts.headers)
+            {
+                const ok = Object.keys(opts.headers);
+                for (let i = 0; i < ok.length; i++) raw.setHeader(ok[i], opts.headers[ok[i]]);
+            }
+            raw.setHeader('Content-Type', ct);
+            raw.setHeader('Content-Length', stat.size);
+            raw.statusCode = this._status;
+
+            const stream = fs.createReadStream(fullPath);
+            stream.on('error', (e) =>
+            {
+                if (cb) return cb(e);
+                try { raw.statusCode = 500; raw.end(); } catch (ex) { }
+            });
+            stream.on('end', () =>
+            {
+                this._sent = true;
+                if (cb) cb(null);
+            });
+            stream.pipe(raw);
+        });
+    }
+
+    /**
+     * Prompt a file download. Sets Content-Disposition: attachment.
+     * @param {string}   filePath  - Path to the file.
+     * @param {string}   [filename] - Override the download filename.
+     * @param {Function} [cb]       - Callback on complete/error.
+     */
+    download(filePath, filename, cb)
+    {
+        if (typeof filename === 'function') { cb = filename; filename = undefined; }
+        const name = filename || nodePath.basename(filePath);
+        this.set('Content-Disposition', `attachment; filename="${name.replace(/"/g, '\\"')}"`);
+        this.sendFile(filePath, {}, cb);
+    }
+
+    /**
+     * Set a cookie on the response.
+     *
+     * @param {string}      name    - Cookie name.
+     * @param {*}           value   - Cookie value (strings, objects/arrays auto-serialise as JSON cookies).
+     * @param {object}      [opts]
+     * @param {string}       [opts.domain]         - Cookie domain.
+     * @param {string}       [opts.path='/']       - Cookie path.
+     * @param {Date|number}  [opts.expires]        - Expiration date.
+     * @param {number}       [opts.maxAge]         - Max-Age in seconds.
+     * @param {boolean}      [opts.httpOnly=true]  - HTTP-only flag (default: true for security).
+     * @param {boolean}      [opts.secure]         - Secure flag.
+     * @param {string}       [opts.sameSite='Lax'] - SameSite attribute (Strict, Lax, None).
+     * @param {boolean}      [opts.signed]         - Sign the cookie value using req.secret.
+     * @param {string}       [opts.priority]       - Priority attribute (Low, Medium, High).
+     * @param {boolean}      [opts.partitioned]    - Partitioned/CHIPS attribute.
+     * @returns {Response} `this` for chaining.
+     *
+     * @example
+     *   res.cookie('name', 'value');
+     *   res.cookie('prefs', { theme: 'dark' });           // auto JSON cookie
+     *   res.cookie('token', 'abc', { signed: true });     // auto-signed
+     *   res.cookie('sid', 'xyz', { secure: true, sameSite: 'Strict' });
+     */
+    cookie(name, value, opts = {})
+    {
+        if (/[=;,\s]/.test(name))
+        {
+            throw new Error('Cookie name must not contain =, ;, comma, or whitespace');
+        }
+
+        // Auto-serialize objects/arrays as JSON cookies (j: prefix)
+        let val = value;
+        if (typeof val === 'object' && val !== null && !(val instanceof Date))
+        {
+            val = 'j:' + JSON.stringify(val);
+        }
+        else
+        {
+            val = String(val);
+        }
+
+        // Auto-sign when opts.signed is true
+        if (opts.signed)
+        {
+            const secret = (this._req && this._req.secret) || (opts.secret);
+            if (!secret) throw new Error('cookieParser(secret) required for signed cookies');
+            const crypto = require('crypto');
+            const sig = crypto
+                .createHmac('sha256', secret)
+                .update(val)
+                .digest('base64')
+                .replace(/=+$/, '');
+            val = `s:${val}.${sig}`;
+        }
+
+        let cookie = `${encodeURIComponent(name)}=${encodeURIComponent(val)}`;
+
+        if (opts.domain) cookie += `; Domain=${opts.domain}`;
+        cookie += `; Path=${opts.path || '/'}`;
+
+        if (opts.maxAge !== undefined)
+        {
+            cookie += `; Max-Age=${Math.floor(opts.maxAge)}`;
+        }
+        else if (opts.expires)
+        {
+            const expires = opts.expires instanceof Date ? opts.expires : new Date(opts.expires);
+            cookie += `; Expires=${expires.toUTCString()}`;
+        }
+
+        if (opts.httpOnly !== false) cookie += '; HttpOnly';
+        if (opts.secure) cookie += '; Secure';
+        cookie += `; SameSite=${opts.sameSite || 'Lax'}`;
+        if (opts.priority) cookie += `; Priority=${opts.priority}`;
+        if (opts.partitioned) cookie += '; Partitioned';
+
+        const raw = this.raw;
+        const existing = raw.getHeader('Set-Cookie');
+        if (existing)
+        {
+            const arr = Array.isArray(existing) ? existing : [existing];
+            arr.push(cookie);
+            raw.setHeader('Set-Cookie', arr);
+        }
+        else
+        {
+            raw.setHeader('Set-Cookie', cookie);
+        }
+
+        return this;
+    }
+
+    /**
+     * Clear a cookie by setting it to expire in the past.
+     * @param {string} name  - Cookie name.
+     * @param {object} [opts] - Must match path/domain of the original cookie.
+     * @returns {Response} `this` for chaining.
+     */
+    clearCookie(name, opts = {})
+    {
+        return this.cookie(name, '', { ...opts, expires: new Date(0), maxAge: 0 });
+    }
+
+    /**
+     * Respond with content-negotiated output based on the request Accept header.
+     * Calls the handler matching the best accepted type.
+     *
+     * @param {Object<string, Function>} types - Map of MIME types to handler functions.
+     *
+     * @example
+     *   res.format({
+     *       'text/html': () => res.html('<h1>Hello</h1>'),
+     *       'application/json': () => res.json({ hello: 'world' }),
+     *       default: () => res.status(406).send('Not Acceptable'),
+     *   });
+     */
+    format(types)
+    {
+        const req = this._req;
+        const accept = (req && req.headers && req.headers['accept']) || '*/*';
+
+        for (const [type, handler] of Object.entries(types))
+        {
+            if (type === 'default') continue;
+            if (accept === '*/*' || accept.indexOf('*/*') !== -1 || accept.indexOf(type) !== -1)
+            {
+                this.type(type);
+                return handler();
+            }
+            // Check main-type wildcard (e.g. text/*)
+            const mainType = type.split('/')[0];
+            if (accept.indexOf(mainType + '/*') !== -1)
+            {
+                this.type(type);
+                return handler();
+            }
+        }
+
+        if (types.default) return types.default();
+        this.status(406).json({ error: 'Not Acceptable' });
+    }
+
+    /**
+     * Set the Link response header with the given links.
+     *
+     * @param {Object<string, string>} links - Map of rel → URL.
+     * @returns {Response} `this` for chaining.
+     *
+     * @example
+     *   res.links({
+     *       next: '/api/users?page=2',
+     *       last: '/api/users?page=5',
+     *   });
+     *   // Link: </api/users?page=2>; rel="next", </api/users?page=5>; rel="last"
+     */
+    links(links)
+    {
+        const parts = Object.entries(links).map(([rel, url]) => `<${url}>; rel="${rel}"`);
+        const existing = this.get('Link');
+        const value = existing ? existing + ', ' + parts.join(', ') : parts.join(', ');
+        this.set('Link', value);
+        return this;
+    }
+
+    /**
+     * Set the Location response header.
+     *
+     * @param {string} url - The URL to set.
+     * @returns {Response} `this` for chaining.
+     */
+    location(url)
+    {
+        this.set('Location', url);
+        return this;
+    }
+
     /**
      * Redirect to the given URL with an optional status code (default 302).
      * @param {number|string} statusOrUrl - Status code or URL.

package/lib/middleware/compress.js

@@ -5,6 +5,7 @@
  *              Zero external dependencies.
  */
 const zlib = require('zlib');
+const log = require('../debug')('zero:compress');
 
 /**
  * Default minimum response size (in bytes) to bother compressing.
@@ -45,18 +46,44 @@ function compress(opts = {})
 
     /**
      * Choose the best encoding from the Accept-Encoding header.
-     * Priority: br > gzip > deflate.
+     * Parses quality values (RFC 7231) and picks the highest-priority match.
+     * Priority when equal quality: br > gzip > deflate.
      * @param {string} header
      * @returns {string|null}
      */
     function negotiate(header)
     {
         if (!header) return null;
-        const h = header.toLowerCase();
-        if (hasBrotli && h.includes('br')) return 'br';
-        if (h.includes('gzip')) return 'gzip';
-        if (h.includes('deflate')) return 'deflate';
-        return null;
+        const encodings = { br: 0, gzip: 0, deflate: 0 };
+        const parts = header.toLowerCase().split(',');
+        for (let i = 0; i < parts.length; i++)
+        {
+            const part = parts[i].trim();
+            const semi = part.indexOf(';');
+            const name = (semi !== -1 ? part.substring(0, semi).trim() : part);
+            let q = 1;
+            if (semi !== -1)
+            {
+                const qMatch = /q\s*=\s*([0-9.]+)/.exec(part.substring(semi));
+                if (qMatch) q = parseFloat(qMatch[1]);
+            }
+            if (name in encodings) encodings[name] = q;
+        }
+        // Filter available encodings
+        if (!hasBrotli) encodings.br = 0;
+        // Pick highest quality; break ties with priority order
+        let best = null;
+        let bestQ = 0;
+        const order = hasBrotli ? ['br', 'gzip', 'deflate'] : ['gzip', 'deflate'];
+        for (let i = 0; i < order.length; i++)
+        {
+            if (encodings[order[i]] > bestQ)
+            {
+                bestQ = encodings[order[i]];
+                best = order[i];
+            }
+        }
+        return best;
     }
 
     /**
@@ -131,9 +158,15 @@ function compress(opts = {})
             raw.removeHeader('Content-Length');
             raw.setHeader('Content-Encoding', encoding);
             raw.setHeader('Vary', 'Accept-Encoding');
+            log.debug('compressing with %s', encoding);
 
             compressStream.on('data', (chunk) => origWrite(chunk));
             compressStream.on('end', () => origEnd());
+            compressStream.on('error', (err) =>
+            {                log.error('compression error: %s', err.message);                // On compression error, remove encoding header and end raw stream
+                try { raw.removeHeader('Content-Encoding'); } catch (e) { }
+                try { origEnd(); } catch (e) { }
+            });
             return true;
         }