threadforge 0.1.1 → 0.2.1

package/src/plugins/PluginManager.js

@@ -1,537 +0,0 @@
-/**
- * ThreadForge Plugin System
- *
- * Plugins add infrastructure to your app without boilerplate.
- * They handle connection management, health checks, nginx routing,
- * graceful shutdown, and inject clients into every service.
- *
- * ═══════════════════════════════════════════════════════════════
- * USAGE
- * ═══════════════════════════════════════════════════════════════
- *
- *   // forge.config.ts
- *   import { defineServices } from 'threadforge';
- *   import { redis, postgres, s3 } from 'threadforge/plugins';
- *
- *   export default defineServices({
- *     plugins: [
- *       redis({ url: 'redis://localhost:6379' }),
- *       postgres({ url: 'postgres://user:pass@localhost:5432/mydb' }),
- *       s3({ bucket: 'my-uploads', region: 'us-east-1' }),
- *     ],
- *
- *     users: {
- *       entry: './services/users.ts',
- *       port: 3001,
- *       plugins: ['redis', 'postgres'],  // opt-in per service
- *     },
- *
- *     uploads: {
- *       entry: './services/uploads.ts',
- *       port: 3002,
- *       plugins: ['s3'],
- *     },
- *   });
- *
- * In your service:
- *
- *   @Prefix('/api/users')
- *   class UserService extends Service {
- *     async onStart(ctx) {
- *       // Injected by plugins — ready to use, connection managed
- *       const cached = await this.redis.get('user:123');
- *       const rows = await this.pg.query('SELECT * FROM users WHERE id = $1', [123]);
- *     }
- *   }
- *
- * ═══════════════════════════════════════════════════════════════
- * PLUGIN LIFECYCLE
- * ═══════════════════════════════════════════════════════════════
- *
- *   forge start
- *     │
- *     ▼ Supervisor reads config, finds plugins
- *     │
- *     ▼ plugin.validate()        — check config, throw if bad
- *     ▼ plugin.env()             — env vars for workers (connection strings)
- *     ▼ plugin.nginx()           — nginx location blocks (admin UIs, proxying)
- *     │
- *     ▼ Workers fork
- *     │
- *     ▼ plugin.connect()         — create client, connect, return instance
- *     ▼ service.redis = client   — injected onto service instance
- *     ▼ service.onStart(ctx)     — your code runs, clients ready
- *     │
- *     ▼ plugin.healthCheck()     — called by /health endpoint
- *     │
- *     ▼ shutdown
- *     ▼ plugin.disconnect()      — close connections, drain pools
- *
- * ═══════════════════════════════════════════════════════════════
- * WRITING A PLUGIN
- * ═══════════════════════════════════════════════════════════════
- *
- *   export function myPlugin(options) {
- *     return {
- *       name: 'myPlugin',
- *       version: '1.0.0',
- *
- *       // What property name to inject on the service (this.myPlugin)
- *       inject: 'myPlugin',
- *
- *       // Validate config before startup (fail fast)
- *       validate() { ... },
- *
- *       // Env vars to pass to workers
- *       env() { return { MY_PLUGIN_URL: options.url }; },
- *
- *       // Create and return the client (called once per worker)
- *       async connect(ctx) {
- *         const client = new MyClient(options.url);
- *         await client.connect();
- *         return client;
- *       },
- *
- *       // Health check (called by GET /health)
- *       async healthCheck(client) {
- *         await client.ping();
- *         return { status: 'ok' };
- *       },
- *
- *       // Clean shutdown
- *       async disconnect(client) {
- *         await client.quit();
- *       },
- *
- *       // Nginx config blocks (optional)
- *       nginx() {
- *         return {
- *           upstreams: [{ name: 'myPlugin', host: 'localhost', port: 8080 }],
- *           locations: [{ path: '/admin/myplugin', proxy_pass: 'myPlugin' }],
- *         };
- *       },
- *
- *       // Prometheus metrics (optional)
- *       metrics(client) {
- *         return { pool_size: client.pool.totalCount };
- *       },
- *     };
- *   }
- */
-
-// ─── Plugin Interface ──────────────────────────────────────
-
-/**
- * @typedef {Object} ForgePlugin
- * @property {string} name            - Unique plugin name
- * @property {string} [version]       - Plugin version
- * @property {string} inject          - Property name on service (this.redis, this.pg, etc.)
- * @property {Function} [validate]    - Validate config, throw on error
- * @property {Function} [env]         - Return env vars for workers: () => Record<string, string>
- * @property {Function} connect       - Create client: (ctx: ForgeContext) => Promise<any>
- * @property {Function} [healthCheck] - Check health: (client: any) => Promise<{status: string}>
- * @property {Function} [disconnect]  - Close connections: (client: any) => Promise<void>
- * @property {Function} [nginx]       - Nginx config: () => { upstreams?, locations? }
- * @property {Function} [metrics]     - Prometheus metrics: (client: any) => Record<string, number>
- * @property {Function} [middleware]  - HTTP middleware: (client: any) => (req, res, next) => void
- * @property {Function} [onWsUpgrade] - WebSocket upgrade hook: (client, ctx) => Promise<boolean|{allow:boolean,statusCode?:number,reason?:string}>
- * @property {Function} [onWsConnect] - WebSocket connect hook: (client, ctx) => Promise<void>
- * @property {Function} [onWsMessage] - WebSocket message hook: (client, ctx) => Promise<void>
- * @property {Function} [onWsClose]   - WebSocket close hook: (client, ctx) => Promise<void>
- */
-
-// ─── Timeout Helper ────────────────────────────────────────
-
-/**
- * Race a promise against a timeout. Resolves/rejects with the promise
- * result if it finishes first, otherwise rejects with a timeout error.
- */
-function withTimeout(promise, ms, label) {
-  return new Promise((resolve, reject) => {
-    const timer = setTimeout(() => {
-      reject(new Error(`${label} timed out after ${ms}ms`));
-    }, ms);
-    promise.then(
-      (val) => {
-        clearTimeout(timer);
-        resolve(val);
-      },
-      (err) => {
-        clearTimeout(timer);
-        reject(err);
-      },
-    );
-  });
-}
-
-// Default timeouts (ms)
-const CONNECT_TIMEOUT = 10_000;
-const HEALTH_TIMEOUT = 5_000;
-const DISCONNECT_TIMEOUT = 5_000;
-
-// ─── Plugin Manager ────────────────────────────────────────
-
-/**
- * Manages plugin lifecycle across the supervisor and workers.
- */
-export class PluginManager {
-  constructor(options = {}) {
-    /** @type {Map<string, ForgePlugin>} */
-    this.plugins = new Map();
-
-    /** @type {Map<string, any>} plugin name → connected client */
-    this.clients = new Map();
-
-    /** @type {Map<string, Promise>} plugin name → in-flight connect promise (C-PLUGIN-2) */
-    this._connecting = new Map();
-
-    this._logger = options.logger ?? {
-      info: (...args) => console.log('[PluginManager]', ...args),
-      warn: (...args) => console.warn('[PluginManager]', ...args),
-      error: (...args) => console.error('[PluginManager]', ...args),
-    };
-  }
-
-  /**
-   * Register plugins from config.
-   */
-  register(plugins) {
-    if (!plugins || !Array.isArray(plugins)) return;
-
-    // Build set of existing inject names
-    const injectNames = new Set();
-    for (const [, p] of this.plugins) {
-      if (p.inject) injectNames.add(p.inject);
-    }
-
-    for (const plugin of plugins) {
-      if (!plugin.name) throw new Error("Plugin must have a name");
-      if (!plugin.inject) throw new Error(`Plugin "${plugin.name}" must have an inject property`);
-      if (!plugin.connect) throw new Error(`Plugin "${plugin.name}" must have a connect() method`);
-      for (const optionalFn of [
-        "validate",
-        "env",
-        "healthCheck",
-        "disconnect",
-        "nginx",
-        "metrics",
-        "middleware",
-        "onWsUpgrade",
-        "onWsConnect",
-        "onWsMessage",
-        "onWsClose",
-      ]) {
-        if (plugin[optionalFn] !== undefined && typeof plugin[optionalFn] !== "function") {
-          throw new Error(`Plugin "${plugin.name}" optional hook "${optionalFn}" must be a function`);
-        }
-      }
-
-      if (this.plugins.has(plugin.name)) {
-        throw new Error(`Duplicate plugin: "${plugin.name}"`);
-      }
-
-      if (injectNames.has(plugin.inject)) {
-        throw new Error(`Duplicate plugin inject name: "${plugin.inject}"`);
-      }
-      injectNames.add(plugin.inject);
-
-      this.plugins.set(plugin.name, plugin);
-    }
-  }
-
-  /**
-   * Validate all plugins (called by Supervisor before forking).
-   * Throws on first error.
-   */
-  validate() {
-    for (const [name, plugin] of this.plugins) {
-      if (plugin.validate) {
-        try {
-          plugin.validate();
-        } catch (err) {
-          throw new Error(`Plugin "${name}" validation failed: ${err.message}`);
-        }
-      }
-    }
-  }
-
-  /**
-   * Collect env vars from all plugins (supervisor passes to workers).
-   */
-  env() {
-    const merged = {};
-    for (const [, plugin] of this.plugins) {
-      if (plugin.env) {
-        const pluginEnv = plugin.env();
-        for (const key of Object.keys(pluginEnv)) {
-          if (merged[key] !== undefined) {
-            throw new Error(`Plugin env var conflict: "${key}" is set by multiple plugins`);
-          }
-        }
-        Object.assign(merged, pluginEnv);
-      }
-    }
-    return merged;
-  }
-
-  /**
-   * Connect all plugins for a specific service.
-   * Only connects plugins the service opts into.
-   *
-   * @param {string[]} servicePlugins - Plugin names this service uses
-   * @param {any} ctx - ForgeContext
-   * @returns {Promise<Map<string, any>>} inject name → client
-   */
-  async connectForService(servicePlugins, ctx) {
-    const clients = new Map();
-
-    // If service doesn't specify plugins, connect ALL registered plugins
-    const pluginNames = servicePlugins ?? [...this.plugins.keys()];
-
-    // H-PLUGIN-2: Connect independent plugins in parallel for faster startup.
-    // Separate into cached/in-flight (resolved immediately) and fresh (connected concurrently).
-    const pendingConnects = []; // Array of { name, plugin, promise }
-
-    for (const name of pluginNames) {
-      const plugin = this.plugins.get(name);
-      if (!plugin) {
-        ctx.logger.warn(`Plugin "${name}" not registered, skipping`);
-        continue;
-      }
-
-      // Reuse existing connection if already connected in this worker
-      if (this.clients.has(name)) {
-        const cached = this.clients.get(name);
-        if (cached !== null && typeof cached === 'object' && cached._pluginError === true) {
-          const attempts = cached.attempts ?? 0;
-          const retryAfterMs = Math.min(5000 * 2 ** attempts, 30000);
-          if (Date.now() - cached.timestamp < retryAfterMs) {
-            const errMsg = cached.errorMessage;
-            const errorProxy = new Proxy({}, {
-              get(_, prop) {
-                if (prop === 'then') return undefined;
-                throw new Error(`Plugin "${name}" is unavailable (connection failed: ${errMsg})`);
-              }
-            });
-            clients.set(plugin.inject, errorProxy);
-            continue;
-          }
-          this.clients.delete(name);
-        } else if (cached !== null && !(typeof cached === 'object' && cached._pluginError === true)) {
-          clients.set(plugin.inject, cached);
-          continue;
-        }
-      }
-
-      // C-PLUGIN-2: Prevent double-connect — join in-flight connection
-      if (this._connecting.has(name)) {
-        pendingConnects.push({ name, plugin, promise: this._connecting.get(name), isJoin: true });
-        continue;
-      }
-
-      // Fresh connection — launch now, await later (parallel)
-      const connectPromise = (async () => {
-        const startTime = performance.now();
-        const client = await withTimeout(plugin.connect(ctx), CONNECT_TIMEOUT, `Plugin "${name}" connect`);
-        const duration = performance.now() - startTime;
-        ctx.metrics?.histogram?.('forge_plugin_connect_duration_ms', duration, { plugin: name, status: 'success' });
-        return client;
-      })();
-      this._connecting.set(name, connectPromise);
-      pendingConnects.push({ name, plugin, promise: connectPromise, isJoin: false });
-    }
-
-    // Await all pending connections concurrently
-    const results = await Promise.allSettled(pendingConnects.map(p => p.promise));
-    for (let i = 0; i < pendingConnects.length; i++) {
-      const { name, plugin, isJoin } = pendingConnects[i];
-      const result = results[i];
-
-      if (result.status === 'fulfilled') {
-        const client = result.value;
-        if (!isJoin) {
-          this.clients.set(name, client);
-          ctx.logger.info(`Plugin connected: ${name}`, { inject: `this.${plugin.inject}` });
-        }
-        clients.set(plugin.inject, client);
-      } else {
-        const err = result.reason;
-        if (!isJoin) {
-          ctx.metrics?.increment?.('forge_plugin_connect_failures_total', { plugin: name });
-          ctx.logger.warn(`Plugin "${name}" connect failed (degraded mode): ${err.message}`);
-          const prevCached = this.clients.get(name);
-          const attempts = (prevCached?._pluginError ? (prevCached.attempts ?? 0) : 0) + 1;
-          this.clients.set(name, { _pluginError: true, timestamp: Date.now(), errorMessage: err.message, attempts });
-        }
-        const pluginName = name;
-        const errMsg = err.message;
-        const errorProxy = new Proxy({}, {
-          get(_, prop) {
-            if (prop === Symbol.toPrimitive || prop === "then" || prop === Symbol.iterator) return undefined;
-            throw new Error(`Plugin "${pluginName}" is unavailable (connect failed: ${errMsg}). Check your ${pluginName} configuration.`);
-          },
-        });
-        clients.set(plugin.inject, errorProxy);
-      }
-      if (!isJoin) this._connecting.delete(name);
-    }
-
-    return clients;
-  }
-
-  /**
-   * Run health checks for all connected plugins.
-   */
-  async healthCheck() {
-    const results = {};
-
-    for (const [name, plugin] of this.plugins) {
-      const client = this.clients.get(name);
-
-      if (!client || (typeof client === 'object' && client._pluginError === true)) {
-        results[name] = this.clients.has(name)
-          ? { status: "error", error: "Plugin failed to connect" }
-          : { status: "not-checked" };
-        continue;
-      }
-
-      if (!plugin.healthCheck) {
-        results[name] = { status: "unknown" };
-        continue;
-      }
-
-      try {
-        results[name] = await withTimeout(plugin.healthCheck(client), HEALTH_TIMEOUT, `Plugin "${name}" healthCheck`);
-      } catch (err) {
-        results[name] = { status: "error", error: err.message };
-      }
-    }
-
-    return results;
-  }
-
-  /**
-   * Collect Prometheus metrics from all plugins.
-   */
-  collectMetrics(metricsCollector) {
-    for (const [name, plugin] of this.plugins) {
-      const client = this.clients.get(name);
-      if (!client || !plugin.metrics) continue;
-
-      try {
-        const pluginMetrics = plugin.metrics(client);
-        for (const [key, value] of Object.entries(pluginMetrics)) {
-          metricsCollector.gauge(`forge_plugin_${name}_${key}`, value);
-        }
-      } catch (err) {
-        this._logger?.warn?.(`Plugin metrics collection failed`, { error: err.message });
-      }
-    }
-  }
-
-  /**
-   * Disconnect all plugins (graceful shutdown).
-   */
-  async disconnectAll(logger) {
-    const errors = [];
-
-    for (const [name, plugin] of this.plugins) {
-      const client = this.clients.get(name);
-      if (!client || (typeof client === 'object' && client._pluginError === true)) {
-        this.clients.delete(name);
-        continue;
-      }
-
-      try {
-        if (plugin.disconnect) {
-          await withTimeout(plugin.disconnect(client), DISCONNECT_TIMEOUT, `Plugin "${name}" disconnect`);
-        }
-        logger?.info(`Plugin disconnected: ${name}`);
-      } catch (err) {
-        errors.push({ name, error: err.message });
-        logger?.error(`Plugin "${name}" disconnect failed: ${err.message}`);
-        // Force cleanup as best effort
-        try {
-          if (typeof client.end === 'function') await client.end().catch(() => {});
-          else if (typeof client.quit === 'function') await client.quit().catch(() => {});
-          else if (typeof client.destroy === 'function') client.destroy();
-        } catch {}
-      }
-
-      this.clients.delete(name);
-    }
-
-    return errors;
-  }
-
-  /**
-   * Get nginx config blocks from all plugins.
-   */
-  nginxBlocks() {
-    const blocks = { upstreams: [], locations: [] };
-
-    for (const [, plugin] of this.plugins) {
-      if (!plugin.nginx) continue;
-      const nginx = plugin.nginx();
-      if (nginx.upstreams) blocks.upstreams.push(...nginx.upstreams);
-      if (nginx.locations) blocks.locations.push(...nginx.locations);
-    }
-
-    return blocks;
-  }
-
-  /**
-   * Get middleware from all plugins (for service HTTP server).
-   */
-  getMiddleware(servicePlugins) {
-    const middleware = [];
-    const names = servicePlugins ?? [...this.plugins.keys()];
-
-    for (const name of names) {
-      const plugin = this.plugins.get(name);
-      const client = this.clients.get(name);
-      if (!plugin?.middleware || !client) continue;
-      middleware.push(plugin.middleware(client));
-    }
-
-    return middleware;
-  }
-
-  /**
-   * Get websocket lifecycle hooks from all plugins for a service.
-   *
-   * @param {string[] | null | undefined} servicePlugins
-   * @returns {Array<{name: string, onWsUpgrade?: Function, onWsConnect?: Function, onWsMessage?: Function, onWsClose?: Function}>}
-   */
-  getWebSocketHooks(servicePlugins) {
-    const hooks = [];
-    const names = servicePlugins ?? [...this.plugins.keys()];
-
-    for (const name of names) {
-      const plugin = this.plugins.get(name);
-      const client = this.clients.get(name);
-
-      if (!plugin || !client) continue;
-      if (typeof client === "object" && client._pluginError === true) continue;
-      if (!plugin.onWsUpgrade && !plugin.onWsConnect && !plugin.onWsMessage && !plugin.onWsClose) continue;
-
-      hooks.push({
-        name,
-        onWsUpgrade: plugin.onWsUpgrade
-          ? (ctx) => plugin.onWsUpgrade(client, ctx)
-          : undefined,
-        onWsConnect: plugin.onWsConnect
-          ? (ctx) => plugin.onWsConnect(client, ctx)
-          : undefined,
-        onWsMessage: plugin.onWsMessage
-          ? (ctx) => plugin.onWsMessage(client, ctx)
-          : undefined,
-        onWsClose: plugin.onWsClose
-          ? (ctx) => plugin.onWsClose(client, ctx)
-          : undefined,
-      });
-    }
-
-    return hooks;
-  }
-}