threadforge 0.1.1 → 0.2.1

package/src/frontend/FrontendDevLifecycle.js

@@ -1,65 +0,0 @@
-/**
- * Bind frontend dev cleanup to process lifecycle events.
- *
- * Ensures dev plugin child processes are cleaned on:
- * - SIGTERM / SIGINT
- * - graceful process drain (`beforeExit`)
- * - final process exit (`exit`, best-effort)
- */
-export function bindFrontendDevCleanup(cleanupFn, options = {}) {
-  if (typeof cleanupFn !== "function") {
-    return {
-      runCleanup: async () => {},
-      dispose: () => {},
-    };
-  }
-
-  const proc = options.processRef ?? process;
-  const logger = options.logger ?? console;
-  let finished = false;
-
-  const runCleanup = async () => {
-    if (finished) return;
-    finished = true;
-    try {
-      await cleanupFn();
-    } catch (err) {
-      logger.warn?.(`  [dev] Frontend cleanup failed: ${err.message}`);
-    }
-  };
-
-  const trigger = () => {
-    void runCleanup();
-  };
-
-  const bindings = [
-    ["SIGTERM", trigger],
-    ["SIGINT", trigger],
-    ["beforeExit", trigger],
-    ["exit", trigger],
-  ];
-
-  for (const [event, handler] of bindings) {
-    proc.once(event, handler);
-  }
-
-  const dispose = () => {
-    for (const [event, handler] of bindings) {
-      proc.removeListener(event, handler);
-    }
-  };
-
-  return { runCleanup, dispose };
-}
-
-export function wrapShutdownWithCleanup(supervisor, runCleanup) {
-  if (!supervisor || typeof supervisor.shutdown !== "function" || typeof runCleanup !== "function") {
-    return;
-  }
-  const originalShutdown = supervisor.shutdown.bind(supervisor);
-  supervisor.shutdown = async (...args) => {
-    await runCleanup();
-    return originalShutdown(...args);
-  };
-}
-

package/src/frontend/FrontendPluginOrchestrator.js

