s3db.js 13.6.0 → 14.0.2

package/src/plugins/api/concerns/state-machine.js

@@ -0,0 +1,288 @@
+/**
+ * State Machine Base Class
+ *
+ * Provides state transition validation and execution for workflows.
+ *
+ * @abstract
+ */
+class StateMachine {
+  constructor(states, transitions) {
+    this.STATES = states;
+    this.TRANSITIONS = transitions;
+  }
+
+  /**
+   * Validate if a transition is allowed from current state
+   *
+   * @param {string} currentState - Current state
+   * @param {string} transitionName - Transition to execute
+   * @returns {Object} { valid: boolean, newState?: string, error?: string }
+   */
+  canTransition(currentState, transitionName) {
+    const transition = this.TRANSITIONS[transitionName];
+
+    if (!transition) {
+      return {
+        valid: false,
+        error: `Unknown transition: ${transitionName}. Valid transitions: ${Object.keys(this.TRANSITIONS).join(', ')}`
+      };
+    }
+
+    // Support multiple "from" states
+    const validFromStates = Array.isArray(transition.from) ? transition.from : [transition.from];
+
+    if (!validFromStates.includes(currentState)) {
+      return {
+        valid: false,
+        error: `Cannot transition from "${currentState}" to "${transition.to}" via "${transitionName}". Expected current state to be one of: ${validFromStates.join(', ')}`
+      };
+    }
+
+    return { valid: true, newState: transition.to };
+  }
+
+  /**
+   * Execute a state transition with validation
+   *
+   * @param {Object} record - Record to transition (must have status field)
+   * @param {string} transitionName - Transition to execute
+   * @param {Object} resource - S3DB resource to update
+   * @param {Object} metadata - Additional fields to update
+   * @returns {Promise<Object>} Updated record
+   * @throws {Error} If transition is invalid or update fails
+   */
+  async transition(record, transitionName, resource, metadata = {}) {
+    const validation = this.canTransition(record.status, transitionName);
+
+    if (!validation.valid) {
+      throw new Error(`State machine error: ${validation.error}`);
+    }
+
+    // Prepare update payload
+    const updateData = {
+      status: validation.newState,
+      ...metadata,
+      lastTransitionAt: new Date().toISOString(),
+      lastTransition: transitionName
+    };
+
+    // Update record
+    const updated = await resource.patch(record.id, updateData);
+
+    return updated;
+  }
+
+  /**
+   * Get all valid transitions from current state
+   *
+   * @param {string} currentState - Current state
+   * @returns {Array<string>} List of valid transition names
+   */
+  getValidTransitions(currentState) {
+    return Object.entries(this.TRANSITIONS)
+      .filter(([_, transition]) => {
+        const validFromStates = Array.isArray(transition.from) ? transition.from : [transition.from];
+        return validFromStates.includes(currentState);
+      })
+      .map(([name]) => name);
+  }
+
+  /**
+   * Check if state is terminal (no outgoing transitions)
+   *
+   * @param {string} state - State to check
+   * @returns {boolean}
+   */
+  isTerminalState(state) {
+    return this.getValidTransitions(state).length === 0;
+  }
+}
+
+/**
+ * Notification State Machine
+ *
+ * Manages notification lifecycle: pending → processing → completed/failed
+ *
+ * States:
+ * - pending: Waiting to be processed
+ * - processing: Currently being sent
+ * - completed: Successfully delivered
+ * - failed: Failed after max retries
+ *
+ * Transitions:
+ * - START_PROCESSING: pending → processing
+ * - COMPLETE: processing → completed
+ * - FAIL: processing → failed
+ * - RETRY: processing → pending (for retry)
+ *
+ * @example
+ * const notificationSM = new NotificationStateMachine();
+ *
+ * // Start processing
+ * await notificationSM.transition(
+ *   notification,
+ *   'START_PROCESSING',
+ *   notificationsResource,
+ *   { processingStartedAt: new Date().toISOString() }
+ * );
+ *
+ * // Complete
+ * await notificationSM.transition(
+ *   notification,
+ *   'COMPLETE',
+ *   notificationsResource,
+ *   { completedAt: new Date().toISOString(), lastStatusCode: 200 }
+ * );
+ */
+export class NotificationStateMachine extends StateMachine {
+  constructor() {
+    const STATES = {
+      PENDING: 'pending',
+      PROCESSING: 'processing',
+      COMPLETED: 'completed',
+      FAILED: 'failed'
+    };
+
+    const TRANSITIONS = {
+      START_PROCESSING: { from: 'pending', to: 'processing' },
+      COMPLETE: { from: 'processing', to: 'completed' },
+      FAIL: { from: 'processing', to: 'failed' },
+      RETRY: { from: 'processing', to: 'pending' }
+    };
+
+    super(STATES, TRANSITIONS);
+  }
+}
+
+/**
+ * Attempt State Machine
+ *
+ * Manages individual attempt lifecycle: queued → running → success/failed/timeout
+ *
+ * States:
+ * - queued: Waiting to be executed
+ * - running: Currently executing
+ * - success: Completed successfully
+ * - failed: Failed (may retry)
+ * - timeout: Timed out (may retry)
+ *
+ * Transitions:
+ * - START: queued → running
+ * - SUCCEED: running → success
+ * - FAIL: running → failed
+ * - TIMEOUT: running → timeout
+ *
+ * @example
+ * const attemptSM = new AttemptStateMachine();
+ *
+ * // Create attempt
+ * const attempt = await attemptSM.create(attemptsResource, {
+ *   notificationId: notification.id,
+ *   attemptNumber: 1,
+ *   channel: 'webhook',
+ *   data: { url: 'https://...' }
+ * });
+ *
+ * // Start execution
+ * await attemptSM.transition(attempt, 'START', attemptsResource, {
+ *   startedAt: new Date().toISOString()
+ * });
+ *
+ * // Complete with success
+ * await attemptSM.transition(attempt, 'SUCCEED', attemptsResource, {
+ *   statusCode: 200,
+ *   response: { success: true },
+ *   completedAt: new Date().toISOString()
+ * });
+ */
+export class AttemptStateMachine extends StateMachine {
+  constructor() {
+    const STATES = {
+      QUEUED: 'queued',
+      RUNNING: 'running',
+      SUCCESS: 'success',
+      FAILED: 'failed',
+      TIMEOUT: 'timeout'
+    };
+
+    const TRANSITIONS = {
+      START: { from: 'queued', to: 'running' },
+      SUCCEED: { from: 'running', to: 'success' },
+      FAIL: { from: 'running', to: 'failed' },
+      TIMEOUT: { from: 'running', to: 'timeout' }
+    };
+
+    super(STATES, TRANSITIONS);
+  }
+
+  /**
+   * Create a new attempt with initial state
+   *
+   * Note: Uses insert() instead of patch() for attempts table
+   *
+   * @param {Object} resource - S3DB attempts resource
+   * @param {Object} data - Attempt data
+   * @returns {Promise<Object>} Created attempt
+   */
+  async create(resource, data) {
+    return await resource.insert({
+      ...data,
+      status: this.STATES.QUEUED,
+      createdAt: new Date().toISOString()
+    });
+  }
+
+  /**
+   * Execute transition for attempt
+   *
+   * Note: Uses insert() instead of patch() since attempts are immutable
+   *
+   * @param {Object} record - Attempt record
+   * @param {string} transitionName - Transition to execute
+   * @param {Object} resource - S3DB resource
+   * @param {Object} metadata - Additional fields
+   * @returns {Promise<Object>} New attempt record
+   */
+  async transition(record, transitionName, resource, metadata = {}) {
+    const validation = this.canTransition(record.status, transitionName);
+
+    if (!validation.valid) {
+      throw new Error(`State machine error: ${validation.error}`);
+    }
+
+    // For attempts, we insert a new record (immutable pattern)
+    const newRecord = await resource.insert({
+      ...record,
+      status: validation.newState,
+      ...metadata,
+      lastTransitionAt: new Date().toISOString(),
+      lastTransition: transitionName
+    });
+
+    return newRecord;
+  }
+}
+
+/**
+ * Factory function to create state machines
+ *
+ * @example
+ * import { createNotificationStateMachine, createAttemptStateMachine } from './state-machine.js';
+ *
+ * const notificationSM = createNotificationStateMachine();
+ * const attemptSM = createAttemptStateMachine();
+ */
+export function createNotificationStateMachine() {
+  return new NotificationStateMachine();
+}
+
+export function createAttemptStateMachine() {
+  return new AttemptStateMachine();
+}
+
+export default {
+  NotificationStateMachine,
+  AttemptStateMachine,
+  createNotificationStateMachine,
+  createAttemptStateMachine
+};

