zero-http 0.2.5 → 0.3.1

package/lib/middleware/index.js

@@ -1,12 +1,17 @@
 /**
  * @module middleware
  * @description Built-in middleware for zero-http.
- *              Re-exports cors, logger, rateLimit, compress, and static file serving.
+ *              Re-exports all middleware.
  */
 const cors = require('./cors');
 const logger = require('./logger');
 const rateLimit = require('./rateLimit');
 const compress = require('./compress');
 const serveStatic = require('./static');
+const helmet = require('./helmet');
+const timeout = require('./timeout');
+const requestId = require('./requestId');
+const cookieParser = require('./cookieParser');
+const errorHandler = require('./errorHandler');
 
-module.exports = { cors, logger, rateLimit, compress, static: serveStatic };
+module.exports = { cors, logger, rateLimit, compress, static: serveStatic, helmet, timeout, requestId, cookieParser, errorHandler };

package/lib/middleware/rateLimit.js

@@ -1,6 +1,6 @@
 /**
  * In-memory rate-limiting middleware.
- * Limits requests per IP address within a sliding window.
+ * Limits requests per IP address within a fixed time window.
  *
  * @param {object}  [opts]
  * @param {number}  [opts.windowMs=60000]   - Time window in milliseconds.
@@ -8,8 +8,12 @@
  * @param {string}  [opts.message]          - Custom error message.
  * @param {number}  [opts.statusCode=429]   - HTTP status for rate-limited responses.
  * @param {function} [opts.keyGenerator]    - (req) => string; custom key extraction (default: req.ip).
+ * @param {function} [opts.skip]            - (req) => boolean; return true to skip rate limiting.
+ * @param {function} [opts.handler]         - (req, res) => void; custom handler for rate-limited requests.
  * @returns {function} Middleware function.
  */
