reqon-dsl 0.2.0 → 0.4.0

package/dist/interpreter/source-manager.d.ts

@@ -0,0 +1,75 @@
+/**
+ * SourceManager handles HTTP source initialization and configuration.
+ *
+ * Extracted from MissionExecutor to improve separation of concerns.
+ * Responsible for:
+ * - Creating HTTP clients for sources
+ * - Configuring authentication providers
+ * - Loading and caching OAS specs
+ * - Configuring rate limiters and circuit breakers per source
+ */
+import type { SourceDefinition } from '../ast/nodes.js';
+import type { ExecutionContext } from './context.js';
+import { type OASSource } from '../oas/index.js';
+import type { RateLimiter } from '../auth/types.js';
+import type { CircuitBreaker } from '../auth/circuit-breaker.js';
+export interface AuthConfig {
+    type: 'bearer' | 'oauth2' | 'none';
+    token?: string;
+    accessToken?: string;
+    refreshToken?: string;
+    tokenEndpoint?: string;
+    clientId?: string;
+    clientSecret?: string;
+}
+export interface SourceManagerConfig {
+    /** Auth configurations by source name */
+    auth?: Record<string, AuthConfig>;
+    /** Logging function */
+    log?: (message: string) => void;
+    /** Mission file directory for resolving relative paths */
+    missionDir?: string;
+}
+export interface SourceManagerDeps {
+    rateLimiter: RateLimiter;
+    circuitBreaker: CircuitBreaker;
+}
+/**
+ * Manages HTTP source initialization and provides access to source configurations.
+ */
+export declare class SourceManager {
+    private oasSources;
+    private sourceConfigs;
+    private config;
+    private deps;
+    constructor(config: SourceManagerConfig, deps: SourceManagerDeps);
+    /**
+     * Initialize a source definition, creating the HTTP client and configuring resilience.
+     */
+    initializeSource(source: SourceDefinition, ctx: ExecutionContext): Promise<void>;
+    /**
+     * Initialize multiple sources.
+     */
+    initializeSources(sources: SourceDefinition[], ctx: ExecutionContext): Promise<void>;
+    /**
+     * Get the OAS source for a given source name.
+     */
+    getOASSource(sourceName: string): OASSource | undefined;
+    /**
+     * Get the source configuration for a given source name.
+     */
+    getSourceConfig(sourceName: string): SourceDefinition | undefined;
+    /**
+     * Get all OAS sources.
+     */
+    getAllOASSources(): Map<string, OASSource>;
+    /**
+     * Get all source configurations.
+     */
+    getAllSourceConfigs(): Map<string, SourceDefinition>;
+    private createAuthProvider;
+    private resolveBaseUrl;
+    private configureRateLimiter;
+    private configureCircuitBreaker;
+    private log;
+}

package/dist/interpreter/source-manager.js

