nvent 0.4.4 → 0.5.0

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

@@ -0,0 +1,320 @@
+import { useStoreAdapter, useNventLogger, useStreamTopics } from "#imports";
+import { getEventBus } from "../../events/eventBus.js";
+import { getTriggerRuntime } from "../../events/utils/triggerRuntime.js";
+export async function resolvePayload(data) {
+  const logger = useNventLogger("trigger");
+  const store = useStoreAdapter();
+  const runtime = getTriggerRuntime(store, logger);
+  return runtime.resolvePayload(data);
+}
+export function useTrigger() {
+  const logger = useNventLogger("trigger");
+  const store = useStoreAdapter();
+  const runtime = getTriggerRuntime(store, logger);
+  return {
+    /**
+     * Register a trigger (programmatic)
+     * Publishes event to bus - triggerWiring handles persistence and orchestration
+     */
+    async registerTrigger(opts) {
+      const eventBus = getEventBus();
+      const existing = runtime.getTrigger(opts.name);
+      const isUpdate = !!existing;
+      if (isUpdate) {
+        logger.info(`Updating trigger: ${opts.name}`);
+        await eventBus.publish({
+          type: "trigger.updated",
+          triggerName: opts.name,
+          data: {
+            type: opts.type,
+            scope: opts.scope,
+            status: opts.status,
+            displayName: opts.displayName,
+            description: opts.description,
+            source: opts.source || "programmatic",
+            webhook: opts.webhook,
+            schedule: opts.schedule,
+            config: opts.config,
+            expectedSubscribers: opts.expectedSubscribers
+          }
+        });
+      } else {
+        logger.info(`Registering trigger: ${opts.name}`);
+        await eventBus.publish({
+          type: "trigger.registered",
+          triggerName: opts.name,
+          data: {
+            name: opts.name,
+            type: opts.type,
+            scope: opts.scope,
+            displayName: opts.displayName,
+            description: opts.description,
+            source: opts.source || "programmatic",
+            expectedSubscribers: opts.expectedSubscribers,
+            webhook: opts.webhook,
+            schedule: opts.schedule,
+            config: opts.config
+          }
+        });
+      }
+    },
+    /**
+     * Subscribe flow to trigger (programmatic)
+     * Publishes event to bus - triggerWiring handles persistence and orchestration
+     */
+    async subscribeTrigger(opts) {
+      const eventBus = getEventBus();
+      const { trigger, flow, mode = "auto" } = opts;
+      const existingSub = runtime.getSubscription(trigger, flow);
+      const isUpdate = !!existingSub;
+      logger.info(`${isUpdate ? "Updating" : "Subscribing"} flow '${flow}' to trigger '${trigger}' (${mode})`);
+      await eventBus.publish({
+        type: "subscription.added",
+        triggerName: trigger,
+        data: {
+          trigger,
+          flow,
+          mode,
+          isUpdate
+        }
+      });
+    },
+    /**
+     * Unsubscribe flow from trigger
+     * Publishes event to bus - triggerWiring handles persistence and orchestration
+     */
+    async unsubscribeTrigger(trigger, flow) {
+      const eventBus = getEventBus();
+      logger.info(`Unsubscribing flow '${flow}' from trigger '${trigger}'`);
+      await eventBus.publish({
+        type: "subscription.removed",
+        triggerName: trigger,
+        data: {
+          trigger,
+          flow
+        }
+      });
+    },
+    /**
+     * Emit trigger (fire event)
+     * Publishes event to bus - triggerWiring handles persistence, stats, and orchestration
+     *
+     * Large payloads are automatically stored in KV store and replaced with references
+     * to keep stream events small and memory-efficient.
+     */
+    async emitTrigger(name, data, opts) {
+      const eventBus = getEventBus();
+      const trigger = runtime.getTrigger(name);
+      if (!trigger) {
+        logger.warn(
+          `Emitting unregistered trigger '${name}'. Consider registering it first with registerTrigger().`
+        );
+      }
+      const threshold = opts?.payloadThreshold || trigger?.config?.payloadThreshold || 10 * 1024;
+      const eventData = await runtime.handleLargePayload(name, data, threshold);
+      logger.debug(`Emitting trigger: ${name}`, {
+        hasReference: !!eventData.__payloadRef,
+        size: eventData.__size
+      });
+      await eventBus.publish({
+        type: "trigger.fired",
+        triggerName: name,
+        data: eventData
+      });
+    },
+    /**
+     * Query methods
+     */
+    /**
+     * Check if a trigger exists in the registry
+     */
+    hasTrigger(name) {
+      return runtime.hasTrigger(name);
+    },
+    /**
+     * Get trigger entry by name
+     */
+    getTrigger(name) {
+      return runtime.getTrigger(name);
+    },
+    /**
+     * Get all registered triggers
+     * @param options - Sorting and pagination options
+     * @param options.sortBy - Field to sort by
+     * @param options.order - Sort order (asc or desc)
+     * @param options.limit - Maximum number of results
+     * @param options.offset - Number of results to skip
+     */
+    getAllTriggers(options) {
+      return runtime.getAllTriggers(options);
+    },
+    /**
+     * Get all flows subscribed to a specific trigger
+     */
+    getSubscribedFlows(trigger) {
+      return runtime.getSubscribedFlows(trigger);
+    },
+    /**
+     * Get all triggers that a flow is subscribed to
+     */
+    getFlowTriggers(flow) {
+      return runtime.getFlowTriggers(flow);
+    },
+    /**
+     * Get subscription details for a specific trigger-flow pair
+     */
+    getSubscription(trigger, flow) {
+      return runtime.getSubscription(trigger, flow);
+    },
+    getAllSubscriptions() {
+      return runtime.getAllSubscriptions();
+    },
+    /**
+     * Initialize runtime from store (called on startup)
+     * Uses index + stream architecture (v0.5.1)
+     */
+    async initialize() {
+      if (runtime.initialized) return;
+      const { StoreSubjects } = useStreamTopics();
+      const indexKey = StoreSubjects.triggerIndex();
+      logger.info("Initializing trigger runtime from index...");
+      if (store.index.read) {
+        const entries = await store.index.read(indexKey, { limit: 1e3 });
+        let activeCount = 0;
+        let totalSubscriptions = 0;
+        for (const entry of entries) {
+          const metadata = entry.metadata;
+          const triggerEntry = {
+            name: metadata.name,
+            type: metadata.type,
+            scope: metadata.scope,
+            status: metadata.status || "active",
+            displayName: metadata.displayName,
+            description: metadata.description,
+            source: metadata.source,
+            registeredAt: metadata.registeredAt,
+            registeredBy: metadata.registeredBy,
+            lastActivityAt: metadata.lastActivityAt,
+            subscriptions: metadata.subscriptions || {},
+            stats: metadata.stats || { totalFires: 0, activeSubscribers: 0 },
+            webhook: metadata.webhook,
+            schedule: metadata.schedule,
+            config: metadata.config,
+            version: metadata.version || 1
+          };
+          runtime.addTrigger(entry.id, triggerEntry);
+          if (metadata.status === "active") {
+            activeCount++;
+          }
+          if (metadata.subscriptions) {
+            for (const [flowName, subData] of Object.entries(metadata.subscriptions)) {
+              const subscription = {
+                triggerName: entry.id,
+                flowName,
+                mode: subData.mode || "auto",
+                source: "programmatic",
+                registeredAt: subData.subscribedAt
+              };
+              runtime.addSubscription(entry.id, flowName, subscription);
+              totalSubscriptions++;
+            }
+          }
+        }
+        logger.info(
+          `Loaded ${activeCount} active triggers with ${totalSubscriptions} subscriptions from index`
+        );
+      } else {
+        logger.warn("Store does not support indexRead, falling back to doc-based loading");
+        if (store.list) {
+          const triggers = await store.list("triggers");
+          for (const { id, doc } of triggers) {
+            runtime.addTrigger(id, doc);
+          }
+          const subscriptions = await store.list("trigger-subscriptions");
+          for (const { doc } of subscriptions) {
+            const sub = doc;
+            runtime.addSubscription(sub.triggerName, sub.flowName, sub);
+          }
+          logger.info(
+            `Loaded ${triggers.length} triggers and ${subscriptions.length} subscriptions from doc store (legacy)`
+          );
+        }
+      }
+      runtime.setInitialized(true);
+    },
+    /**
+     * Get runtime state (for debugging)
+     */
+    getRuntime() {
+      return runtime.getRuntimeStats();
+    },
+    /**
+     * Delete a trigger completely (removes all data)
+     * Publishes event to bus - triggerWiring handles persistence and orchestration
+     */
+    async deleteTrigger(name) {
+      const eventBus = getEventBus();
+      const trigger = runtime.getTrigger(name);
+      if (!trigger) {
+        logger.warn(`Cannot delete non-existent trigger: ${name}`);
+        return;
+      }
+      logger.info(`Deleting trigger: ${name}`);
+      await eventBus.publish({
+        type: "trigger.deleted",
+        triggerName: name,
+        data: {}
+      });
+    },
+    /**
+     * Update trigger status (active/inactive/retired)
+     * For future status management UI
+     */
+    async updateTriggerStatus(name, status) {
+      const eventBus = getEventBus();
+      const trigger = runtime.getTrigger(name);
+      if (!trigger) {
+        logger.warn(`Cannot update status of non-existent trigger: ${name}`);
+        return;
+      }
+      logger.info(`Updating trigger ${name} status to: ${status}`);
+      await eventBus.publish({
+        type: "trigger.updated",
+        triggerName: name,
+        data: {
+          ...trigger,
+          status
+        }
+      });
+    },
+    /**
+     * Get trigger statistics
+     * v0.5.1: New analytics method
+     */
+    async getTriggerStats(name) {
+      const { StoreSubjects } = useStreamTopics();
+      const indexKey = StoreSubjects.triggerIndex();
+      if (!store.index.get) {
+        const trigger = runtime.getTrigger(name);
+        return trigger?.stats;
+      }
+      const entry = await store.index.get(indexKey, name);
+      if (!entry?.metadata) return null;
+      return entry.metadata.stats;
+    },
+    /**
+     * Get trigger history from stream
+     * v0.5.1: New analytics method
+     */
+    async getTriggerHistory(name, opts) {
+      const { StoreSubjects } = useStreamTopics();
+      const streamName = StoreSubjects.triggerStream(name);
+      const events = await store.stream.read(streamName, {
+        limit: opts?.limit || 100,
+        types: opts?.types,
+        order: "desc"
+      });
+      return events;
+    }
+  };
+}

