zero-http 0.2.0

package/index.js

@@ -0,0 +1,43 @@
+/**
+ * @module zero-http
+ * @description Public entry point for the zero-http package.
+ *              Re-exports every middleware, the app factory, and the fetch helper.
+ */
+const App = require('./lib/app');
+const cors = require('./lib/cors');
+const fetch = require('./lib/fetch');
+const body = require('./lib/body');
+const serveStatic = require('./lib/static');
+const rateLimit = require('./lib/rateLimit');
+const logger = require('./lib/logger');
+
+module.exports = {
+    /**
+     * Create a new application instance.
+     * @returns {import('./lib/app')} Fresh App with an empty middleware stack.
+     */
+    createApp: () => new App(),
+    /** @see module:cors */
+    cors,
+    /** @see module:fetch */
+    fetch,
+    // body parsers
+    /** @see module:body/json */
+    json: body.json,
+    /** @see module:body/urlencoded */
+    urlencoded: body.urlencoded,
+    /** @see module:body/text */
+    text: body.text,
+    /** @see module:body/raw */
+    raw: body.raw,
+    /** @see module:body/multipart */
+    multipart: body.multipart,
+    // serving
+    /** @see module:static */
+    static: serveStatic,
+    // middleware
+    /** @see module:rateLimit */
+    rateLimit,
+    /** @see module:logger */
+    logger,
+};

package/lib/app.js

@@ -0,0 +1,159 @@
+/**
+ * @module app
+ * @description Express-like HTTP application with middleware pipeline and
+ *              method-based routing.  Created via `createApp()` in the public API.
+ */
+const http = require('http');
+const Router = require('./router');
+const Request = require('./request');
+const Response = require('./response');
+
+class App
+{
+    /**
+     * Create a new App instance.
+     * Initialises an empty middleware stack, a {@link Router}, and binds
+     * `this.handler` for direct use with `http.createServer()`.
+     *
+     * @constructor
+     */
+    constructor()
+    {
+        /** @type {Router} */
+        this.router = new Router();
+        /** @type {Function[]} */
+        this.middlewares = [];
+        /** @type {Function|null} */
+        this._errorHandler = null;
+
+        // Bind for use as `http.createServer(app.handler)`
+        this.handler = (req, res) => this.handle(req, res);
+    }
+
+    /**
+     * Register middleware.
+     * - `use(fn)` — global middleware applied to every request.
+     * - `use('/prefix', fn)` — path-scoped middleware (strips the prefix
+     *   before calling `fn` so downstream sees relative paths).
+     *
+     * @param {string|Function} pathOrFn - A path prefix string, or middleware function.
+     * @param {Function}        [fn]     - Middleware function when first arg is a path.
+     */
+    use(pathOrFn, fn)
+    {
+        if (typeof pathOrFn === 'function')
+        {
+            this.middlewares.push(pathOrFn);
+        }
+        else if (typeof pathOrFn === 'string' && typeof fn === 'function')
+        {
+            const prefix = pathOrFn.endsWith('/') ? pathOrFn.slice(0, -1) : pathOrFn;
+            this.middlewares.push((req, res, next) =>
+            {
+                const urlPath = req.url.split('?')[0];
+                if (urlPath === prefix || urlPath.startsWith(prefix + '/'))
+                {
+                    // strip prefix from url so downstream sees relative paths
+                    const origUrl = req.url;
+                    req.url = req.url.slice(prefix.length) || '/';
+                    fn(req, res, () => { req.url = origUrl; next(); });
+                }
+                else
+                {
+                    next();
+                }
+            });
+        }
+    }
+
+    /**
+     * Register a global error handler.
+     * The handler receives `(err, req, res, next)` and is invoked whenever
+     * a middleware or route handler throws or passes an error to `next(err)`.
+     *
+     * @param {Function} fn - Error-handling function `(err, req, res, next) => void`.
+     */
+    onError(fn)
+    {
+        this._errorHandler = fn;
+    }
+
+    /**
+     * Core request handler.  Wraps the raw Node `req`/`res` in
+     * {@link Request}/{@link Response} wrappers, runs the middleware
+     * pipeline, then falls through to the router.
+     *
+     * @param {import('http').IncomingMessage} req - Raw Node request.
+     * @param {import('http').ServerResponse}  res - Raw Node response.
+     */
+    handle(req, res)
+    {
+        const request = new Request(req);
+        const response = new Response(res);
+
+        let idx = 0;
+        const run = (err) =>
+        {
+            if (err)
+            {
+                if (this._errorHandler) return this._errorHandler(err, request, response, run);
+                response.status(500).json({ error: err.message || 'Internal Server Error' });
+                return;
+            }
+            if (idx < this.middlewares.length)
+            {
+                const mw = this.middlewares[idx++];
+                try
+                {
+                    const result = mw(request, response, run);
+                    // Handle promise-returning middleware
+                    if (result && typeof result.catch === 'function')
+                    {
+                        result.catch(run);
+                    }
+                }
+                catch (e)
+                {
+                    run(e);
+                }
+                return;
+            }
+            this.router.handle(request, response);
+        };
+
+        run();
+    }
+
+    /**
+     * Start listening for HTTP connections.
+     *
+     * @param {number}   [port=3000] - Port number to bind.
+     * @param {Function} [cb]        - Callback invoked once the server is listening.
+     * @returns {import('http').Server} The underlying Node HTTP server.
+     */
+    listen(port = 3000, cb)
+    {
+        const server = http.createServer(this.handler);
+        return server.listen(port, cb);
+    }
+
+    /**
+     * Register one or more handler functions for a specific HTTP method and path.
+     *
+     * @param {string}      method - HTTP method (GET, POST, etc.) or 'ALL'.
+     * @param {string}      path   - Route pattern (e.g. '/users/:id').
+     * @param {...Function} fns    - Handler functions `(req, res, next) => void`.
+     */
+    route(method, path, ...fns) { this.router.add(method, path, fns); }
+
+    /** @see App#route — shortcut for GET requests.    */ get(path, ...fns) { this.route('GET', path, ...fns); }
+    /** @see App#route — shortcut for POST requests.   */ post(path, ...fns) { this.route('POST', path, ...fns); }
+    /** @see App#route — shortcut for PUT requests.    */ put(path, ...fns) { this.route('PUT', path, ...fns); }
+    /** @see App#route — shortcut for DELETE requests. */ delete(path, ...fns) { this.route('DELETE', path, ...fns); }
+    /** @see App#route — shortcut for PATCH requests.  */ patch(path, ...fns) { this.route('PATCH', path, ...fns); }
+    /** @see App#route — shortcut for OPTIONS requests.*/ options(path, ...fns) { this.route('OPTIONS', path, ...fns); }
+    /** @see App#route — shortcut for HEAD requests.   */ head(path, ...fns) { this.route('HEAD', path, ...fns); }
+    /** @see App#route — matches every HTTP method.    */ all(path, ...fns) { this.route('ALL', path, ...fns); }
+}
+
+module.exports = App;

