zero-http 0.2.5 → 0.3.1

package/lib/orm/schema.js

@@ -0,0 +1,172 @@
+/**
+ * @module orm/schema
+ * @description Schema definition and validation for ORM models.
+ *              Validates data against column definitions, coerces types,
+ *              and enforces constraints (required, unique, min, max, enum, match).
+ */
+
+/**
+ * Supported column types.
+ * @enum {string}
+ */
+const TYPES = {
+    STRING:   'string',
+    INTEGER:  'integer',
+    FLOAT:    'float',
+    BOOLEAN:  'boolean',
+    DATE:     'date',
+    DATETIME: 'datetime',
+    JSON:     'json',
+    TEXT:     'text',
+    BLOB:     'blob',
+    UUID:     'uuid',
+};
+
+/**
+ * Validate and sanitise a single value against a column definition.
+ *
+ * @param {*}      value   - Raw input value.
+ * @param {object} colDef  - Column definition.
+ * @param {string} colName - Column name (for error messages).
+ * @returns {*} Coerced value.
+ * @throws {Error} On validation failure.
+ */
+function validateValue(value, colDef, colName)
+{
+    const type = colDef.type || 'string';
+
+    // Handle null/undefined
+    if (value === undefined || value === null)
+    {
+        if (colDef.required && colDef.default === undefined)
+            throw new Error(`"${colName}" is required`);
+        if (colDef.default !== undefined)
+            return typeof colDef.default === 'function' ? colDef.default() : colDef.default;
+        return colDef.nullable !== false ? null : undefined;
+    }
+
+    switch (type)
+    {
+        case 'string':
+        case 'text':
+        {
+            const val = String(value);
+            if (colDef.minLength !== undefined && val.length < colDef.minLength)
+                throw new Error(`"${colName}" must be at least ${colDef.minLength} characters`);
+            if (colDef.maxLength !== undefined && val.length > colDef.maxLength)
+                throw new Error(`"${colName}" must be at most ${colDef.maxLength} characters`);
+            if (colDef.match && !colDef.match.test(val))
+                throw new Error(`"${colName}" does not match pattern ${colDef.match}`);
+            if (colDef.enum && !colDef.enum.includes(val))
+                throw new Error(`"${colName}" must be one of [${colDef.enum.join(', ')}]`);
+            // Sanitise: prevent SQL-like injection patterns in string values
+            return val;
+        }
+        case 'integer':
+        {
+            const val = typeof value === 'string' ? parseInt(value, 10) : Math.floor(Number(value));
+            if (isNaN(val)) throw new Error(`"${colName}" must be an integer`);
+            if (colDef.min !== undefined && val < colDef.min)
+                throw new Error(`"${colName}" must be >= ${colDef.min}`);
+            if (colDef.max !== undefined && val > colDef.max)
+                throw new Error(`"${colName}" must be <= ${colDef.max}`);
+            return val;
+        }
+        case 'float':
+        {
+            const val = Number(value);
+            if (isNaN(val)) throw new Error(`"${colName}" must be a number`);
+            if (colDef.min !== undefined && val < colDef.min)
+                throw new Error(`"${colName}" must be >= ${colDef.min}`);
+            if (colDef.max !== undefined && val > colDef.max)
+                throw new Error(`"${colName}" must be <= ${colDef.max}`);
+            return val;
+        }
+        case 'boolean':
+        {
+            if (typeof value === 'boolean') return value;
+            if (typeof value === 'string')
+            {
+                const lower = value.toLowerCase();
+                if (['true', '1', 'yes'].includes(lower)) return true;
+                if (['false', '0', 'no'].includes(lower)) return false;
+            }
+            if (typeof value === 'number') return value !== 0;
+            throw new Error(`"${colName}" must be a boolean`);
+        }
+        case 'date':
+        case 'datetime':
+        {
+            if (value instanceof Date) return value;
+            const d = new Date(value);
+            if (isNaN(d.getTime())) throw new Error(`"${colName}" must be a valid date`);
+            return d;
+        }
+        case 'json':
+        {
+            if (typeof value === 'string')
+            {
+                try { return JSON.parse(value); }
+                catch (e) { throw new Error(`"${colName}" must be valid JSON`); }
+            }
+            // Already an object/array — return as-is for storage
+            return value;
+        }
+        case 'uuid':
+        {
+            const val = String(value);
+            if (!/^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i.test(val))
+                throw new Error(`"${colName}" must be a valid UUID`);
+            return val;
+        }
+        case 'blob':
+            return Buffer.isBuffer(value) ? value : Buffer.from(value);
+        default:
+            return value;
+    }
+}
+
+/**
+ * Validate all columns of a data object against the schema.
+ *
+ * @param {object} data     - Input data object.
+ * @param {object} columns  - Schema column definitions.
+ * @param {object} [options]
+ * @param {boolean} [options.partial=false] - When true, only validates provided fields (for updates).
+ * @returns {{ valid: boolean, errors: string[], sanitized: object }}
+ */
+function validate(data, columns, options = {})
+{
+    const errors = [];
+    const sanitized = {};
+
+    for (const [colName, colDef] of Object.entries(columns))
+    {
+        // Skip auto fields on create
+        if (colDef.primaryKey && colDef.autoIncrement && data[colName] === undefined) continue;
+
+        if (options.partial && data[colName] === undefined) continue;
+
+        try
+        {
+            sanitized[colName] = validateValue(data[colName], colDef, colName);
+        }
+        catch (e)
+        {
+            errors.push(e.message);
+        }
+    }
+
+    // Reject unknown keys (prevent mass-assignment)
+    for (const key of Object.keys(data))
+    {
+        if (!columns[key])
+        {
+            errors.push(`Unknown column "${key}"`);
+        }
+    }
+
+    return { valid: errors.length === 0, errors, sanitized };
+}
+
+module.exports = { TYPES, validateValue, validate };

