zero-http 0.2.0

package/lib/rateLimit.js

@@ -0,0 +1,64 @@
+/**
+ * In-memory rate-limiting middleware.
+ * Limits requests per IP address within a sliding window.
+ *
+ * @param {object}  [opts]
+ * @param {number}  [opts.windowMs=60000]   - Time window in milliseconds.
+ * @param {number}  [opts.max=100]          - Maximum requests per window per IP.
+ * @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).
+ * @returns {function} Middleware function.
+ */
+function rateLimit(opts = {})
+{
+    const windowMs = opts.windowMs || 60_000;
+    const max = opts.max || 100;
+    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 hits = new Map(); // key → { count, resetTime }
+
+    // Periodic cleanup to prevent memory leaks
+    const cleanupInterval = setInterval(() =>
+    {
+        const now = Date.now();
+        for (const [key, entry] of hits)
+        {
+            if (now >= entry.resetTime) hits.delete(key);
+        }
+    }, windowMs);
+    if (cleanupInterval.unref) cleanupInterval.unref();
+
+    return (req, res, next) =>
+    {
+        const key = keyGenerator(req);
+        const now = Date.now();
+        let entry = hits.get(key);
+
+        if (!entry || now >= entry.resetTime)
+        {
+            entry = { count: 0, resetTime: now + windowMs };
+            hits.set(key, entry);
+        }
+
+        entry.count++;
+
+        // Set rate-limit headers
+        const remaining = Math.max(0, max - entry.count);
+        res.set('X-RateLimit-Limit', String(max));
+        res.set('X-RateLimit-Remaining', String(remaining));
+        res.set('X-RateLimit-Reset', String(Math.ceil(entry.resetTime / 1000)));
+
+        if (entry.count > max)
+        {
+            res.set('Retry-After', String(Math.ceil(windowMs / 1000)));
+            return res.status(statusCode).json({ error: message });
+        }
+
+        next();
+    };
+}
+
+module.exports = rateLimit;

package/lib/request.js

@@ -0,0 +1,76 @@
+/**
+ * @module request
+ * @description Lightweight wrapper around Node's `IncomingMessage`.
+ *              Provides parsed query string, params, body, and convenience helpers.
+ */
+
+/**
+ * Wrapped HTTP request.
+ *
+ * @property {import('http').IncomingMessage} raw     - Original Node request.
+ * @property {string}  method  - HTTP method (e.g. 'GET').
+ * @property {string}  url     - Full request URL including query string.
+ * @property {object}  headers - Lower-cased request headers.
+ * @property {object}  query   - Parsed query-string key/value pairs.
+ * @property {object}  params  - Route parameters populated by the router.
+ * @property {*}       body    - Request body (set by body-parsing middleware).
+ * @property {string|null} ip  - Remote IP address.
+ */
+class Request
+{
+    /**
+     * @param {import('http').IncomingMessage} req - Raw Node incoming message.
+     */
+    constructor(req)
+    {
+        this.raw = req;
+        this.method = req.method;
+        this.url = req.url;
+        this.headers = req.headers;
+        this.query = this._parseQuery();
+        this.params = {};
+        this.body = null;
+        this.ip = req.socket ? req.socket.remoteAddress : null;
+    }
+
+    /**
+     * Parse the query string from `this.url` into a plain object.
+     *
+     * @private
+     * @returns {Object<string, string>} Parsed key-value pairs.
+     */
+    _parseQuery()
+    {
+        const idx = this.url.indexOf('?');
+        if (idx === -1) return {};
+        return Object.fromEntries(new URLSearchParams(this.url.slice(idx + 1)));
+    }
+
+    /**
+     * Get a specific request header (case-insensitive).
+     * @param {string} name
+     * @returns {string|undefined}
+     */
+    get(name)
+    {
+        return this.headers[name.toLowerCase()];
+    }
+
+    /**
+     * Check if the request Content-Type matches the given type.
+     * @param {string} type - e.g. 'json', 'html', 'application/json'
+     * @returns {boolean}
+     */
+    is(type)
+    {
+        const ct = this.headers['content-type'] || '';
+        if (type.indexOf('/') === -1)
+        {
+            // shorthand: 'json' → 'application/json', 'html' → 'text/html'
+            return ct.indexOf(type) !== -1;
+        }
+        return ct.indexOf(type) !== -1;
+    }
+}
+
+module.exports = Request;

package/lib/response.js