+const log = require('../debug')('zero:rateLimit');
+
 function rateLimit(opts = {})
 {
     const windowMs = opts.windowMs || 60_000;
@@ -17,6 +21,8 @@ function rateLimit(opts = {})
     const statusCode = opts.statusCode || 429;
     const message = opts.message || 'Too many requests, please try again later.';
     const keyGenerator = typeof opts.keyGenerator === 'function' ? opts.keyGenerator : (req) => req.ip || 'unknown';
+    const skipFn = typeof opts.skip === 'function' ? opts.skip : null;
+    const handlerFn = typeof opts.handler === 'function' ? opts.handler : null;
 
     const hits = new Map(); // key → { count, resetTime }
 
@@ -33,6 +39,9 @@ function rateLimit(opts = {})
 
     return (req, res, next) =>
     {
+        // Allow skipping rate limit for certain requests
+        if (skipFn && skipFn(req)) return next();
+
         const key = keyGenerator(req);
         const now = Date.now();
         let entry = hits.get(key);
@@ -53,7 +62,9 @@ function rateLimit(opts = {})
 
         if (entry.count > max)
         {
+            log.warn('rate limit exceeded for %s', key);
             res.set('Retry-After', String(Math.ceil(windowMs / 1000)));
+            if (handlerFn) return handlerFn(req, res);
             return res.status(statusCode).json({ error: message });
         }
 

package/lib/middleware/requestId.js

@@ -0,0 +1,54 @@
+/**
+ * @module requestId
+ * @description Request ID middleware.
+ *              Assigns a unique identifier to each incoming request for
+ *              tracing and debugging. Sets the ID on both the request
+ *              object and as a response header.
+ */
+const crypto = require('crypto');
+
+/**
+ * Create a request ID middleware.
+ *
+ * @param {object}   [opts]
+ * @param {string}   [opts.header='X-Request-Id']   - Response header name.
+ * @param {Function} [opts.generator]               - Custom ID generator `() => string`.
+ * @param {boolean}  [opts.trustProxy=false]         - Trust incoming X-Request-Id header from proxy.
+ * @returns {Function} Middleware `(req, res, next) => void`.
+ *
+ * @example
+ *   app.use(requestId());
+ *   app.get('/', (req, res) => {
+ *       console.log(req.id); // e.g. '7f3a2b1c-...'
+ *   });
+ */
+function requestId(opts = {})
+{
+    const headerName = opts.header || 'X-Request-Id';
+    const trustProxy = !!opts.trustProxy;
+    const generator = typeof opts.generator === 'function'
+        ? opts.generator
+        : () => crypto.randomUUID();
+
+    return (req, res, next) =>
+    {
+        let id;
+
+        if (trustProxy)
+        {
+            const existing = req.headers[headerName.toLowerCase()];
+            if (existing && typeof existing === 'string' && existing.length <= 128)
+            {
+                id = existing;
+            }
+        }
+
+        if (!id) id = generator();
+
+        req.id = id;
+        res.set(headerName, id);
+        next();
+    };
+}
+
+module.exports = requestId;

package/lib/middleware/static.js

@@ -6,6 +6,7 @@
  */
 const fs = require('fs');
 const path = require('path');
+const log = require('../debug')('zero:static');
 
 /**
  * Extension → MIME-type lookup table.
@@ -78,14 +79,25 @@ const MIME = {
 };
 
 /**
- * Stream a file to the raw Node response, setting Content-Type and
- * Content-Length headers from the extension and optional `stat` result.
+ * Generate a weak ETag from file stats (mtime + size).
+ * @param {import('fs').Stats} stat
+ * @returns {string}
+ */
+function generateETag(stat)
+{
+    return 'W/"' + stat.size.toString(16) + '-' + stat.mtimeMs.toString(16) + '"';
+}
+
+/**
+ * Stream a file to the raw Node response, setting Content-Type,
+ * Content-Length, ETag, and Last-Modified headers.
  *
  * @param {import('./response')} res      - Wrapped response object.
  * @param {string}               filePath - Absolute path to the file.
  * @param {import('fs').Stats}   [stat]   - Pre-fetched `fs.Stats` (for Content-Length).
+ * @param {import('./request')}  [req]    - Wrapped request (for conditional checks).
  */
-function sendFile(res, filePath, stat)
+function sendFile(res, filePath, stat, req)
 {
     const ext = path.extname(filePath).toLowerCase();
     const ct = MIME[ext] || 'application/octet-stream';
@@ -93,11 +105,77 @@ function sendFile(res, filePath, stat)
     try
     {
         raw.setHeader('Content-Type', ct);
-        if (stat && stat.size) raw.setHeader('Content-Length', stat.size);
+        if (stat)
+        {
+            if (stat.size) raw.setHeader('Content-Length', stat.size);
+            // ETag and Last-Modified for caching
+            const etag = generateETag(stat);
+            raw.setHeader('ETag', etag);
+            raw.setHeader('Last-Modified', stat.mtime.toUTCString());
+            raw.setHeader('Accept-Ranges', 'bytes');
+
+            // Conditional request handling (304 Not Modified)
+            if (req)
+            {
+                const ifNoneMatch = req.headers['if-none-match'];
+                const ifModifiedSince = req.headers['if-modified-since'];
+                if (ifNoneMatch && ifNoneMatch === etag)
+                {
+                    raw.statusCode = 304;
+                    raw.end();
+                    return;
+                }
+                if (ifModifiedSince && !ifNoneMatch)
+                {
+                    const since = Date.parse(ifModifiedSince);
+                    if (!isNaN(since) && stat.mtimeMs <= since)
+                    {
+                        raw.statusCode = 304;
+                        raw.end();
+                        return;
+                    }
+                }
+
+                // Range request support (HTTP 206)
+                const rangeHeader = req.headers['range'];
+                if (rangeHeader && stat.size > 0)
+                {
+                    const match = /^bytes=(\d*)-(\d*)$/.exec(rangeHeader);
+                    if (match)
+                    {
+                        let start = match[1] ? parseInt(match[1], 10) : 0;
+                        let end = match[2] ? parseInt(match[2], 10) : stat.size - 1;
+                        if (!match[1] && match[2])
+                        {
+                            // suffix range: bytes=-500 means last 500 bytes
+                            start = Math.max(0, stat.size - parseInt(match[2], 10));
+                            end = stat.size - 1;
+                        }
+                        if (start > end || start >= stat.size || end >= stat.size)
+                        {
+                            raw.statusCode = 416;
+                            raw.setHeader('Content-Range', 'bytes */' + stat.size);
+                            raw.setHeader('Content-Length', 0);
+                            raw.end();
+                            return;
+                        }
+                        raw.statusCode = 206;
+                        raw.setHeader('Content-Range', 'bytes ' + start + '-' + end + '/' + stat.size);
+                        raw.setHeader('Content-Length', end - start + 1);
+                        const stream = fs.createReadStream(filePath, { start, end });
+                        stream.on('error', (err) => { log.warn('file read error %s: %s', filePath, err.message); try { raw.statusCode = 404; raw.end(); } catch (e) { } });
+                        log.debug('serving %s (range %d-%d)', filePath, start, end);
+                        stream.pipe(raw);
+                        return;
+                    }
+                }
+            }
+        }
     }
     catch (e) { /* best-effort */ }
     const stream = fs.createReadStream(filePath);
-    stream.on('error', () => { try { raw.statusCode = 404; raw.end(); } catch (e) { } });
+    stream.on('error', (err) => { log.warn('file read error %s: %s', filePath, err.message); try { raw.statusCode = 404; raw.end(); } catch (e) { } });
+    log.debug('serving %s', filePath);
     stream.pipe(raw);
 }
 
@@ -136,9 +214,15 @@ function serveStatic(root, options = {})
     return (req, res, next) =>
     {
         if (req.method !== 'GET' && req.method !== 'HEAD') return next();
-        const urlPath = decodeURIComponent(req.url.split('?')[0]);
-        let file = path.join(root, urlPath);
-        if (!file.startsWith(root)) return res.status(403).json({ error: 'Forbidden' });
+        let urlPath;
+        try { urlPath = decodeURIComponent(req.url.split('?')[0]); } catch (e) { return res.status(400).json({ error: 'Bad Request' }); }
+
+        // Block null bytes (poison byte attack)
+        if (urlPath.indexOf('\0') !== -1) return res.status(400).json({ error: 'Bad Request' });
+
+        let file = path.resolve(root, '.' + path.sep + urlPath);
+        // Normalize and verify the resolved path is within root (prevents path traversal)
+        if (!file.startsWith(root + path.sep) && file !== root) return res.status(403).json({ error: 'Forbidden' });
 
         if (isDotfile(file) && dotfiles === 'deny') return res.status(403).json({ error: 'Forbidden' });
 
@@ -160,7 +244,7 @@ function serveStatic(root, options = {})
                             {
                                 if (isDotfile(f) && dotfiles === 'deny') return res.status(403).json({ error: 'Forbidden' });
                                 applyHeaders(res, f);
-                                return sendFile(res, f, st2);
+                                return sendFile(res, f, st2, req);
                             }
                             tryExt(i + 1);
                         });
@@ -179,7 +263,7 @@ function serveStatic(root, options = {})
                     if (err2) return next();
                     if (isDotfile(idxFile) && dotfiles === 'deny') return res.status(403).json({ error: 'Forbidden' });
                     applyHeaders(res, idxFile);
-                    sendFile(res, idxFile, st2);
+                    sendFile(res, idxFile, st2, req);
                 });
             }
             else