package/lib/router/index.js

@@ -5,6 +5,8 @@
  *              mounting, and route introspection.
  */
 
+const log = require('../debug')('zero:router');
+
 /**
  * Convert a route path pattern into a RegExp and extract named parameter keys.
  * Supports `:param` segments and trailing `*` wildcards.
@@ -56,6 +58,11 @@ class Router
         this.routes = [];
         /** @type {{ prefix: string, router: Router }[]} */
         this._children = [];
+        /**
+         * Parameter pre-processing handlers (set by parent App).
+         * @type {Object<string, Function[]>}
+         */
+        this._paramHandlers = {};
     }
 
     /**
@@ -74,6 +81,7 @@ class Router
         const entry = { method: method.toUpperCase(), path, regex, keys, handlers };
         if (options.secure !== undefined) entry.secure = !!options.secure;
         this.routes.push(entry);
+        log.debug('route added %s %s', method.toUpperCase(), path);
     }
 
     /**
@@ -90,6 +98,7 @@ class Router
         {
             const cleanPrefix = prefix.endsWith('/') ? prefix.slice(0, -1) : prefix;
             this._children.push({ prefix: cleanPrefix, router });
+            log.debug('mounted child router at %s', cleanPrefix);
         }
     }
 
@@ -103,46 +112,10 @@ class Router
      */
     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 (!this._matchAndExecute(req, res))
         {
-            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();
+            res.status(404).json({ error: 'Not Found' });
         }
-
-        // 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' });
     }
 
     /**
@@ -155,42 +128,129 @@ class Router
      * @private
      */
     _tryHandle(req, res)
+    {
+        return this._matchAndExecute(req, res);
+    }
+
+    /**
+     * Shared route matching and handler execution.
+     * Returns `true` if a route matched (handler invoked), `false` otherwise.
+     *
+     * @param {import('./request')}  req
+     * @param {import('./response')} res
+     * @returns {boolean}
+     * @private
+     */
+    _matchAndExecute(req, res)
     {
         const method = req.method.toUpperCase();
         const url = req.url.split('?')[0];
+        log.debug('%s %s', method, url);
 
-        for (const r of this.routes)
+        // Try own routes first
+        for (let ri = 0; ri < this.routes.length; ri++)
         {
+            const r = this.routes[ri];
             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] || ''));
+            for (let i = 0; i < r.keys.length; i++)
+            {
+                req.params[r.keys[i]] = decodeURIComponent(m[i + 1] || '');
+            }
+
+            // Run param pre-processing handlers
+            const paramHandlers = this._paramHandlers || {};
+            let paramKeys;
+            let paramCount = 0;
+            for (let i = 0; i < r.keys.length; i++)
+            {
+                if (paramHandlers[r.keys[i]])
+                {
+                    if (!paramKeys) paramKeys = [];
+                    paramKeys.push(r.keys[i]);
+                    paramCount++;
+                }
+            }
+
+            let pIdx = 0;
+            const runParams = () =>
+            {
+                if (pIdx < paramCount)
+                {
+                    const pk = paramKeys[pIdx++];
+                    const fns = paramHandlers[pk];
+                    let fIdx = 0;
+                    const nextParam = () =>
+                    {
+                        if (fIdx < fns.length)
+                        {
+                            const fn = fns[fIdx++];
+                            try
+                            {
+                                const result = fn(req, res, nextParam, req.params[pk]);
+                                if (result && typeof result.catch === 'function')
+                                {
+                                    result.catch(e => this._handleRouteError(e, req, res));
+                                }
+                            }
+                            catch (e) { this._handleRouteError(e, req, res); }
+                        }
+                        else { runParams(); }
+                    };
+                    nextParam();
+                }
+                else { runHandlers(); }
+            };
+
             let idx = 0;