@@ -1,187 +0,0 @@
-/**
- * Frontend Plugin Orchestrator
- *
- * Handles frontend/tooling plugin registration and lifecycle. This is
- * intentionally separate from the service runtime PluginManager.
- */
-
-export const FRONTEND_PLUGIN_CAPABILITIES = Object.freeze([
-  "frontend-build",
-  "static-serve",
-  "frontend-dev",
-]);
-
-const CAPABILITY_SET = new Set(FRONTEND_PLUGIN_CAPABILITIES);
-const REQUIRED_METHODS = Object.freeze({
-  "frontend-build": "buildSite",
-  "static-serve": "staticMounts",
-  "frontend-dev": "devSite",
-});
-
-function ensureFunction(plugin, key) {
-  if (plugin[key] !== undefined && typeof plugin[key] !== "function") {
-    throw new Error(`Frontend plugin "${plugin.name}": "${key}" must be a function when provided`);
-  }
-}
-
-function normalizePlugin(plugin) {
-  if (!plugin || typeof plugin !== "object" || Array.isArray(plugin)) {
-    throw new Error("Frontend plugin must be an object");
-  }
-
-  if (typeof plugin.name !== "string" || plugin.name.trim() === "") {
-    throw new Error("Frontend plugin must have a non-empty name");
-  }
-
-  if (!Array.isArray(plugin.capabilities) || plugin.capabilities.length === 0) {
-    throw new Error(`Frontend plugin "${plugin.name}" must declare a non-empty capabilities array`);
-  }
-
-  const dedupedCapabilities = [...new Set(plugin.capabilities)];
-  for (const capability of dedupedCapabilities) {
-    if (!CAPABILITY_SET.has(capability)) {
-      throw new Error(
-        `Frontend plugin "${plugin.name}" has invalid capability "${capability}". Valid capabilities: ${FRONTEND_PLUGIN_CAPABILITIES.join(", ")}`,
-      );
-    }
-
-    const requiredMethod = REQUIRED_METHODS[capability];
-    if (typeof plugin[requiredMethod] !== "function") {
-      throw new Error(
-        `Frontend plugin "${plugin.name}" declares capability "${capability}" but is missing required method "${requiredMethod}()"`,
-      );
-    }
-  }
-
-  ensureFunction(plugin, "validate");
-  ensureFunction(plugin, "register");
-  ensureFunction(plugin, "dispose");
-
-  return {
-    ...plugin,
-    capabilities: dedupedCapabilities,
-  };
-}
-
-export class FrontendPluginOrchestrator {
-  constructor(options = {}) {
-    /** @type {Map<string, any>} */
-    this.plugins = new Map();
-    this._logger = options.logger ?? {
-      info: (...args) => console.log("[FrontendPluginOrchestrator]", ...args),
-      warn: (...args) => console.warn("[FrontendPluginOrchestrator]", ...args),
-      error: (...args) => console.error("[FrontendPluginOrchestrator]", ...args),
-    };
-  }
-
-  register(plugins) {
-    if (!plugins || !Array.isArray(plugins)) return;
-
-    for (const rawPlugin of plugins) {
-      const plugin = normalizePlugin(rawPlugin);
-      if (this.plugins.has(plugin.name)) {
-        throw new Error(`Duplicate frontend plugin: "${plugin.name}"`);
-      }
-      this.plugins.set(plugin.name, plugin);
-    }
-  }
-
-  get(name) {
-    return this.plugins.get(name) ?? null;
-  }
-
-  has(name) {
-    return this.plugins.has(name);
-  }
-
-  list() {
-    return [...this.plugins.values()];
-  }
-
-  pluginsForCapability(capability) {
-    if (!CAPABILITY_SET.has(capability)) {
-      throw new Error(
-        `Invalid frontend capability "${capability}". Valid capabilities: ${FRONTEND_PLUGIN_CAPABILITIES.join(", ")}`,
-      );
-    }
-    return [...this.plugins.values()].filter((plugin) => plugin.capabilities.includes(capability));
-  }
-
-  async validateAll(ctx = {}) {
-    for (const [name, plugin] of this.plugins) {
-      if (!plugin.validate) continue;
-      try {
-        await plugin.validate(ctx);
-      } catch (err) {
-        throw new Error(`Frontend plugin "${name}" validation failed: ${err.message}`);
-      }
-    }
-  }
-
-  async registerAll(ctx = {}) {
-    for (const [name, plugin] of this.plugins) {
-      if (!plugin.register) continue;
-      try {
-        await plugin.register(ctx);
-      } catch (err) {
-        throw new Error(`Frontend plugin "${name}" register hook failed: ${err.message}`);
-      }
-    }
-  }
-
-  async disposeAll(ctx = {}) {
-    const errors = [];
-    const plugins = [...this.plugins.values()].reverse();
-
-    for (const plugin of plugins) {
-      if (!plugin.dispose) continue;
-      try {
-        await plugin.dispose(ctx);
-      } catch (err) {
-        errors.push({ name: plugin.name, error: err.message });
-        this._logger.warn?.(`Frontend plugin "${plugin.name}" dispose failed: ${err.message}`);
-      }
-    }
-
-    return errors;
-  }
-
-  resolvePluginForSite(site) {
-    const pluginName = site?.frontend?.plugin;
-    if (!pluginName) return null;
-
-    const plugin = this.get(pluginName);
-    if (!plugin) {
-      throw new Error(`Site "${site.siteId ?? "unknown"}" references unknown frontend plugin "${pluginName}"`);
-    }
-    return plugin;
-  }
-
-  async buildSite(site, ctx = {}) {
-    if (!site?.frontend) return null;
-    const plugin = this.resolvePluginForSite(site);
-    if (!plugin.capabilities.includes("frontend-build")) {
-      throw new Error(`Frontend plugin "${plugin.name}" does not support "frontend-build"`);
-    }
-    return plugin.buildSite(ctx, site);
-  }
-
-  async staticMounts(site, ctx = {}) {
-    if (!site?.frontend) return [];
-    const plugin = this.resolvePluginForSite(site);
-    if (!plugin.capabilities.includes("static-serve")) {
-      return [];
-    }
-    return plugin.staticMounts(ctx, site);
-  }
-
-  async devSite(site, ctx = {}) {
-    if (!site?.frontend) return null;
-    const plugin = this.resolvePluginForSite(site);
-    if (!plugin.capabilities.includes("frontend-dev")) {
-      throw new Error(`Frontend plugin "${plugin.name}" does not support "frontend-dev"`);
-    }
-    return plugin.devSite(ctx, site);
-  }
-}
-

package/src/frontend/SiteResolver.js