package/lib/body/index.js

@@ -0,0 +1,14 @@
+/**
+ * @module body
+ * @description Barrel export for all body-parsing utilities and middleware.
+ */
+const rawBuffer = require('./rawBuffer');
+const isTypeMatch = require('./typeMatch');
+const sendError = require('./sendError');
+const json = require('./json');
+const urlencoded = require('./urlencoded');
+const text = require('./text');
+const raw = require('./raw');
+const multipart = require('./multipart');
+
+module.exports = { rawBuffer, isTypeMatch, sendError, json, urlencoded, text, raw, multipart };

package/lib/body/json.js

@@ -0,0 +1,54 @@
+/**
+ * @module body/json
+ * @description JSON body-parsing middleware.
+ *              Reads the request body, parses it as JSON, and sets `req.body`.
+ */
+const rawBuffer = require('./rawBuffer');
+const isTypeMatch = require('./typeMatch');
+const sendError = require('./sendError');
+
+/**
+ * Create a JSON body-parsing middleware.
+ *
+ * @param {object}          [options]
+ * @param {string|number}   [options.limit]    - Max body size (e.g. `'10kb'`).
+ * @param {Function}        [options.reviver]  - `JSON.parse` reviver function.
+ * @param {boolean}         [options.strict=true] - When true, reject non-object/array roots.
+ * @param {string|Function} [options.type='application/json'] - Content-Type to match.
+ * @returns {Function} Async middleware `(req, res, next) => void`.
+ */
+function json(options = {})
+{
+  const opts = options || {};
+  const limit = opts.limit || null;
+  const reviver = opts.reviver;
+  const strict = (opts.hasOwnProperty('strict')) ? !!opts.strict : true;
+  const typeOpt = opts.type || 'application/json';
+
+  return async (req, res, next) =>
+  {
+    const ct = (req.headers['content-type'] || '');
+    if (!isTypeMatch(ct, typeOpt)) return next();
+    try
+    {
+      const buf = await rawBuffer(req, { limit });
+      const txt = buf.toString('utf8');
+      if (!txt) { req.body = null; return next(); }
+      let parsed;
+      try { parsed = JSON.parse(txt, reviver); } catch (e) { req.body = null; return next(); }
+      if (strict && (typeof parsed !== 'object' || parsed === null || Array.isArray(parsed) === false && Object.keys(parsed).length === 0 && !Array.isArray(parsed)))
+      {
+        // If strict, prefer objects/arrays; allow arrays but reject primitives
+        if (typeof parsed !== 'object') { req.body = null; return next(); }
+      }
+      req.body = parsed;
+    } catch (err)
+    {
+      if (err && err.status === 413) return sendError(res, 413, 'payload too large');
+      req.body = null;
+    }
+    next();
+  };
+}
+
+module.exports = json;