-            const next = () =>
+            const runHandlers = () =>
             {
                 if (idx < r.handlers.length)
                 {
                     const h = r.handlers[idx++];
-                    return h(req, res, next);
+                    try
+                    {
+                        const result = h(req, res, runHandlers);
+                        if (result && typeof result.catch === 'function')
+                        {
+                            result.catch(e => this._handleRouteError(e, req, res));
+                        }
+                    }
+                    catch (e)
+                    {
+                        this._handleRouteError(e, req, res);
+                    }
                 }
             };
-            next();
+
+            if (paramCount > 0) runParams();
+            else runHandlers();
             return true;
         }
 
-        for (const child of this._children)
+        // Try child routers
+        for (let ci = 0; ci < this._children.length; ci++)
         {
+            const child = this._children[ci];
             if (url === child.prefix || url.startsWith(child.prefix + '/'))
             {
                 const origUrl = req.url;
+                const origBaseUrl = req.baseUrl || '';
+                req.baseUrl = origBaseUrl + child.prefix;
                 req.url = req.url.slice(child.prefix.length) || '/';
-                const found = child.router._tryHandle(req, res);
-                if (found) return true;
+                child.router._paramHandlers = this._paramHandlers;
+                try
+                {
+                    const found = child.router._matchAndExecute(req, res);
+                    if (found) return true;
+                }
+                catch (e) { this._handleRouteError(e, req, res); return true; }
                 req.url = origUrl;
+                req.baseUrl = origBaseUrl;
             }
         }
 
@@ -249,6 +309,35 @@ class Router
 
     // -- Introspection -----------------------------------
 
+    /**
+     * Handle an error thrown by a route handler.
+     * Delegates to the app-level error handler if available, otherwise
+     * sends a generic 500 JSON response.
+     *
+     * @param {Error} err
+     * @param {import('../http/request')} req
+     * @param {import('../http/response')} res
+     * @private
+     */
+    _handleRouteError(err, req, res)
+    {
+        log.error('route error: %s', err.message || err);
+        // Check if the app has an error handler (set via app.onError())
+        if (req.app && req.app._errorHandler)
+        {
+            return req.app._errorHandler(err, req, res, () => {});
+        }
+        const statusCode = err.statusCode || err.status || 500;
+        if (!res.headersSent && !(res.raw && res.raw.headersSent))
+        {
+            res.status(statusCode).json(
+                typeof err.toJSON === 'function'
+                    ? err.toJSON()
+                    : { error: err.message || 'Internal Server Error' }
+            );
+        }
+    }
+
     /**
      * Return a flat list of all registered routes, including those in
      * mounted child routers.  Useful for debugging or auto-documentation.

package/lib/sse/stream.js

@@ -8,6 +8,8 @@
  *   - `lastEventId`  {string|null}  The `Last-Event-ID` header from the client reconnection.
  *   - `eventCount`   {number}  Total events sent on this stream.
  *   - `bytesSent`    {number}  Total bytes written to the stream.
+ *
+ * @requires ../debug
  *   - `connectedAt`  {number}  Timestamp (ms) when the stream was opened.
  *   - `uptime`       {number}  Milliseconds since the stream was opened (computed).
  *   - `data`         {object}  Arbitrary user-data store.
@@ -26,6 +28,7 @@ class SSEStream
     {
         this._raw = raw;
         this._closed = false;
+        this._log = require('../debug')('zero:sse');
 
         /** `true` when the underlying connection is over TLS (HTTPS). */
         this.secure = !!opts.secure;
@@ -67,10 +70,11 @@ class SSEStream
         {
             this._closed = true;
             this._clearKeepAlive();
+            this._log.debug('stream closed, %d events sent', this.eventCount);
             this._emit('close');
         });
 
-        raw.on('error', (err) => this._emit('error', err));
+        raw.on('error', (err) => { this._log.error('stream error: %s', err.message); this._emit('error', err); });
     }
 
     // -- Event Emitter ---------------------------------
