@flowdrop/flowdrop 1.0.0

package/dist/services/interruptService.js

@@ -0,0 +1,280 @@
+/**
+ * Interrupt Service
+ *
+ * Handles API interactions for Human-in-the-Loop (HITL) interrupts,
+ * including fetching interrupt details, resolving interrupts with user
+ * responses, and optional dedicated polling for interrupt status.
+ *
+ * @module services/interruptService
+ */
+import { defaultInterruptPollingConfig } from '../types/interrupt.js';
+import { buildEndpointUrl, getEndpointHeaders } from '../config/endpoints.js';
+import { getEndpointConfig } from './api.js';
+import { logger } from '../utils/logger.js';
+/**
+ * Interrupt Service class
+ *
+ * Provides methods to interact with interrupt API endpoints including
+ * fetching, resolving, cancelling, and listing interrupts.
+ * Supports optional dedicated polling for interrupt status.
+ */
+export class InterruptService {
+    static instance;
+    pollingInterval = null;
+    pollingSessionId = null;
+    currentBackoff;
+    pollingConfig;
+    /**
+     * Private constructor for singleton pattern
+     */
+    constructor() {
+        this.pollingConfig = { ...defaultInterruptPollingConfig };
+        this.currentBackoff = this.pollingConfig.interval ?? defaultInterruptPollingConfig.interval;
+    }
+    /**
+     * Get the singleton instance of InterruptService
+     *
+     * @returns The InterruptService singleton instance
+     */
+    static getInstance() {
+        if (!InterruptService.instance) {
+            InterruptService.instance = new InterruptService();
+        }
+        return InterruptService.instance;
+    }
+    /**
+     * Configure interrupt polling settings
+     *
+     * @param config - Polling configuration options
+     */
+    setPollingConfig(config) {
+        this.pollingConfig = { ...this.pollingConfig, ...config };
+        this.currentBackoff = this.pollingConfig.interval ?? defaultInterruptPollingConfig.interval;
+    }
+    /**
+     * Get the current polling configuration
+     *
+     * @returns Current polling configuration
+     */
+    getPollingConfig() {
+        return { ...this.pollingConfig };
+    }
+    /**
+     * Check if interrupt endpoints are configured
+     *
+     * @returns True if interrupt endpoints are available
+     */
+    isConfigured() {
+        const config = getEndpointConfig();
+        return Boolean(config?.endpoints?.interrupts);
+    }
+    /**
+     * Get the endpoint configuration
+     *
+     * @throws Error if endpoint configuration is not set
+     * @returns The endpoint configuration
+     */
+    getConfig() {
+        const config = getEndpointConfig();
+        if (!config) {
+            throw new Error('Endpoint configuration not set. Call setEndpointConfig() first.');
+        }
+        if (!config.endpoints.interrupts) {
+            throw new Error('Interrupt endpoints not configured.');
+        }
+        return config;
+    }
+    /**
+     * Generic API request helper
+     *
+     * @param url - The URL to fetch
+     * @param options - Fetch options
+     * @returns The parsed JSON response
+     */
+    async request(url, options = {}) {
+        const config = this.getConfig();
+        const headers = getEndpointHeaders(config, 'interrupts');
+        const response = await fetch(url, {
+            ...options,
+            headers: {
+                ...headers,
+                ...options.headers
+            }
+        });
+        if (!response.ok) {
+            const errorData = await response.json().catch(() => ({}));
+            const errorMessage = errorData.error ||
+                errorData.message ||
+                `HTTP ${response.status}: ${response.statusText}`;
+            throw new Error(errorMessage);
+        }
+        return response.json();
+    }
+    // =========================================================================
+    // Interrupt Operations
+    // =========================================================================
+    /**
+     * Get interrupt details by ID
+     *
+     * @param interruptId - The interrupt UUID
+     * @returns The interrupt details
+     */
+    async getInterrupt(interruptId) {
+        const config = this.getConfig();
+        const url = buildEndpointUrl(config, config.endpoints.interrupts.get, {
+            interruptId
+        });
+        const response = await this.request(url);
+        if (!response.data) {
+            throw new Error('Interrupt not found');
+        }
+        return response.data;
+    }
+    /**
+     * Resolve an interrupt with user response
+     *
+     * @param interruptId - The interrupt UUID
+     * @param value - The user's response value
+     * @returns The updated interrupt
+     */
+    async resolveInterrupt(interruptId, value) {
+        const config = this.getConfig();
+        const url = buildEndpointUrl(config, config.endpoints.interrupts.resolve, {
+            interruptId
+        });
+        const resolution = { value };
+        const response = await this.request(url, {
+            method: 'POST',
+            body: JSON.stringify(resolution)
+        });
+        if (!response.data) {
+            throw new Error('Failed to resolve interrupt: No data returned');
+        }
+        return response.data;
+    }
+    /**
+     * Cancel a pending interrupt
+     *
+     * @param interruptId - The interrupt UUID
+     * @returns The updated interrupt
+     */
+    async cancelInterrupt(interruptId) {
+        const config = this.getConfig();
+        const url = buildEndpointUrl(config, config.endpoints.interrupts.cancel, {
+            interruptId
+        });
+        const response = await this.request(url, {
+            method: 'POST'
+        });
+        if (!response.data) {
+            throw new Error('Failed to cancel interrupt: No data returned');
+        }
+        return response.data;
+    }
+    /**
+     * List interrupts for a playground session
+     *
+     * @param sessionId - The session UUID
+     * @returns Array of interrupts for the session
+     */
+    async listSessionInterrupts(sessionId) {
+        const config = this.getConfig();
+        const url = buildEndpointUrl(config, config.endpoints.interrupts.listBySession, {
+            sessionId
+        });
+        const response = await this.request(url);
+        return response.data ?? [];
+    }
+    /**
+     * List interrupts for a pipeline
+     *
+     * @param pipelineId - The pipeline UUID
+     * @returns Array of interrupts for the pipeline
+     */
+    async listPipelineInterrupts(pipelineId) {
+        const config = this.getConfig();
+        const url = buildEndpointUrl(config, config.endpoints.interrupts.listByPipeline, {
+            pipelineId
+        });
+        const response = await this.request(url);
+        return response.data ?? [];
+    }
+    // =========================================================================
+    // Polling (Optional)
+    // =========================================================================
+    /**
+     * Start polling for interrupts in a session
+     *
+     * This is optional - interrupts are typically detected via message metadata.
+     * Use this for scenarios where dedicated polling is preferred.
+     *
+     * @param sessionId - The session UUID to poll
+     * @param callback - Callback function to handle new interrupts
+     */
+    startPolling(sessionId, callback) {
+        if (!this.pollingConfig.enabled) {
+            logger.warn('[InterruptService] Polling is disabled. Enable via setPollingConfig().');
+            return;
+        }
+        // Stop any existing polling
+        this.stopPolling();
+        this.pollingSessionId = sessionId;
+        this.currentBackoff = this.pollingConfig.interval ?? defaultInterruptPollingConfig.interval;
+        const poll = async () => {
+            if (this.pollingSessionId !== sessionId) {
+                return;
+            }
+            try {
+                const interrupts = await this.listSessionInterrupts(sessionId);
+                const pendingInterrupts = interrupts.filter((i) => i.status === 'pending');
+                // Reset backoff on successful request
+                this.currentBackoff = this.pollingConfig.interval ?? defaultInterruptPollingConfig.interval;
+                // Call the callback with pending interrupts
+                callback(pendingInterrupts);
+            }
+            catch (error) {
+                logger.error('[InterruptService] Polling error:', error);
+                // Exponential backoff on error
+                const maxBackoff = this.pollingConfig.maxBackoff ?? defaultInterruptPollingConfig.maxBackoff;
+                this.currentBackoff = Math.min(this.currentBackoff * 2, maxBackoff);
+            }
+            // Schedule next poll
+            if (this.pollingSessionId === sessionId) {
+                this.pollingInterval = setTimeout(poll, this.currentBackoff);
+            }
+        };
+        // Start polling immediately
+        void poll();
+    }
+    /**
+     * Stop polling for interrupts
+     */
+    stopPolling() {
+        if (this.pollingInterval) {
+            clearTimeout(this.pollingInterval);
+            this.pollingInterval = null;
+        }
+        this.pollingSessionId = null;
+        this.currentBackoff = this.pollingConfig.interval ?? defaultInterruptPollingConfig.interval;
+    }
+    /**
+     * Check if polling is active
+     *
+     * @returns True if polling is active
+     */
+    isPolling() {
+        return this.pollingSessionId !== null;
+    }
+    /**
+     * Get the current polling session ID
+     *
+     * @returns The session ID being polled, or null
+     */
+    getPollingSessionId() {
+        return this.pollingSessionId;
+    }
+}
+/**
+ * Export singleton instance
+ */
+export const interruptService = InterruptService.getInstance();