@@ -0,0 +1,157 @@
+/**
+ * SourceManager handles HTTP source initialization and configuration.
+ *
+ * Extracted from MissionExecutor to improve separation of concerns.
+ * Responsible for:
+ * - Creating HTTP clients for sources
+ * - Configuring authentication providers
+ * - Loading and caching OAS specs
+ * - Configuring rate limiters and circuit breakers per source
+ */
+import { resolve } from 'node:path';
+import { HttpClient, BearerAuthProvider, OAuth2AuthProvider } from './http.js';
+import { loadOAS } from '../oas/index.js';
+/**
+ * Manages HTTP source initialization and provides access to source configurations.
+ */
+export class SourceManager {
+    oasSources = new Map();
+    sourceConfigs = new Map();
+    config;
+    deps;
+    constructor(config, deps) {
+        this.config = config;
+        this.deps = deps;
+    }
+    /**
+     * Initialize a source definition, creating the HTTP client and configuring resilience.
+     */
+    async initializeSource(source, ctx) {
+        // Store source config for later reference
+        this.sourceConfigs.set(source.name, source);
+        const authProvider = this.createAuthProvider(source.name);
+        const baseUrl = await this.resolveBaseUrl(source);
+        this.configureRateLimiter(source);
+        this.configureCircuitBreaker(source);
+        const client = new HttpClient({
+            baseUrl,
+            auth: authProvider,
+            rateLimiter: this.deps.rateLimiter,
+            circuitBreaker: this.deps.circuitBreaker,
+            sourceName: source.name,
+        });
+        ctx.sources.set(source.name, client);
+        this.log(`Initialized source: ${source.name}`);
+    }
+    /**
+     * Initialize multiple sources.
+     */
+    async initializeSources(sources, ctx) {
+        for (const source of sources) {
+            await this.initializeSource(source, ctx);
+        }
+    }
+    /**
+     * Get the OAS source for a given source name.
+     */
+    getOASSource(sourceName) {
+        return this.oasSources.get(sourceName);
+    }
+    /**
+     * Get the source configuration for a given source name.
+     */
+    getSourceConfig(sourceName) {
+        return this.sourceConfigs.get(sourceName);
+    }
+    /**
+     * Get all OAS sources.
+     */
+    getAllOASSources() {
+        return this.oasSources;
+    }
+    /**
+     * Get all source configurations.
+     */
+    getAllSourceConfigs() {
+        return this.sourceConfigs;
+    }
+    createAuthProvider(sourceName) {
+        const authConfig = this.config.auth?.[sourceName];
+        if (!authConfig) {
+            return undefined;
+        }
+        if (authConfig.type === 'bearer' && authConfig.token) {
+            return new BearerAuthProvider(authConfig.token);
+        }
+        if (authConfig.type === 'oauth2' && authConfig.accessToken) {
+            return new OAuth2AuthProvider({
+                accessToken: authConfig.accessToken,
+                refreshToken: authConfig.refreshToken,
+                tokenEndpoint: authConfig.tokenEndpoint,
+                clientId: authConfig.clientId,
+                clientSecret: authConfig.clientSecret,
+            });
+        }
+        return undefined;
+    }
+    async resolveBaseUrl(source) {
+        let baseUrl = source.config.base;
+        // If source has OAS spec, load it
+        if (source.specPath) {
+            try {
+                // Resolve relative spec paths against mission directory
+                const specPath = this.config.missionDir
+                    ? resolve(this.config.missionDir, source.specPath)
+                    : source.specPath;
+                const oasSource = await loadOAS(specPath);
+                this.oasSources.set(source.name, oasSource);
+                // Use base URL from OAS if not explicitly provided
+                if (!baseUrl) {
+                    baseUrl = oasSource.baseUrl;
+                }
+                this.log(`Loaded OAS spec for ${source.name}: ${oasSource.operations.size} operations`);
+            }
+            catch (error) {
+                throw new Error(`Failed to load OAS spec for ${source.name}: ${error.message}`);
+            }
+        }
+        if (!baseUrl) {
+            throw new Error(`Source ${source.name} has no base URL (provide 'base' or OAS spec with servers)`);
+        }
+        return baseUrl;
+    }
+    configureRateLimiter(source) {
+        if (!source.config.rateLimit) {
+            return;
+        }
+        this.deps.rateLimiter.configure(source.name, {
+            strategy: source.config.rateLimit.strategy,
+            maxWait: source.config.rateLimit.maxWait,
+            fallbackRpm: source.config.rateLimit.fallbackRpm,
+        });
+        this.log(`Rate limit config for ${source.name}: strategy=${source.config.rateLimit.strategy ?? 'pause'}, ` +
+            `maxWait=${source.config.rateLimit.maxWait ?? 300}s`);
+    }
+    configureCircuitBreaker(source) {
+        if (!source.config.circuitBreaker) {
+            return;
+        }
+        this.deps.circuitBreaker.configure(source.name, {
+            failureThreshold: source.config.circuitBreaker.failureThreshold,
+            // Convert seconds to milliseconds for the circuit breaker
+            resetTimeout: source.config.circuitBreaker.resetTimeout
+                ? source.config.circuitBreaker.resetTimeout * 1000
+                : undefined,
+            successThreshold: source.config.circuitBreaker.successThreshold,
+            failureWindow: source.config.circuitBreaker.failureWindow
+                ? source.config.circuitBreaker.failureWindow * 1000
+                : undefined,
+        });
+        this.log(`Circuit breaker config for ${source.name}: ` +
+            `failureThreshold=${source.config.circuitBreaker.failureThreshold ?? 5}, ` +
+            `resetTimeout=${source.config.circuitBreaker.resetTimeout ?? 30}s`);
+    }
+    log(message) {
+        this.config.log?.(message);
+    }
+}

