zero-http 0.2.0 → 0.2.1

package/lib/{response.js → http/response.js}

@@ -1,8 +1,9 @@
 /**
- * @module response
+ * @module http/response
  * @description Lightweight wrapper around Node's `ServerResponse`.
  *              Provides chainable helpers for status, headers, and body output.
  */
+const SSEStream = require('../sse/stream');
 
 /**
  * Wrapped HTTP response.
@@ -160,6 +161,74 @@ class Response
         this.set('Location', target);
         this.send('');
     }
+
+    // -- Server-Sent Events (SSE) ---------------------
+
+    /**
+     * Open a Server-Sent Events stream.  Sets the correct headers and
+     * returns an SSE controller object with methods for pushing events.
+     *
+     * The connection stays open until the client disconnects or you call
+     * `sse.close()`.
+     *
+     * @param {object} [opts]
+     * @param {number}  [opts.retry]          - Reconnection interval hint (ms) sent to client.
+     * @param {object}  [opts.headers]        - Additional headers to set on the response.
+     * @param {number}  [opts.keepAlive=0]    - Auto keep-alive interval in ms. `0` to disable.
+     * @param {string}  [opts.keepAliveComment='ping'] - Comment text for keep-alive messages.
+     * @param {boolean} [opts.autoId=false]   - Auto-increment event IDs on every `.send()` / `.event()`.
+     * @param {number}  [opts.startId=1]      - Starting value for auto-IDs.
+     * @param {number}  [opts.pad=0]          - Bytes of initial padding (helps flush proxy buffers).
+     * @param {number}  [opts.status=200]     - HTTP status code for the SSE response.
+     * @returns {SSEStream} SSE controller.
+     *
+     * @example
+     *   app.get('/events', (req, res) => {
+     *       const sse = res.sse({ retry: 5000, keepAlive: 30000, autoId: true });
+     *       sse.send('hello');                         // id: 1, data: hello
+     *       sse.event('update', { x: 1 });             // id: 2, event: update
+     *       sse.comment('debug note');                  // : debug note
+     *       sse.on('close', () => console.log('gone'));
+     *   });
+     */
+    sse(opts = {})
+    {
+        if (this._sent) return null;
+        this._sent = true;
+
+        const raw = this.raw;
+        const statusCode = opts.status || 200;
+        raw.writeHead(statusCode, {
+            'Content-Type': 'text/event-stream',
+            'Cache-Control': 'no-cache',
+            'Connection': 'keep-alive',
+            'X-Accel-Buffering': 'no',
+            ...(opts.headers || {}),
+        });
+
+        // Initial padding to push past proxy buffers (e.g. 2 KB)
+        if (opts.pad && opts.pad > 0)
+        {
+            raw.write(': ' + ' '.repeat(opts.pad) + '\n\n');
+        }
+
+        if (opts.retry)
+        {
+            raw.write(`retry: ${opts.retry}\n\n`);
+        }
+
+        // Capture the Last-Event-ID header from the request if available
+        const lastEventId = this._headers['_sse_last_event_id'] || null;
+
+        return new SSEStream(raw, {
+            keepAlive: opts.keepAlive || 0,
+            keepAliveComment: opts.keepAliveComment || 'ping',
+            autoId: !!opts.autoId,
+            startId: opts.startId || 1,
+            lastEventId,
+            secure: !!(raw.socket && raw.socket.encrypted),
+        });
+    }
 }
 
 module.exports = Response;

package/lib/middleware/compress.js

