@zero-server/orm 0.9.1 → 0.9.3

package/lib/orm/replicas.js

@@ -0,0 +1,241 @@
+/**
+ * @module orm/replicas
+ * @description Read replica management with automatic read/write splitting,
+ *              round-robin and random selection strategies, sticky writes,
+ *              and health checking.
+ *
+ * @example
+ *   const { Database, ReplicaManager } = require('@zero-server/sdk');
+ *
+ *   const db = Database.connectWithReplicas('postgres',
+ *       { host: 'primary.db', database: 'app' },
+ *       [
+ *           { host: 'replica1.db', database: 'app' },
+ *           { host: 'replica2.db', database: 'app' },
+ *       ],
+ *       { strategy: 'round-robin', stickyWindow: 2000 }
+ *   );
+ */
+
+const log = require('../debug')('zero:replicas');
+
+class ReplicaManager
+{
+    /**
+     * @constructor
+     * @param {object}  [options] - Configuration options.
+     * @param {string}  [options.strategy='round-robin'] - Selection strategy: 'round-robin' | 'random'.
+     * @param {boolean} [options.stickyWrite=true]       - Read from primary after a write for stickyWindow ms.
+     * @param {number}  [options.stickyWindow=1000]      - Duration (ms) to read from primary after a write.
+     */
+    constructor(options = {})
+    {
+        /** @private */ this._primary = null;
+        /** @private */ this._replicas = [];
+
+        // Validate strategy against whitelist
+        const allowed = ['round-robin', 'random'];
+        const strategy = options.strategy || 'round-robin';
+        if (!allowed.includes(strategy))
+        {
+            throw new Error(`Invalid replica strategy: "${strategy}". Must be one of: ${allowed.join(', ')}`);
+        }
+        /** @private */ this._strategy = strategy;
+        /** @private */ this._idx = 0;
+
+        // Sticky writes: read from primary after a write to avoid stale reads
+        /** @private */ this._stickyWrite = options.stickyWrite !== false;
+        /** @private */ this._stickyWindow = Math.max(0, Number(options.stickyWindow) || 1000);
+        /** @private */ this._lastWriteAt = 0;
+    }
+
+    /**
+     * Set the primary (read-write) adapter.
+     * @param {object} adapter - Database adapter instance.
+     * @throws {Error} If adapter is null or undefined.
+     */
+    setPrimary(adapter)
+    {
+        if (!adapter) throw new Error('Primary adapter must not be null');
+        this._primary = adapter;
+    }
+
+    /**
+     * Add a read replica adapter.
+     * @param {object} adapter - Database adapter instance.
+     */
+    addReplica(adapter)
+    {
+        if (!adapter) throw new Error('Replica adapter must not be null');
+        this._replicas.push({ adapter, healthy: true, lastChecked: 0 });
+    }
+
+    /**
+     * Number of registered replicas.
+     * @type {number}
+     */
+    get replicaCount()
+    {
+        return this._replicas.length;
+    }
+
+    /**
+     * Get an adapter for read operations.
+     * Respects strategy, health status, and sticky writes.
+     *
+     * @returns {object} Adapter instance.
+     */
+    getReadAdapter()
+    {
+        // Sticky writes: use primary during the sticky window
+        if (this._stickyWrite && (Date.now() - this._lastWriteAt) < this._stickyWindow)
+        {
+            log('Sticky write window active, using primary for read');
+            return this._primary;
+        }
+
+        const healthy = this._replicas.filter(r => r.healthy);
+        if (!healthy.length)
+        {
+            log('No healthy replicas, falling back to primary');
+            return this._primary;
+        }
+
+        let replica;
+        if (this._strategy === 'random')
+        {
+            replica = healthy[Math.floor(Math.random() * healthy.length)];
+        }
+        else
+        {
+            // round-robin (reset index to prevent unbounded growth)
+            replica = healthy[this._idx % healthy.length];
+            this._idx = (this._idx + 1) % Number.MAX_SAFE_INTEGER;
+        }
+
+        return replica.adapter;
+    }
+
+    /**
+     * Get the primary adapter for write operations.
+     * Also updates the last write timestamp for sticky window tracking.
+     *
+     * @returns {object} Primary adapter instance.
+     */
+    getWriteAdapter()
+    {
+        this._lastWriteAt = Date.now();
+        return this._primary;
+    }
+
+    /**
+     * Mark a replica as unhealthy (excluded from read routing).
+     * @param {object} adapter - Database adapter instance.
+     */
+    markUnhealthy(adapter)
+    {
+        const replica = this._replicas.find(r => r.adapter === adapter);
+        if (replica)
+        {
+            replica.healthy = false;
+            log('Replica marked unhealthy');
+        }
+    }
+
+    /**
+     * Mark a replica as healthy (re-included in read routing).
+     * @param {object} adapter - Database adapter instance.
+     */
+    markHealthy(adapter)
+    {
+        const replica = this._replicas.find(r => r.adapter === adapter);
+        if (replica)
+        {
+            replica.healthy = true;
+        }
+    }
+
+    /**
+     * Run a health check on all replicas.
+     * Calls adapter.ping() if available.
+     *
+     * @returns {Promise<Array<{ healthy: boolean, lastChecked: number }>>}
+     */
+    async healthCheck()
+    {
+        const checks = this._replicas.map(async (replica) =>
+        {
+            try
+            {
+                if (typeof replica.adapter.ping === 'function')
+                {
+                    replica.healthy = await replica.adapter.ping();
+                }
+                else
+                {
+                    // Adapters without ping are assumed healthy
+                    replica.healthy = true;
+                }
+            }
+            catch
+            {
+                replica.healthy = false;
+            }
+            replica.lastChecked = Date.now();
+            return { healthy: replica.healthy, lastChecked: replica.lastChecked };
+        });
+
+        return Promise.all(checks);
+    }
+
+    /**
+     * Get all adapters (primary + replicas).
+     * @returns {object[]} Primary and all replica adapters.
+     */
+    getAllAdapters()
+    {
+        return [this._primary, ...this._replicas.map(r => r.adapter)].filter(Boolean);
+    }
+
+    /**
+     * Remove a replica adapter from the pool.
+     * @param {object} adapter - Database adapter instance.
+     */
+    removeReplica(adapter)
+    {
+        this._replicas = this._replicas.filter(r => r.adapter !== adapter);
+    }
+
+    /**
+     * Get pool status summary.
+     * @returns {{ primary: boolean, total: number, healthy: number, unhealthy: number, strategy: string }}
+     */
+    status()
+    {
+        const healthy = this._replicas.filter(r => r.healthy).length;
+        return {
+            primary: !!this._primary,
+            total: this._replicas.length,
+            healthy,
+            unhealthy: this._replicas.length - healthy,
+            strategy: this._strategy,
+        };
+    }
+
+    /**
+     * Close all adapters (primary + replicas).
+     * @returns {Promise<void>}
+     */
+    async closeAll()
+    {
+        for (const adapter of this.getAllAdapters())
+        {
+            if (typeof adapter.close === 'function')
+            {
+                await adapter.close();
+            }
+        }
+    }
+}
+
+module.exports = { ReplicaManager };