package/dist/runtime/scheduler/index.d.ts

@@ -0,0 +1,33 @@
+/**
+ * Scheduler Factory and Composable
+ *
+ * Provides a unified scheduler interface for the entire application.
+ * Uses Scheduler with store adapter (supports both distributed and single-instance modes).
+ */
+import type { SchedulerAdapter } from './types.js';
+/**
+ * Create a scheduler instance
+ * Uses Scheduler which adapts based on store capabilities:
+ * - With indexAdd/indexGet: Full distributed locking
+ * - Without: Degrades gracefully to KV-based locking (single instance)
+ */
+export declare function createScheduler(store: any): SchedulerAdapter;
+/**
+ * Get the global scheduler instance
+ * Must be initialized first with initializeScheduler()
+ */
+export declare function useScheduler(): SchedulerAdapter;
+/**
+ * Initialize the scheduler
+ * Should be called once during app startup
+ */
+export declare function initializeScheduler(store: any): Promise<SchedulerAdapter>;
+/**
+ * Shutdown the scheduler
+ * Should be called during app shutdown
+ */
+export declare function shutdownScheduler(): Promise<void>;
+/**
+ * Reset the scheduler instance (for testing)
+ */
+export declare function resetScheduler(): void;

package/dist/runtime/scheduler/index.js