package/dist/services/nodeExecutionService.d.ts

@@ -0,0 +1,63 @@
+/**
+ * Node Execution Service
+ * Handles fetching and managing node execution information from the backend
+ */
+import type { NodeExecutionInfo } from '../types/index.js';
+/**
+ * Service for managing node execution information
+ */
+export declare class NodeExecutionService {
+    private static instance;
+    private cache;
+    private cacheTimeout;
+    private lastFetch;
+    private apiUnavailable;
+    private apiUnavailableUntil;
+    private constructor();
+    static getInstance(): NodeExecutionService;
+    /**
+     * Get execution information for a specific node from pipeline data
+     */
+    getNodeExecutionInfo(nodeId: string, pipelineId?: string): Promise<NodeExecutionInfo | null>;
+    /**
+     * Get execution information for multiple nodes from pipeline data
+     */
+    getMultipleNodeExecutionInfo(nodeIds: string[], pipelineId?: string): Promise<Record<string, NodeExecutionInfo>>;
+    /**
+     * Get all node execution counts
+     */
+    getAllNodeExecutionCounts(): Promise<Record<string, number>>;
+    /**
+     * Get cached execution info for a node
+     */
+    getCachedNodeExecutionInfo(nodeId: string): NodeExecutionInfo | null;
+    /**
+     * Clear cache for a specific node
+     */
+    clearNodeCache(nodeId: string): void;
+    /**
+     * Clear all cache
+     */
+    clearAllCache(): void;
+    /**
+     * Check if cache is stale
+     */
+    isCacheStale(): boolean;
+    /**
+     * Update execution info for a node (for real-time updates)
+     */
+    updateNodeExecutionInfo(nodeId: string, executionInfo: Partial<NodeExecutionInfo>): void;
+    /**
+     * Map job status to execution status
+     */
+    private mapJobStatusToExecutionStatus;
+    /**
+     * Batch update execution info for multiple nodes
+     */
+    updateMultipleNodeExecutionInfo(updates: Record<string, Partial<NodeExecutionInfo>>): void;
+    /**
+     * Reset API availability status (useful for testing or when API becomes available)
+     */
+    resetApiAvailability(): void;
+}
+export declare const nodeExecutionService: NodeExecutionService;

