nvent 0.5.15 → 1.0.0-alpha.2

package/dist/runtime/nitro/utils/engine.js

@@ -0,0 +1,130 @@
+import { spawn } from "node:child_process";
+import { createConnection } from "node:net";
+import { consola } from "consola";
+const logger = consola.withTag("nvent:iii-engine");
+const READY_POLL_INTERVAL_MS = 200;
+const READY_TIMEOUT_MS = 15e3;
+async function pollReady(httpPort) {
+  const url = `http://localhost:${httpPort}`;
+  const deadline = Date.now() + READY_TIMEOUT_MS;
+  while (Date.now() < deadline) {
+    try {
+      const res = await fetch(url, { signal: AbortSignal.timeout(500) });
+      if (res.status < 600) return;
+    } catch {
+    }
+    await new Promise((r) => setTimeout(r, READY_POLL_INTERVAL_MS));
+  }
+  throw new Error(`iii engine did not become ready within ${READY_TIMEOUT_MS}ms (HTTP port ${httpPort})`);
+}
+function isTcpPortOpen(port, host = "127.0.0.1") {
+  return new Promise((resolve) => {
+    const socket = createConnection({ port, host }, () => {
+      socket.destroy();
+      resolve(true);
+    });
+    socket.once("error", () => resolve(false));
+    setTimeout(() => {
+      socket.destroy();
+      resolve(false);
+    }, 1e3);
+  });
+}
+function parseEngineLineLevel(line) {
+  if (line.includes("[ERROR]")) return "error";
+  if (line.includes("[WARN]")) return "warn";
+  if (line.includes("[INFO]")) return "info";
+  return null;
+}
+const LOG_LEVEL_RANK = { none: 0, error: 1, warn: 2, info: 3 };
+function shouldShow(lineLevel, minLevel) {
+  return LOG_LEVEL_RANK[lineLevel] <= LOG_LEVEL_RANK[minLevel];
+}
+export class EngineManager {
+  process = null;
+  opts;
+  constructor(opts) {
+    this.opts = { httpPort: 3111, wsPort: 49134, logLevel: "warn", ...opts };
+  }
+  isRunning() {
+    return this.process !== null && !this.process.killed && this.process.exitCode === null;
+  }
+  async start() {
+    if (this.isRunning()) {
+      logger.warn("iii engine is already running");
+      return;
+    }
+    const { binaryPath, configPath, httpPort, wsPort, logLevel } = this.opts;
+    if (logLevel === "info") logger.info(`Starting iii engine \u2014 config: ${configPath}`);
+    this.process = spawn(binaryPath, ["--config", configPath], {
+      stdio: ["ignore", "pipe", "pipe"],
+      detached: false
+    });
+    let lastLevel = "info";
+    this.process.stdout?.on("data", (chunk) => {
+      if (logLevel === "none") return;
+      for (const line of chunk.toString().split("\n").filter(Boolean)) {
+        const parsed = parseEngineLineLevel(line);
+        if (parsed) lastLevel = parsed;
+        const effectiveLevel = parsed ?? lastLevel;
+        if (!shouldShow(effectiveLevel, logLevel)) continue;
+        if (effectiveLevel === "error") logger.error(`[iii] ${line}`);
+        else if (effectiveLevel === "warn") logger.warn(`[iii] ${line}`);
+        else logger.info(`[iii] ${line}`);
+      }
+    });
+    this.process.stderr?.on("data", (chunk) => {
+      if (logLevel === "none") return;
+      for (const line of chunk.toString().split("\n").filter(Boolean))
+        logger.warn(`[iii] ${line}`);
+    });
+    let earlyExitCode = null;
+    const earlyExitPromise = new Promise((resolve) => {
+      this.process.once("exit", (code, signal) => {
+        earlyExitCode = code;
+        if (!earlyExitCode && logLevel === "info") logger.info(`iii engine exited (code=${code}, signal=${signal})`);
+        this.process = null;
+        resolve();
+      });
+    });
+    this.process.on("error", (err) => {
+      logger.error(`iii engine process error: ${err.message}`);
+      this.process = null;
+    });
+    await Promise.race([pollReady(httpPort), earlyExitPromise]);
+    if (earlyExitCode !== null && earlyExitCode !== 0) {
+      const [httpOk, wsOk] = await Promise.all([isTcpPortOpen(httpPort), isTcpPortOpen(wsPort)]);
+      if (httpOk && wsOk) {
+        if (logLevel === "info") logger.info(`iii engine already running on HTTP :${httpPort} / WS :${wsPort} \u2014 reusing`);
+        return;
+      }
+      throw new Error(
+        `iii engine failed to start (exit code ${earlyExitCode}). Ports ${httpPort} (HTTP) or ${wsPort} (WS) may be in use.`
+      );
+    }
+    if (logLevel === "info") logger.info(`iii engine ready (WS :${wsPort}, HTTP :${httpPort})`);
+  }
+  async stop() {
+    if (!this.isRunning() || !this.process) return;
+    const { logLevel } = this.opts;
+    if (logLevel === "info") logger.info("Stopping iii engine...");
+    return new Promise((resolve) => {
+      this.process.once("exit", () => {
+        this.process = null;
+        if (logLevel === "info") logger.info("iii engine stopped");
+        resolve();
+      });
+      this.process.kill("SIGTERM");
+      setTimeout(() => {
+        if (this.process) this.process.kill("SIGKILL");
+      }, 5e3);
+    });
+  }
+  async restart() {
+    await this.stop();
+    await this.start();
+  }
+}
+export function createEngineManager(opts) {
+  return new EngineManager(opts);
+}