package/lib/body/multipart.js

@@ -0,0 +1,310 @@
+/**
+ * @module body/multipart
+ * @description Streaming multipart/form-data parser.
+ *              Writes uploaded files to a temp directory and collects
+ *              form fields.  Sets `req.body = { fields, files }`.
+ */
+const fs = require('fs');
+const os = require('os');
+const path = require('path');
+const sendError = require('./sendError');
+
+/**
+ * Generate a unique filename with an optional prefix.
+ *
+ * @param {string} [prefix='miniex'] - Filename prefix.
+ * @returns {string}
+ */
+function uniqueName(prefix = 'miniex')
+{
+    return `${prefix}-${Date.now()}-${Math.floor(Math.random() * 1e9)}`;
+}
+
+/**
+ * Recursively create a directory if it doesn't exist.
+ *
+ * @param {string} dir - Directory path.
+ */
+function ensureDir(dir)
+{
+    try { fs.mkdirSync(dir, { recursive: true }); } catch (e) { }
+}
+
+/**
+ * Parse raw MIME header text (CRLF-separated) into a plain object.
+ *
+ * @param {string} headerText - Raw header block.
+ * @returns {Object<string, string>} Lower-cased header key/value map.
+ */
+function parseHeaders(headerText)
+{
+    const lines = headerText.split('\r\n');
+    const obj = {};
+    for (const l of lines)
+    {
+        const idx = l.indexOf(':');
+        if (idx === -1) continue;
+        const k = l.slice(0, idx).trim().toLowerCase();
+        const v = l.slice(idx + 1).trim();
+        obj[k] = v;
+    }
+    return obj;
+}
+
+/**
+ * Extract `name` and `filename` fields from a `Content-Disposition` header.
+ *
+ * @param {string} cd - Content-Disposition value.
+ * @returns {Object<string, string>} Parsed disposition parameters.
+ */
+function parseContentDisposition(cd)
+{
+    const m = /form-data;(.*)/i.exec(cd);
+    if (!m) return {};
+    const parts = m[1].split(';').map(s => s.trim());
+    const out = {};
+    for (const p of parts)
+    {
+        const mm = /([^=]+)="?([^"]+)"?/.exec(p);
+        if (mm) out[mm[1]] = mm[2];
+    }
+    return out;
+}
+
+/**
+ * Create a streaming multipart/form-data parsing middleware.
+ *
+ * @param {object} [opts]
+ * @param {string} [opts.dir]             - Upload directory (default: OS temp dir).
+ * @param {number} [opts.maxFileSize]     - Maximum file size in bytes.
+ * @returns {Function} Async middleware `(req, res, next) => void`.
+ */
+function multipart(opts = {})
+{
+    return async (req, res, next) =>
+    {
+        const ct = req.headers['content-type'] || '';
+        const m = /boundary=(?:"([^"]+)"|([^;\s]+))/i.exec(ct);
+        if (!m) return next();
+        const boundary = (m[1] || m[2] || '').replace(/^"|"$/g, '');
+        const dashBoundary = `--${boundary}`;
+        const dashBoundaryBuf = Buffer.from('\r\n' + dashBoundary);
+        const startBoundaryBuf = Buffer.from(dashBoundary);
+
+        let tmpDir;
+        if (opts.dir)
+        {
+            tmpDir = path.isAbsolute(opts.dir) ? opts.dir : path.join(process.cwd(), opts.dir);
+        } else
+        {
+            tmpDir = path.join(os.tmpdir(), 'zero-http-uploads');
+        }
+        const maxFileSize = opts.maxFileSize || null; // bytes
+        ensureDir(tmpDir);
+
+        const fields = {};
+        const files = {};
+
+        let buffer = Buffer.alloc(0);
+        let state = 'start'; // start, headers, body
+        let current = null; // { headers, name, filename, contentType, writeStream, collectedSize }
+
+        const pendingWrites = [];
+
+        function abortFileTooLarge()
+        {
+            try { current.writeStream.end(); } catch (e) { }
+            try { fs.unlinkSync(current.filePath); } catch (e) { }
+            if (!req._multipartErrorHandled)
+            {
+                req._multipartErrorHandled = true;
+                sendError(res, 413, 'file too large');
+                req.raw.pause && req.raw.pause();
+            }
+        }
+
+        function closeCurrent()
+        {
+            if (!current) return;
+            if (current.writeStream)
+            {
+                // end the stream and record file after it's flushed to disk
+                // capture values so we don't rely on `current` later
+                const info = { name: current.name, filename: current.filename, filePath: current.filePath, contentType: current.contentType, size: current.collectedSize };
+                const p = new Promise((resolve) =>
+                {
+                    current.writeStream.on('finish', () =>
+                    {
+                        files[info.name] = { originalFilename: info.filename, storedName: path.basename(info.filePath), path: info.filePath, contentType: info.contentType, size: info.size };
+                        resolve();
+                    });
+                    current.writeStream.on('error', () =>
+                    {
+                        resolve();
+                    });
+                });
+                pendingWrites.push(p);
+                current.writeStream.end();
+            } else
+            {
+                fields[current.name] = current.value || '';
+            }
+            current = null;
+        }
+
+        req.raw.on('data', (chunk) =>
+        {
+            buffer = Buffer.concat([buffer, chunk]);
+
+            while (true)
+            {
+                if (state === 'start')
+                {
+                    // look for starting boundary
+                    const idx = buffer.indexOf(startBoundaryBuf);
+                    if (idx === -1)
+                    {
+                        // boundary not yet found
+                        if (buffer.length > startBoundaryBuf.length) buffer = buffer.slice(buffer.length - startBoundaryBuf.length);
+                        break;
+                    }
+                    // consume up to after boundary and CRLF
+                    const after = idx + startBoundaryBuf.length;
+                    if (buffer.length < after + 2) break; // wait for CRLF
+                    buffer = buffer.slice(after);
+                    if (buffer.slice(0, 2).toString() === '\r\n') buffer = buffer.slice(2);
+                    state = 'headers';
+                } else if (state === 'headers')
+                {
+                    const idx = buffer.indexOf('\r\n\r\n');
+                    if (idx === -1)
+                    {
+                        // wait for more
+                        if (buffer.length > 1024 * 1024)
+                        {
+                            // keep buffer bounded
+                            buffer = buffer.slice(buffer.length - 1024 * 16);
+                        }
+                        break;
+                    }
+                    const headerText = buffer.slice(0, idx).toString('utf8');
+                    buffer = buffer.slice(idx + 4);
+                    const hdrs = parseHeaders(headerText);
+                    const disp = hdrs['content-disposition'] || '';
+                    const cd = parseContentDisposition(disp);
+                    const name = cd.name;
+                    const filename = cd.filename;
+                    const contentType = hdrs['content-type'] || null;
+                    current = { headers: hdrs, name, filename, contentType, collectedSize: 0 };
+                    if (filename)
+                    {
+                        // create temp file; preserve the original extension when possible
+                        const ext = path.extname(filename) || '';
+                        const safeExt = ext.replace(/[^a-z0-9.]/gi, '');
+                        let fname = uniqueName('upload');
+                        if (safeExt) fname = fname + (safeExt.startsWith('.') ? safeExt : ('.' + safeExt));
+                        const filePath = path.join(tmpDir, fname);
+                        current.filePath = filePath;
+                        current.writeStream = fs.createWriteStream(filePath);
+                    } else
+                    {
+                        current.value = '';
+                    }
+                    state = 'body';
+                } else if (state === 'body')
+                {
+                    // look for boundary preceded by CRLF
+                    const idx = buffer.indexOf(dashBoundaryBuf);
+                    if (idx === -1)
+                    {
+                        // keep tail in buffer to match partial boundary
+                        const keep = Math.max(dashBoundaryBuf.length, 1024);
+                        const writeLen = buffer.length - keep;
+                        if (writeLen > 0)
+                        {
+                            const toWrite = buffer.slice(0, writeLen);
+                            if (current.writeStream)
+                            {
+                                current.writeStream.write(toWrite);
+                                current.collectedSize += toWrite.length;
+                                if (maxFileSize && current.collectedSize > maxFileSize)
+                                {
+                                    abortFileTooLarge();
+                                    return;
+                                }
+                            } else
+                            {
+                                current.value += toWrite.toString('utf8');
+                            }
+                            buffer = buffer.slice(writeLen);
+                        }
+                        break;
+                    }
+                    // boundary found at idx; data before idx is body chunk (without the leading CRLF)
+                    const bodyChunk = buffer.slice(0, idx);
+                    // if bodyChunk starts with CRLF, strip it
+                    const toWrite = (bodyChunk.slice(0, 2).toString() === '\r\n') ? bodyChunk.slice(2) : bodyChunk;
+                    if (toWrite.length)
+                    {
+                        if (current.writeStream)
+                        {
+                            current.writeStream.write(toWrite);
+                            current.collectedSize += toWrite.length;
+                            if (maxFileSize && current.collectedSize > maxFileSize)
+                            {
+                                abortFileTooLarge();
+                                return;
+                            }
+                        } else
+                        {
+                            current.value += toWrite.toString('utf8');
+                        }
+                    }
+                    // consume boundary marker
+                    buffer = buffer.slice(idx + dashBoundaryBuf.length);
+                    // check for final boundary '--'
+                    if (buffer.slice(0, 2).toString() === '--')
+                    {
+                        // final
+                        closeCurrent();
+                        // wait for any pending file flushes then continue
+                        req.raw.pause && req.raw.pause();
+                        Promise.all(pendingWrites).then(() =>
+                        {
+                            req.body = { fields, files };
+                            req._multipart = true;
+                            return next();
+                        }).catch(() =>
+                        {
+                            req.body = { fields, files };
+                            req._multipart = true;
+                            return next();
+                        });
+                        return;
+                    }
+                    // trim leading CRLF if present
+                    if (buffer.slice(0, 2).toString() === '\r\n') buffer = buffer.slice(2);
+                    // close current and continue to next headers
+                    closeCurrent();
+                    state = 'headers';
+                }
+            }
+        });
+
+        req.raw.on('end', () =>
+        {
+            // finish any current
+            if (current) closeCurrent();
+            req.body = { fields, files };
+            req._multipart = true;
+            next();
+        });
+
+        req.raw.on('error', (err) =>
+        {
+            next();
+        });
+    };
+}
+
+module.exports = multipart;

