threadforge 0.1.1 → 0.2.1

package/src/core/config.js

@@ -1,637 +0,0 @@
-/**
- * ThreadForge Configuration v2
- *
- * Key design changes:
- *
- * 1. Services declare their TYPE:
- *    - "edge"       → binds an HTTP port, receives external traffic
- *    - "internal"   → no port, only reachable via IPC from other services
- *    - "background" → no port, no inbound IPC, runs tasks (cron, queue consumer)
- *
- *    Only edge services need ports. Internal services live behind the
- *    IPC bus and are never directly exposed.
- *
- * 2. Services declare DEPENDENCIES (connects):
- *    Instead of a full mesh (N*(N-1)/2 channels), services declare
- *    which other services they talk to. This means 8 services might
- *    only need 8 channels instead of 28.
- *
- * 3. Services can be COLOCATED into process groups:
- *    Lightweight internal services can share a process. One Node.js
- *    event loop handles multiple services via in-process function calls
- *    (zero IPC overhead). Only CPU-heavy services need isolated processes.
- *
- *    This means 8 services might run in 3 processes instead of 8,
- *    saving ~200MB of memory.
- *
- * 4. Thread allocation is per-PROCESS GROUP, not per-service.
- */
-
-const VALID_TYPES = ["edge", "internal", "background", "remote"];
-const VALID_MODES = ["cluster"];
-const VALID_STRATEGIES = ["round-robin", "hash", "least-pending", "broadcast", "primary"];
-const WEBSOCKET_PATH_RE = /^\/[a-zA-Z0-9/_-]*$/;
-
-function normalizeWebsocketConfig(serviceName, serviceType, websocket) {
-  if (websocket === undefined || websocket === null || websocket === false) return null;
-
-  if (serviceType !== "edge") {
-    throw new Error(`Service "${serviceName}": websocket config is only valid for edge services`);
-  }
-
-  let paths = ["/ws"];
-  let enabled = true;
-
-  if (websocket === true) {
-    paths = ["/ws"];
-  } else if (Array.isArray(websocket)) {
-    paths = websocket;
-  } else if (typeof websocket === "object") {
-    enabled = websocket.enabled !== false;
-    if (websocket.paths !== undefined) {
-      if (!Array.isArray(websocket.paths)) {
-        throw new Error(`Service "${serviceName}": websocket.paths must be an array`);
-      }
-      paths = websocket.paths;
-    }
-  } else {
-    throw new Error(
-      `Service "${serviceName}": websocket must be boolean, array of paths, or { enabled, paths } object`,
-    );
-  }
-
-  if (!enabled) return { enabled: false, paths: [] };
-
-  if (paths.length === 0) {
-    throw new Error(`Service "${serviceName}": websocket.paths must include at least one path when enabled`);
-  }
-
-  const normalizedPaths = [...new Set(paths)].map((p) => {
-    if (typeof p !== "string" || !WEBSOCKET_PATH_RE.test(p)) {
-      throw new Error(
-        `Service "${serviceName}": invalid websocket path "${p}". Use absolute paths containing [a-zA-Z0-9/_-]`,
-      );
-    }
-    return p;
-  });
-
-  return { enabled: true, paths: normalizedPaths };
-}
-
-/**
- * Validate and normalize service config.
- */
-function normalizeService(name, config) {
-  const VALID_SERVICE_NAME = /^[a-z][a-z0-9_-]*(:[a-z][a-z0-9_-]*)?$/;
-  if (!VALID_SERVICE_NAME.test(name)) {
-    throw new Error(`Invalid service name "${name}": must start with a lowercase letter and contain only [a-z0-9_-] (or use appname:servicename format)`);
-  }
-  if (name.length > 63) {
-    throw new Error(`Service name "${name}" exceeds max length of 63 characters`);
-  }
-
-  const type = config.type ?? "internal";
-  if (!VALID_TYPES.includes(type)) {
-    throw new Error(`Service "${name}" has invalid type: ${type}. Use: ${VALID_TYPES.join(", ")}`);
-  }
-
-  if (config.mode && !VALID_MODES.includes(config.mode)) {
-    const hint = config.mode === 'worker'
-      ? ` mode 'worker' (worker_threads) is not yet implemented. Use mode 'cluster' (default).`
-      : '';
-    throw new Error(`Service "${name}": invalid mode "${config.mode}".${hint} Valid modes: ${VALID_MODES.join(', ')}`);
-  }
-
-  // Remote services don't need an entry file — they're on another machine
-  if (type === "remote") {
-    if (!config.address) {
-      throw new Error(`Remote service "${name}" requires an address (e.g., 'http://billing.internal:4001')`);
-    }
-    if (!/^https?:\/\/.+/.test(config.address)) {
-      throw new Error(`Remote service "${name}": address must be a valid HTTP(S) URL, got "${config.address}"`);
-    }
-    try {
-      new URL(config.address);
-    } catch {
-      throw new Error(`Remote service "${name}": address is not a parseable URL: "${config.address}"`);
-    }
-    // CFG-2: Validate routing.strategy for remote services too
-    const remoteRouting = config.routing ?? { strategy: "round-robin" };
-    if (remoteRouting.strategy && !VALID_STRATEGIES.includes(remoteRouting.strategy)) {
-      throw new Error(`Service "${name}": invalid routing strategy "${remoteRouting.strategy}". Valid strategies: ${VALID_STRATEGIES.join(", ")}`);
-    }
-
-    return {
-      name,
-      entry: null,
-      type: "remote",
-      port: null,
-      address: config.address,
-      connects: config.connects ?? [],
-      group: null,
-      threads: 0,
-      weight: 0,
-      mode: "cluster",
-      env: {},
-      routing: remoteRouting,
-      websocket: null,
-    };
-  }
-
-  if (!config.entry) {
-    throw new Error(`Service "${name}" is missing required field: entry`);
-  }
-
-  // Only edge services need a port
-  if (type === "edge" && !config.port) {
-    throw new Error(`Edge service "${name}" requires a port`);
-  }
-
-  if (type !== "edge" && config.port && !config.group && !config.remotePort) {
-    console.warn(
-      `[ThreadForge] Note: Service "${name}" has type "${type}" with port ${config.port}. ` +
-        `This port will be used for cross-machine HTTP access (/__forge/invoke, /__forge/event).`,
-    );
-  }
-
-  if (config.group && config.group.startsWith('_isolated:')) {
-    throw new Error(`Service "${name}": group name cannot start with "_isolated:" (reserved prefix)`);
-  }
-
-  if (config.env) {
-    if (typeof config.env !== 'object' || Array.isArray(config.env)) {
-      throw new Error(`Service "${name}": env must be a plain object`);
-    }
-    for (const [k, v] of Object.entries(config.env)) {
-      if (typeof v !== 'string') {
-        throw new Error(`Service "${name}": env.${k} must be a string, got ${typeof v}`);
-      }
-    }
-  }
-
-  const connects = config.connects ?? [];
-  if (!Array.isArray(connects)) {
-    throw new Error(`Service "${name}" connects must be an array of service names`);
-  }
-
-  if (config.port !== undefined && config.port !== null) {
-    if (!Number.isInteger(config.port) || config.port < 1 || config.port > 65535) {
-      throw new Error(`Service "${name}": port must be an integer between 1-65535, got ${config.port}`);
-    }
-  }
-
-  if (config.weight !== undefined) {
-    if (typeof config.weight !== "number" || !Number.isInteger(config.weight) || config.weight < 1) {
-      throw new Error(`Service "${name}": weight must be a positive integer, got ${config.weight}`);
-    }
-  }
-
-  if (config.prefix !== undefined && config.prefix !== null) {
-    if (typeof config.prefix !== "string" || !config.prefix.startsWith("/")) {
-      throw new Error(`Service "${name}": prefix must start with /, got "${config.prefix}"`);
-    }
-    if (config.prefix.includes("?") || config.prefix.includes("#")) {
-      throw new Error(`Service "${name}": prefix cannot contain query strings or fragments`);
-    }
-  }
-
-  const websocket = normalizeWebsocketConfig(name, type, config.websocket);
-
-  // CFG-1: Validate threads — must be "auto" or a positive integer
-  const threads = config.threads ?? "auto";
-  if (threads !== "auto") {
-    if (typeof threads !== "number" || !Number.isInteger(threads) || threads <= 0 || !Number.isFinite(threads)) {
-      throw new Error(`Service "${name}": threads must be "auto" or a positive integer, got ${JSON.stringify(threads)}`);
-    }
-  }
-
-  // CFG-2: Validate routing.strategy
-  const routing = config.routing ?? { strategy: "round-robin" };
-  if (routing.strategy && !VALID_STRATEGIES.includes(routing.strategy)) {
-    throw new Error(`Service "${name}": invalid routing strategy "${routing.strategy}". Valid strategies: ${VALID_STRATEGIES.join(", ")}`);
-  }
-
-  return {
-    name,
-    entry: config.entry,
-    type,
-    port: config.port ?? null,
-    connects,
-    group: config.group ?? null, // colocation group name
-    threads,
-    weight: config.weight ?? 1,
-    mode: config.mode ?? "cluster",
-    env: config.env ?? {},
-    routing,
-    prefix: config.prefix ?? null,
-    plugins: config.plugins ?? null, // null = all plugins, [...] = specific
-    websocket,
-  };
-}
-
-/**
- * Resolve colocation groups.
- *
- * Services in the same group run in the same process(es).
- * They communicate via direct function calls (zero overhead).
- * Services without a group get their own isolated process.
- *
- * Returns a map of group name → array of service configs.
- */
-function resolveGroups(services) {
-  const groups = new Map();
-
-  for (const [name, svc] of Object.entries(services)) {
-    // Remote services don't run locally — no process group needed
-    if (svc.type === "remote") continue;
-
-    const groupName = svc.group ?? `_isolated:${name}`;
-
-    if (!groups.has(groupName)) {
-      groups.set(groupName, {
-        name: groupName,
-        services: [],
-        threads: 0,
-        weight: 0,
-        hasEdge: false,
-        port: null,
-      });
-    }
-
-    const group = groups.get(groupName);
-    group.services.push(svc);
-    group.weight = Math.max(group.weight, svc.weight);
-
-    if (svc.type === "edge") {
-      group.hasEdge = true;
-      group.port = svc.port;
-    }
-
-    // Group inherits the highest thread count / weight of its members
-    if (typeof svc.threads === "number" && svc.threads > 0) {
-      group.threads = typeof group.threads === "number" ? Math.max(group.threads, svc.threads) : svc.threads;
-    } else if (svc.threads === "auto" && group.threads === 0) {
-      group.threads = "auto";
-    }
-  }
-
-  return groups;
-}
-
-/**
- * Resolve the channel topology from dependency declarations.
- *
- * Instead of full mesh, only create channels between services
- * that actually declare they need to talk to each other.
- *
- * Returns array of { from, to } pairs.
- */
-function detectCycles(services) {
-  const WHITE = 0, GRAY = 1, BLACK = 2;
-  const color = {};
-  const parent = {};
-
-  for (const name of Object.keys(services)) {
-    color[name] = WHITE;
-  }
-
-  function dfs(name) {
-    color[name] = GRAY;
-    for (const target of (services[name]?.connects ?? [])) {
-      if (!services[target]) continue;
-      if (color[target] === GRAY) {
-        // Found a back edge — reconstruct the cycle path
-        const cycle = [target];
-        let cur = name;
-        while (cur !== target) {
-          cycle.push(cur);
-          cur = parent[cur];
-        }
-        cycle.push(target);
-        cycle.reverse();
-
-        // Skip bidirectional pairs (A→B→A) — those are valid IPC channels
-        if (cycle.length === 3 && cycle[0] === cycle[2]) continue;
-
-        throw new Error(`Circular dependency detected: ${cycle.join(" \u2192 ")}`);
-      }
-      if (color[target] === WHITE) {
-        parent[target] = name;
-        dfs(target);
-      }
-    }
-    color[name] = BLACK;
-  }
-
-  for (const name of Object.keys(services)) {
-    if (color[name] === WHITE) {
-      dfs(name);
-    }
-  }
-}
-
-function resolveChannels(services) {
-  const channels = [];
-  const seen = new Set();
-
-  for (const [name, svc] of Object.entries(services)) {
-    for (const target of svc.connects) {
-      if (!services[target]) {
-        throw new Error(`Service "${name}" declares connection to "${target}", but no such service exists.`);
-      }
-
-      // Deduplicate bidirectional
-      const key = [name, target].sort().join("<->");
-      if (!seen.has(key)) {
-        seen.add(key);
-        channels.push({ from: name, to: target });
-      }
-    }
-  }
-
-  detectCycles(services);
-
-  return channels;
-}
-
-/**
- * Detect circular dependencies at the group level.
- * Self-loops (a group connecting to itself) are allowed — that's colocated.
- */
-function detectGroupCycles(services, groups) {
-  // Build service→group mapping
-  const svcToGroup = {};
-  for (const [groupName, group] of groups) {
-    for (const svc of group.services) {
-      svcToGroup[svc.name] = groupName;
-    }
-  }
-
-  // Build group-level adjacency
-  const groupAdj = new Map();
-  for (const [name, svc] of Object.entries(services)) {
-    const fromGroup = svcToGroup[name];
-    if (!fromGroup) continue;
-    for (const target of svc.connects) {
-      const toGroup = svcToGroup[target];
-      if (!toGroup || toGroup === fromGroup) continue; // skip self-loops
-      if (!groupAdj.has(fromGroup)) groupAdj.set(fromGroup, new Set());
-      groupAdj.get(fromGroup).add(toGroup);
-    }
-  }
-
-  // DFS cycle detection
-  const WHITE = 0, GRAY = 1, BLACK = 2;
-  const color = {};
-  const parent = {};
-  for (const [groupName] of groups) {
-    color[groupName] = WHITE;
-  }
-
-  function dfs(g) {
-    color[g] = GRAY;
-    for (const target of (groupAdj.get(g) ?? [])) {
-      if (color[target] === GRAY) {
-        const cycle = [target];
-        let cur = g;
-        while (cur !== target) {
-          cycle.push(cur);
-          cur = parent[cur];
-        }
-        cycle.push(target);
-        cycle.reverse();
-        // Skip bidirectional pairs (A→B→A)
-        if (cycle.length === 3 && cycle[0] === cycle[2]) continue;
-        throw new Error(`Circular group dependency detected: ${cycle.join(" \u2192 ")}`);
-      }
-      if (color[target] === WHITE) {
-        parent[target] = g;
-        dfs(target);
-      }
-    }
-    color[g] = BLACK;
-  }
-
-  for (const [groupName] of groups) {
-    if (color[groupName] === WHITE) dfs(groupName);
-  }
-}
-
-/**
- * Define services for the ThreadForge runtime.
- */
-export function defineServices(servicesMap, options = {}) {
-  if (!servicesMap || typeof servicesMap !== "object") {
-    throw new Error("defineServices() requires a services object");
-  }
-
-  // D5: Accept plugins as top-level key in servicesMap or in options.
-  // If plugins appears inside the services object, emit a deprecation warning
-  // and prefer options.plugins when both are provided.
-  let plugins;
-  if (options.plugins) {
-    plugins = options.plugins;
-  } else if (servicesMap.plugins) {
-    console.warn(
-      `[ThreadForge] Deprecation: "plugins" inside the services object is deprecated. ` +
-      `Pass it as a separate top-level key: defineServices({ ...services }, { plugins: [...] })`
-    );
-    plugins = servicesMap.plugins;
-  } else {
-    plugins = [];
-  }
-  const filteredMap = { ...servicesMap };
-  delete filteredMap.plugins;
-
-  if (options.frontendPlugins !== undefined && !Array.isArray(options.frontendPlugins)) {
-    throw new Error("defineServices(): frontendPlugins must be an array when provided");
-  }
-  if (options.sites !== undefined && (typeof options.sites !== "object" || Array.isArray(options.sites))) {
-    throw new Error("defineServices(): sites must be an object map when provided");
-  }
-
-  const entries = Object.entries(filteredMap);
-  if (entries.length === 0) {
-    throw new Error("defineServices() requires at least one service");
-  }
-
-  // H1: Check for reserved service names
-  for (const [name] of entries) {
-    if (name === 'plugins') {
-      throw new Error(`"plugins" is a reserved name and cannot be used as a service name`);
-    }
-  }
-
-  // Check for duplicate ports among all services
-  const ports = new Map();
-  for (const [name, config] of entries) {
-    if (config.port) {
-      if (ports.has(config.port)) {
-        throw new Error(`Port ${config.port} is used by both "${ports.get(config.port)}" and "${name}"`);
-      }
-      ports.set(config.port, name);
-    }
-  }
-
-  // Check for metricsPort collision
-  const metricsPort = options.metricsPort ?? 9090;
-  for (const [name, config] of entries) {
-    if (config.port === metricsPort) {
-      throw new Error(`Service "${name}" port ${config.port} conflicts with metricsPort (${metricsPort})`);
-    }
-  }
-
-  // Normalize all services
-  const services = {};
-  for (const [name, config] of entries) {
-    services[name] = normalizeService(name, config);
-  }
-
-  // Validate thread counts and plugin arrays
-  for (const [name, svc] of Object.entries(services)) {
-    if (svc.type !== "remote" && typeof svc.threads === "number") {
-      if (!Number.isInteger(svc.threads) || svc.threads <= 0 || !Number.isFinite(svc.threads)) {
-        throw new Error(`Service "${name}": threads must be a positive integer or "auto", got ${svc.threads}`);
-      }
-    }
-    if (svc.plugins) {
-      if (!Array.isArray(svc.plugins)) {
-        throw new Error(`Service "${name}": plugins must be an array`);
-      }
-      for (const p of svc.plugins) {
-        if (typeof p !== "string" || p.trim() === "") {
-          throw new Error(`Service "${name}": plugin name must be a non-empty string`);
-        }
-      }
-      if (new Set(svc.plugins).size !== svc.plugins.length) {
-        throw new Error(`Service "${name}": duplicate plugin entries detected`);
-      }
-    }
-  }
-
-  // Self-reference check
-  for (const [name, svc] of Object.entries(services)) {
-    if (svc.connects.includes(name)) {
-      throw new Error(`Service "${name}" cannot connect to itself.`);
-    }
-  }
-
-  // Resolve topology
-  const groups = resolveGroups(services);
-  const channels = resolveChannels(services);
-
-  // M3: Detect group-level circular dependencies
-  detectGroupCycles(services, groups);
-
-  // M-14: Warn on unknown option keys to catch typos early
-  const KNOWN_OPTIONS = new Set([
-    'metricsPort', 'logging', 'watch', 'registryMode', 'host', 'httpBasePort',
-    'ingress', 'plugins', 'frontendPlugins', 'sites',
-    // Internal keys used by platform/host modes
-    '_configUrl', '_isHostMode', '_isPlatformMode', '_hostMeta', '_hostMetaJSON',
-  ]);
-  for (const key of Object.keys(options)) {
-    if (!KNOWN_OPTIONS.has(key) && !key.startsWith('_')) {
-      console.warn(`[ThreadForge] Unknown option "${key}" in defineServices(). Known options: ${[...KNOWN_OPTIONS].filter(k => !k.startsWith('_')).join(', ')}`);
-    }
-  }
-
-  // Only pass through known option keys to prevent typos polluting the config
-  // A12: Namespace internal fields into _internal sub-object
-  const result = {
-    services,
-    groups: Object.fromEntries(groups),
-    channels,
-    plugins,
-    frontendPlugins: options.frontendPlugins ?? [],
-    sites: options.sites ?? {},
-    metricsPort: options.metricsPort !== undefined ? options.metricsPort : 9090,
-    logging: options.logging ?? { level: "info", structured: true },
-    watch: options.watch ?? false,
-    registryMode: options.registryMode,
-    host: options.host,
-    httpBasePort: options.httpBasePort,
-    ingress: options.ingress,
-    _internal: {
-      configUrl: options._configUrl,
-      isHostMode: options._isHostMode,
-      isPlatformMode: options._isPlatformMode,
-      hostMeta: options._hostMeta,
-      hostMetaJSON: options._hostMetaJSON,
-    },
-    // Backward compat: expose legacy underscore keys as getters
-    get _configUrl() { return this._internal.configUrl; },
-    set _configUrl(value) { this._internal.configUrl = value; },
-    get _isHostMode() { return this._internal.isHostMode; },
-    set _isHostMode(value) { this._internal.isHostMode = value; },
-    get _isPlatformMode() { return this._internal.isPlatformMode; },
-    set _isPlatformMode(value) { this._internal.isPlatformMode = value; },
-    get _hostMeta() { return this._internal.hostMeta; },
-    set _hostMeta(value) { this._internal.hostMeta = value; },
-    get _hostMetaJSON() { return this._internal.hostMetaJSON; },
-    set _hostMetaJSON(value) { this._internal.hostMetaJSON = value; },
-  };
-
-  return result;
-}
-
-/**
- * Detect if a config object is already normalized by defineServices().
- * This lets loadConfig accept both:
- *   1) raw service maps
- *   2) pre-normalized defineServices(...) exports
- */
-function isNormalizedConfig(config) {
-  if (!config || typeof config !== "object" || Array.isArray(config)) return false;
-  if (!config.services || typeof config.services !== "object" || Array.isArray(config.services)) return false;
-  if (!config.groups || typeof config.groups !== "object" || Array.isArray(config.groups)) return false;
-  if (!Array.isArray(config.channels)) return false;
-
-  return Object.values(config.services).every((svc) => {
-    return (
-      svc &&
-      typeof svc === "object" &&
-      !Array.isArray(svc) &&
-      typeof svc.name === "string" &&
-      typeof svc.type === "string" &&
-      Array.isArray(svc.connects)
-    );
-  });
-}
-
-/**
- * Load a forge config file from disk.
- */
-export async function loadConfig(configPath) {
-  try {
-    const module = await import(configPath);
-    const config = module.default ?? module;
-
-    // Accept configs that already exported defineServices(...) output.
-    if (isNormalizedConfig(config)) {
-      return config;
-    }
-
-    // Accept configs exported via definePlatform(...) / defineHost(...).
-    // Use lazy imports to avoid circular module initialization at load time.
-    if (config && typeof config === "object" && !Array.isArray(config)) {
-      if (config._isPlatformConfig) {
-        const { resolveAndDefinePlatform } = await import("./platform-config.js");
-        return await resolveAndDefinePlatform(config);
-      }
-
-      if (config._isHostConfig) {
-        const { resolveAndDefine } = await import("./host-config.js");
-        return await resolveAndDefine(config);
-      }
-    }
-
-    // Raw object exports are normalized/validated here.
-    return defineServices(config);
-  } catch (err) {
-    if (err.code === "ERR_MODULE_NOT_FOUND") {
-      throw new Error(`Config file not found or import error: ${configPath}\n  ${err.message}`);
-    }
-    throw err;
-  }
-}