package/dist/runtime/nitro/utils/nventDir.d.ts

@@ -0,0 +1 @@
+export declare function resolveNventDir(importMetaUrl: string): string;

package/dist/runtime/nitro/utils/nventDir.js

@@ -0,0 +1,20 @@
+import { dirname, join, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+export function resolveNventDir(importMetaUrl) {
+  if (process.env.NVENT_DIR) return process.env.NVENT_DIR;
+  if (importMetaUrl && !importMetaUrl.endsWith("/_entry.js")) {
+    try {
+      const serverDir = dirname(fileURLToPath(importMetaUrl));
+      const candidate = join(serverDir, "..", "nvent");
+      if (candidate !== "/nvent") {
+        console.log(`[nvent] resolveNventDir via importMetaUrl: ${candidate}`);
+        return candidate;
+      }
+    } catch (e) {
+      console.warn(`[nvent] resolveNventDir: failed to parse importMetaUrl=${importMetaUrl}`, e);
+    }
+  }
+  const fromCwd = resolve(process.cwd(), "nvent");
+  console.log(`[nvent] resolveNventDir via CWD fallback: ${fromCwd} (importMetaUrl=${importMetaUrl})`);
+  return fromCwd;
+}

package/dist/runtime/nitro/utils/useIii.d.ts

@@ -0,0 +1,23 @@
+/**
+ * useIii — returns the iii SDK instance stored by the worker plugin.
+ *
+ * Available in any Nitro event handler or iii function:
+ * ```ts
+ * const { iii } = useIii()
+ * const result = await iii.trigger('orders::process', data)
+ *
+ * // Inside a registered function handler, get the execution context separately:
+ * const { iii } = useIii()
+ * const { logger } = getContext()  // auto-imported from iii-sdk via #imports
+ * ```
+ */
+import type { registerWorker } from 'iii-sdk';
+type IiiInstance = ReturnType<typeof registerWorker>;
+export declare function useIii(): {
+    iii: IiiInstance;
+};
+/**
+ * useIiiHealth — returns the current engine health status.
+ */
+export declare function useIiiHealth(): Promise<Record<string, unknown>>;
+export { getContext } from 'iii-sdk';

package/dist/runtime/nitro/utils/useIii.js

@@ -0,0 +1,14 @@
+import { useNitroApp } from "#imports";
+export function useIii() {
+  const nitroApp = useNitroApp();
+  const iii = nitroApp.$iii;
+  if (!iii) {
+    throw new Error("[nvent] iii SDK not initialized. Is the iii-worker Nitro plugin loaded?");
+  }
+  return { iii };
+}
+export async function useIiiHealth() {
+  const { iii } = useIii();
+  return iii.trigger({ function_id: "engine::health::check", payload: {} });
+}
+export { getContext } from "iii-sdk";

package/dist/runtime/nitro/utils/workers/node.d.ts

@@ -0,0 +1,24 @@
+import type { registerWorker } from 'iii-sdk';
+import { FunctionContext } from '../defineFunction.js';
+type IiiClient = ReturnType<typeof registerWorker>;
+export interface NodeFnInfo {
+    name: string;
+    description?: string;
+    handler: (input: unknown, ctx: FunctionContext) => Promise<unknown>;
+    triggers: Array<{
+        type: string;
+        function_id: string;
+        config?: Record<string, unknown>;
+    }>;
+    enqueues: string[];
+    flows: string[];
+    /** Explicit stream name for implicit ctx.stream ops. Falls back to flows[0] then name prefix. */
+    stream?: string;
+    filePath?: string;
+}
+/**
+ * Registers all Node.js (TypeScript) functions and their triggers with the iii client.
+ * Mirrors the Python side: one registration per trigger, with a validated function ID.
+ */
+export declare function registerNodeFunctions(iii: IiiClient, fns: NodeFnInfo[]): void;
+export {};

package/dist/runtime/nitro/utils/workers/node.js

@@ -0,0 +1,57 @@
+import { FunctionContext, NVENT_STREAM_KEY } from "../defineFunction.js";
+function extractStreamContext(input) {
+  if (typeof input === "object" && input !== null && NVENT_STREAM_KEY in input) {
+    return input[NVENT_STREAM_KEY];
+  }
+}
+function stripStreamContext(input) {
+  if (typeof input === "object" && input !== null && NVENT_STREAM_KEY in input) {
+    const { [NVENT_STREAM_KEY]: _, ...rest } = input;
+    return rest;
+  }
+  return input;
+}
+function triggerSuffix(type, cfg) {
+  if (type === "http") return `http(${cfg.http_method ?? "GET"}_${cfg.api_path ?? "/"})`;
+  if (type === "queue") return `queue(${cfg.topic ?? ""})`;
+  if (type === "cron") return `cron(${cfg.expression ?? ""})`;
+  return type;
+}
+export function registerNodeFunctions(iii, fns) {
+  for (const fn of fns) {
+    const metadata = {
+      name: fn.name,
+      description: fn.description,
+      filePath: fn.filePath,
+      triggers: (fn.triggers ?? []).map((t) => {
+        const cfg = t.config ?? {};
+        if (t.type === "http") return { type: "http", path: cfg.api_path, method: cfg.http_method };
+        if (t.type === "queue") return { type: "queue", topic: cfg.topic };
+        if (t.type === "cron") return { type: "cron", expression: cfg.expression };
+        return { type: t.type, ...cfg };
+      }),
+      flows: fn.flows ?? [],
+      enqueues: fn.enqueues ?? []
+    };
+    const seenSuffixes = /* @__PURE__ */ new Set();
+    for (const [index, trigger] of (fn.triggers ?? []).entries()) {
+      const cfg = trigger.config ?? {};
+      let suffix = triggerSuffix(trigger.type, cfg);
+      if (seenSuffixes.has(suffix)) suffix = `${suffix}::${index}`;
+      seenSuffixes.add(suffix);
+      const function_id = `steps::${fn.name}::trigger::${suffix}`;
+      const triggerType = trigger.type;
+      const streamName = fn.stream ?? fn.flows?.[0] ?? fn.name.split("::")[0];
+      iii.registerFunction(
+        { id: function_id, metadata },
+        (input) => {
+          const inherited = extractStreamContext(input);
+          const cleanInput = stripStreamContext(input);
+          const effectiveStream = inherited?.name ?? streamName;
+          return fn.handler(cleanInput, new FunctionContext(triggerType, fn.name, effectiveStream, inherited?.groupId));
+        }
+      );
+      iii.registerTrigger({ type: trigger.type, function_id, config: { ...cfg, metadata } });
+    }
+  }
+}

package/dist/runtime/nitro/utils/workers/python.d.ts

@@ -0,0 +1,67 @@
+/**
+ * Python Worker Manager
+ *
+ * Manages spawning and lifecycle of Python worker processes that connect
+ * Python functions to the iii engine.
+ *
+ * Lives in src/iii/ so it can be used by both:
+ *   - module.ts (dev) — starts workers in the Nuxt process for HMR
+ *   - the Nitro plugin (prod) — starts workers at server startup
+ */
+/** Minimal function descriptor — matches PythonFunctionMeta from registry.ts */
+export interface PyFnInfo {
+    id: string;
+    absPath: string;
+    standalone: boolean;
+}
+export declare class PythonWorkerManager {
+    /** Absolute path to _runtime.py */
+    private readonly runtimeScript;
+    private readonly wsUrl;
+    private readonly workerName;
+    private readonly fns;
+    private readonly python;
+    private readonly logLevel;
+    private process;
+    private stopped;
+    private restartAttempts;
+    constructor(
+    /** Absolute path to _runtime.py */
+    runtimeScript: string, wsUrl: string, workerName: string, fns: PyFnInfo[], python?: string, logLevel?: string);
+    isRunning(): boolean;
+    start(): Promise<void>;
+    restart(): Promise<void>;
+    stop(): Promise<void>;
+    private _spawn;
+    private _scheduleRestart;
+    private _kill;
+}
+/**
+ * Orchestrates all Python workers:
+ * - Shared worker: one process for all non-standalone functions
+ * - Standalone workers: one dedicated process per function with `standalone: true`
+ */
+export declare class PythonWorkersOrchestrator {
+    private readonly workersDir;
+    /** Content of worker_runtime.py, written to workersDir/_runtime.py */
+    private readonly runtimeContent;
+    /** Content of nvent.py, written to workersDir/nvent.py */
+    private readonly nventHelperContent;
+    private readonly wsUrl;
+    private readonly pythonBin;
+    private readonly logLevel;
+    private workers;
+    private lastFns;
+    private runtimeScript;
+    constructor(workersDir: string, 
+    /** Content of worker_runtime.py, written to workersDir/_runtime.py */
+    runtimeContent: string, 
+    /** Content of nvent.py, written to workersDir/nvent.py */
+    nventHelperContent: string, wsUrl: string, pythonBin: string, logLevel?: string);
+    start(fns: PyFnInfo[]): Promise<void>;
+    /** Called when a Python source file changes. Pass updated fns to handle additions/removals. */
+    onFileChanged(changedPath: string, fns?: PyFnInfo[]): Promise<void>;
+    stop(): Promise<void>;
+    private _prepareDir;
+    private _makeWorker;
+}

package/dist/runtime/nitro/utils/workers/python.js

@@ -0,0 +1,220 @@
+import { spawn } from "node:child_process";
+import { mkdirSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import { consola } from "consola";
+const logger = consola.withTag("nvent:python");
+function parsePythonLineLevel(line) {
+  if (line.startsWith("[ERROR]") || line.startsWith("[CRITICAL]")) return "error";
+  if (line.startsWith("[WARNING]") || line.startsWith("[WARN]")) return "warn";
+  if (line.startsWith("[INFO]")) return "info";
+  if (line.startsWith("[DEBUG]")) return "info";
+  return null;
+}
+const LOG_LEVEL_RANK = { none: 0, error: 1, warn: 2, info: 3 };
+function shouldShow(lineLevel, minLevel) {
+  return (LOG_LEVEL_RANK[lineLevel] ?? 0) <= (LOG_LEVEL_RANK[minLevel] ?? 0);
+}
+const MAX_BACKOFF_MS = 3e4;
+export class PythonWorkerManager {
+  constructor(runtimeScript, wsUrl, workerName, fns, python = "python3", logLevel = "warn") {
+    this.runtimeScript = runtimeScript;
+    this.wsUrl = wsUrl;
+    this.workerName = workerName;
+    this.fns = fns;
+    this.python = python;
+    this.logLevel = logLevel;
+  }
+  process = null;
+  stopped = false;
+  restartAttempts = 0;
+  isRunning() {
+    return this.process !== null && !this.process.killed && this.process.exitCode === null;
+  }
+  async start() {
+    if (this.isRunning()) return;
+    this.stopped = false;
+    this.restartAttempts = 0;
+    this._spawn();
+  }
+  async restart() {
+    this.stopped = true;
+    await this._kill();
+    this.stopped = false;
+    this.restartAttempts = 0;
+    this._spawn();
+  }
+  async stop() {
+    this.stopped = true;
+    await this._kill();
+  }
+  _spawn() {
+    if (this.logLevel === "info") logger.info(`Starting Python worker \u2014 ${this.workerName}`);
+    const fnArgs = this.fns.flatMap((fn) => [fn.absPath, fn.id]);
+    this.process = spawn(this.python, [this.runtimeScript, this.wsUrl, this.workerName, ...fnArgs], {
+      stdio: ["ignore", "pipe", "pipe"],
+      detached: false
+    });
+    let stdoutBuffer = "";
+    this.process.stdout?.on("data", (chunk) => {
+      const text = chunk.toString();
+      stdoutBuffer += text;
+      if (this.logLevel === "none") return;
+      for (const line of text.split("\n").filter(Boolean)) {
+        const level = parsePythonLineLevel(line) ?? "info";
+        if (!shouldShow(level, this.logLevel)) continue;
+        if (level === "error") logger.error(`[python] ${line}`);
+        else if (level === "warn") logger.warn(`[python] ${line}`);
+        else logger.info(`[python] ${line}`);
+      }
+    });
+    this.process.stderr?.on("data", (chunk) => {
+      if (this.logLevel === "none") return;
+      for (const line of chunk.toString().split("\n").filter(Boolean))
+        logger.error(`[python] ${line}`);
+    });
+    this.process.on("exit", (code, signal) => {
+      if (this.logLevel === "info") logger.info(`Python worker exited (code=${code}, signal=${signal})`);
+      this.process = null;
+      if (this.stopped) return;
+      if (code === 1 && stdoutBuffer.includes("iii package not found")) {
+        logger.error("Python worker stopped: iii SDK not installed. Run: pip install iii-sdk");
+        this.stopped = true;
+        return;
+      }
+      this._scheduleRestart();
+    });
+    this.process.on("error", (err) => {
+      logger.error(`Python worker process error: ${err.message}`);
+      this.process = null;
+      if (err.code === "ENOENT") {
+        logger.error(`Python binary not found: ${this.python}. Check functions.python.path in nvent config.`);
+        this.stopped = true;
+        return;
+      }
+      if (!this.stopped) this._scheduleRestart();
+    });
+  }
+  _scheduleRestart() {
+    this.restartAttempts++;
+    const delay = Math.min(500 * 2 ** this.restartAttempts, MAX_BACKOFF_MS);
+    logger.warn(`Python worker will restart in ${delay}ms (attempt ${this.restartAttempts})`);
+    setTimeout(() => {
+      if (!this.stopped) this._spawn();
+    }, delay);
+  }
+  _kill() {
+    if (!this.isRunning() || !this.process) return Promise.resolve();
+    return new Promise((resolve) => {
+      this.process.once("exit", () => {
+        this.process = null;
+        resolve();
+      });
+      this.process.kill("SIGTERM");
+      setTimeout(() => {
+        if (this.process) this.process.kill("SIGKILL");
+      }, 5e3);
+    });
+  }
+}
+export class PythonWorkersOrchestrator {
+  constructor(workersDir, runtimeContent, nventHelperContent, wsUrl, pythonBin, logLevel = "warn") {
+    this.workersDir = workersDir;
+    this.runtimeContent = runtimeContent;
+    this.nventHelperContent = nventHelperContent;
+    this.wsUrl = wsUrl;
+    this.pythonBin = pythonBin;
+    this.logLevel = logLevel;
+    this.runtimeScript = join(workersDir, "_runtime.py");
+  }
+  workers = /* @__PURE__ */ new Map();
+  lastFns = [];
+  runtimeScript;
+  async start(fns) {
+    this.lastFns = fns;
+    if (fns.length === 0) return;
+    this._prepareDir();
+    const sharedFns = fns.filter((fn) => !fn.standalone);
+    const standaloneFns = fns.filter((fn) => fn.standalone);
+    if (sharedFns.length > 0) {
+      const worker = this._makeWorker("__shared__", sharedFns);
+      await worker.start();
+      this.workers.set("__shared__", worker);
+    }
+    for (const fn of standaloneFns) {
+      const worker = this._makeWorker(fn.id, [fn]);
+      await worker.start();
+      this.workers.set(fn.id, worker);
+    }
+  }
+  /** Called when a Python source file changes. Pass updated fns to handle additions/removals. */
+  async onFileChanged(changedPath, fns) {
+    const effectiveFns = fns ?? this.lastFns;
+    this.lastFns = effectiveFns;
+    this._prepareDir();
+    const sharedFns = effectiveFns.filter((fn) => !fn.standalone);
+    const standaloneFns = effectiveFns.filter((fn) => fn.standalone);
+    const changedFn = effectiveFns.find((fn) => fn.absPath === changedPath);
+    const affectsShared = !changedFn?.standalone;
+    if (affectsShared) {
+      if (sharedFns.length > 0) {
+        const existing = this.workers.get("__shared__");
+        if (existing) {
+          await existing.restart();
+        } else {
+          const worker = this._makeWorker("__shared__", sharedFns);
+          await worker.start();
+          this.workers.set("__shared__", worker);
+        }
+      } else {
+        const existing = this.workers.get("__shared__");
+        if (existing) {
+          await existing.stop();
+          this.workers.delete("__shared__");
+        }
+      }
+    }
+    if (changedFn?.standalone) {
+      const existing = this.workers.get(changedFn.id);
+      if (existing) {
+        await existing.restart();
+      } else {
+        const worker = this._makeWorker(changedFn.id, [changedFn]);
+        await worker.start();
+        this.workers.set(changedFn.id, worker);
+      }
+    }
+    for (const [id, worker] of this.workers) {
+      if (id === "__shared__") continue;
+      if (!effectiveFns.find((fn) => fn.id === id)) {
+        await worker.stop();
+        this.workers.delete(id);
+      }
+    }
+    for (const fn of standaloneFns) {
+      if (!this.workers.has(fn.id)) {
+        const worker = this._makeWorker(fn.id, [fn]);
+        await worker.start();
+        this.workers.set(fn.id, worker);
+      }
+    }
+  }
+  async stop() {
+    for (const worker of this.workers.values()) await worker.stop();
+    this.workers.clear();
+  }
+  _prepareDir() {
+    mkdirSync(this.workersDir, { recursive: true });
+    writeFileSync(this.runtimeScript, this.runtimeContent, "utf-8");
+    writeFileSync(join(this.workersDir, "nvent.py"), this.nventHelperContent, "utf-8");
+  }
+  _makeWorker(name, fns) {
+    return new PythonWorkerManager(
+      this.runtimeScript,
+      this.wsUrl,
+      `nvent-python-${name}`,
+      fns,
+      this.pythonBin,
+      this.logLevel
+    );
+  }
+}