@@ -0,0 +1,194 @@
+/**
+ * @module compress
+ * @description Response compression middleware using Node's built-in `zlib`.
+ *              Supports gzip, deflate, and brotli (Node >= 11.7).
+ *              Zero external dependencies.
+ */
+const zlib = require('zlib');
+
+/**
+ * Default minimum response size (in bytes) to bother compressing.
+ * Responses smaller than this are sent uncompressed.
+ * @type {number}
+ */
+const DEFAULT_THRESHOLD = 1024;
+
+/**
+ * MIME types that are worth compressing.
+ * Binary formats (images, video, zip) are already compressed and gain little.
+ * @type {RegExp}
+ */
+const COMPRESSIBLE = /^text\/|^application\/(json|javascript|xml|x-www-form-urlencoded|ld\+json|graphql|wasm)|^image\/svg\+xml/;
+
+/**
+ * Create a compression middleware.
+ *
+ * @param {object}  [opts]
+ * @param {number}  [opts.threshold=1024]  - Minimum body size in bytes to compress.
+ * @param {number}  [opts.level]           - Compression level (zlib.constants.Z_DEFAULT_COMPRESSION).
+ * @param {string|string[]} [opts.encoding] - Force specific encoding(s). Default: auto-negotiate.
+ * @param {Function} [opts.filter]         - `(req, res) => boolean` — return false to skip compression.
+ * @returns {Function} Middleware `(req, res, next) => void`.
+ *
+ * @example
+ *   const { createApp, compress } = require('zero-http');
+ *   const app = createApp();
+ *   app.use(compress());                // gzip/deflate/br auto-negotiated
+ *   app.use(compress({ threshold: 0 })) // compress everything
+ */
+function compress(opts = {})
+{
+    const threshold = opts.threshold !== undefined ? opts.threshold : DEFAULT_THRESHOLD;
+    const level = opts.level !== undefined ? opts.level : undefined;
+    const filterFn = typeof opts.filter === 'function' ? opts.filter : null;
+    const hasBrotli = typeof zlib.createBrotliCompress === 'function';
+
+    /**
+     * Choose the best encoding from the Accept-Encoding header.
+     * Priority: br > gzip > deflate.
+     * @param {string} header
+     * @returns {string|null}
+     */
+    function negotiate(header)
+    {
+        if (!header) return null;
+        const h = header.toLowerCase();
+        if (hasBrotli && h.includes('br')) return 'br';
+        if (h.includes('gzip')) return 'gzip';
+        if (h.includes('deflate')) return 'deflate';
+        return null;
+    }
+
+    /**
+     * Create a compression stream for the chosen encoding.
+     * @param {string} encoding
+     * @returns {import('stream').Transform}
+     */
+    function createStream(encoding)
+    {
+        const zlibOpts = {};
+        if (level !== undefined) zlibOpts.level = level;
+        switch (encoding)
+        {
+            case 'br':
+                return zlib.createBrotliCompress(level !== undefined
+                    ? { params: { [zlib.constants.BROTLI_PARAM_QUALITY]: level } }
+                    : undefined);
+            case 'gzip':
+                return zlib.createGzip(zlibOpts);
+            case 'deflate':
+                return zlib.createDeflate(zlibOpts);
+            default:
+                return null;
+        }
+    }
+
+    return (req, res, next) =>
+    {
+        // Skip if client doesn't accept encoding
+        const acceptEncoding = req.headers['accept-encoding'] || '';
+        const encoding = negotiate(acceptEncoding);
+        if (!encoding) return next();
+
+        // Allow user to skip compression
+        if (filterFn && !filterFn(req, res)) return next();
+
+        // Monkey-patch the raw response's write/end to pipe through compression
+        const raw = res.raw;
+        const origWrite = raw.write.bind(raw);
+        const origEnd = raw.end.bind(raw);
+        let compressStream = null;
+        let headersWritten = false;
+        const chunks = [];
+
+        function initCompress()
+        {
+            if (compressStream) return true;
+
+            // If headers were already committed (e.g. res.sse() calls
+            // writeHead before write), we can no longer modify them.
+            if (raw.headersSent) return false;
+
+            // Check Content-Type — skip non-compressible types
+            const ct = raw.getHeader('content-type') || '';
+            if (ct && !COMPRESSIBLE.test(ct))
+            {
+                return false;
+            }
+
+            // Never compress SSE streams — compression buffers
+            // the small frames and prevents real-time delivery.
+            if (ct.includes('text/event-stream'))
+            {
+                return false;
+            }
+
+            compressStream = createStream(encoding);
+            if (!compressStream) return false;
+
+            // Remove Content-Length (we don't know compressed size ahead of time)
+            raw.removeHeader('content-length');
+            raw.removeHeader('Content-Length');
+            raw.setHeader('Content-Encoding', encoding);
+            raw.setHeader('Vary', 'Accept-Encoding');
+
+            compressStream.on('data', (chunk) => origWrite(chunk));
+            compressStream.on('end', () => origEnd());
+            return true;
+        }
+
+        raw.write = function (chunk, enc, callback)
+        {
+            if (!headersWritten)
+            {
+                headersWritten = true;
+                const ct = raw.getHeader('content-type') || '';
+                initCompress();
+                if (compressStream)
+                {
+                    compressStream.write(chunk, enc, callback);
+                    return true;
+                }
+            }
+            if (compressStream)
+            {
+                compressStream.write(chunk, enc, callback);
+                return true;
+            }
+            return origWrite(chunk, enc, callback);
+        };
+
+        raw.end = function (chunk, encoding, callback)
+        {
+            if (!headersWritten)
+            {
+                headersWritten = true;
+
+                // Check threshold — if the total body is small, skip compression
+                const totalChunk = chunk ? (Buffer.isBuffer(chunk) ? chunk : Buffer.from(String(chunk))) : null;
+                if (totalChunk && totalChunk.length < threshold)
+                {
+                    return origEnd(chunk, encoding, callback);
+                }
+
+                if (initCompress())
+                {
+                    if (chunk) compressStream.end(chunk, encoding, callback);
+                    else compressStream.end(callback);
+                    return;
+                }
+            }
+            if (compressStream)
+            {
+                if (chunk) compressStream.end(chunk, encoding, callback);
+                else compressStream.end(callback);
+                return;
+            }
+            return origEnd(chunk, encoding, callback);
+        };
+
+        next();
+    };
+}
+
+module.exports = compress;