@@ -187,7 +271,7 @@ function serveStatic(root, options = {})
                 if (isDotfile(file) && dotfiles === 'ignore') return next();
                 if (isDotfile(file) && dotfiles === 'deny') return res.status(403).json({ error: 'Forbidden' });
                 applyHeaders(res, file);
-                sendFile(res, file, st);
+                sendFile(res, file, st, req);
             }
         });
     };

package/lib/middleware/timeout.js

@@ -0,0 +1,72 @@
+/**
+ * @module timeout
+ * @description Request timeout middleware.
+ *              Automatically sends a 408 response if the handler doesn't
+ *              respond within the configured time limit.
+ *              Helps prevent Slowloris-style attacks and hung requests.
+ */
+
+/**
+ * Create a request timeout middleware.
+ *
+ * @param {number}  [ms=30000]        - Timeout in milliseconds (default 30s).
+ * @param {object}  [opts]
+ * @param {number}  [opts.status=408] - HTTP status code for timeout responses.
+ * @param {string}  [opts.message='Request Timeout'] - Error message body.
+ * @returns {Function} Middleware `(req, res, next) => void`.
+ *
+ * @example
+ *   app.use(timeout(5000)); // 5 second timeout
+ *   app.use(timeout(10000, { message: 'Too slow' }));
+ */
+const log = require('../debug')('zero:timeout');
+
+function timeout(ms = 30000, opts = {})
+{
+    if (typeof ms === 'object') { opts = ms; ms = 30000; }
+
+    const statusCode = opts.status || 408;
+    const message = opts.message || 'Request Timeout';
+
+    return (req, res, next) =>
+    {
+        let timedOut = false;
+
+        const timer = setTimeout(() =>
+        {
+            timedOut = true;
+            req._timedOut = true;
+            log.warn('request timed out after %dms: %s %s', ms, req.method, req.url);
+
+            // Only send response if headers haven't been sent yet
+            if (!res.headersSent && !res._sent)
+            {
+                res.status(statusCode).json({ error: message });
+            }
+        }, ms);
+
+        // Unref so the timer doesn't keep the process alive
+        if (timer.unref) timer.unref();
+
+        // Clear timeout when response finishes
+        const raw = res.raw;
+        const onFinish = () =>
+        {
+            clearTimeout(timer);
+            raw.removeListener('finish', onFinish);
+            raw.removeListener('close', onFinish);
+        };
+        raw.on('finish', onFinish);
+        raw.on('close', onFinish);
+
+        // Expose timedOut check on request
+        Object.defineProperty(req, 'timedOut', {
+            get() { return timedOut; },
+            configurable: true,
+        });
+
+        next();
+    };
+}
+
+module.exports = timeout;