package/dist/services/nodeExecutionService.js

@@ -0,0 +1,266 @@
+/**
+ * Node Execution Service
+ * Handles fetching and managing node execution information from the backend
+ */
+import { getEndpointConfig } from './api.js';
+import { buildEndpointUrl } from '../config/endpoints.js';
+import { NODE_EXECUTION_CACHE_TIMEOUT_MS, PIPELINE_API_UNAVAILABLE_DURATION_MS } from '../config/constants.js';
+import { logger } from '../utils/logger.js';
+/**
+ * Service for managing node execution information
+ */
+export class NodeExecutionService {
+    static instance;
+    cache = new Map();
+    cacheTimeout = NODE_EXECUTION_CACHE_TIMEOUT_MS;
+    lastFetch = 0;
+    apiUnavailable = false;
+    apiUnavailableUntil = 0;
+    constructor() { }
+    static getInstance() {
+        if (!NodeExecutionService.instance) {
+            NodeExecutionService.instance = new NodeExecutionService();
+        }
+        return NodeExecutionService.instance;
+    }
+    /**
+     * Get execution information for a specific node from pipeline data
+     */
+    async getNodeExecutionInfo(nodeId, pipelineId) {
+        if (!pipelineId) {
+            return null;
+        }
+        try {
+            const endpointConfig = getEndpointConfig();
+            if (!endpointConfig)
+                throw new Error('Endpoint config not available');
+            const url = buildEndpointUrl(endpointConfig, endpointConfig.endpoints.pipelines.get, {
+                id: pipelineId
+            });
+            const response = await fetch(url);
+            if (!response.ok) {
+                throw new Error(`HTTP error! status: ${response.status}`);
+            }
+            const pipelineData = await response.json();
+            const jobs = pipelineData.jobs || [];
+            const nodeStatuses = pipelineData.node_statuses || {};
+            // Find the job for this node
+            const nodeJob = jobs.find((job) => job.node_id === nodeId);
+            const nodeStatus = nodeStatuses[nodeId];
+            if (!nodeJob && !nodeStatus) {
+                return {
+                    status: 'idle',
+                    executionCount: 0,
+                    isExecuting: false
+                };
+            }
+            const executionInfo = {
+                status: this.mapJobStatusToExecutionStatus(nodeStatus?.status || nodeJob?.status || 'idle'),
+                executionCount: nodeJob?.execution_count || 0,
+                isExecuting: nodeStatus?.status === 'running' || nodeJob?.status === 'running',
+                lastExecuted: nodeJob?.last_executed || nodeStatus?.last_executed,
+                lastExecutionDuration: nodeJob?.execution_time || nodeStatus?.execution_time,
+                lastError: nodeJob?.error || nodeStatus?.error
+            };
+            this.cache.set(nodeId, executionInfo);
+            return executionInfo;
+        }
+        catch (error) {
+            logger.error('Failed to fetch node execution info:', error);
+            return null;
+        }
+    }
+    /**
+     * Get execution information for multiple nodes from pipeline data
+     */
+    async getMultipleNodeExecutionInfo(nodeIds, pipelineId) {
+        if (!pipelineId) {
+            return {};
+        }
+        // Check if API is temporarily unavailable
+        if (this.apiUnavailable && Date.now() < this.apiUnavailableUntil) {
+            const defaultExecutionInfo = {};
+            nodeIds.forEach((nodeId) => {
+                defaultExecutionInfo[nodeId] = {
+                    status: 'idle',
+                    executionCount: 0,
+                    isExecuting: false
+                };
+            });
+            return defaultExecutionInfo;
+        }
+        try {
+            const endpointConfig = getEndpointConfig();
+            if (!endpointConfig)
+                throw new Error('Endpoint config not available');
+            const url = buildEndpointUrl(endpointConfig, endpointConfig.endpoints.pipelines.get, {
+                id: pipelineId
+            });
+            const response = await fetch(url);
+            if (!response.ok) {
+                // If the endpoint returns 404, it means the pipeline API is not available
+                // Mark API as unavailable for 5 minutes to prevent repeated calls
+                if (response.status === 404) {
+                    logger.warn(`Pipeline API endpoint not available for pipeline ${pipelineId}`);
+                    this.apiUnavailable = true;
+                    this.apiUnavailableUntil = Date.now() + PIPELINE_API_UNAVAILABLE_DURATION_MS;
+                    const defaultExecutionInfo = {};
+                    nodeIds.forEach((nodeId) => {
+                        defaultExecutionInfo[nodeId] = {
+                            status: 'idle',
+                            executionCount: 0,
+                            isExecuting: false
+                        };
+                    });
+                    return defaultExecutionInfo;
+                }
+                throw new Error(`HTTP error! status: ${response.status}`);
+            }
+            const result = await response.json();
+            const jobs = result.jobs || [];
+            const executionInfoMap = {};
+            // Initialize all nodes with default values
+            nodeIds.forEach((nodeId) => {
+                executionInfoMap[nodeId] = {
+                    status: 'idle',
+                    executionCount: 0,
+                    isExecuting: false
+                };
+            });
+            // Update with actual job data
+            jobs.forEach((job) => {
+                const nodeId = job.node_id;
+                if (nodeIds.includes(nodeId)) {
+                    executionInfoMap[nodeId] = {
+                        status: this.mapJobStatusToExecutionStatus(job.status),
+                        executionCount: job.execution_count || 0,
+                        isExecuting: job.status === 'running',
+                        lastExecuted: job.completed || job.started,
+                        lastExecutionDuration: job.execution_time,
+                        lastError: job.error_message
+                    };
+                    // Update cache
+                    this.cache.set(nodeId, executionInfoMap[nodeId]);
+                }
+            });
+            return executionInfoMap;
+        }
+        catch (error) {
+            logger.error('Failed to fetch multiple node execution info:', error);
+            // Return default values instead of empty object to prevent repeated calls
+            const defaultExecutionInfo = {};
+            nodeIds.forEach((nodeId) => {
+                defaultExecutionInfo[nodeId] = {
+                    status: 'idle',
+                    executionCount: 0,
+                    isExecuting: false
+                };
+            });
+            return defaultExecutionInfo;
+        }
+    }
+    /**
+     * Get all node execution counts
+     */
+    async getAllNodeExecutionCounts() {
+        try {
+            const endpointConfig = getEndpointConfig();
+            if (!endpointConfig)
+                throw new Error('Endpoint config not available');
+            const url = buildEndpointUrl(endpointConfig, '/node-execution-counts');
+            const response = await fetch(url);
+            if (!response.ok) {
+                throw new Error(`HTTP error! status: ${response.status}`);
+            }
+            const result = await response.json();
+            if (result.success && result.data) {
+                return result.data;
+            }
+            return {};
+        }
+        catch (error) {
+            logger.error('Failed to fetch all node execution counts:', error);
+            return {};
+        }
+    }
+    /**
+     * Get cached execution info for a node
+     */
+    getCachedNodeExecutionInfo(nodeId) {
+        return this.cache.get(nodeId) || null;
+    }
+    /**
+     * Clear cache for a specific node
+     */
+    clearNodeCache(nodeId) {
+        this.cache.delete(nodeId);
+    }
+    /**
+     * Clear all cache
+     */
+    clearAllCache() {
+        this.cache.clear();
+        this.lastFetch = 0;
+    }
+    /**
+     * Check if cache is stale
+     */
+    isCacheStale() {
+        return Date.now() - this.lastFetch > this.cacheTimeout;
+    }
+    /**
+     * Update execution info for a node (for real-time updates)
+     */
+    updateNodeExecutionInfo(nodeId, executionInfo) {
+        const existing = this.cache.get(nodeId);
+        if (existing) {
+            this.cache.set(nodeId, { ...existing, ...executionInfo });
+        }
+        else {
+            this.cache.set(nodeId, {
+                status: 'idle',
+                executionCount: 0,
+                isExecuting: false,
+                ...executionInfo
+            });
+        }
+    }
+    /**
+     * Map job status to execution status
+     */
+    mapJobStatusToExecutionStatus(jobStatus) {
+        switch (jobStatus) {
+            case 'pending':
+                return 'pending';
+            case 'running':
+                return 'running';
+            case 'completed':
+                return 'completed';
+            case 'failed':
+                return 'failed';
+            case 'cancelled':
+                return 'cancelled';
+            case 'skipped':
+                return 'skipped';
+            default:
+                return 'idle';
+        }
+    }
+    /**
+     * Batch update execution info for multiple nodes
+     */
+    updateMultipleNodeExecutionInfo(updates) {
+        Object.entries(updates).forEach(([nodeId, executionInfo]) => {
+            this.updateNodeExecutionInfo(nodeId, executionInfo);
+        });
+    }
+    /**
+     * Reset API availability status (useful for testing or when API becomes available)
+     */
+    resetApiAvailability() {
+        this.apiUnavailable = false;
+        this.apiUnavailableUntil = 0;
+    }
+}
+// Export singleton instance
+export const nodeExecutionService = NodeExecutionService.getInstance();