webspresso 0.0.104 → 0.0.106

package/core/orm/json-fields.js

@@ -3,6 +3,8 @@
  * @module core/orm/json-fields
  */
 
+const { safeJsonParse } = require('../utils/json');
+
 /**
  * Get JSON column names from model
  * @param {import('./types').ModelDefinition} model - Model definition
@@ -15,7 +17,25 @@ function getJsonColumns(model) {
   const jsonCols = new Set();
   if (model && model.columns) {
     for (const [name, meta] of model.columns) {
-      if (meta.type === 'json' || meta.type === 'array' || meta.type === 'files') {
+      if (meta && (meta.type === 'json' || meta.type === 'array' || meta.type === 'files')) {
+        jsonCols.add(name);
+      }
+    }
+  }
+  if (model && model.schema && model.schema.shape) {
+    for (const [name, fieldSchema] of Object.entries(model.schema.shape)) {
+      let current = fieldSchema;
+      while (current && current._def) {
+        if (current._def.innerType) {
+          current = current._def.innerType;
+        } else if (current._def.schema) {
+          current = current._def.schema;
+        } else {
+          break;
+        }
+      }
+      const typeName = current?._def?.typeName;
+      if (typeName === 'ZodRecord' || typeName === 'ZodObject' || typeName === 'ZodArray') {
         jsonCols.add(name);
       }
     }
@@ -57,13 +77,7 @@ function deserializeJsonFields(record, jsonColumns) {
 
   for (const col of jsonColumns) {
     if (col in record && record[col] !== null && record[col] !== undefined) {
-      if (typeof record[col] === 'string') {
-        try {
-          record[col] = JSON.parse(record[col]);
-        } catch {
-          // If parsing fails, keep the original string value
-        }
-      }
+      record[col] = safeJsonParse(record[col], record[col]);
     }
   }
   return record;

package/core/orm/migrate-cloud.js

@@ -0,0 +1,194 @@
+/**
+ * Webspresso Cloud-Ready Database Migration Runner
+ * Zero-dependency: Safe pre-flight connectivity retries, stale lock auto-healing,
+ * dry-run evaluation, and zero-downtime deployment compatibility for Google Cloud Run & AWS.
+ *
+ * @module core/orm/migrate-cloud
+ */
+
+'use strict';
+
+const { sleep } = require('../utils/time');
+
+/**
+ * Wait for database connectivity with exponential backoff
+ * Handles Cloud SQL Auth Proxy / AWS RDS Aurora cold-starts
+ * @param {import('knex').Knex} knex
+ * @param {Object} [options]
+ * @param {number} [options.retries=5]
+ * @param {number} [options.initialDelayMs=1000]
+ * @param {number} [options.maxDelayMs=10000]
+ * @param {Function} [options.onRetry]
+ * @returns {Promise<boolean>}
+ */
+async function waitForDatabaseConnection(knex, options = {}) {
+  const retries = options.retries ?? 5;
+  const initialDelay = options.initialDelayMs ?? 1000;
+  const maxDelay = options.maxDelayMs ?? 10000;
+  const onRetry = options.onRetry || (() => {});
+
+  let attempt = 0;
+  let delay = initialDelay;
+
+  while (attempt <= retries) {
+    try {
+      await knex.raw('SELECT 1');
+      return true;
+    } catch (err) {
+      attempt++;
+      if (attempt > retries) {
+        throw new Error(`Database connection failed after ${retries} attempts: ${err.message}`);
+      }
+      onRetry({ attempt, retries, delay, error: err });
+      await sleep(delay);
+      delay = Math.min(delay * 2, maxDelay);
+    }
+  }
+
+  return false;
+}
+
+/**
+ * Safely inspect and release stale migration lock
+ * @param {import('knex').Knex} knex
+ * @param {Object} [migrationConfig]
+ * @returns {Promise<boolean>} True if lock was released
+ */
+async function freeStaleMigrationLock(knex, migrationConfig = {}) {
+  try {
+    if (knex.migrate && typeof knex.migrate.forceFreeMigrationsLock === 'function') {
+      await knex.migrate.forceFreeMigrationsLock(migrationConfig);
+      return true;
+    }
+  } catch (_) {}
+  return false;
+}
+
+/**
+ * Get pending and completed migrations without running them
+ * @param {import('knex').Knex} knex
+ * @param {Object} [migrationConfig]
+ * @returns {Promise<{ completed: string[], pending: string[] }>}
+ */
+async function getMigrationStatus(knex, migrationConfig = {}) {
+  if (!knex.migrate || typeof knex.migrate.list !== 'function') {
+    return { completed: [], pending: [] };
+  }
+
+  const [completedList, pendingList] = await knex.migrate.list(migrationConfig);
+  const completed = (completedList || []).map((m) => (typeof m === 'string' ? m : m.name || String(m)));
+  const pending = (pendingList || []).map((m) => (typeof m === 'string' ? m : m.name || String(m)));
+
+  return { completed, pending };
+}
+
+/**
+ * Execute Cloud Migration with safety guarantees
+ * @param {import('knex').Knex} knex
+ * @param {Object} [options]
+ * @param {Object} [options.migrationConfig] - Custom knex migration options
+ * @param {boolean} [options.dryRun=false] - Only report pending migrations without executing
+ * @param {boolean} [options.unlockIfStale=true] - Force unlock if migrations lock was left hanging
+ * @param {boolean} [options.waitForDb=true] - Retry connecting to database before failing
+ * @param {number} [options.retries=5] - Connection retries
+ * @param {Function} [options.logger] - Custom logger callback
+ * @returns {Promise<{
+ *   success: boolean;
+ *   batch: number;
+ *   applied: string[];
+ *   pendingBefore: string[];
+ *   durationMs: number;
+ *   dryRun: boolean;
+ * }>}
+ */
+async function runCloudMigration(knex, options = {}) {
+  const {
+    migrationConfig = {},
+    dryRun = false,
+    unlockIfStale = true,
+    waitForDb = true,
+    retries = 5,
+    logger = null,
+  } = options;
+
+  const log = (msg) => {
+    if (typeof logger === 'function') logger(msg);
+  };
+
+  const startTime = Date.now();
+
+  // 1. Connectivity Check & Wait
+  if (waitForDb) {
+    log('Checking database connectivity...');
+    await waitForDatabaseConnection(knex, {
+      retries,
+      onRetry: ({ attempt, retries: max, delay, error }) => {
+        log(`Database not ready (attempt ${attempt}/${max}: ${error.message}). Retrying in ${delay}ms...`);
+      },
+    });
+    log('Database connection established.');
+  }
+
+  // 2. Inspect current migration status
+  const { completed, pending } = await getMigrationStatus(knex, migrationConfig);
+
+  if (dryRun) {
+    return {
+      success: true,
+      batch: 0,
+      applied: [],
+      pendingBefore: pending,
+      durationMs: Date.now() - startTime,
+      dryRun: true,
+    };
+  }
+
+  // 3. Stale Lock Handling
+  if (unlockIfStale) {
+    try {
+      // Check if locked
+      const lockTable = migrationConfig.tableName ? `${migrationConfig.tableName}_lock` : 'knex_migrations_lock';
+      const hasLockTable = await knex.schema.hasTable(lockTable);
+      if (hasLockTable) {
+        const lockRow = await knex(lockTable).first();
+        if (lockRow && (lockRow.is_locked === 1 || lockRow.is_locked === true)) {
+          log('Warning: Found active migration lock from previous aborted job. Unlocking...');
+          await freeStaleMigrationLock(knex, migrationConfig);
+          log('Migration lock released successfully.');
+        }
+      }
+    } catch (lockErr) {
+      log(`Note: Lock check skipped (${lockErr.message})`);
+    }
+  }
+
+  // 4. Run Migration
+  let batch = 0;
+  let applied = [];
+
+  if (pending.length > 0) {
+    log(`Applying ${pending.length} pending migration(s)...`);
+    const result = await knex.migrate.latest(migrationConfig);
+    batch = result[0];
+    applied = result[1] || [];
+    log(`Migration batch ${batch} applied successfully (${applied.length} files).`);
+  } else {
+    log('Database schema is already up to date.');
+  }
+
+  return {
+    success: true,
+    batch,
+    applied,
+    pendingBefore: pending,
+    durationMs: Date.now() - startTime,
+    dryRun: false,
+  };
+}
+
+module.exports = {
+  waitForDatabaseConnection,
+  freeStaleMigrationLock,
+  getMigrationStatus,
+  runCloudMigration,
+};