@@ -171,7 +175,13 @@ class SSEStream
      */
     _formatData(data)
     {
-        const payload = typeof data === 'object' ? JSON.stringify(data) : String(data);
+        let payload;
+        if (typeof data === 'object')
+        {
+            try { payload = JSON.stringify(data); }
+            catch (e) { payload = '[Serialization Error]'; }
+        }
+        else { payload = String(data); }
         return payload.split('\n').map(line => `data: ${line}\n`).join('');
     }
 
@@ -240,7 +250,9 @@ class SSEStream
     comment(text)
     {
         if (this._closed) return this;
-        this._write(`: ${text}\n\n`);
+        // Escape newlines to prevent SSE frame injection
+        const safe = String(text).split('\n').join('\n: ');
+        this._write(`: ${safe}\n\n`);
         return this;
     }
 

package/lib/ws/connection.js

@@ -4,6 +4,8 @@
  *              Implements RFC 6455 framing for text, binary, ping, pong, and close.
  */
 
+const log = require('../debug')('zero:ws');
+
 /** Auto-incrementing connection ID counter. */
 let _wsIdCounter = 0;
 
@@ -66,6 +68,7 @@ class WebSocketConnection
 
         /** Unique connection identifier. */
         this.id = 'ws_' + (++_wsIdCounter) + '_' + Date.now().toString(36);
+        log.info('connection opened id=%s ip=%s', this.id, socket.remoteAddress);
 
         /** Current ready state. */
         this.readyState = WS_READY_STATE.OPEN;
@@ -121,10 +124,11 @@ class WebSocketConnection
             {
                 this.readyState = WS_READY_STATE.CLOSED;
                 this._clearPing();
+                log.info('connection closed id=%s', this.id);
                 this._emit('close', 1006, '');
             }
         });
-        socket.on('error', (err) => this._emit('error', err));
+        socket.on('error', (err) => { log.error('socket error id=%s: %s', this.id, err.message); this._emit('error', err); });
         socket.on('drain', () => this._emit('drain'));
     }
 
@@ -229,7 +233,14 @@ class WebSocketConnection
      */
     sendJSON(obj, cb)
     {
-        return this.send(JSON.stringify(obj), { callback: cb });
+        let json;
+        try { json = JSON.stringify(obj); }
+        catch (e)
+        {
+            this._emit('error', new Error('Failed to serialize JSON: ' + e.message));
+            return false;
+        }
+        return this.send(json, { callback: cb });
     }
 
     /**
@@ -371,7 +382,12 @@ class WebSocketConnection
             else if (payloadLen === 127)
             {
                 if (this._buffer.length < 10) return;
-                payloadLen = this._buffer.readUInt32BE(6);
+                // RFC 6455: 64-bit unsigned integer; read upper and lower 32-bit halves
+                const upper = this._buffer.readUInt32BE(2);
+                const lower = this._buffer.readUInt32BE(6);
+                // Reject frames where upper 32 bits are set (>4GB not supported)
+                if (upper > 0) { this.close(1009, 'Message too big'); this._buffer = Buffer.alloc(0); return; }
+                payloadLen = lower;
                 offset = 10;
             }
 

package/lib/ws/handshake.js

@@ -7,6 +7,7 @@
  */
 const crypto = require('crypto');
 const WebSocketConnection = require('./connection');
+const log = require('../debug')('zero:ws');
 
 /** RFC 6455 magic GUID used in the Sec-WebSocket-Accept hash. */
 const WS_MAGIC = '258EAFA5-E914-47DA-95CA-C5AB0DC85B11';
@@ -29,6 +30,7 @@ function handleUpgrade(req, socket, head, wsHandlers)
 
     if (!entry)
     {
+        log.warn('no WS handler for %s', urlPath);
         socket.write('HTTP/1.1 404 Not Found\r\n\r\n');
         socket.destroy();
         return;
@@ -84,6 +86,7 @@ function handleUpgrade(req, socket, head, wsHandlers)
 
     handshake += '\r\n';
     socket.write(handshake);
+    log.info('upgrade complete for %s', urlPath);
 
     // -- Parse query string ----------------------------
     const qIdx = req.url.indexOf('?');

package/lib/ws/index.js

@@ -1,12 +1,14 @@
 /**
  * @module ws
  * @description WebSocket support for zero-http.
- *              Exports the connection class and upgrade handler.
+ *              Exports the connection class, upgrade handler, and pool manager.
  */
 const WebSocketConnection = require('./connection');
 const handleUpgrade = require('./handshake');
+const WebSocketPool = require('./room');
 
 module.exports = {
     WebSocketConnection,
     handleUpgrade,
+    WebSocketPool,
 };