@@ -0,0 +1,165 @@
+/**
+ * @module response
+ * @description Lightweight wrapper around Node's `ServerResponse`.
+ *              Provides chainable helpers for status, headers, and body output.
+ */
+
+/**
+ * Wrapped HTTP response.
+ *
+ * @property {import('http').ServerResponse} raw - Original Node response.
+ */
+class Response
+{
+    /**
+     * @param {import('http').ServerResponse} res - Raw Node server response.
+     */
+    constructor(res)
+    {
+        this.raw = res;
+        /** @type {number} */
+        this._status = 200;
+        /** @type {Object<string, string>} */
+        this._headers = {};
+        /** @type {boolean} */
+        this._sent = false;
+    }
+
+    /**
+     * Set HTTP status code. Chainable.
+     *
+     * @param {number} code - HTTP status code (e.g. 200, 404).
+     * @returns {Response} `this` for chaining.
+     */
+    status(code) { this._status = code; return this; }
+
+    /**
+     * Set a response header. Chainable.
+     *
+     * @param {string} name  - Header name.
+     * @param {string} value - Header value.
+     * @returns {Response} `this` for chaining.
+     */
+    set(name, value) { this._headers[name] = value; return this; }
+
+    /**
+     * Get a previously-set response header (case-insensitive).
+     *
+     * @param {string} name - Header name.
+     * @returns {string|undefined}
+     */
+    get(name)
+    {
+        const key = Object.keys(this._headers).find(k => k.toLowerCase() === name.toLowerCase());
+        return key ? this._headers[key] : undefined;
+    }
+
+    /**
+     * Set the Content-Type header.
+     * Accepts a shorthand alias (`'json'`, `'html'`, `'text'`, etc.) or
+     * a full MIME string. Chainable.
+     *
+     * @param {string} ct - MIME type or shorthand alias.
+     * @returns {Response} `this` for chaining.
+     */
+    type(ct)
+    {
+        const map = {
+            json: 'application/json',
+            html: 'text/html',
+            text: 'text/plain',
+            xml: 'application/xml',
+            form: 'application/x-www-form-urlencoded',
+            bin: 'application/octet-stream',
+        };
+        this._headers['Content-Type'] = map[ct] || ct;
+        return this;
+    }
+
+    /**
+     * Send a response body and finalise the response.
+     * Auto-detects Content-Type (Buffer → octet-stream, string → text or
+     * HTML, object → JSON) when not explicitly set.
+     *
+     * @param {string|Buffer|object|null} body - Response payload.
+     */
+    send(body)
+    {
+        if (this._sent) return;
+        const res = this.raw;
+
+        Object.entries(this._headers).forEach(([k, v]) => res.setHeader(k, v));
+        res.statusCode = this._status;
+
+        if (body === undefined || body === null)
+        {
+            res.end();
+            this._sent = true;
+            return;
+        }
+
+        // Auto-detect Content-Type if not already set
+        const hasContentType = Object.keys(this._headers).some(k => k.toLowerCase() === 'content-type');
+
+        if (Buffer.isBuffer(body))
+        {
+            if (!hasContentType) res.setHeader('Content-Type', 'application/octet-stream');
+            res.end(body);
+        }
+        else if (typeof body === 'string')
+        {
+            if (!hasContentType)
+            {
+                // Heuristic: if it looks like HTML, set text/html
+                res.setHeader('Content-Type', body.trimStart().startsWith('<') ? 'text/html' : 'text/plain');
+            }
+            res.end(body);
+        }
+        else
+        {
+            // Object / array → JSON
+            if (!hasContentType) res.setHeader('Content-Type', 'application/json');
+            res.end(JSON.stringify(body));
+        }
+        this._sent = true;
+    }
+
+    /**
+     * Send a JSON response.  Sets `Content-Type: application/json`.
+     *
+     * @param {*} obj - Value to serialise as JSON.
+     */
+    json(obj) { this.set('Content-Type', 'application/json'); return this.send(obj); }
+
+    /**
+     * Send a plain-text response.  Sets `Content-Type: text/plain`.
+     *
+     * @param {string} str - Text payload.
+     */
+    text(str) { this.set('Content-Type', 'text/plain'); return this.send(String(str)); }
+
+    /**
+     * Send an HTML response.  Sets `Content-Type: text/html`.
+     *
+     * @param {string} str - HTML payload.
+     */
+    html(str) { this.set('Content-Type', 'text/html'); return this.send(String(str)); }
+
+    /**
+     * Redirect to the given URL with an optional status code (default 302).
+     * @param {number|string} statusOrUrl - Status code or URL.
+     * @param {string} [url] - URL if first arg was status code.
+     */
+    redirect(statusOrUrl, url)
+    {
+        if (this._sent) return;
+        let code = 302;
+        let target = statusOrUrl;
+        if (typeof statusOrUrl === 'number') { code = statusOrUrl; target = url; }
+        this._status = code;
+        this.set('Location', target);
+        this.send('');
+    }
+}
+
+module.exports = Response;

package/lib/router.js