package/lib/middleware/index.js

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

package/lib/router/index.js

@@ -0,0 +1,278 @@
+/**
+ * @module router
+ * @description Full-featured pattern-matching router with named parameters,
+ *              wildcard catch-alls, sequential handler chains, sub-router
+ *              mounting, and route introspection.
+ */
+
+/**
+ * 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 };
+}
+
+/**
+ * Join two path segments, avoiding double slashes.
+ * @param {string} base
+ * @param {string} child
+ * @returns {string}
+ */
+function joinPath(base, child)
+{
+    if (base === '/') return child;
+    if (child === '/') return base;
+    return base.replace(/\/$/, '') + '/' + child.replace(/^\//, '');
+}
+
+class Router
+{
+    /**
+     * Create a new Router with an empty route table.
+     * Can be used standalone as a sub-router or internally by App.
+     */
+    constructor()
+    {
+        this.routes = [];
+        /** @type {{ prefix: string, router: Router }[]} */
+        this._children = [];
+    }
+
+    /**
+     * 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`.
+     * @param {object}     [options]
+     * @param {boolean}    [options.secure] - When `true`, route matches only HTTPS requests;
+     *                                       when `false`, only HTTP. Omit to match both.
+     */
+    add(method, path, handlers, options = {})
+    {
+        const { regex, keys } = pathToRegex(path);
+        const entry = { method: method.toUpperCase(), path, regex, keys, handlers };
+        if (options.secure !== undefined) entry.secure = !!options.secure;
+        this.routes.push(entry);
+    }
+
+    /**
+     * Mount a child Router under a path prefix.
+     * Requests matching the prefix are delegated to the child router with
+     * the prefix stripped from `req.url`.
+     *
+     * @param {string} prefix - Path prefix (e.g. '/api').
+     * @param {Router} router - Child router instance.
+     */
+    use(prefix, router)
+    {
+        if (typeof prefix === 'string' && router instanceof Router)
+        {
+            const cleanPrefix = prefix.endsWith('/') ? prefix.slice(0, -1) : prefix;
+            this._children.push({ prefix: cleanPrefix, router });
+        }
+    }
+
+    /**
+     * Match an incoming request against the route table and execute the first
+     * matching handler chain.  Delegates to child routers when mounted.
+     * 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];
+
+        // Try own routes first
+        for (const r of this.routes)
+        {
+            if (r.method !== 'ALL' && r.method !== method) continue;
+            // Protocol-aware matching: skip if secure flag doesn't match
+            if (r.secure === true && !req.secure) continue;
+            if (r.secure === false && req.secure) continue;
+            const m = url.match(r.regex);
+            if (!m) continue;
+            req.params = {};
+            r.keys.forEach((k, i) => req.params[k] = decodeURIComponent(m[i + 1] || ''));
+            let idx = 0;
+            const next = () =>
+            {
+                if (idx < r.handlers.length)
+                {
+                    const h = r.handlers[idx++];
+                    return h(req, res, next);
+                }
+            };
+            return next();
+        }
+
+        // Try child routers
+        for (const child of this._children)
+        {
+            if (url === child.prefix || url.startsWith(child.prefix + '/'))
+            {
+                const origUrl = req.url;
+                req.url = req.url.slice(child.prefix.length) || '/';
+                const found = child.router._tryHandle(req, res);
+                if (found) return;
+                req.url = origUrl; // restore if child didn't match
+            }
+        }
+
+        res.status(404).json({ error: 'Not Found' });
+    }
+
+    /**
+     * Try to handle a request without sending 404 on miss.
+     * Used internally by parent routers to probe child routers.
+     *
+     * @param {import('./request')}  req
+     * @param {import('./response')} res
+     * @returns {boolean} `true` if a route matched.
+     * @private
+     */
+    _tryHandle(req, res)
+    {
+        const method = req.method.toUpperCase();
+        const url = req.url.split('?')[0];
+
+        for (const r of this.routes)
+        {
+            if (r.method !== 'ALL' && r.method !== method) continue;
+            // Protocol-aware matching: skip if secure flag doesn't match
+            if (r.secure === true && !req.secure) continue;
+            if (r.secure === false && req.secure) continue;
+            const m = url.match(r.regex);
+            if (!m) continue;
+            req.params = {};
+            r.keys.forEach((k, i) => req.params[k] = decodeURIComponent(m[i + 1] || ''));
+            let idx = 0;
+            const next = () =>
+            {
+                if (idx < r.handlers.length)
+                {
+                    const h = r.handlers[idx++];
+                    return h(req, res, next);
+                }
+            };
+            next();
+            return true;
+        }
+
+        for (const child of this._children)
+        {
+            if (url === child.prefix || url.startsWith(child.prefix + '/'))
+            {
+                const origUrl = req.url;
+                req.url = req.url.slice(child.prefix.length) || '/';
+                const found = child.router._tryHandle(req, res);
+                if (found) return true;
+                req.url = origUrl;
+            }
+        }
+
+        return false;
+    }
+
+    // -- Convenience route methods (mirror App API) ----------
+
+    /**
+     * @private
+     * Extract an options object from the head of the handlers array when
+     * the first argument is a plain object (not a function).
+     *
+     * Allows: `router.get('/path', { secure: true }, handler)`
+     */
+    _extractOpts(fns)
+    {
+        let opts = {};
+        if (fns.length > 0 && typeof fns[0] === 'object' && typeof fns[0] !== 'function')
+        {
+            opts = fns.shift();
+        }
+        return opts;
+    }
+
+    /** @see Router#add */ get(path, ...fns) { const o = this._extractOpts(fns); this.add('GET', path, fns, o); return this; }
+    /** @see Router#add */ post(path, ...fns) { const o = this._extractOpts(fns); this.add('POST', path, fns, o); return this; }
+    /** @see Router#add */ put(path, ...fns) { const o = this._extractOpts(fns); this.add('PUT', path, fns, o); return this; }
+    /** @see Router#add */ delete(path, ...fns) { const o = this._extractOpts(fns); this.add('DELETE', path, fns, o); return this; }
+    /** @see Router#add */ patch(path, ...fns) { const o = this._extractOpts(fns); this.add('PATCH', path, fns, o); return this; }
+    /** @see Router#add */ options(path, ...fns) { const o = this._extractOpts(fns); this.add('OPTIONS', path, fns, o); return this; }
+    /** @see Router#add */ head(path, ...fns) { const o = this._extractOpts(fns); this.add('HEAD', path, fns, o); return this; }
+    /** @see Router#add */ all(path, ...fns) { const o = this._extractOpts(fns); this.add('ALL', path, fns, o); return this; }
+
+    /**
+     * Chainable route builder — register multiple methods on the same path.
+     *
+     * @example
+     *   router.route('/users')
+     *     .get((req, res) => { ... })
+     *     .post((req, res) => { ... });
+     *
+     * @param {string} path - Route pattern.
+     * @returns {object} Chain object with HTTP verb methods.
+     */
+    route(path)
+    {
+        const self = this;
+        const chain = {};
+        for (const m of ['get', 'post', 'put', 'delete', 'patch', 'options', 'head', 'all'])
+        {
+            chain[m] = (...fns) => { const o = self._extractOpts(fns); self.add(m.toUpperCase(), path, fns, o); return chain; };
+        }
+        return chain;
+    }
+
+    // -- Introspection -----------------------------------
+
+    /**
+     * Return a flat list of all registered routes, including those in
+     * mounted child routers.  Useful for debugging or auto-documentation.
+     *
+     * @param {string} [prefix=''] - Internal: accumulated prefix from parent routers.
+     * @returns {{ method: string, path: string }[]}
+     */
+    inspect(prefix = '')
+    {
+        const list = [];
+        for (const r of this.routes)
+        {
+            const entry = { method: r.method, path: joinPath(prefix, r.path) };
+            if (r.secure === true) entry.secure = true;
+            else if (r.secure === false) entry.secure = false;
+            list.push(entry);
+        }
+        for (const child of this._children)
+        {
+            const childPrefix = prefix ? joinPath(prefix, child.prefix) : child.prefix;
+            list.push(...child.router.inspect(childPrefix));
+        }
+        return list;
+    }
+}
+
+module.exports = Router;

package/lib/sse/index.js

@@ -0,0 +1,8 @@
+/**
+ * @module sse
+ * @description Server-Sent Events support for zero-http.
+ *              Exports the SSEStream class.
+ */
+const SSEStream = require('./stream');
+
+module.exports = { SSEStream };