nvent 0.4.0

package/dist/runtime/server/events/eventStoreFactory.d.ts

@@ -0,0 +1,19 @@
+import { getStreamNames } from './streamNames.js';
+import type { EventStoreAdapter } from './types.js';
+export interface EventStoreInstance {
+    name: string;
+    append: EventStoreAdapter['append'];
+    read: EventStoreAdapter['read'];
+    subscribe: EventStoreAdapter['subscribe'];
+}
+export interface EventStoreFactory {
+    adapter: EventStoreAdapter;
+    names: ReturnType<typeof getStreamNames>;
+    stream(name: string): EventStoreInstance;
+    /** Idempotently start stream store wiring that persists ingress events and projections */
+    start(): void;
+    /** Stop wiring and release listeners */
+    stop(): void;
+}
+export declare function getEventStoreFactory(): EventStoreFactory;
+export declare function setEventStoreFactory(f: EventStoreFactory): void;

package/dist/runtime/server/events/eventStoreFactory.js

@@ -0,0 +1,44 @@
+import { useRuntimeConfig, useServerLogger } from "#imports";
+import { getStreamNames } from "./streamNames.js";
+import { createRedisAdapter } from "./adapters/redis/redisAdapter.js";
+import { createMemoryAdapter } from "./adapters/memoryAdapter.js";
+import { createFileAdapter } from "./adapters/fileAdapter.js";
+import { createWiringRegistry } from "./wiring/registry.js";
+const logger = useServerLogger("event-store-factory");
+let cachedFactory = null;
+export function getEventStoreFactory() {
+  if (cachedFactory) return cachedFactory;
+  const rc = useRuntimeConfig();
+  const adapter = rc?.queue?.eventStore?.adapter || "memory";
+  let adapterInstance;
+  if (adapter === "memory") adapterInstance = createMemoryAdapter();
+  else if (adapter === "file") adapterInstance = createFileAdapter();
+  else if (adapter === "redis") adapterInstance = createRedisAdapter();
+  else adapterInstance = createMemoryAdapter();
+  logger.debug("Event store initialized", { adapter, adapterType: adapter });
+  const names = getStreamNames();
+  const wiring = createWiringRegistry({ adapter: adapterInstance, names });
+  const factory = {
+    adapter: adapterInstance,
+    names,
+    stream(name) {
+      return {
+        name,
+        append: (s, e) => adapterInstance.append(s, e),
+        read: (s, o) => adapterInstance.read(s, o),
+        subscribe: (s, cb) => adapterInstance.subscribe(s, cb)
+      };
+    },
+    start() {
+      wiring.start();
+    },
+    stop() {
+      wiring.stop();
+    }
+  };
+  cachedFactory = factory;
+  return factory;
+}
+export function setEventStoreFactory(f) {
+  cachedFactory = f;
+}

package/dist/runtime/server/events/streamNames.d.ts

@@ -0,0 +1,17 @@
+/**
+ * Stream naming utilities
+ *
+ * Core streams:
+ * - nq:flow:{runId}        - Flow run event stream
+ * - nq:flows:{flowName}    - Sorted set index of flow runs by flow name
+ */
+export interface StreamNamesConfig {
+    flow?: string | ((runId: string) => string);
+    flowIndex?: string | ((flowName: string) => string);
+}
+export interface StreamNames {
+    flow: (runId: string) => string;
+    flowIndex: (flowName: string) => string;
+}
+export declare function getStreamNames(): StreamNames;
+export default getStreamNames;

package/dist/runtime/server/events/streamNames.js

@@ -0,0 +1,17 @@
+import { useRuntimeConfig } from "#imports";
+function defaults() {
+  return {
+    flow: (runId) => `nq:flow:${runId}`,
+    flowIndex: (flowName) => `nq:flows:${flowName}`
+  };
+}
+export function getStreamNames() {
+  const rc = useRuntimeConfig();
+  const cfg = rc?.queue?.eventStore?.streams || {};
+  const d = defaults();
+  return {
+    flow: typeof cfg.flow === "string" ? (runId) => `${cfg.flow}${runId}` : cfg.flow || d.flow,
+    flowIndex: typeof cfg.flowIndex === "string" ? (flowName) => `${cfg.flowIndex}${flowName}` : cfg.flowIndex || d.flowIndex
+  };
+}
+export default getStreamNames;