@@ -0,0 +1,87 @@
+/**
+ * @module router
+ * @description Simple pattern-matching router with named parameters,
+ *              wildcard catch-alls, and sequential handler chains.
+ */
+
+/**
+ * Convert a route path pattern into a RegExp and extract named parameter keys.
+ * Supports `:param` segments and trailing `*` wildcards.
+ *
+ * @param   {string} path - Route pattern (e.g. '/users/:id', '/api/*').
+ * @returns {{ regex: RegExp, keys: string[] }} Compiled regex and ordered parameter names.
+ */
+function pathToRegex(path)
+{
+    // Wildcard catch-all: /api/*
+    if (path.endsWith('*'))
+    {
+        const prefix = path.slice(0, -1); // e.g. "/api/"
+        const escaped = prefix.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+        return { regex: new RegExp('^' + escaped + '(.*)$'), keys: ['0'] };
+    }
+
+    const parts = path.split('/').filter(Boolean);
+    const keys = [];
+    const pattern = parts.map(p =>
+    {
+        if (p.startsWith(':')) { keys.push(p.slice(1)); return '([^/]+)'; }
+        return p.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+    }).join('/');
+    return { regex: new RegExp('^/' + pattern + '/?$'), keys };
+}
+
+class Router
+{
+    /** Create a new Router with an empty route table. */
+    constructor() { this.routes = []; }
+
+    /**
+     * Register a route.
+     *
+     * @param {string}     method   - HTTP method (e.g. 'GET') or 'ALL' to match any.
+     * @param {string}     path     - Route pattern.
+     * @param {Function[]} handlers - One or more handler functions `(req, res, next) => void`.
+     */
+    add(method, path, handlers)
+    {
+        const { regex, keys } = pathToRegex(path);
+        this.routes.push({ method: method.toUpperCase(), path, regex, keys, handlers });
+    }
+
+    /**
+     * Match an incoming request against the route table and execute the first
+     * matching handler chain.  Sends a 404 JSON response when no route matches.
+     *
+     * @param {import('./request')}  req - Wrapped request.
+     * @param {import('./response')} res - Wrapped response.
+     */
+    handle(req, res)
+    {
+        const method = req.method.toUpperCase();
+        const url = req.url.split('?')[0];
+        for (const r of this.routes)
+        {
+            // ALL matches any method
+            if (r.method !== 'ALL' && r.method !== method) continue;
+            const m = url.match(r.regex);
+            if (!m) continue;
+            req.params = {};
+            r.keys.forEach((k, i) => req.params[k] = decodeURIComponent(m[i + 1] || ''));
+            // run handlers sequentially
+            let idx = 0;
+            const next = () =>
+            {
+                if (idx < r.handlers.length)
+                {
+                    const h = r.handlers[idx++];
+                    return h(req, res, next);
+                }
+            };
+            return next();
+        }
+        res.status(404).json({ error: 'Not Found' });
+    }
+}
+
+module.exports = Router;

package/lib/static.js

@@ -0,0 +1,196 @@
+/**
+ * @module static
+ * @description Static file-serving middleware with MIME detection, directory
+ *              index files, extension fallbacks, dotfile policies, caching,
+ *              and custom header hooks.
+ */
+const fs = require('fs');
+const path = require('path');
+
+/**
+ * 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',
+};
+
+/**
+ * Stream a file to the raw Node response, setting Content-Type and
+ * Content-Length headers from the extension and optional `stat` result.
+ *
+ * @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).
+ */
+function sendFile(res, filePath, stat)
+{
+    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 && stat.size) raw.setHeader('Content-Length', stat.size);
+    }
+    catch (e) { /* best-effort */ }
+    const stream = fs.createReadStream(filePath);
+    stream.on('error', () => { try { raw.statusCode = 404; raw.end(); } catch (e) { } });
+    stream.pipe(raw);
+}
+
+/**
+ * Create a static-file-serving middleware.
+ *
+ * @param {string} root              - Root directory to serve files from.
+ * @param {object} [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.
+ * @returns {Function} Middleware `(req, res, next) => void`.
+ */
+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;
+
+    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) { }
+    }
+
+    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' });
+
+        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);
+                                return sendFile(res, f, st2);
+                            }
+                            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);
+                    sendFile(res, idxFile, st2);
+                });
+            }
+            else
+            {
+                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);
+            }
+        });
+    };
+}
+
+module.exports = serveStatic;

package/package.json

@@ -0,0 +1,44 @@
+{
+  "name": "zero-http",
+  "version": "0.2.0",
+  "description": "Zero-dependency, minimal Express-like HTTP server and tiny fetch replacement",
+  "main": "index.js",
+  "files": [
+    "lib",
+    "documentation",
+    "index.js",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "start": "node documentation/full-server.js",
+    "docs": "node documentation/full-server.js",
+    "test": "node --test"
+  },
+  "keywords": [
+    "http",
+    "server",
+    "router",
+    "middleware",
+    "fetch",
+    "multipart",
+    "static",
+    "zero-http"
+  ],
+  "author": "Anthony Wiedman",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/tonywied17/zero-http-npm.git"
+  },
+  "bugs": {
+    "url": "https://github.com/tonywied17/zero-http-npm/issues"
+  },
+  "homepage": "https://zero-http.molex.cloud",
+  "engines": {
+    "node": ">=14.0.0"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}