package/lib/body/raw.js

@@ -0,0 +1,40 @@
+/**
+ * @module body/raw
+ * @description Raw-buffer body-parsing middleware.
+ *              Stores the full request body as a Buffer on `req.body`.
+ */
+const rawBuffer = require('./rawBuffer');
+const isTypeMatch = require('./typeMatch');
+const sendError = require('./sendError');
+
+/**
+ * Create a raw-buffer body-parsing middleware.
+ *
+ * @param {object}          [options]
+ * @param {string|number}   [options.limit]                           - Max body size.
+ * @param {string|Function} [options.type='application/octet-stream'] - Content-Type to match.
+ * @returns {Function} Async middleware `(req, res, next) => void`.
+ */
+function raw(options = {})
+{
+    const opts = options || {};
+    const limit = opts.limit || null;
+    const typeOpt = opts.type || 'application/octet-stream';
+
+    return async (req, res, next) =>
+    {
+        const ct = (req.headers['content-type'] || '');
+        if (!isTypeMatch(ct, typeOpt)) return next();
+        try
+        {
+            req.body = await rawBuffer(req, { limit });
+        } catch (err)
+        {
+            if (err && err.status === 413) return sendError(res, 413, 'payload too large');
+            req.body = Buffer.alloc(0);
+        }
+        next();
+    };
+}
+
+module.exports = raw;