package/lib/orm/schema.js

@@ -0,0 +1,307 @@
+/**
+ * @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).
+ *
+ * @example
+ *   const { TYPES, validate } = require('@zero-server/sdk').Schema;
+ *
+ *   const columns = {
+ *       name:  { type: TYPES.STRING, required: true, minLength: 1 },
+ *       email: { type: TYPES.STRING, required: true, match: /@/ },
+ *       age:   { type: TYPES.INTEGER, min: 0, max: 150 },
+ *   };
+ *
+ *   const { valid, errors, sanitized } = validate(
+ *       { name: 'Alice', email: 'alice@example.com', age: '30' },
+ *       columns,
+ *   );
+ *   // valid: true, sanitized.age === 30 (coerced from string)
+ */
+
+/**
+ * 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',
+    // Extended numeric types
+    BIGINT:   'bigint',
+    SMALLINT: 'smallint',
+    TINYINT:  'tinyint',
+    DECIMAL:  'decimal',
+    DOUBLE:   'double',
+    REAL:     'real',
+    // Extended string / binary types
+    CHAR:     'char',
+    BINARY:   'binary',
+    VARBINARY:'varbinary',
+    // Temporal types
+    TIMESTAMP:'timestamp',
+    TIME:     'time',
+    // MySQL-specific
+    ENUM:     'enum',
+    SET:      'set',
+    MEDIUMTEXT: 'mediumtext',
+    LONGTEXT:   'longtext',
+    MEDIUMBLOB: 'mediumblob',
+    LONGBLOB:   'longblob',
+    YEAR:     'year',
+    // PostgreSQL-specific
+    SERIAL:   'serial',
+    BIGSERIAL:'bigserial',
+    JSONB:    'jsonb',
+    INTERVAL: 'interval',
+    INET:     'inet',
+    CIDR:     'cidr',
+    MACADDR:  'macaddr',
+    MONEY:    'money',
+    XML:      'xml',
+    CITEXT:   'citext',
+    ARRAY:    'array',
+    // SQLite
+    NUMERIC:  'numeric',
+};
+
+/**
+ * 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':
+        case 'mediumtext':
+        case 'longtext':
+        case 'char':
+        case 'citext':
+        case 'xml':
+        {
+            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':
+        case 'bigint':
+        case 'smallint':
+        case 'tinyint':
+        case 'serial':
+        case 'bigserial':
+        case 'year':
+        {
+            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':
+        case 'decimal':
+        case 'double':
+        case 'real':
+        case 'numeric':
+        case 'money':
+        {
+            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':
+        case 'timestamp':
+        case 'time':
+        case 'interval':
+        {
+            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':
+        case 'jsonb':
+        {
+            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':
+        case 'mediumblob':
+        case 'longblob':
+        case 'binary':
+        case 'varbinary':
+            return Buffer.isBuffer(value) ? value : Buffer.from(value);
+        case 'enum':
+        {
+            const val = String(value);
+            if (colDef.enum && !colDef.enum.includes(val))
+                throw new Error(`"${colName}" must be one of [${colDef.enum.join(', ')}]`);
+            return val;
+        }
+        case 'set':
+        {
+            const vals = Array.isArray(value) ? value : String(value).split(',');
+            if (colDef.values)
+            {
+                for (const v of vals)
+                    if (!colDef.values.includes(v.trim()))
+                        throw new Error(`"${colName}" contains invalid value "${v.trim()}". Allowed: [${colDef.values.join(', ')}]`);
+            }
+            return vals.map(v => v.trim()).join(',');
+        }
+        case 'inet':
+        case 'cidr':
+        case 'macaddr':
+            return String(value);
+        case 'array':
+            return Array.isArray(value) ? value : [value];
+        default:
+            return value;
+    }
+}
+
+// -- Validation -------------------------------------------
+
+/**
+ * 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] - Configuration 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;
+
+        // Skip guarded fields not present in data (stripped by mass-assignment)
+        if (colDef.guarded && 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 };
+}
+
+// -- DDL Security Helpers --------------------------------
+
+const VALID_FK_ACTIONS = new Set(['CASCADE', 'SET NULL', 'SET DEFAULT', 'RESTRICT', 'NO ACTION']);
+
+/**
+ * Validate and return a FK action string, or throw.
+ * @param {string} action - Foreign key action string (CASCADE, SET NULL, etc.).
+ * @returns {string} Uppercase validated action
+ */
+function validateFKAction(action)
+{
+    const upper = String(action).toUpperCase();
+    if (!VALID_FK_ACTIONS.has(upper))
+        throw new Error(`Invalid FK action: "${action}". Allowed: ${[...VALID_FK_ACTIONS].join(', ')}`);
+    return upper;
+}
+
+/**
+ * Validate a CHECK expression for dangerous SQL patterns.
+ * @param {string} expr - SQL CHECK expression to validate.
+ * @returns {string} The original expression (validated).
+ */
+function validateCheck(expr)
+{
+    const s = String(expr);
+    // Block semicolons, comment markers, and common injection patterns
+    if (/;|--|\bDROP\b|\bDELETE\b|\bINSERT\b|\bUPDATE\b|\bALTER\b|\bCREATE\b|\bEXEC\b/i.test(s))
+        throw new Error(`Potentially dangerous CHECK expression: "${s}"`);
+    return s;
+}
+
+module.exports = { TYPES, validateValue, validate, validateFKAction, validateCheck };