package/src/plugins/api/index.js

@@ -37,6 +37,7 @@ import { requirePluginDependency } from '../concerns/plugin-dependencies.js';
 import tryFn from '../../concerns/try-fn.js';
 import { ApiServer } from './server.js';
 import { idGenerator } from '../../concerns/id.js';
+import { resolveResourceName } from '../concerns/resource-names.js';
 
 const AUTH_DRIVER_KEYS = ['jwt', 'apiKey', 'basic', 'oidc', 'oauth2'];
 
@@ -61,9 +62,10 @@ function normalizeAuthConfig(authOptions = {}) {
     pathAuth: authOptions.pathAuth,
     strategy: authOptions.strategy || 'any',
     priorities: authOptions.priorities || {},
-    resource: authOptions.resource || 'users',
+    resource: authOptions.resource,
     usernameField: authOptions.usernameField || 'email',
-    passwordField: authOptions.passwordField || 'password'
+    passwordField: authOptions.passwordField || 'password',
+    createResource: authOptions.createResource !== false
   };
 
   const seen = new Set();
@@ -130,7 +132,29 @@ export class ApiPlugin extends Plugin {
   constructor(options = {}) {
     super(options);
 
+    const resourceNamesOption = options.resourceNames || {};
+    this._usersResourceDescriptor = {
+      defaultName: 'plg_api_users',
+      override: resourceNamesOption.authUsers || options.auth?.resource
+    };
     const normalizedAuth = normalizeAuthConfig(options.auth);
+    normalizedAuth.registration = {
+      enabled: options.auth?.registration?.enabled === true,
+      allowedFields: Array.isArray(options.auth?.registration?.allowedFields)
+        ? options.auth.registration.allowedFields
+        : [],
+      defaultRole: options.auth?.registration?.defaultRole || 'user'
+    };
+    normalizedAuth.loginThrottle = {
+      enabled: options.auth?.loginThrottle?.enabled !== false,
+      maxAttempts: options.auth?.loginThrottle?.maxAttempts || 5,
+      windowMs: options.auth?.loginThrottle?.windowMs || 60_000,
+      blockDurationMs: options.auth?.loginThrottle?.blockDurationMs || 300_000,
+      maxEntries: options.auth?.loginThrottle?.maxEntries || 10_000
+    };
+    this.usersResourceName = this._resolveUsersResourceName();
+    normalizedAuth.resource = this.usersResourceName;
+    normalizedAuth.createResource = options.auth?.createResource !== false;
 
     this.config = {
       // Server configuration
@@ -182,7 +206,8 @@ export class ApiPlugin extends Plugin {
         enabled: options.rateLimit?.enabled || false,
         windowMs: options.rateLimit?.windowMs || 60000, // 1 minute
         maxRequests: options.rateLimit?.maxRequests || 100,
-        keyGenerator: options.rateLimit?.keyGenerator || null
+        keyGenerator: options.rateLimit?.keyGenerator || null,
+        maxUniqueKeys: options.rateLimit?.maxUniqueKeys || 1000
       },
 
       // Logging configuration
@@ -288,7 +313,22 @@ export class ApiPlugin extends Plugin {
       },
 
       // Custom global middlewares
-      middlewares: options.middlewares || []
+      middlewares: options.middlewares || [],
+
+      requestId: options.requestId || { enabled: false },
+      sessionTracking: options.sessionTracking || { enabled: false },
+      events: options.events || { enabled: false },
+      metrics: options.metrics || { enabled: false },
+      failban: {
+        ...(options.failban || {}),
+        enabled: options.failban?.enabled === true,
+        resourceNames: resourceNamesOption.failban || options.failban?.resourceNames || {}
+      },
+      static: Array.isArray(options.static) ? options.static : [],
+      health: typeof options.health === 'object'
+        ? options.health
+        : { enabled: options.health !== false },
+      maxBodySize: options.maxBodySize || 10 * 1024 * 1024
     };
 
     this.config.resources = this._normalizeResourcesConfig(options.resources);
@@ -410,18 +450,43 @@ export class ApiPlugin extends Plugin {
    * @private
    */
   async _createUsersResource() {
+    const existingResource = this._findExistingUsersResource();
+
+    if (!this.config.auth.createResource) {
+      if (!existingResource) {
+        throw new Error(
+          `[API Plugin] Auth resource "${this.usersResourceName}" not found and auth.createResource is false`
+        );
+      }
+      this.usersResource = existingResource;
+      this.config.auth.resource = existingResource.name;
+      if (this.config.verbose) {
+        console.log(`[API Plugin] Using existing ${existingResource.name} resource for authentication`);
+      }
+      return;
+    }
+
+    if (existingResource) {
+      this.usersResource = existingResource;
+      this.config.auth.resource = existingResource.name;
+      if (this.config.verbose) {
+        console.log(`[API Plugin] Reusing existing ${existingResource.name} resource for authentication`);
+      }
+      return;
+    }
+
     const [ok, err, resource] = await tryFn(() =>
       this.database.createResource({
-        name: 'plg_users',
+        name: this.usersResourceName,
         attributes: {
           id: 'string|required',
           username: 'string|required|minlength:3',
-          email: 'string|required|email',  // Required to support email-based auth
+          email: 'string|required|email',
           password: 'secret|required|minlength:8',
           apiKey: 'string|optional',
           jwtSecret: 'string|optional',
           role: 'string|default:user',
-          scopes: 'array|items:string|optional',  // Authorization scopes (e.g., ['read:users', 'write:cars'])
+          scopes: 'array|items:string|optional',
           active: 'boolean|default:true',
           createdAt: 'string|optional',
           lastLoginAt: 'string|optional',
@@ -433,20 +498,40 @@ export class ApiPlugin extends Plugin {
       })
     );
 
-    if (ok) {
-      this.usersResource = resource;
-      if (this.config.verbose) {
-        console.log('[API Plugin] Created plg_users resource for authentication');
+    if (!ok) {
+      throw err;
+    }
+
+    this.usersResource = resource;
+    this.config.auth.resource = resource.name;
+    if (this.config.verbose) {
+      console.log(`[API Plugin] Created ${this.usersResourceName} resource for authentication`);
+    }
+  }
+
+  _findExistingUsersResource() {
+    const candidates = new Set([this.usersResourceName]);
+
+    const identityPlugin = this.database?.plugins?.identity || this.database?.plugins?.Identity;
+    if (identityPlugin) {
+      const identityNames = [
+        identityPlugin.usersResource?.name,
+        identityPlugin.config?.resources?.users?.mergedConfig?.name,
+        identityPlugin.config?.resources?.users?.userConfig?.name
+      ].filter(Boolean);
+      for (const name of identityNames) {
+        candidates.add(name);
       }
-    } else if (this.database.resources.plg_users) {
-      // Resource already exists
-      this.usersResource = this.database.resources.plg_users;
-      if (this.config.verbose) {
-        console.log('[API Plugin] Using existing plg_users resource');
+    }
+
+    for (const name of candidates) {
+      if (!name) continue;
+      const resource = this.database.resources?.[name];
+      if (resource) {
+        return resource;
       }
-    } else {
-      throw err;
     }
+    return null;
   }
   /**
    * Setup middlewares
@@ -584,25 +669,41 @@ export class ApiPlugin extends Plugin {
    */
   async _createRateLimitMiddleware() {
     const requests = new Map();
-    const { windowMs, maxRequests, keyGenerator } = this.config.rateLimit;
+    const { windowMs, maxRequests, keyGenerator, maxUniqueKeys } = this.config.rateLimit;
+
+    const getClientIp = (c) => {
+      const forwarded = c.req.header('x-forwarded-for');
+      if (forwarded) {
+        return forwarded.split(',')[0].trim();
+      }
+      const cfConnecting = c.req.header('cf-connecting-ip');
+      if (cfConnecting) {
+        return cfConnecting;
+      }
+      return c.req.raw?.socket?.remoteAddress || 'unknown';
+    };
 
     return async (c, next) => {
       // Generate key (IP or custom)
-      const key = keyGenerator
-        ? keyGenerator(c)
-        : c.req.header('x-forwarded-for') || c.req.header('cf-connecting-ip') || 'unknown';
+      const key = keyGenerator ? keyGenerator(c) : getClientIp(c) || 'unknown';
 
-      // Get or create request count
-      if (!requests.has(key)) {
-        requests.set(key, { count: 0, resetAt: Date.now() + windowMs });
-      }
+      let record = requests.get(key);
 
-      const record = requests.get(key);
+      // Reset expired records to prevent unbounded memory growth
+      if (record && Date.now() > record.resetAt) {
+        requests.delete(key);
+        record = null;
+      }
 
-      // Reset if window expired
-      if (Date.now() > record.resetAt) {
-        record.count = 0;
-        record.resetAt = Date.now() + windowMs;
+      if (!record) {
+        record = { count: 0, resetAt: Date.now() + windowMs };
+        requests.set(key, record);
+        if (requests.size > maxUniqueKeys) {
+          const oldestKey = requests.keys().next().value;
+          if (oldestKey) {
+            requests.delete(oldestKey);
+          }
+        }
       }
 
       // Check limit
@@ -706,14 +807,15 @@ export class ApiPlugin extends Plugin {
         return;
       }
 
-      // Skip if already compressed
-      if (c.res.headers.has('content-encoding')) {
+      // Skip if already compressed or body consumed
+      if (c.res.headers.has('content-encoding') || c.res.bodyUsed) {
         return;
       }
 
       // Skip if content-type should not be compressed
       const contentType = c.res.headers.get('content-type') || '';
-      if (skipContentTypes.some(type => contentType.startsWith(type))) {
+      const isTextLike = contentType.startsWith('text/') || contentType.includes('json');
+      if (skipContentTypes.some(type => contentType.startsWith(type)) || !isTextLike) {
         return;
       }
 
@@ -909,11 +1011,22 @@ export class ApiPlugin extends Plugin {
       port: this.config.port,
       host: this.config.host,
       database: this.database,
+      namespace: this.namespace,
       versionPrefix: this.config.versionPrefix,
       resources: this.config.resources,
       routes: this.config.routes,
       templates: this.config.templates,
       middlewares: this.compiledMiddlewares,
+      cors: this.config.cors,
+      security: this.config.security,
+      requestId: this.config.requestId,
+      sessionTracking: this.config.sessionTracking,
+      events: this.config.events,
+      metrics: this.config.metrics,
+      failban: this.config.failban,
+      static: this.config.static,
+      health: this.config.health,
+      maxBodySize: this.config.maxBodySize,
       verbose: this.config.verbose,
       auth: this.config.auth,
       docsEnabled: this.config.docs.enabled,
@@ -942,10 +1055,24 @@ export class ApiPlugin extends Plugin {
 
     if (this.server) {
       await this.server.stop();
-      this.server = null;
     }
+    this.server = null;
+  }
 
-    this.emit('plugin.stopped');
+  _resolveUsersResourceName() {
+    return resolveResourceName('api', this._usersResourceDescriptor, {
+      namespace: this.namespace
+    });
+  }
+
+  onNamespaceChanged() {
+    this.usersResourceName = this._resolveUsersResourceName();
+    if (this.config?.auth) {
+      this.config.auth.resource = this.usersResourceName;
+    }
+    if (this.server?.failban) {
+      this.server.failban.setNamespace(this.namespace);
+    }
   }
 
   /**
@@ -959,11 +1086,9 @@ export class ApiPlugin extends Plugin {
 
     // Optionally delete users resource
     if (purgeData && this.usersResource) {
-      // Delete all users (plugin data cleanup happens automatically via base Plugin class)
-      const [ok] = await tryFn(() => this.database.deleteResource('plg_users'));
-
+      const [ok] = await tryFn(() => this.database.deleteResource(this.usersResourceName));
       if (ok && this.config.verbose) {
-        console.log('[API Plugin] Deleted plg_users resource');
+        console.log(`[API Plugin] Deleted ${this.usersResourceName} resource`);
       }
     }
 
@@ -994,4 +1119,18 @@ export { OIDCClient } from './auth/oidc-client.js';
 export * from './concerns/guards-helpers.js';
 
 // Export template engine utilities
-export { setupTemplateEngine, ejsEngine, jsxEngine } from './utils/template-engine.js';
+export { setupTemplateEngine, ejsEngine, pugEngine, jsxEngine } from './utils/template-engine.js';
+
+// Export OpenGraph helper
+export { OpenGraphHelper } from './concerns/opengraph-helper.js';
+
+// Export state machines
+export {
+  NotificationStateMachine,
+  AttemptStateMachine,
+  createNotificationStateMachine,
+  createAttemptStateMachine
+} from './concerns/state-machine.js';
+
+// Export route context utilities (NEW!)
+export { RouteContext, withContext } from './concerns/route-context.js';