package/core/orm/model.js

@@ -39,6 +39,7 @@ function defineModel(options) {
     timestamps: timestampsOpt,
     softDelete: softDeleteOpt,
     softDeletes: softDeletesOpt,
+    rls: rlsOpt,
     options: nestedOptions = {},
   } = options;
 
@@ -185,6 +186,13 @@ function defineModel(options) {
     };
   }
 
+  const rlsConfig = rlsOpt !== undefined
+    ? rlsOpt
+    : (nestedOptions.rls !== undefined ? nestedOptions.rls : scopes.rls);
+  const normalizedRls = (typeof rlsConfig === 'function' || (rlsConfig && typeof rlsConfig === 'object'))
+    ? rlsConfig
+    : null;
+
   // Create model definition
   const model = {
     name,
@@ -198,9 +206,11 @@ function defineModel(options) {
       timestamps: Boolean(timestampsConfig),
       tenant: scopes.tenant || null,
     },
+    rls: normalizedRls,
     options: {
       timestamps: timestampsConfig || false,
       softDelete: softDeleteConfig || false,
+      rls: normalizedRls,
       ...nestedOptions,
     },
     columns,

package/core/orm/pool.js

@@ -0,0 +1,97 @@
+/**
+ * Serverless & Container Database Connection Pool Management
+ * Optimizes Knex pool configurations for Google Cloud Run, AWS Lambda/Fargate,
+ * and autoscaling container workloads to prevent database socket exhaustion.
+ * @module core/orm/pool
+ */
+
+'use strict';
+
+/**
+ * Detect if running in a serverless or auto-scaling container environment
+ * @param {Record<string, string>} [env=process.env]
+ * @returns {{ isServerless: boolean, platform: 'cloudrun'|'aws-lambda'|'ecs'|'serverless'|'standard' }}
+ */
+function isServerlessEnvironment(env = process.env) {
+  if (env.K_SERVICE || env.K_REVISION || env.CLOUD_RUN_JOB) {
+    return { isServerless: true, platform: 'cloudrun' };
+  }
+  if (env.AWS_LAMBDA_FUNCTION_NAME) {
+    return { isServerless: true, platform: 'aws-lambda' };
+  }
+  if (env.AWS_EXECUTION_ENV && !env.AWS_LAMBDA_FUNCTION_NAME) {
+    return { isServerless: true, platform: 'ecs' };
+  }
+  if (env.SERVERLESS === 'true' || env.WEBSPRESSO_SERVERLESS === 'true' || env.CONTAINER_SCALE === 'true') {
+    return { isServerless: true, platform: 'serverless' };
+  }
+  return { isServerless: false, platform: 'standard' };
+}
+
+/**
+ * Normalize and apply serverless pool protections to Knex configuration
+ * @param {Object} knexConfig
+ * @param {Object|Record<string, string>} [optionsOrEnv]
+ * @returns {Object} Normalized Knex configuration
+ */
+function normalizeServerlessPoolConfig(knexConfig = {}, optionsOrEnv = {}) {
+  // Determine if optionsOrEnv is an environment map or options object
+  const env = optionsOrEnv && optionsOrEnv.env ? optionsOrEnv.env : (
+    (optionsOrEnv.K_SERVICE || optionsOrEnv.K_REVISION || optionsOrEnv.CLOUD_RUN_JOB || optionsOrEnv.AWS_LAMBDA_FUNCTION_NAME || optionsOrEnv.AWS_EXECUTION_ENV || optionsOrEnv.SERVERLESS || optionsOrEnv.WEBSPRESSO_SERVERLESS || optionsOrEnv.CONTAINER_SCALE || optionsOrEnv.NODE_ENV)
+      ? optionsOrEnv
+      : process.env
+  );
+  const explicitOptions = typeof optionsOrEnv === 'object' && !optionsOrEnv.NODE_ENV ? optionsOrEnv : {};
+
+  const client = knexConfig.client || 'sqlite3';
+  // SQLite and Cloudflare D1 don't use external TCP connection pools
+  if (client === 'better-sqlite3' || client === 'sqlite3' || knexConfig.d1) {
+    return knexConfig;
+  }
+
+  const { isServerless, platform } = isServerlessEnvironment(env);
+  const userPool = knexConfig.pool || {};
+
+  // Check if serverless pool optimization should be applied
+  const isExplicitlyRequested = Boolean(
+    knexConfig.serverlessPool === true ||
+    userPool.serverless === true ||
+    env.WEBSPRESSO_SERVERLESS_POOL === 'true'
+  );
+
+  const isAutoEnabled = isServerless && knexConfig.serverlessPool !== false && userPool.serverless !== false;
+
+  if (!isExplicitlyRequested && !isAutoEnabled) {
+    return knexConfig;
+  }
+
+  // Serverless pool defaults:
+  // In serverless, idle containers shouldn't hold open DB connections: min: 0
+  const serverlessMin = explicitOptions.min ?? (userPool.min !== undefined ? userPool.min : 0);
+
+  // Max connections per container instance should be small (default: 2 for Lambda, 5 for Cloud Run/containers)
+  const defaultMax = isServerless && platform === 'aws-lambda' ? 2 : 5;
+  const serverlessMax = explicitOptions.max ?? (userPool.max !== undefined ? userPool.max : defaultMax);
+
+  const normalizedPool = {
+    ...userPool,
+    min: serverlessMin,
+    max: serverlessMax,
+    idleTimeoutMillis: explicitOptions.idleTimeoutMillis ?? userPool.idleTimeoutMillis ?? 30000,
+    acquireTimeoutMillis: explicitOptions.acquireTimeoutMillis ?? userPool.acquireTimeoutMillis ?? 10000,
+    createTimeoutMillis: explicitOptions.createTimeoutMillis ?? userPool.createTimeoutMillis ?? 5000,
+    destroyTimeoutMillis: explicitOptions.destroyTimeoutMillis ?? userPool.destroyTimeoutMillis ?? 5000,
+    propagateCreateError: userPool.propagateCreateError ?? false,
+    serverless: true,
+  };
+
+  return {
+    ...knexConfig,
+    pool: normalizedPool,
+  };
+}
+
+module.exports = {
+  isServerlessEnvironment,
+  normalizeServerlessPoolConfig,
+};

package/core/orm/query-builder.js

@@ -383,12 +383,56 @@ class QueryBuilder {
     return this;
   }
 
+  /**
+   * Set authenticated user context for RLS
+   * @param {Object|null} user - User object
+   * @returns {this}
+   */
+  forUser(user) {
+    this.scopeContext.user = user;
+    return this;
+  }
+
+  /**
+   * Bypass Row Level Security on this query
+   * @returns {this}
+   */
+  withoutRls() {
+    this.scopeContext.rlsDisabled = true;
+    return this;
+  }
+
+  /**
+   * Apply custom scope context
+   * @param {Object} customContext
+   * @returns {this}
+   */
+  withContext(customContext) {
+    Object.assign(this.scopeContext, customContext);
+    return this;
+  }
+
+  /**
+   * Explicitly set action mode for RLS
+   * @param {'read'|'update'|'delete'|'create'} action
+   * @returns {this}
+   */
+  asAction(action) {
+    this.action = action;
+    return this;
+  }
+
   /**
    * Resolve active Knex instance (explicit or ambient transaction)
    * @returns {import('knex').Knex|import('knex').Knex.Transaction}
    */
   getActiveKnex() {
     if (this.knex && (this.knex.isTransaction || typeof this.knex.commit === 'function')) {
+      if (typeof this.knex.isCompleted === 'function' && this.knex.isCompleted()) {
+        const ambientTrx = getAmbientTransaction();
+        if (ambientTrx) return ambientTrx;
+        return this.knex;
+      }
       return this.knex;
     }
     const ambientTrx = getAmbientTransaction();
@@ -404,7 +448,14 @@ class QueryBuilder {
    */
   _hookTrx() {
     const active = this.getActiveKnex();
-    return (active && (active.isTransaction || typeof active.commit === 'function')) ? active : null;
+    if (!active) return null;
+    if (active.isTransaction || typeof active.commit === 'function') {
+      if (typeof active.isCompleted === 'function' && active.isCompleted()) {
+        return null;
+      }
+      return active;
+    }
+    return null;
   }
 
   /**
@@ -414,12 +465,12 @@ class QueryBuilder {
    * @returns {import('knex').Knex.QueryBuilder}
    */
   toKnex(options = {}) {
-    const { includeLimitOffset = true } = options;
+    const { includeLimitOffset = true, action = this.action || 'read', mutationData = null } = options;
     const activeKnex = this.getActiveKnex();
     let qb = activeKnex(this.model.table);
 
-    // Apply global scopes
-    qb = applyScopes(qb, this.scopeContext, this.model);
+    // Apply global scopes (soft delete, multi-tenant, RLS)
+    qb = applyScopes(qb, this.scopeContext, this.model, action, mutationData);
 
     // Apply selects
     if (this.state.selects.length > 0) {
@@ -488,6 +539,15 @@ class QueryBuilder {
     return qb;
   }
 
+  /**
+   * Compile the query to a SQL string and parameter bindings
+   * @param {Object} [options]
+   * @returns {{ sql: string, bindings: Array<any>, method: string }}
+   */
+  toSQL(options = {}) {
+    return this.toKnex(options).toSQL();
+  }
+
   /**
    * Execute query and return first result
    * @returns {Promise<Object|null>}
@@ -795,7 +855,7 @@ class QueryBuilder {
    * @returns {Promise<number>} Number of deleted records
    */
   async delete() {
-    const n = await this.toKnex().delete();
+    const n = await this.toKnex({ action: 'delete' }).delete();
     if (this.cacheLayer && n > 0) {
       this.cacheLayer.invalidateModelAll(this.model);
     }
@@ -808,8 +868,10 @@ class QueryBuilder {
    * @returns {Promise<number>} Number of updated records
    */
   async update(data) {
+    const { checkUpdateRls } = require('./scopes');
+    checkUpdateRls(data, this.scopeContext, this.model);
     const serialized = serializeJsonFields(data, this.jsonColumns);
-    const n = await this.toKnex().update(serialized);
+    const n = await this.toKnex({ action: 'update', mutationData: data }).update(serialized);
     if (this.cacheLayer && n > 0) {
       this.cacheLayer.invalidateModelAll(this.model);
     }
@@ -839,14 +901,15 @@ class QueryBuilder {
   clone() {
     const cloned = new QueryBuilder(this.model, this.knex, { ...this.scopeContext }, this.cacheLayer);
     cloned.jsonColumns = this.jsonColumns;
+    cloned.action = this.action;
     cloned.state = {
-      wheres: [...this.state.wheres],
-      orderBys: [...this.state.orderBys],
+      wheres: this.state.wheres.map(w => ({ ...w })),
+      orderBys: this.state.orderBys.map(o => ({ ...o })),
       selects: [...this.state.selects],
       withs: [...this.state.withs],
       limitValue: this.state.limitValue,
       offsetValue: this.state.offsetValue,
-      scopeContext: { ...this.state.scopeContext },
+      scopeContext: cloned.scopeContext,
     };
     return cloned;
   }