@@ -1,63 +0,0 @@
-function normalizeBasePath(basePath = "/") {
-  if (!basePath || basePath === "/") return "/";
-  let normalized = String(basePath).trim();
-  if (!normalized.startsWith("/")) normalized = `/${normalized}`;
-  if (normalized.length > 1 && normalized.endsWith("/")) normalized = normalized.slice(0, -1);
-  return normalized;
-}
-
-export function resolveSitesMap(config) {
-  if (!config || typeof config !== "object" || Array.isArray(config)) {
-    return {};
-  }
-
-  const sites = config._sites ?? config.sites ?? null;
-  if (sites && typeof sites === "object" && !Array.isArray(sites)) {
-    return sites;
-  }
-
-  // Allow passing a raw site map directly.
-  const values = Object.values(config);
-  const isLikelySiteMap = values.length > 0 && values.every((value) =>
-    value &&
-    typeof value === "object" &&
-    !Array.isArray(value) &&
-    (
-      Array.isArray(value.services) ||
-      Array.isArray(value.domains) ||
-      value.frontend !== undefined ||
-      value.staticDir !== undefined
-    )
-  );
-
-  return isLikelySiteMap ? config : {};
-}
-
-export function resolveFrontendSites(config) {
-  return Object.values(resolveSitesMap(config)).filter((site) => site?.frontend);
-}
-
-export function resolveStaticMountsForService(serviceName, sitesConfig) {
-  if (!serviceName || typeof serviceName !== "string") return [];
-  const sites = resolveSitesMap(sitesConfig);
-  const mounts = [];
-
-  for (const site of Object.values(sites)) {
-    if (!site?.services?.includes(serviceName)) continue;
-
-    const frontend = site.frontend ?? null;
-    const dir = frontend?.outDir ?? site.staticDir;
-    if (!dir) continue;
-
-    mounts.push({
-      siteId: site.siteId ?? null,
-      domains: Array.isArray(site.domains) ? site.domains : [],
-      basePath: normalizeBasePath(frontend?.basePath ?? site.basePath ?? "/"),
-      dir,
-      spaFallback: frontend?.spaFallback ?? false,
-      cachePolicy: "short",
-    });
-  }
-
-  return mounts;
-}

package/src/frontend/StaticMountRegistry.js

@@ -1,90 +0,0 @@
-/**
- * Static Mount Registry
- *
- * Resolves incoming host/path tuples to static mount descriptors.
- */
-
-function normalizeBasePath(basePath) {
-  if (!basePath || basePath === "/") return "/";
-  let value = basePath.trim();
-  if (!value.startsWith("/")) value = `/${value}`;
-  if (value.length > 1 && value.endsWith("/")) value = value.slice(0, -1);
-  return value;
-}
-
-function normalizeDomains(domains) {
-  if (!Array.isArray(domains)) return [];
-  return [...new Set(domains.filter((d) => typeof d === "string" && d.trim() !== "").map((d) => d.toLowerCase()))];
-}
-
-function matchBasePath(pathname, basePath) {
-  if (basePath === "/") return true;
-  return pathname === basePath || pathname.startsWith(`${basePath}/`);
-}
-
-function relativeFromBase(pathname, basePath) {
-  if (basePath === "/") return pathname;
-  const relative = pathname.slice(basePath.length);
-  return relative === "" ? "/" : relative;
-}
-
-export class StaticMountRegistry {
-  constructor(mounts = []) {
-    this._mounts = [];
-    this.setMounts(mounts);
-  }
-
-  setMounts(mounts = []) {
-    if (!Array.isArray(mounts)) {
-      throw new Error("Static mounts must be an array");
-    }
-
-    const normalized = mounts.map((mount) => {
-      if (!mount || typeof mount !== "object" || Array.isArray(mount)) {
-        throw new Error("Each static mount must be an object");
-      }
-      if (typeof mount.dir !== "string" || mount.dir.trim() === "") {
-        throw new Error("Each static mount must have a non-empty dir");
-      }
-
-      return {
-        siteId: mount.siteId ?? null,
-        domains: normalizeDomains(mount.domains),
-        basePath: normalizeBasePath(mount.basePath),
-        dir: mount.dir,
-        spaFallback: Boolean(mount.spaFallback),
-        cachePolicy: mount.cachePolicy ?? "short",
-      };
-    });
-
-    // Prefer exact-domain mounts over wildcard mounts, then longest base path.
-    normalized.sort((a, b) => {
-      const domainWeight = (b.domains.length > 0 ? 1 : 0) - (a.domains.length > 0 ? 1 : 0);
-      if (domainWeight !== 0) return domainWeight;
-      return b.basePath.length - a.basePath.length;
-    });
-
-    this._mounts = normalized;
-  }
-
-  list() {
-    return this._mounts;
-  }
-
-  resolve(host, pathname) {
-    const normalizedHost = typeof host === "string" ? host.toLowerCase() : "";
-
-    for (const mount of this._mounts) {
-      if (mount.domains.length > 0 && !mount.domains.includes(normalizedHost)) continue;
-      if (!matchBasePath(pathname, mount.basePath)) continue;
-
-      return {
-        ...mount,
-        relativePath: relativeFromBase(pathname, mount.basePath),
-      };
-    }
-
-    return null;
-  }
-}
-

package/src/frontend/plugins/viteFrontend.js