package/dist/runtime/server/events/types.d.ts

@@ -0,0 +1,63 @@
+import type { EventRecord } from '../../types.js';
+export interface PublishContext {
+    queue?: string;
+    jobId?: string;
+    /** Flow run ID for flow events */
+    flowId?: string;
+    /** Trigger ID for trigger events */
+    triggerId?: string;
+}
+export interface PublishPayload<T = any> {
+    type: string;
+    runId: string;
+    flowName: string;
+    stepName?: string;
+    stepId?: string;
+    attempt?: number;
+    data?: T;
+}
+export interface EventReadOptions {
+    fromId?: string;
+    limit?: number;
+    direction?: 'forward' | 'backward';
+}
+export interface EventSubscription {
+    unsubscribe(): void;
+}
+export interface IndexEntry {
+    id: string;
+    score: number;
+    metadata?: {
+        status?: 'running' | 'completed' | 'failed';
+        startedAt?: number;
+        completedAt?: number;
+        stepCount?: number;
+        completedSteps?: number;
+        emittedEvents?: string[];
+        version?: number;
+    };
+}
+export interface IndexReadOptions {
+    offset?: number;
+    limit?: number;
+}
+export interface EventStoreAdapter {
+    append(subject: string, e: Omit<EventRecord, 'id' | 'ts'>): Promise<EventRecord>;
+    read(subject: string, opts?: EventReadOptions): Promise<EventRecord[]>;
+    subscribe(subject: string, onEvent: (e: EventRecord) => void): Promise<EventSubscription>;
+    indexAdd?(key: string, id: string, score: number, metadata?: Record<string, any>): Promise<void>;
+    indexGet?(key: string, id: string): Promise<IndexEntry | null>;
+    indexUpdate?(key: string, id: string, metadata: Record<string, any>): Promise<boolean>;
+    indexUpdateWithRetry?(key: string, id: string, metadata: Record<string, any>, maxRetries?: number): Promise<void>;
+    indexIncrement?(key: string, id: string, field: string, increment?: number): Promise<number>;
+    indexRead?(key: string, opts?: IndexReadOptions): Promise<IndexEntry[]>;
+    setMetadataTTL?(flowName: string, runId: string, ttlSeconds: number): Promise<void>;
+    cleanupCompletedFlows?(key: string, retentionSeconds: number): Promise<number>;
+    /** Delete a specific stream/subject */
+    deleteStream?(subject: string): Promise<void>;
+    /** Delete all streams matching a pattern (e.g., 'flow:*' or 'trigger:webhook-*') */
+    deleteByPattern?(pattern: string): Promise<number>;
+    /** Delete an index key */
+    deleteIndex?(key: string): Promise<void>;
+    close(): Promise<void>;
+}

package/dist/runtime/server/events/wiring/flowWiring.d.ts

@@ -0,0 +1,33 @@
+import type { EventStoreAdapter } from '../types.js';
+import type { EventRecord } from '../../../types.js';
+export interface FlowWiringDeps {
+    adapter: EventStoreAdapter;
+}
+/**
+ * Check if all dependencies for a step are met
+ * Returns true if all subscriptions have been emitted or completed
+ */
+export declare function checkPendingStepTriggers(step: any, emittedEvents: Set<string>, completedSteps: Set<string>): boolean;
+/**
+ * Analyze flow completion status from events
+ * Returns status, step counts, and timestamps
+ */
+export declare function analyzeFlowCompletion(flowSteps: Record<string, any>, entryStep: string | undefined, events: EventRecord[]): {
+    status: 'running' | 'completed' | 'failed';
+    totalSteps: number;
+    completedSteps: number;
+    startedAt: number;
+    completedAt: number;
+};
+/**
+ * v0.4 Lean Flow Wiring
+ *
+ * 1. Persists flow events to streams using runId
+ * 2. Maintains a sorted set index using projection names for listing runs
+ *
+ * Events arrive as "ingress" (no id/ts) and are persisted to `nq:flow:{runId}` streams.
+ */
+export declare function createFlowWiring(deps: FlowWiringDeps): {
+    start: () => void;
+    stop: () => void;
+};