package/lib/middleware/validator.js

@@ -0,0 +1,257 @@
+/**
+ * @module middleware/validator
+ * @description Request validation middleware.
+ *              Validates `req.body`, `req.query`, and `req.params` against a
+ *              schema object.  Returns 422 with detailed errors on failure.
+ *
+ * @example
+ *   const { createApp, validate } = require('zero-http');
+ *   const app = createApp();
+ *
+ *   app.post('/users', validate({
+ *       body: {
+ *           name:  { type: 'string', required: true, minLength: 1, maxLength: 100 },
+ *           email: { type: 'string', required: true, match: /^[^@]+@[^@]+\.[^@]+$/ },
+ *           age:   { type: 'integer', min: 0, max: 150 },
+ *       },
+ *       query: {
+ *           format: { type: 'string', enum: ['json', 'xml'], default: 'json' },
+ *       },
+ *   }), (req, res) => {
+ *       // req.body / req.query are now validated and sanitised
+ *   });
+ */
+
+/**
+ * Supported shorthand types for validation rules.
+ * @private
+ */
+const COERCE = {
+    string(v)  { return v == null ? v : String(v); },
+    integer(v) { const n = parseInt(v, 10); return Number.isNaN(n) ? v : n; },
+    number(v)  { const n = Number(v); return Number.isNaN(n) ? v : n; },
+    float(v)   { const n = parseFloat(v); return Number.isNaN(n) ? v : n; },
+    boolean(v)
+    {
+        if (typeof v === 'boolean') return v;
+        if (typeof v === 'string')
+        {
+            const l = v.toLowerCase();
+            if (l === 'true' || l === '1' || l === 'yes' || l === 'on') return true;
+            if (l === 'false' || l === '0' || l === 'no' || l === 'off') return false;
+        }
+        return v;
+    },
+    array(v)
+    {
+        if (Array.isArray(v)) return v;
+        if (typeof v === 'string')
+        {
+            try { const p = JSON.parse(v); if (Array.isArray(p)) return p; } catch {}
+            return v.split(',').map(s => s.trim());
+        }
+        return v;
+    },
+    json(v)
+    {
+        if (typeof v === 'string') { try { return JSON.parse(v); } catch {} }
+        return v;
+    },
+    date(v)
+    {
+        if (v instanceof Date) return v;
+        const d = new Date(v);
+        return Number.isNaN(d.getTime()) ? v : d;
+    },
+    uuid(v)   { return v == null ? v : String(v); },
+    email(v)  { return v == null ? v : String(v).trim().toLowerCase(); },
+    url(v)    { return v == null ? v : String(v).trim(); },
+};
+
+/**
+ * Validate a single value against a rule definition.
+ *
+ * @param {*}      value    - Raw input value.
+ * @param {object} rule     - Rule definition.
+ * @param {string} field    - Field name (for error messages).
+ * @returns {{ value: *, error: string|null }}
+ * @private
+ */
+function validateField(value, rule, field)
+{
+    // Apply default
+    if ((value === undefined || value === null || value === '') && rule.default !== undefined)
+    {
+        value = typeof rule.default === 'function' ? rule.default() : rule.default;
+    }
+
+    // Required check
+    if (rule.required && (value === undefined || value === null || value === ''))
+    {
+        return { value, error: `${field} is required` };
+    }
+
+    // If not required and absent, skip further checks
+    if (value === undefined || value === null) return { value, error: null };
+
+    // Type coercion
+    if (rule.type && COERCE[rule.type]) value = COERCE[rule.type](value);
+
+    // Type validation
+    if (rule.type)
+    {
+        switch (rule.type)
+        {
+            case 'string':
+                if (typeof value !== 'string') return { value, error: `${field} must be a string` };
+                break;
+            case 'integer':
+                if (!Number.isInteger(value)) return { value, error: `${field} must be an integer` };
+                break;
+            case 'number':
+            case 'float':
+                if (typeof value !== 'number' || Number.isNaN(value)) return { value, error: `${field} must be a number` };
+                break;
+            case 'boolean':
+                if (typeof value !== 'boolean') return { value, error: `${field} must be a boolean` };
+                break;
+            case 'array':
+                if (!Array.isArray(value)) return { value, error: `${field} must be an array` };
+                break;
+            case 'date':
+                if (!(value instanceof Date)) return { value, error: `${field} must be a valid date` };
+                break;
+            case 'email':
+                if (typeof value !== 'string' || !/^[^\s@]+@[^\s@]+\.[^\s@]+$/.test(value))
+                    return { value, error: `${field} must be a valid email` };
+                break;
+            case 'url':
+                try { new URL(value); }
+                catch { return { value, error: `${field} must be a valid URL` }; }
+                break;
+            case 'uuid':
+                if (!/^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i.test(value))
+                    return { value, error: `${field} must be a valid UUID` };
+                break;
+        }
+    }
+
+    // Constraints
+    if (rule.minLength !== undefined && typeof value === 'string' && value.length < rule.minLength)
+        return { value, error: `${field} must be at least ${rule.minLength} characters` };
+    if (rule.maxLength !== undefined && typeof value === 'string' && value.length > rule.maxLength)
+        return { value, error: `${field} must be at most ${rule.maxLength} characters` };
+    if (rule.min !== undefined && typeof value === 'number' && value < rule.min)
+        return { value, error: `${field} must be >= ${rule.min}` };
+    if (rule.max !== undefined && typeof value === 'number' && value > rule.max)
+        return { value, error: `${field} must be <= ${rule.max}` };
+    if (rule.match && typeof value === 'string' && !rule.match.test(value))
+        return { value, error: `${field} format is invalid` };
+    if (rule.enum && !rule.enum.includes(value))
+        return { value, error: `${field} must be one of: ${rule.enum.join(', ')}` };
+    if (rule.minItems !== undefined && Array.isArray(value) && value.length < rule.minItems)
+        return { value, error: `${field} must have at least ${rule.minItems} items` };
+    if (rule.maxItems !== undefined && Array.isArray(value) && value.length > rule.maxItems)
+        return { value, error: `${field} must have at most ${rule.maxItems} items` };
+
+    // Custom validator function
+    if (typeof rule.validate === 'function')
+    {
+        const msg = rule.validate(value);
+        if (typeof msg === 'string') return { value, error: msg };
+    }
+
+    return { value, error: null };
+}
+
+/**
+ * Validate an object against a schema.
+ *
+ * @param {object} data   - Input data.
+ * @param {object} schema - { fieldName: ruleObject }
+ * @param {object} [opts]
+ * @param {boolean} [opts.stripUnknown=true] - Remove fields not in schema.
+ * @returns {{ sanitized: object, errors: string[] }}
+ * @private
+ */
+function validateObject(data, schema, opts = {})
+{
+    const errors = [];
+    const sanitized = {};
+    const stripUnknown = opts.stripUnknown !== false;
+    const source = data || {};
+
+    for (const [field, rule] of Object.entries(schema))
+    {
+        const { value, error } = validateField(source[field], rule, field);
+        if (error) errors.push(error);
+        else if (value !== undefined) sanitized[field] = value;
+    }
+
+    // Preserve unknown fields if not stripping
+    if (!stripUnknown)
+    {
+        for (const key of Object.keys(source))
+        {
+            if (!(key in schema)) sanitized[key] = source[key];
+        }
+    }
+
+    return { sanitized, errors };
+}
+
+/**
+ * Create a validation middleware.
+ *
+ * @param {object} schema
+ * @param {object} [schema.body]   - Rules for req.body fields.
+ * @param {object} [schema.query]  - Rules for req.query fields.
+ * @param {object} [schema.params] - Rules for req.params fields.
+ * @param {object} [options]
+ * @param {boolean}  [options.stripUnknown=true] - Remove fields not in schema.
+ * @param {Function} [options.onError]           - Custom error handler `(errors, req, res) => {}`.
+ * @returns {Function} Middleware function.
+ */
+function validate(schema, options = {})
+{
+    return function validatorMiddleware(req, res, next)
+    {
+        const allErrors = [];
+
+        if (schema.body)
+        {
+            const { sanitized, errors } = validateObject(req.body, schema.body, options);
+            if (errors.length) allErrors.push(...errors.map(e => `body.${e}`));
+            else req.body = sanitized;
+        }
+
+        if (schema.query)
+        {
+            const { sanitized, errors } = validateObject(req.query, schema.query, options);
+            if (errors.length) allErrors.push(...errors.map(e => `query.${e}`));
+            else req.query = sanitized;
+        }
+
+        if (schema.params)
+        {
+            const { sanitized, errors } = validateObject(req.params, schema.params, options);
+            if (errors.length) allErrors.push(...errors.map(e => `params.${e}`));
+            else req.params = sanitized;
+        }
+
+        if (allErrors.length > 0)
+        {
+            if (options.onError) return options.onError(allErrors, req, res);
+            res.status(422).json({ errors: allErrors });
+            return;
+        }
+
+        next();
+    };
+}
+
+// Also export helpers for standalone use
+validate.field = validateField;
+validate.object = validateObject;
+
+module.exports = validate;