@@ -1,79 +0,0 @@
-import path from "node:path";
-import { spawn } from "node:child_process";
-
-function defaultRunCommand(command, options = {}) {
-  return new Promise((resolve, reject) => {
-    const child = spawn(command, {
-      cwd: options.cwd,
-      env: options.env,
-      shell: true,
-      stdio: "inherit",
-    });
-
-    child.on("error", reject);
-    child.on("close", (code) => {
-      if (code === 0) {
-        resolve();
-      } else {
-        reject(new Error(`Command failed (${code}): ${command}`));
-      }
-    });
-  });
-}
-
-/**
- * Reference frontend plugin for Vite-based apps.
- *
- * It intentionally shells out to project scripts (build/dev) instead of
- * linking to Vite APIs directly, which keeps the core runtime dependency-free.
- */
-export function viteFrontend(options = {}) {
-  const name = options.name ?? "vite";
-  const buildCommand = options.buildCommand ?? "npm run build";
-  const runCommand = options.runCommand ?? defaultRunCommand;
-
-  return {
-    name,
-    capabilities: ["frontend-build", "static-serve"],
-    validate() {
-      if (typeof buildCommand !== "string" || buildCommand.trim() === "") {
-        throw new Error(`Frontend plugin "${name}": buildCommand must be a non-empty string`);
-      }
-      if (typeof runCommand !== "function") {
-        throw new Error(`Frontend plugin "${name}": runCommand must be a function`);
-      }
-    },
-    async buildSite(_ctx, site) {
-      if (!site?.frontend) {
-        throw new Error(`Frontend plugin "${name}": buildSite requires a site.frontend config`);
-      }
-
-      const root = path.resolve(site.frontend.root);
-      const outDir = path.resolve(site.frontend.outDir);
-      const env = {
-        ...process.env,
-        ...site.frontend.env,
-      };
-
-      await runCommand(buildCommand, { cwd: root, env });
-
-      return {
-        siteId: site.siteId,
-        outDir,
-      };
-    },
-    async staticMounts(_ctx, site) {
-      if (!site?.frontend) return [];
-      return [
-        {
-          siteId: site.siteId,
-          domains: site.domains ?? [],
-          basePath: site.frontend.basePath ?? "/",
-          dir: site.frontend.outDir,
-          spaFallback: site.frontend.spaFallback ?? true,
-          cachePolicy: "short",
-        },
-      ];
-    },
-  };
-}

package/src/frontend/types.js

@@ -1,35 +0,0 @@
-/**
- * @typedef {"frontend-build" | "static-serve" | "frontend-dev"} FrontendPluginCapability
- */
-
-/**
- * @typedef {Object} FrontendSiteDefinition
- * @property {string} siteId
- * @property {string[]} domains
- * @property {string} basePath
- * @property {string[]} services
- * @property {Object | null} [frontend]
- * @property {string | null} [staticDir]
- */
-
-/**
- * @typedef {Object} FrontendBuildResult
- * @property {string} siteId
- * @property {string} outDir
- * @property {string} [manifestPath]
- * @property {string} [assetsHash]
- * @property {string[]} [warnings]
- */
-
-/**
- * @typedef {Object} FrontendStaticMount
- * @property {string | null} siteId
- * @property {string[]} domains
- * @property {string} basePath
- * @property {string} dir
- * @property {boolean} [spaFallback]
- * @property {"immutable" | "short" | "none"} [cachePolicy]
- */
-
-export {};
-

package/src/index.js

@@ -1,58 +0,0 @@
-// ThreadForge - Multi-threaded Node.js Service Runtime
-// Public API
-//
-// D8: Core exports only. Internal plumbing is available via 'threadforge/internals'
-// (src/internals.js) for advanced use cases.
-
-// Core
-export { defineServices } from "./core/config.js";
-export { defineHost } from "./core/host-config.js";
-export { definePlatform } from "./core/platform-config.js";
-export { ForgeContext } from "./core/ForgeContext.js";
-export { RequestContext } from "./core/RequestContext.js";
-
-// Interceptors
-export {
-  CircuitBreaker,
-  deadlineInterceptor,
-  isRetryable,
-  loggingInterceptor,
-  metricsInterceptor,
-  retryInterceptor,
-  runInterceptorChain,
-} from "./core/Interceptors.js";
-
-// Routing
-export {
-  BroadcastStrategy,
-  createStrategy,
-  HashStrategy,
-  LeastPendingStrategy,
-  PrimaryStrategy,
-  RoundRobinStrategy,
-} from "./core/RoutingStrategy.js";
-
-// Decorators
-export {
-  Auth,
-  Emit,
-  Expose,
-  getContract,
-  Internal,
-  On,
-  Prefix,
-  RateLimit,
-  Route,
-  Validate,
-} from "./decorators/index.js";
-
-// Plugins
-export { PluginManager } from "./plugins/PluginManager.js";
-export { cors, cron, postgres, realtime, redis, s3 } from "./plugins/index.js";
-export { viteFrontend } from "./frontend/plugins/viteFrontend.js";
-
-// Services
-export { Service } from "./services/Service.js";
-
-// Internal plumbing is available via 'threadforge/internals' for advanced use cases.
-// See src/internals.js for the full list of internal exports.