package/dist/interpreter/step-handlers/apply-handler.d.ts

@@ -0,0 +1,29 @@
+import type { ApplyStep, TransformDefinition } from '../../ast/nodes.js';
+import type { StepHandler, StepHandlerDeps } from './types.js';
+/**
+ * Extended dependencies for ApplyHandler - includes transform definition
+ */
+export interface ApplyHandlerDeps extends StepHandlerDeps {
+    transform: TransformDefinition;
+}
+/**
+ * Handles apply transform steps with overloading support.
+ *
+ * The apply step applies a named transform to a source value.
+ * If the transform has multiple variants (overloaded), it finds
+ * the first matching variant based on schema matching and guards.
+ */
+export declare class ApplyHandler implements StepHandler<ApplyStep> {
+    private deps;
+    constructor(deps: ApplyHandlerDeps);
+    execute(step: ApplyStep): Promise<void>;
+    /**
+     * Find the first matching transform variant for the given source value.
+     *
+     * Matching rules:
+     * 1. Wildcard ('_') always matches
+     * 2. Named schema must match using schema matcher
+     * 3. Optional guard condition must evaluate to truthy
+     */
+    private findMatchingVariant;
+}

package/dist/interpreter/step-handlers/apply-handler.js

@@ -0,0 +1,79 @@
+import { evaluate } from '../evaluator.js';
+import { matchesSchema } from '../schema-matcher.js';
+import { setVariable } from '../context.js';
+/**
+ * Handles apply transform steps with overloading support.
+ *
+ * The apply step applies a named transform to a source value.
+ * If the transform has multiple variants (overloaded), it finds
+ * the first matching variant based on schema matching and guards.
+ */
+export class ApplyHandler {
+    deps;
+    constructor(deps) {
+        this.deps = deps;
+    }
+    async execute(step) {
+        const source = evaluate(step.source, this.deps.ctx);
+        const transform = this.deps.transform;
+        // Find matching variant
+        const variant = this.findMatchingVariant(source, transform.variants);
+        if (!variant) {
+            throw new Error(`No matching transform variant found for '${transform.name}'. ` +
+                `Source does not match any of the ${transform.variants.length} variant(s).`);
+        }
+        // Apply the variant's mappings
+        const mapped = {};
+        for (const mapping of variant.mappings) {
+            mapped[mapping.field] = evaluate(mapping.expression, this.deps.ctx, source);
+        }
+        // Store result - either in a variable (if 'as' specified) or in response
+        if (step.as) {
+            setVariable(this.deps.ctx, step.as, mapped);
+            this.deps.log(`Applied ${transform.name} to ${step.as}`);
+        }
+        else {
+            this.deps.ctx.response = mapped;
+            this.deps.log(`Applied ${transform.name} -> ${variant.targetSchema}`);
+        }
+    }
+    /**
+     * Find the first matching transform variant for the given source value.
+     *
+     * Matching rules:
+     * 1. Wildcard ('_') always matches
+     * 2. Named schema must match using schema matcher
+     * 3. Optional guard condition must evaluate to truthy
+     */
+    findMatchingVariant(source, variants) {
+        for (const variant of variants) {
+            // Wildcard always matches
+            if (variant.sourceSchema === '_') {
+                // Check guard if present
+                if (variant.guard) {
+                    const guardResult = evaluate(variant.guard, this.deps.ctx, source);
+                    if (!guardResult)
+                        continue;
+                }
+                return variant;
+            }
+            // Check if source matches the schema
+            const schema = this.deps.ctx.schemas.get(variant.sourceSchema);
+            if (!schema) {
+                // Schema not defined - skip this variant
+                this.deps.log(`Warning: Schema '${variant.sourceSchema}' not found, skipping variant`);
+                continue;
+            }
+            if (matchesSchema(source, schema)) {
+                // Check guard if present
+                if (variant.guard) {
+                    const guardResult = evaluate(variant.guard, this.deps.ctx, source);
+                    if (!guardResult)
+                        continue;
+                }
+                return variant;
+            }
+        }
+        return undefined;
+    }
+}

