zero-http 0.2.0 → 0.2.2

package/lib/app.js

@@ -1,12 +1,15 @@
 /**
  * @module app
- * @description Express-like HTTP application with middleware pipeline and
- *              method-based routing.  Created via `createApp()` in the public API.
+ * @description Express-like HTTP application with middleware pipeline,
+ *              method-based routing, HTTPS support, built-in WebSocket
+ *              upgrade handling, and route introspection.
+ *              Created via `createApp()` in the public API.
  */
 const http = require('http');
+const https = require('https');
 const Router = require('./router');
-const Request = require('./request');
-const Response = require('./response');
+const { Request, Response } = require('./http');
+const { handleUpgrade } = require('./ws');
 
 class App
 {
@@ -25,19 +28,26 @@ class App
         this.middlewares = [];
         /** @type {Function|null} */
         this._errorHandler = null;
+        /** @type {Map<string, { handler: Function, opts: object }>} WebSocket upgrade handlers keyed by path */
+        this._wsHandlers = new Map();
+        /** @type {import('http').Server|import('https').Server|null} */
+        this._server = null;
 
         // Bind for use as `http.createServer(app.handler)`
         this.handler = (req, res) => this.handle(req, res);
     }
 
+    // -- Middleware -------------------------------------
+
     /**
-     * Register middleware.
+     * Register middleware or mount a sub-router.
      * - `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).
+     * - `use('/prefix', router)` — mount a Router sub-app at the given prefix.
      *
-     * @param {string|Function} pathOrFn - A path prefix string, or middleware function.
-     * @param {Function}        [fn]     - Middleware function when first arg is a path.
+     * @param {string|Function}       pathOrFn - A path prefix string, or middleware function.
+     * @param {Function|Router}       [fn]     - Middleware function or Router when first arg is a path.
      */
     use(pathOrFn, fn)
     {
@@ -45,6 +55,11 @@ class App
         {
             this.middlewares.push(pathOrFn);
         }
+        else if (typeof pathOrFn === 'string' && fn instanceof Router)
+        {
+            // Mount a sub-router
+            this.router.use(pathOrFn, fn);
+        }
         else if (typeof pathOrFn === 'string' && typeof fn === 'function')
         {
             const prefix = pathOrFn.endsWith('/') ? pathOrFn.slice(0, -1) : pathOrFn;
@@ -78,6 +93,8 @@ class App
         this._errorHandler = fn;
     }
 
+    // -- Request Handling ------------------------------
+
     /**
      * Core request handler.  Wraps the raw Node `req`/`res` in
      * {@link Request}/{@link Response} wrappers, runs the middleware
@@ -124,27 +141,151 @@ class App
         run();
     }
 
+    // -- Server Lifecycle ------------------------------
+
     /**
-     * Start listening for HTTP connections.
+     * Start listening for HTTP or HTTPS connections.
+     *
+     * @param {number}   [port=3000]   - Port number to bind.
+     * @param {object|Function} [opts] - TLS options `{ key, cert, ... }` for HTTPS, or a callback.
+     * @param {Function} [cb]          - Callback invoked once the server is listening.
+     * @returns {import('http').Server|import('https').Server} The underlying server.
+     *
+     * @example
+     *   // Plain HTTP
+     *   app.listen(3000, () => console.log('HTTP on 3000'));
      *
-     * @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.
+     *   // HTTPS
+     *   app.listen(443, { key: fs.readFileSync('key.pem'), cert: fs.readFileSync('cert.pem') },
+     *              () => console.log('HTTPS on 443'));
      */
-    listen(port = 3000, cb)
+    listen(port = 3000, opts, cb)
     {
-        const server = http.createServer(this.handler);
+        // Normalise arguments — allow `listen(port, cb)` without opts
+        if (typeof opts === 'function') { cb = opts; opts = undefined; }
+
+        const isHTTPS = opts && (opts.key || opts.pfx || opts.cert);
+        const server = isHTTPS
+            ? https.createServer(opts, this.handler)
+            : http.createServer(this.handler);
+
+        this._server = server;
+
+        // Always attach WebSocket upgrade handling so ws() works
+        // regardless of registration order (before or after listen).
+        server.on('upgrade', (req, socket, head) =>
+        {
+            if (this._wsHandlers.size > 0)
+                handleUpgrade(req, socket, head, this._wsHandlers);
+            else
+                socket.destroy();
+        });
+
         return server.listen(port, cb);
     }
 
+    /**
+     * Gracefully close the server, stopping new connections.
+     *
+     * @param {Function} [cb] - Callback invoked once the server has closed.
+     */
+    close(cb)
+    {
+        if (this._server) this._server.close(cb);
+    }
+
+    // -- WebSocket Support -----------------------------
+
+    /**
+     * Register a WebSocket upgrade handler for a path.
+     *
+     * The handler receives `(ws, req)` where `ws` is a rich WebSocket
+     * connection object.  See {@link WebSocketConnection} for the full API.
+     *
+     * @param {string}   path        - URL path to listen for upgrade requests.
+     * @param {object|Function} [opts] - Options object, or the handler function directly.
+     * @param {number}   [opts.maxPayload=1048576]  - Maximum incoming frame size in bytes (default 1 MB).
+     * @param {number}   [opts.pingInterval=30000]  - Auto-ping interval in ms. Set `0` to disable.
+     * @param {Function} [opts.verifyClient]        - `(req) => boolean` — return false to reject the upgrade.
+     * @param {Function} handler     - `(ws, req) => void`.
+     *
+     * @example
+     *   // Simple
+     *   app.ws('/chat', (ws, req) => {
+     *       ws.on('message', data => ws.send('echo: ' + data));
+     *   });
+     *
+     *   // With options
+     *   app.ws('/feed', { maxPayload: 64 * 1024, pingInterval: 15000 }, (ws, req) => {
+     *       console.log('client', ws.id, 'from', ws.ip);
+     *       ws.sendJSON({ hello: 'world' });
+     *   });
+     */
+    ws(path, opts, handler)
+    {
+        // Normalise arguments: ws(path, handler) or ws(path, opts, handler)
+        if (typeof opts === 'function') { handler = opts; opts = {}; }
+        if (!opts) opts = {};
+
+        this._wsHandlers.set(path, { handler, opts });
+    }
+
+    // -- Route Introspection ---------------------------
+
+    /**
+     * Return a flat list of all registered routes across the router tree,
+     * including mounted sub-routers.  Useful for debugging, auto-generated
+     * docs, or CLI tooling.
+     *
+     * @returns {{ method: string, path: string }[]}
+     *
+     * @example
+     *   app.routes().forEach(r => console.log(r.method, r.path));
+     *   // GET  /users
+     *   // POST /users
+     *   // GET  /api/v1/items/:id
+     */
+    routes()
+    {
+        const list = this.router.inspect();
+
+        /* Include WebSocket upgrade handlers */
+        for (const [wsPath, { opts }] of this._wsHandlers)
+        {
+            const entry = { method: 'WS', path: wsPath };
+            if (opts && opts.maxPayload !== undefined) entry.maxPayload = opts.maxPayload;
+            if (opts && opts.pingInterval !== undefined) entry.pingInterval = opts.pingInterval;
+            list.push(entry);
+        }
+
+        return list;
+    }
+
+    // -- Route Registration ----------------------------
+
+    /**
+     * Extract an options object from the head of the handlers array when
+     * the first argument is a plain object (not a function).
+     * @private
+     */
+    _extractOpts(fns)
+    {
+        let opts = {};
+        if (fns.length > 0 && typeof fns[0] === 'object' && typeof fns[0] !== 'function')
+        {
+            opts = fns.shift();
+        }
+        return opts;
+    }
+
     /**
      * 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`.
+     * @param {...Function|object} fns - Optional options object `{ secure }` followed by handler functions.
      */
-    route(method, path, ...fns) { this.router.add(method, path, fns); }
+    route(method, path, ...fns) { const o = this._extractOpts(fns); this.router.add(method, path, fns, o); }
 
     /** @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); }

package/lib/body/json.js

@@ -15,6 +15,7 @@ const sendError = require('./sendError');
  * @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.
+ * @param {boolean}         [options.requireSecure=false] - When true, reject non-HTTPS requests with 403.
  * @returns {Function} Async middleware `(req, res, next) => void`.
  */
 function json(options = {})
@@ -24,9 +25,11 @@ function json(options = {})
   const reviver = opts.reviver;
   const strict = (opts.hasOwnProperty('strict')) ? !!opts.strict : true;
   const typeOpt = opts.type || 'application/json';
+  const requireSecure = !!opts.requireSecure;
 
   return async (req, res, next) =>
   {
+    if (requireSecure && !req.secure) return sendError(res, 403, 'HTTPS required');
     const ct = (req.headers['content-type'] || '');
     if (!isTypeMatch(ct, typeOpt)) return next();
     try

package/lib/body/multipart.js

@@ -77,12 +77,14 @@ function parseContentDisposition(cd)
  * @param {object} [opts]
  * @param {string} [opts.dir]             - Upload directory (default: OS temp dir).
  * @param {number} [opts.maxFileSize]     - Maximum file size in bytes.
+ * @param {boolean} [opts.requireSecure=false] - When true, reject non-HTTPS requests with 403.
  * @returns {Function} Async middleware `(req, res, next) => void`.
  */
 function multipart(opts = {})
 {
     return async (req, res, next) =>
     {
+        if (opts.requireSecure && !req.secure) return sendError(res, 403, 'HTTPS required');
         const ct = req.headers['content-type'] || '';
         const m = /boundary=(?:"([^"]+)"|([^;\s]+))/i.exec(ct);
         if (!m) return next();

package/lib/body/raw.js

@@ -13,6 +13,7 @@ const sendError = require('./sendError');
  * @param {object}          [options]
  * @param {string|number}   [options.limit]                           - Max body size.
  * @param {string|Function} [options.type='application/octet-stream'] - Content-Type to match.
+ * @param {boolean}         [options.requireSecure=false]             - When true, reject non-HTTPS requests with 403.
  * @returns {Function} Async middleware `(req, res, next) => void`.
  */
 function raw(options = {})
@@ -20,9 +21,11 @@ function raw(options = {})
     const opts = options || {};
     const limit = opts.limit || null;
     const typeOpt = opts.type || 'application/octet-stream';
+    const requireSecure = !!opts.requireSecure;
 
     return async (req, res, next) =>
     {
+        if (requireSecure && !req.secure) return sendError(res, 403, 'HTTPS required');
         const ct = (req.headers['content-type'] || '');
         if (!isTypeMatch(ct, typeOpt)) return next();
         try

package/lib/body/text.js

@@ -14,6 +14,7 @@ const sendError = require('./sendError');
  * @param {string|number}   [options.limit]              - Max body size.
  * @param {string}          [options.encoding='utf8']    - Character encoding.
  * @param {string|Function} [options.type='text/*']      - Content-Type to match.
+ * @param {boolean}         [options.requireSecure=false] - When true, reject non-HTTPS requests with 403.
  * @returns {Function} Async middleware `(req, res, next) => void`.
  */
 function text(options = {})
@@ -22,9 +23,11 @@ function text(options = {})
   const limit = opts.limit || null;
   const encoding = opts.encoding || 'utf8';
   const typeOpt = opts.type || 'text/*';
+  const requireSecure = !!opts.requireSecure;
 
   return async (req, res, next) =>
   {
+    if (requireSecure && !req.secure) return sendError(res, 403, 'HTTPS required');
     const ct = (req.headers['content-type'] || '');
     if (!isTypeMatch(ct, typeOpt)) return next();
     try

package/lib/body/urlencoded.js

@@ -30,6 +30,7 @@ function appendValue(prev, val)
  * @param {string|number}   [options.limit]     - Max body size (e.g. `'10kb'`).
  * @param {string|Function} [options.type='application/x-www-form-urlencoded'] - Content-Type to match.
  * @param {boolean}         [options.extended=false] - Use nested bracket parsing (e.g. `a[b][c]=1`).
+ * @param {boolean}         [options.requireSecure=false] - When true, reject non-HTTPS requests with 403.
  * @returns {Function} Async middleware `(req, res, next) => void`.
  */
 function urlencoded(options = {})
@@ -38,9 +39,11 @@ function urlencoded(options = {})
     const limit = opts.limit || null;
     const typeOpt = opts.type || 'application/x-www-form-urlencoded';
     const extended = !!opts.extended;
+    const requireSecure = !!opts.requireSecure;
 
     return async (req, res, next) =>
     {
+        if (requireSecure && !req.secure) return sendError(res, 403, 'HTTPS required');
         const ct = (req.headers['content-type'] || '');
         if (!isTypeMatch(ct, typeOpt)) return next();
         try

package/lib/{fetch.js → fetch/index.js}

@@ -23,7 +23,21 @@ const STATUS_CODES = http.STATUS_CODES;
  * @param {import('http').Agent} [opts.agent]      - Custom HTTP agent.
  * @param {Function} [opts.onDownloadProgress]     - `({ loaded, total }) => void` callback.
  * @param {Function} [opts.onUploadProgress]       - `({ loaded, total }) => void` callback.
- * @returns {Promise<{ status: number, statusText: string, ok: boolean, headers: object, arrayBuffer: Function, text: Function, json: Function }>}
+ *
+ * TLS / HTTPS options (passed through to `https.request()` when the URL is `https:`):
+ * @param {boolean}  [opts.rejectUnauthorized]     - Reject connections with unverified certs (default: Node default `true`).
+ * @param {string|Buffer|Array} [opts.ca]          - Override default CA certificates.
+ * @param {string|Buffer}       [opts.cert]        - Client certificate (PEM) for mutual TLS.
+ * @param {string|Buffer}       [opts.key]         - Private key (PEM) for mutual TLS.
+ * @param {string|Buffer}       [opts.pfx]         - PFX / PKCS12 bundle (alternative to cert+key).
+ * @param {string}              [opts.passphrase]  - Passphrase for the key or PFX.
+ * @param {string}              [opts.servername]   - SNI server name override.
+ * @param {string}              [opts.ciphers]      - Colon-separated cipher list.
+ * @param {string}              [opts.secureProtocol] - SSL/TLS protocol method name.
+ * @param {string}              [opts.minVersion]   - Minimum TLS version (`'TLSv1.2'`, etc.).
+ * @param {string}              [opts.maxVersion]   - Maximum TLS version.
+ *
+ * @returns {Promise<{ status: number, statusText: string, ok: boolean, secure: boolean, url: string, headers: object, arrayBuffer: Function, text: Function, json: Function }>}
  */
 function miniFetch(url, opts = {})
 {
@@ -66,6 +80,19 @@ function miniFetch(url, opts = {})
             const options = { method, headers };
             if (opts.agent) options.agent = opts.agent;
 
+            // Pass through TLS options for HTTPS requests
+            if (lib === https)
+            {
+                const tlsKeys = [
+                    'rejectUnauthorized', 'ca', 'cert', 'key', 'pfx', 'passphrase',
+                    'servername', 'ciphers', 'secureProtocol', 'minVersion', 'maxVersion'
+                ];
+                for (const k of tlsKeys)
+                {
+                    if (opts[k] !== undefined) options[k] = opts[k];
+                }
+            }
+
             const req = lib.request(u, options, (res) =>
             {
                 const chunks = [];
@@ -101,6 +128,8 @@ function miniFetch(url, opts = {})
                         status,
                         statusText: STATUS_CODES[status] || '',
                         ok: status >= 200 && status < 300,
+                        secure: u.protocol === 'https:',
+                        url: u.href,
                         headers: responseHeaders,
                         arrayBuffer: () => Promise.resolve(buf),
                         text: () => Promise.resolve(buf.toString('utf8')),

package/lib/http/index.js

@@ -0,0 +1,9 @@
+/**
+ * @module http
+ * @description HTTP request/response wrappers for zero-http.
+ *              Exports Request and Response classes.
+ */
+const Request = require('./request');
+const Response = require('./response');
+
+module.exports = { Request, Response };

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

@@ -1,5 +1,5 @@
 /**
- * @module request
+ * @module http/request
  * @description Lightweight wrapper around Node's `IncomingMessage`.
  *              Provides parsed query string, params, body, and convenience helpers.
  */
@@ -31,6 +31,12 @@ class Request
         this.params = {};
         this.body = null;
         this.ip = req.socket ? req.socket.remoteAddress : null;
+
+        /** `true` when the connection is over TLS (HTTPS). */
+        this.secure = !!(req.socket && req.socket.encrypted);
+
+        /** Protocol string — `'https'` or `'http'`. */
+        this.protocol = this.secure ? 'https' : 'http';
     }
 
     /**

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;