package/dist/runtime/server/events/wiring/flowWiring.js

@@ -0,0 +1,406 @@
+import { getEventBus } from "../eventBus.js";
+import { useServerLogger, useEventStore, $useAnalyzedFlows, $useQueueRegistry, useQueue } from "#imports";
+const logger = useServerLogger("flow-wiring");
+export function checkPendingStepTriggers(step, emittedEvents, completedSteps) {
+  if (!step.subscribes || step.subscribes.length === 0) {
+    return true;
+  }
+  return step.subscribes.every((sub) => {
+    if (emittedEvents.has(sub)) return true;
+    const [prefix, value] = sub.split(":");
+    if (prefix === "step" && value) {
+      return completedSteps.has(value);
+    }
+    return false;
+  });
+}
+async function checkAndTriggerPendingSteps(flowName, runId, store) {
+  try {
+    const analyzedFlows = $useAnalyzedFlows();
+    const registry = $useQueueRegistry();
+    const { enqueue } = useQueue();
+    const flowDef = analyzedFlows.find((f) => f.id === flowName);
+    if (!flowDef?.steps) return;
+    const indexKey = store.names().flowIndex(flowName);
+    const flowEntry = await store.indexGet(indexKey, runId);
+    if (!flowEntry?.metadata) return;
+    const emittedEvents = new Set(flowEntry.metadata.emittedEvents || []);
+    const streamName = store.names().flow(runId);
+    const allEvents = await store.read(streamName);
+    const completedSteps = /* @__PURE__ */ new Set();
+    for (const event of allEvents) {
+      if (event.type === "step.completed" && "stepName" in event) {
+        completedSteps.add(event.stepName);
+      }
+    }
+    for (const [stepName, stepDef] of Object.entries(flowDef.steps)) {
+      const step = stepDef;
+      if (!step.subscribes || completedSteps.has(stepName)) continue;
+      const canTrigger = checkPendingStepTriggers(step, emittedEvents, completedSteps);
+      if (canTrigger) {
+        const flowRegistry = (registry?.flows || {})[flowName];
+        const stepMeta = flowRegistry?.steps?.[stepName];
+        if (stepMeta?.queue) {
+          const emitData = {};
+          const subscribes = step.subscribes || [];
+          for (const sub of subscribes) {
+            const emitEvent = allEvents.find(
+              (evt) => evt.type === "emit" && evt.data?.name === sub
+            );
+            if (emitEvent && emitEvent.data?.payload !== void 0) {
+              emitData[sub] = emitEvent.data.payload;
+            }
+          }
+          const payload = {
+            flowId: runId,
+            flowName,
+            input: emitData
+            // Keyed by event name
+          };
+          const jobId = `${runId}__${stepName}`;
+          try {
+            await enqueue(stepMeta.queue, { name: stepName, data: payload, opts: { jobId } });
+            logger.debug("Triggered pending step", {
+              flowName,
+              runId,
+              step: stepName,
+              subscribes: step.subscribes
+            });
+          } catch {
+          }
+        }
+      }
+    }
+  } catch (err) {
+    logger.warn("Failed to check pending steps", {
+      flowName,
+      runId,
+      error: err?.message
+    });
+  }
+}
+export function analyzeFlowCompletion(flowSteps, entryStep, events) {
+  const allSteps = entryStep ? [entryStep, ...Object.keys(flowSteps)] : Object.keys(flowSteps);
+  const completedSteps = /* @__PURE__ */ new Set();
+  const failedSteps = /* @__PURE__ */ new Set();
+  const retriedSteps = /* @__PURE__ */ new Map();
+  let startedAt = 0;
+  let completedAt = 0;
+  for (const event of events) {
+    if (event.type === "flow.start") {
+      startedAt = typeof event.ts === "string" ? new Date(event.ts).getTime() : 0;
+    }
+    if (event.type === "step.completed" && "stepName" in event) {
+      completedSteps.add(event.stepName);
+    }
+    if (event.type === "step.retry" && "stepName" in event) {
+      const currentAttempts = retriedSteps.get(event.stepName) || 0;
+      retriedSteps.set(event.stepName, currentAttempts + 1);
+    }
+    if (event.type === "step.failed" && "stepName" in event) {
+      failedSteps.add(event.stepName);
+    }
+  }
+  const finalFailedSteps = /* @__PURE__ */ new Set();
+  for (const stepName of failedSteps) {
+    let lastRetryIndex = -1;
+    let lastFailedIndex = -1;
+    for (let i = 0; i < events.length; i++) {
+      const event = events[i];
+      if ("stepName" in event && event.stepName === stepName) {
+        if (event.type === "step.retry") {
+          lastRetryIndex = i;
+        }
+        if (event.type === "step.failed") {
+          lastFailedIndex = i;
+        }
+      }
+    }
+    if (lastFailedIndex > lastRetryIndex) {
+      finalFailedSteps.add(stepName);
+    }
+  }
+  const totalSteps = allSteps.length;
+  const hasFinalFailures = finalFailedSteps.size > 0;
+  let hasBlockingFailure = false;
+  if (hasFinalFailures) {
+    for (const failedStepName of finalFailedSteps) {
+      const failedStepDef = flowSteps[failedStepName];
+      if (failedStepDef?.emits && failedStepDef.emits.length > 0) {
+        for (const [stepName, stepDef] of Object.entries(flowSteps)) {
+          const step = stepDef;
+          if (stepName === failedStepName) continue;
+          if (step.subscribes && step.subscribes.length > 0) {
+            const dependsOnFailedStep = step.subscribes.some((sub) => {
+              return failedStepDef.emits.some(
+                (emit) => sub === `${failedStepName}.${emit}` || sub === emit
+              );
+            });
+            if (dependsOnFailedStep && !completedSteps.has(stepName)) {
+              hasBlockingFailure = true;
+              break;
+            }
+          }
+        }
+      }
+      if (hasBlockingFailure) break;
+    }
+  }
+  if (hasBlockingFailure) {
+    return {
+      status: "failed",
+      totalSteps,
+      completedSteps: completedSteps.size,
+      startedAt,
+      completedAt: Date.now()
+    };
+  }
+  const allCompleted = allSteps.every(
+    (step) => completedSteps.has(step) || finalFailedSteps.has(step)
+  );
+  let status = "running";
+  if (allCompleted) {
+    status = "completed";
+    completedAt = Date.now();
+  }
+  return {
+    status,
+    totalSteps,
+    completedSteps: completedSteps.size,
+    startedAt,
+    completedAt
+  };
+}
+export function createFlowWiring(deps) {
+  const { adapter } = deps;
+  const bus = getEventBus();
+  const unsubs = [];
+  let wired = false;
+  const indexFlowRun = async (flowName, flowId, timestamp, metadata) => {
+    try {
+      const store = useEventStore();
+      const names = store.names();
+      const indexKey = names.flowIndex(flowName);
+      await store.indexAdd(indexKey, flowId, timestamp, metadata);
+      logger.debug("Indexed run", { flowName, flowId, indexKey, timestamp, metadata });
+    } catch (err) {
+      logger.error("Failed to index run", { error: err });
+    }
+  };
+  function start() {
+    if (wired) return;
+    wired = true;
+    const store = useEventStore();
+    const names = store.names();
+    const handlePersistence = async (e) => {
+      try {
+        if (e.id && e.ts) {
+          return;
+        }
+        const runId = e.runId;
+        if (!runId) {
+          return;
+        }
+        const flowName = e.flowName;
+        if (!flowName) {
+          return;
+        }
+        const streamName = names.flow(runId);
+        const eventData = {
+          type: e.type,
+          runId: e.runId,
+          flowName: e.flowName,
+          data: e.data
+        };
+        if ("stepName" in e && e.stepName) eventData.stepName = e.stepName;
+        if ("stepId" in e && e.stepId) eventData.stepId = e.stepId;
+        if ("attempt" in e && e.attempt) eventData.attempt = e.attempt;
+        await adapter.append(streamName, eventData);
+        if (e.type === "flow.completed" || e.type === "flow.failed") {
+          logger.info("Stored terminal event to stream", {
+            type: e.type,
+            flowName,
+            runId
+          });
+        } else {
+          logger.debug("Stored event to stream", {
+            type: e.type,
+            flowName,
+            runId,
+            stepName: "stepName" in e ? e.stepName : void 0
+          });
+        }
+      } catch (err) {
+        logger.error("ERROR persisting event", {
+          type: e.type,
+          runId: e.runId,
+          flowName: e.flowName,
+          error: err?.message
+        });
+      }
+    };
+    const handleOrchestration = async (e) => {
+      try {
+        if (e.id && e.ts) {
+          return;
+        }
+        if (e.type === "flow.completed" || e.type === "flow.failed") {
+          return;
+        }
+        const runId = e.runId;
+        if (!runId) return;
+        const flowName = e.flowName;
+        if (!flowName) return;
+        const streamName = names.flow(runId);
+        const indexKey = names.flowIndex(flowName);
+        if (e.type === "flow.start") {
+          const timestamp = Date.now();
+          await indexFlowRun(flowName, runId, timestamp, {
+            status: "running",
+            startedAt: timestamp,
+            stepCount: 0,
+            completedSteps: 0,
+            emittedEvents: []
+          });
+        }
+        if (e.type === "step.completed") {
+          try {
+            const newCount = await store.indexIncrement(indexKey, runId, "completedSteps", 1);
+            logger.debug("Incremented completedSteps", {
+              flowName,
+              runId,
+              stepName: "stepName" in e ? e.stepName : "unknown",
+              newCount
+            });
+          } catch (err) {
+            logger.warn("Failed to update completedSteps", {
+              flowName,
+              runId,
+              error: err?.message
+            });
+          }
+        }
+        if (e.type === "emit") {
+          const emitEvent = e;
+          const eventName = emitEvent.data?.name || emitEvent.data?.topic;
+          if (!eventName) {
+            logger.warn("Emit event missing name/topic", { flowName, runId, data: emitEvent.data });
+          } else {
+            try {
+              const currentEntry = await store.indexGet(indexKey, runId);
+              const emittedEvents = (currentEntry?.metadata?.emittedEvents || []).filter((item) => item != null && typeof item === "string");
+              if (!emittedEvents.includes(eventName)) {
+                await store.indexUpdateWithRetry(indexKey, runId, {
+                  emittedEvents: [...emittedEvents, eventName]
+                });
+                logger.debug("Tracked emit event", {
+                  flowName,
+                  runId,
+                  name: eventName,
+                  allEmitted: [...emittedEvents, eventName]
+                });
+              }
+            } catch (err) {
+              logger.warn("Failed to track emitted event", {
+                flowName,
+                runId,
+                event: eventName,
+                error: err?.message
+              });
+            }
+            await checkAndTriggerPendingSteps(flowName, runId, store);
+          }
+        }
+        if (e.type === "step.completed" || e.type === "step.failed") {
+          await checkAndTriggerPendingSteps(flowName, runId, store);
+          await new Promise((resolve) => setTimeout(resolve, 50));
+          try {
+            const allEvents = await store.read(streamName);
+            const analyzedFlows = $useAnalyzedFlows();
+            const flowDef = analyzedFlows.find((f) => f.id === flowName);
+            if (flowDef?.steps) {
+              const entryStepName = flowDef.entry?.step;
+              const analysis = analyzeFlowCompletion(flowDef.steps, entryStepName, allEvents);
+              const updateMetadata = {
+                status: analysis.status,
+                stepCount: analysis.totalSteps
+              };
+              if (analysis.status !== "running" && analysis.completedAt) {
+                updateMetadata.completedAt = analysis.completedAt;
+              }
+              await store.indexUpdateWithRetry(indexKey, runId, updateMetadata);
+              if (analysis.status === "completed" || analysis.status === "failed") {
+                const eventType = analysis.status === "completed" ? "flow.completed" : "flow.failed";
+                const terminalEventExists = allEvents.some(
+                  (evt) => evt.type === "flow.completed" || evt.type === "flow.failed"
+                );
+                if (terminalEventExists) {
+                  logger.debug("Terminal event already exists, skipping publish", {
+                    flowName,
+                    runId,
+                    eventType
+                  });
+                } else {
+                  logger.info("Publishing terminal event to bus", {
+                    flowName,
+                    runId,
+                    eventType
+                  });
+                  await bus.publish({
+                    type: eventType,
+                    runId,
+                    flowName,
+                    data: {}
+                  });
+                }
+              }
+            }
+          } catch (err) {
+            logger.warn("Failed to analyze flow completion", {
+              flowName,
+              runId,
+              error: err?.message
+            });
+          }
+        }
+      } catch (err) {
+        logger.error("ERROR handling event", {
+          type: e.type,
+          runId: e.runId,
+          flowName: e.flowName,
+          error: err?.message,
+          stack: err?.stack
+        });
+      }
+    };
+    const eventTypes = [
+      "flow.start",
+      "flow.completed",
+      "flow.failed",
+      "step.started",
+      "step.completed",
+      "step.failed",
+      "step.retry",
+      "log",
+      "emit",
+      "state"
+    ];
+    for (const type of eventTypes) {
+      unsubs.push(bus.onType(type, handlePersistence));
+    }
+    for (const type of eventTypes) {
+      unsubs.push(bus.onType(type, handleOrchestration));
+    }
+  }
+  function stop() {
+    for (const u of unsubs.splice(0)) {
+      try {
+        u();
+      } catch {
+      }
+    }
+    wired = false;
+    logger.debug("Flow wiring stopped");
+  }
+  return { start, stop };
+}

