@zero-server/middleware 0.9.0 → 0.9.2

package/lib/middleware/static.js

@@ -0,0 +1,326 @@
+/**
+ * @module static
+ * @description Static file-serving middleware with MIME detection, directory
+ *              index files, extension fallbacks, dotfile policies, caching,
+ *              custom header hooks, and HTTP/2 server push for linked assets.
+ */
+const fs = require('fs');
+const path = require('path');
+const log = require('../debug')('zero:static');
+
+/**
+ * Extension → MIME-type lookup table.
+ * @type {Object<string, string>}
+ */
+const MIME = {
+    // Text
+    '.html': 'text/html',
+    '.htm': 'text/html',
+    '.css': 'text/css',
+    '.txt': 'text/plain',
+    '.csv': 'text/csv',
+    '.xml': 'application/xml',
+    '.json': 'application/json',
+    '.jsonld': 'application/ld+json',
+
+    // JavaScript / WASM
+    '.js': 'application/javascript',
+    '.mjs': 'application/javascript',
+    '.wasm': 'application/wasm',
+
+    // Images
+    '.png': 'image/png',
+    '.jpg': 'image/jpeg',
+    '.jpeg': 'image/jpeg',
+    '.gif': 'image/gif',
+    '.webp': 'image/webp',
+    '.avif': 'image/avif',
+    '.svg': 'image/svg+xml',
+    '.ico': 'image/x-icon',
+    '.bmp': 'image/bmp',
+    '.tiff': 'image/tiff',
+    '.tif': 'image/tiff',
+
+    // Fonts
+    '.woff': 'font/woff',
+    '.woff2': 'font/woff2',
+    '.ttf': 'font/ttf',
+    '.otf': 'font/otf',
+    '.eot': 'application/vnd.ms-fontobject',
+
+    // Audio
+    '.mp3': 'audio/mpeg',
+    '.ogg': 'audio/ogg',
+    '.wav': 'audio/wav',
+    '.flac': 'audio/flac',
+    '.aac': 'audio/aac',
+    '.m4a': 'audio/mp4',
+
+    // Video
+    '.mp4': 'video/mp4',
+    '.webm': 'video/webm',
+    '.ogv': 'video/ogg',
+    '.avi': 'video/x-msvideo',
+    '.mov': 'video/quicktime',
+
+    // Documents / Archives
+    '.pdf': 'application/pdf',
+    '.zip': 'application/zip',
+    '.gz': 'application/gzip',
+    '.tar': 'application/x-tar',
+    '.7z': 'application/x-7z-compressed',
+
+    // Other
+    '.map': 'application/json',
+    '.yaml': 'text/yaml',
+    '.yml': 'text/yaml',
+    '.md': 'text/markdown',
+    '.sh': 'application/x-sh',
+};
+
+/**
+ * Generate a weak ETag from file stats (mtime + size).
+ * @private
+ * @param {import('fs').Stats} stat - File system stat object.
+ * @returns {string} Weak ETag string (e.g. `W/"1a2b-3c4d"`).
+ */
+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.
+ *
+ * @private
+ * @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, req)
+{
+    const ext = path.extname(filePath).toLowerCase();
+    const ct = MIME[ext] || 'application/octet-stream';
+    const raw = res.raw;
+    try
+    {
+        raw.setHeader('Content-Type', ct);
+        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', (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);
+}
+
+/**
+ * Create a static-file-serving middleware.
+ *
+ * @param {string} root              - Root directory to serve files from.
+ * @param {object} [options] - Configuration options.
+ * @param {string|false}  [options.index='index.html'] - Default file for directory requests, or `false` to disable.
+ * @param {number}        [options.maxAge=0]           - `Cache-Control` max-age in **milliseconds**.
+ * @param {string}        [options.dotfiles='ignore']  - Dotfile policy: `'allow'` | `'deny'` | `'ignore'`.
+ * @param {string[]}      [options.extensions]         - Array of fallback extensions (e.g. `['html', 'htm']`).
+ * @param {Function}      [options.setHeaders]         - `(res, filePath) => void` hook to set custom headers.
+ * @param {string[]|Function} [options.pushAssets]      - HTTP/2 server push. Array of paths
+ *        (relative to root) to push when serving HTML files, or a function `(filePath) => string[]`.
+ * @returns {Function} Middleware `(req, res, next) => void`.
+ *
+ * @example
+ *   app.use(serveStatic('public'));                            // serve ./public
+ *   app.use(serveStatic('dist', { maxAge: 86400000 }));       // 1-day cache
+ *   app.use(serveStatic('assets', { extensions: ['html'] })); // .html fallback
+ *
+ * @example | HTTP/2 Server Push
+ *   app.use(serveStatic('public', {
+ *       pushAssets: ['/styles/main.css', '/modules/app.js'],
+ *   }));
+ */
+function serveStatic(root, options = {})
+{
+    root = path.resolve(root);
+    const index = options.hasOwnProperty('index') ? options.index : 'index.html';
+    const maxAge = options.hasOwnProperty('maxAge') ? options.maxAge : 0;
+    const dotfiles = options.hasOwnProperty('dotfiles') ? options.dotfiles : 'ignore'; // allow|deny|ignore
+    const extensions = Array.isArray(options.extensions) ? options.extensions : null;
+    const setHeaders = typeof options.setHeaders === 'function' ? options.setHeaders : null;
+    const pushAssets = options.pushAssets || null;
+
+    function isDotfile(p)
+    {
+        return path.basename(p).startsWith('.');
+    }
+
+    function applyHeaders(res, filePath)
+    {
+        if (maxAge) try { res.raw.setHeader('Cache-Control', 'max-age=' + Math.floor(Number(maxAge) / 1000)); } catch (e) { }
+        if (setHeaders) try { setHeaders(res, filePath); } catch (e) { }
+    }
+
+    /**
+     * Push linked assets via HTTP/2 server push when serving HTML files.
+     * @private
+     */
+    function pushLinkedAssets(res, filePath)
+    {
+        if (!pushAssets) return;
+        // Only push for HTML files
+        const ext = path.extname(filePath).toLowerCase();
+        if (ext !== '.html' && ext !== '.htm') return;
+        // Only push on HTTP/2 connections
+        if (!res.supportsPush) return;
+
+        const assets = typeof pushAssets === 'function'
+            ? pushAssets(filePath)
+            : pushAssets;
+
+        if (!Array.isArray(assets)) return;
+
+        for (const assetPath of assets)
+        {
+            const absPath = path.resolve(root, '.' + path.sep + assetPath);
+            // Security: verify asset is within root
+            if (!absPath.startsWith(root + path.sep) && absPath !== root) continue;
+            res.push(assetPath, { filePath: absPath });
+        }
+    }
+
+    return (req, res, next) =>
+    {
+        if (req.method !== 'GET' && req.method !== 'HEAD') return next();
+        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' });
+
+        fs.stat(file, (err, st) =>
+        {
+            if (err)
+            {
+                // try extensions fallback
+                if (extensions && !urlPath.endsWith('/'))
+                {
+                    (function tryExt(i)
+                    {
+                        if (i >= extensions.length) return next();
+                        const ext = extensions[i].startsWith('.') ? extensions[i] : '.' + extensions[i];
+                        const f = file + ext;
+                        fs.stat(f, (e2, st2) =>
+                        {
+                            if (!e2 && st2 && st2.isFile())
+                            {
+                                if (isDotfile(f) && dotfiles === 'deny') return res.status(403).json({ error: 'Forbidden' });
+                                applyHeaders(res, f);
+                                pushLinkedAssets(res, f);
+                                return sendFile(res, f, st2, req);
+                            }
+                            tryExt(i + 1);
+                        });
+                    })(0);
+                    return;
+                }
+                return next();
+            }
+
+            if (st.isDirectory())
+            {
+                if (!index) return next();
+                const idxFile = path.join(file, index);
+                fs.stat(idxFile, (err2, st2) =>
+                {
+                    if (err2) return next();
+                    if (isDotfile(idxFile) && dotfiles === 'deny') return res.status(403).json({ error: 'Forbidden' });
+                    applyHeaders(res, idxFile);
+                    pushLinkedAssets(res, idxFile);
+                    sendFile(res, idxFile, st2, req);
+                });
+            }
+            else
+            {
+                if (isDotfile(file) && dotfiles === 'ignore') return next();
+                if (isDotfile(file) && dotfiles === 'deny') return res.status(403).json({ error: 'Forbidden' });
+                applyHeaders(res, file);
+                pushLinkedAssets(res, file);
+                sendFile(res, file, st, req);
+            }
+        });
+    };
+}
+
+module.exports = serveStatic;

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] - Configuration options.
+ * @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,255 @@
+/**
+ * @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-server/sdk');
+ *   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 }}
+ */
+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] - Configuration options.
+ * @param {boolean} [opts.stripUnknown=true] - Remove fields not in schema.
+ * @returns {{ sanitized: object, errors: string[] }}
+ */
+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 - Validation rules object.
+ * @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] - Validation 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;

package/package.json

@@ -1,10 +1,10 @@
 {
   "name": "@zero-server/middleware",
-  "version": "0.9.0",
+  "version": "0.9.2",
   "description": "20+ zero-dependency middleware.",
   "keywords": [
     "zero-server",
-    "zero-http",
+    "zero-server",
     "middleware"
   ],
   "author": "Anthony Wiedman",
@@ -20,6 +20,7 @@
     "./package.json": "./package.json"
   },
   "files": [
+    "lib",
     "index.js",
     "index.d.ts",
     "README.md",
@@ -43,6 +44,14 @@
   },
   "sideEffects": false,
   "dependencies": {
-    "@zero-server/sdk": "0.9.0"
+    "@zero-server/errors": "0.9.2"
+  },
+  "peerDependencies": {
+    "@zero-server/sdk": ">=0.9.2"
+  },
+  "peerDependenciesMeta": {
+    "@zero-server/sdk": {
+      "optional": true
+    }
   }
 }