package/dist/interpreter/step-handlers/for-handler.d.ts

@@ -1,9 +1,25 @@
 import type { ForStep, ActionStep } from '../../ast/nodes.js';
 import type { StepHandler, StepHandlerDeps } from './types.js';
 import type { ExecutionContext } from '../context.js';
+import { QueueSignal } from '../signals.js';
+import type { DebugController, DebugSnapshot } from '../../debug/index.js';
 export interface ForHandlerDeps extends StepHandlerDeps {
     executeStep: (step: ActionStep, actionName: string, ctx: ExecutionContext) => Promise<void>;
     actionName: string;
+    debugController?: DebugController;
+    captureDebugSnapshot?: (action: string, stepIndex: number, stepType: string, pauseReason: {
+        type: 'loop-iteration';
+        variable: string;
+        index: number;
+        total: number;
+    }, ctx: ExecutionContext) => DebugSnapshot;
+    handleDebugCommand?: (cmd: {
+        type: string;
+    }) => void;
+    /** Optional callback to check for pause requests (called every N iterations) */
+    checkPause?: () => Promise<void>;
+    /** Handle a `queue` directive raised within a loop item. */
+    handleQueue?: (signal: QueueSignal) => Promise<void>;
 }
 /**
  * Handles for...in...where iteration steps

package/dist/interpreter/step-handlers/for-handler.js

@@ -1,5 +1,9 @@
 import { evaluate } from '../evaluator.js';
 import { childContext, setVariable, getVariable } from '../context.js';
+import { StepError } from '../../errors/index.js';
+import { SkipSignal, QueueSignal } from '../signals.js';
+/** Heartbeat interval for loop iterations */
+const LOOP_HEARTBEAT_INTERVAL = 10;
 /**
  * Handles for...in...where iteration steps
  */