package/dist/runtime/server/events/wiring/registry.d.ts

@@ -0,0 +1,10 @@
+import type { StreamAdapter } from '../types.js';
+export interface WiringDeps {
+    adapter: StreamAdapter;
+    names?: any;
+}
+export interface Wiring {
+    start(): void;
+    stop(): void;
+}
+export declare function createWiringRegistry(deps: WiringDeps): Wiring;

package/dist/runtime/server/events/wiring/registry.js

@@ -0,0 +1,24 @@
+import { createFlowWiring } from "./flowWiring.js";
+export function createWiringRegistry(deps) {
+  const wirings = [
+    createFlowWiring({ adapter: deps.adapter })
+    // add future wirings here (triggers, webhooks, etc.)
+  ];
+  let started = false;
+  return {
+    start() {
+      if (started) return;
+      started = true;
+      for (const w of wirings) w.start();
+    },
+    stop() {
+      for (const w of wirings) {
+        try {
+          w.stop();
+        } catch {
+        }
+      }
+      started = false;
+    }
+  };
+}

package/dist/runtime/server/plugins/00.event-store.d.ts

@@ -0,0 +1,13 @@
+/**
+ * Flow Run Snapshots (stream-based)
+ *
+ * Writes append-only snapshot events to nq:proj:flow:<flowName>:<runId>
+ * for key lifecycle kinds:
+ *  - flow.start -> status=running
+ *  - flow.complete -> status=completed
+ *  - runner.log (with correlationId) -> logsCount++ (as a patch)
+ *
+ * Consumers reduce the small snapshot stream to a final object.
+ */
+declare const _default: any;
+export default _default;

package/dist/runtime/server/plugins/00.event-store.js

@@ -0,0 +1,16 @@
+import { defineNitroPlugin } from "#imports";
+import { getEventStoreFactory } from "../events/eventStoreFactory.js";
+export default defineNitroPlugin(() => {
+  const factory = getEventStoreFactory();
+  factory.start();
+  return {
+    hooks: {
+      close: async () => {
+        try {
+          factory.stop();
+        } catch {
+        }
+      }
+    }
+  };
+});

package/dist/runtime/server/plugins/00.ws-lifecycle.d.ts

@@ -0,0 +1,5 @@
+/**
+ * Nitro plugin to handle graceful WebSocket shutdown during HMR
+ */
+declare const _default: any;
+export default _default;