@@ -0,0 +1,38 @@
+import { Scheduler } from "./scheduler.js";
+import { useRuntimeConfig } from "#imports";
+let schedulerInstance = null;
+export function createScheduler(store) {
+  const config = useRuntimeConfig();
+  const prefix = config.nvent.store?.prefix || "nvent";
+  const useIndexLocking = !!(store.indexAdd && store.index.get);
+  return new Scheduler({
+    store,
+    keyPrefix: `${prefix}:scheduler`,
+    lockTTL: 3e5,
+    // 5 minutes
+    useIndexLocking
+  });
+}
+export function useScheduler() {
+  if (!schedulerInstance) {
+    throw new Error("Scheduler not initialized. Call initializeScheduler() first.");
+  }
+  return schedulerInstance;
+}
+export async function initializeScheduler(store) {
+  if (schedulerInstance) {
+    return schedulerInstance;
+  }
+  schedulerInstance = createScheduler(store);
+  await schedulerInstance.start();
+  return schedulerInstance;
+}
+export async function shutdownScheduler() {
+  if (schedulerInstance) {
+    await schedulerInstance.stop();
+    schedulerInstance = null;
+  }
+}
+export function resetScheduler() {
+  schedulerInstance = null;
+}

package/dist/runtime/scheduler/scheduler.d.ts