@@ -10,15 +14,77 @@ export class ForHandler {
     }
     async execute(step) {
         const collection = await this.getCollection(step);
+        const originalCount = collection.length;
         // Apply filter if present
         const filtered = step.condition
             ? collection.filter((item) => evaluate(step.condition, this.deps.ctx, item))
             : collection;
-        this.deps.log(`Iterating over ${filtered.length} items`);
+        // Emit loop.start event
+        this.deps.emit?.('loop.start', {
+            variable: step.variable,
+            collectionSize: filtered.length,
+            hasFilter: !!step.condition,
+        });
+        this.deps.log(`Iterating over ${filtered.length} ${filtered.length === 1 ? 'item' : 'items'}`);
+        let processedCount = 0;
+        let failedCount = 0;
         // Execute steps for each item
-        for (const item of filtered) {
-            await this.executeForItem(step, item);
+        for (let i = 0; i < filtered.length; i++) {
+            const item = filtered[i];
+            // Check for pause request every N iterations
+            if (i > 0 && i % LOOP_HEARTBEAT_INTERVAL === 0) {
+                await this.deps.checkPause?.();
+                // Emit heartbeat every N iterations
+                this.deps.emit?.('loop.heartbeat', {
+                    variable: step.variable,
+                    current: i,
+                    total: filtered.length,
+                    processedCount,
+                });
+            }
+            // Emit loop.iteration event
+            this.deps.emit?.('loop.iteration', {
+                variable: step.variable,
+                itemIndex: i,
+                totalItems: filtered.length,
+            });
+            // Debug pause point - before each loop iteration (step-into mode)
+            if (this.deps.debugController &&
+                this.deps.captureDebugSnapshot &&
+                this.deps.handleDebugCommand) {
+                const location = {
+                    action: this.deps.actionName,
+                    stepIndex: -1, // Use -1 for loop iterations
+                    stepType: 'for-iteration',
+                    isLoopIteration: true,
+                    loopInfo: { variable: step.variable, index: i, total: filtered.length },
+                };
+                if (this.deps.debugController.shouldPause(location)) {
+                    // Create child context to capture loop variable
+                    const previewCtx = childContext(this.deps.ctx);
+                    setVariable(previewCtx, step.variable, item);
+                    const snapshot = this.deps.captureDebugSnapshot(this.deps.actionName, -1, 'for-iteration', { type: 'loop-iteration', variable: step.variable, index: i, total: filtered.length }, previewCtx);
+                    const command = await this.deps.debugController.pause(snapshot);
+                    this.deps.handleDebugCommand(command);
+                }
+            }
+            try {
+                await this.executeForItem(step, item);
+                processedCount++;
+            }
+            catch (error) {
+                failedCount++;
+                throw error; // Re-throw to propagate
+            }
         }
+        // Emit loop.complete event
+        this.deps.emit?.('loop.complete', {
+            variable: step.variable,
+            totalItems: filtered.length,
+            itemsProcessed: processedCount,
+            itemsSkipped: originalCount - filtered.length,
+            itemsFailed: failedCount,
+        });
     }
     async getCollection(step) {
         let collection;
@@ -36,16 +102,32 @@ export class ForHandler {
             collection = evaluate(step.collection, this.deps.ctx);
         }
         if (!Array.isArray(collection)) {
-            throw new Error('For loop collection must be an array');
+            throw new StepError('For loop collection must be an array', 'for', {
+                action: this.deps.actionName,
+            });
         }
         return collection;
     }
     async executeForItem(step, item) {
         const childCtx = childContext(this.deps.ctx);
         setVariable(childCtx, step.variable, item);
-        // Execute each inner step with child context
-        for (const innerStep of step.steps) {
-            await this.deps.executeStep(innerStep, this.deps.actionName, childCtx);
+        try {
+            // Execute each inner step with child context
+            for (const innerStep of step.steps) {
+                await this.deps.executeStep(innerStep, this.deps.actionName, childCtx);
+            }
+        }
+        catch (error) {
+            // `skip` skips the rest of this item's steps; the loop continues.
+            if (error instanceof SkipSignal) {
+                return;
+            }
+            // `queue` stashes the item and moves on to the next iteration.
+            if (error instanceof QueueSignal) {
+                await this.deps.handleQueue?.(error);
+                return;
+            }
+            throw error;
         }
     }
 }

package/dist/interpreter/step-handlers/index.d.ts

@@ -4,5 +4,7 @@ export { MapHandler } from './map-handler.js';
 export { ValidateHandler } from './validate-handler.js';
 export { StoreHandler } from './store-handler.js';
 export { MatchHandler, type MatchHandlerDeps, type MatchResult } from './match-handler.js';
-export { WebhookHandler, type WebhookHandlerDeps, type WebhookHandlerResult } from './webhook-handler.js';
-export { NoMatchError, AbortError, SkipSignal, RetrySignal, JumpSignal, QueueSignal, } from '../signals.js';
+export { ApplyHandler, type ApplyHandlerDeps } from './apply-handler.js';
+export { WebhookHandler, type WebhookHandlerDeps, type WebhookHandlerResult, } from './webhook-handler.js';
+export { PauseHandler, type PauseHandlerDeps, type PauseHandlerResult } from './pause-handler.js';
+export { NoMatchError, AbortError, SkipSignal, RetrySignal, JumpSignal, QueueSignal, PauseSignal, } from '../signals.js';

package/dist/interpreter/step-handlers/index.js

@@ -3,6 +3,8 @@ export { MapHandler } from './map-handler.js';
 export { ValidateHandler } from './validate-handler.js';
 export { StoreHandler } from './store-handler.js';
 export { MatchHandler } from './match-handler.js';
-export { WebhookHandler } from './webhook-handler.js';
+export { ApplyHandler } from './apply-handler.js';
+export { WebhookHandler, } from './webhook-handler.js';
+export { PauseHandler } from './pause-handler.js';
 // Export signals from the canonical location
-export { NoMatchError, AbortError, SkipSignal, RetrySignal, JumpSignal, QueueSignal, } from '../signals.js';
+export { NoMatchError, AbortError, SkipSignal, RetrySignal, JumpSignal, QueueSignal, PauseSignal, } from '../signals.js';

package/dist/interpreter/step-handlers/match-handler.d.ts

@@ -1,6 +1,7 @@
 import type { MatchStep, ActionStep, FlowDirective } from '../../ast/nodes.js';
 import type { StepHandlerDeps } from './types.js';
 import type { ExecutionContext } from '../context.js';
+import type { DebugController, DebugSnapshot } from '../../debug/index.js';
 /**
  * Result of executing a match step
  */
@@ -15,6 +16,14 @@ export interface MatchResult {
 export interface MatchHandlerDeps extends StepHandlerDeps {
     executeStep: (step: ActionStep, actionName: string, ctx: ExecutionContext) => Promise<void>;
     actionName: string;
+    debugController?: DebugController;
+    captureDebugSnapshot?: (action: string, stepIndex: number, stepType: string, pauseReason: {
+        type: 'match-arm';
+        schema: string;
+    }, ctx: ExecutionContext) => DebugSnapshot;
+    handleDebugCommand?: (cmd: {
+        type: string;
+    }) => void;
 }
 /**
  * Handles match steps (schema overloading with flow control)

package/dist/interpreter/step-handlers/match-handler.js

@@ -11,31 +11,60 @@ export class MatchHandler {
     }
     async execute(step) {
         const value = evaluate(step.target, this.deps.ctx);
-        // Get schema names from arms in order
-        const schemaNames = step.arms.map(arm => arm.schema);
-        // Find matching schema
-        const matchedSchema = findMatchingSchema(value, this.deps.ctx.schemas, schemaNames);
-        if (!matchedSchema) {
-            throw new NoMatchError(value);
+        // Find matching arm, checking guards
+        let matchedArm = null;
+        for (const arm of step.arms) {
+            // Check if schema matches
+            if (arm.schema !== '_') {
+                // Check if this schema matches the value
+                const schemaMatches = findMatchingSchema(value, this.deps.ctx.schemas, [arm.schema]);
+                if (!schemaMatches) {
+                    continue;
+                }
+            }
+            // If there's a guard, check it
+            if (arm.guard) {
+                const guardResult = evaluate(arm.guard, this.deps.ctx, value);
+                if (!guardResult) {
+                    continue; // Guard failed, try next arm
+                }
+            }
+            // Found a match
+            matchedArm = arm;
+            break;
         }
-        this.deps.log(`Matched schema: ${matchedSchema}`);
-        // Find the matching arm
-        const arm = step.arms.find(a => a.schema === matchedSchema);
-        if (!arm) {
-            // Shouldn't happen if findMatchingSchema works correctly
+        if (!matchedArm) {
             throw new NoMatchError(value);
         }
+        this.deps.log(`Matched schema: ${matchedArm.schema}${matchedArm.guard ? ' (with guard)' : ''}`);
         // Handle flow directive
-        if (arm.flow) {
+        if (matchedArm.flow) {
             // 'continue' means proceed normally - don't throw
-            if (arm.flow.type === 'continue') {
+            if (matchedArm.flow.type === 'continue') {
                 return;
             }
-            this.handleFlowDirective(arm.flow, value);
+            this.handleFlowDirective(matchedArm.flow, value);
         }
         // Execute steps
-        if (arm.steps) {
-            for (const innerStep of arm.steps) {
+        if (matchedArm.steps) {
+            // Debug pause point - before match arm body (step-into mode)
+            if (this.deps.debugController &&
+                this.deps.captureDebugSnapshot &&
+                this.deps.handleDebugCommand) {
+                const location = {
+                    action: this.deps.actionName,
+                    stepIndex: -1, // Use -1 for match arms
+                    stepType: 'match-arm',
+                    isMatchArm: true,
+                    matchInfo: { schema: matchedArm.schema },
+                };
+                if (this.deps.debugController.shouldPause(location)) {
+                    const snapshot = this.deps.captureDebugSnapshot(this.deps.actionName, -1, 'match-arm', { type: 'match-arm', schema: matchedArm.schema }, this.deps.ctx);
+                    const command = await this.deps.debugController.pause(snapshot);
+                    this.deps.handleDebugCommand(command);
+                }
+            }
+            for (const innerStep of matchedArm.steps) {
                 await this.deps.executeStep(innerStep, this.deps.actionName, this.deps.ctx);
             }
         }
@@ -52,10 +81,11 @@ export class MatchHandler {
                 throw new JumpSignal(flow.action, flow.then);
             case 'queue':
                 throw new QueueSignal(value, flow.target);
-            default:
+            default: {
                 // This should never happen if TypeScript is working correctly
                 const _exhaustive = flow;
                 throw new Error(`Unknown flow directive: ${_exhaustive.type}`);
+            }
         }
     }
 }