@@ -0,0 +1,113 @@
+/**
+ * Scheduler
+ *
+ * Store-based scheduler with distributed locking for horizontal scaling.
+ * Ensures only one instance executes each scheduled job.
+ */
+import type { ScheduledJob, SchedulerAdapter } from './types.js';
+import type { StoreAdapter } from '../adapters/interfaces/store.js';
+export interface SchedulerOptions {
+    /**
+     * Store adapter for locking (Redis recommended)
+     */
+    store: StoreAdapter;
+    /**
+     * Key prefix for locks and job data
+     * Uses configured store prefix + ':scheduler'
+     * @default '{prefix}:scheduler' (e.g., 'nvent:scheduler')
+     */
+    keyPrefix?: string;
+    /**
+     * Lock TTL in milliseconds
+     * @default 300000 (5 minutes)
+     */
+    lockTTL?: number;
+    /**
+     * Unique instance identifier
+     * @default Auto-generated
+     */
+    instanceId?: string;
+    /**
+     * Use store indexes for locking (more robust) vs simple KV
+     * @default true
+     */
+    useIndexLocking?: boolean;
+}
+export declare class Scheduler implements SchedulerAdapter {
+    private store;
+    private keyPrefix;
+    private lockTTL;
+    private instanceId;
+    private useIndexLocking;
+    private jobs;
+    private jobConfigs;
+    private lockRenewalTimers;
+    private started;
+    private logger;
+    constructor(options: SchedulerOptions);
+    schedule(job: ScheduledJob): Promise<string>;
+    /**
+     * Execute job with distributed lock
+     * Prevents multiple instances from running the same job
+     */
+    private executeWithLock;
+    private executeJob;
+    /**
+     * Acquire distributed lock using store adapter
+     */
+    private acquireLock;
+    /**
+     * Release distributed lock
+     */
+    private releaseLock;
+    /**
+     * Start periodic lock renewal (for long-running jobs)
+     */
+    private startLockRenewal;
+    /**
+     * Stop lock renewal
+     */
+    private stopLockRenewal;
+    /**
+     * Persist job configuration
+     */
+    private persistJob;
+    /**
+     * Update job statistics
+     */
+    private updateJobStats;
+    unschedule(jobId: string): Promise<boolean>;
+    /**
+     * Recover jobs from store on startup
+     * Critical for:
+     * - Restarts: Re-create in-memory schedulers
+     * - Horizontal scaling: New instances pick up existing jobs
+     * - Orphaned awaits: Resume flows waiting on schedules
+     */
+    private recoverJobs;
+    /**
+     * Recover a single job from persisted data
+     *
+     * IMPORTANT: This method reconstructs in-memory schedulers (CronJob/setInterval)
+     * WITHOUT calling schedule() to avoid re-persisting handler functions (which
+     * cannot be serialized). Handlers are reconstructed from metadata where possible.
+     */
+    private recoverJob;
+    /**
+     * Recover well-known job patterns when index scan is not available
+     * This includes:
+     * - stall-detection (always exists)
+     * - await-time-* (flows waiting on time delays)
+     * - await-schedule-* (flows waiting on cron schedules)
+     */
+    private recoverWellKnownJobs;
+    start(): Promise<void>;
+    stop(): Promise<void>;
+    getScheduledJobs(): Promise<ScheduledJob[]>;
+    /**
+     * Get all persisted jobs from store (for debugging/monitoring)
+     * This shows ALL jobs across ALL instances with their runtime stats
+     */
+    getAllPersistedJobs(): Promise<ScheduledJob[]>;
+    isHealthy(): Promise<boolean>;
+}