reqon-dsl 0.2.0 → 0.4.0

package/dist/config/constants.js

@@ -0,0 +1,139 @@
+/**
+ * Centralized Configuration Constants
+ *
+ * This module contains all default values and configuration constants used
+ * throughout the Reqon framework. Centralizing these values makes it easier
+ * to understand, tune, and override defaults.
+ */
+// ============================================
+// HTTP Client Configuration
+// ============================================
+/**
+ * Default retry configuration for HTTP requests
+ */
+export const HTTP_RETRY_DEFAULTS = {
+    /** Maximum number of retry attempts */
+    MAX_ATTEMPTS: 3,
+    /** Initial delay between retries in milliseconds */
+    INITIAL_DELAY_MS: 1000,
+    /** Maximum delay between retries in milliseconds */
+    MAX_DELAY_MS: 30000,
+    /** Backoff strategy: 'exponential', 'linear', or 'constant' */
+    BACKOFF: 'exponential',
+    /** Per-attempt request timeout in milliseconds (aborts a hung request) */
+    TIMEOUT_MS: 30000,
+};
+/**
+ * Default HTTP headers
+ */
+export const HTTP_DEFAULT_HEADERS = {
+    CONTENT_TYPE: 'application/json',
+    ACCEPT: 'application/json',
+};
+// ============================================
+// Rate Limiter Configuration
+// ============================================
+/**
+ * Default rate limiter configuration
+ */
+export const RATE_LIMIT_DEFAULTS = {
+    /** Default strategy when rate limited: 'pause', 'throttle', or 'fail' */
+    STRATEGY: 'pause',
+    /** Maximum wait time in seconds before timing out */
+    MAX_WAIT_SECONDS: 300,
+    /** Seconds before starting to notify about ongoing waits */
+    NOTIFY_AT_SECONDS: 10,
+    /** Fallback requests per minute when no rate limit info available */
+    FALLBACK_RPM: 60,
+    /** Maximum age for stale rate limit entries (1 hour in ms) */
+    MAX_STALE_AGE_MS: 60 * 60 * 1000,
+    /** Cleanup interval for stale entries (5 minutes in ms) */
+    CLEANUP_INTERVAL_MS: 5 * 60 * 1000,
+    /** Number of responses between cleanup checks */
+    CLEANUP_CHECK_INTERVAL: 100,
+    /** Maximum entries before forced cleanup */
+    MAX_ENTRIES_BEFORE_CLEANUP: 1000,
+};
+// ============================================
+// Circuit Breaker Configuration
+// ============================================
+/**
+ * Default circuit breaker configuration
+ */
+export const CIRCUIT_BREAKER_DEFAULTS = {
+    /** Number of failures before opening circuit */
+    FAILURE_THRESHOLD: 5,
+    /** Time in milliseconds before attempting recovery */
+    RESET_TIMEOUT_MS: 30000,
+    /** Number of successful requests in half-open to close circuit */
+    SUCCESS_THRESHOLD: 2,
+    /** Time window in milliseconds for counting failures */
+    FAILURE_WINDOW_MS: 60000,
+    /** HTTP status codes to count as failures */
+    FAILURE_STATUS_CODES: [500, 501, 502, 503, 504],
+    /** Whether to count network errors as failures */
+    COUNT_NETWORK_ERRORS: true,
+};
+// ============================================
+// Webhook Server Configuration
+// ============================================
+/**
+ * Default webhook server configuration
+ */
+export const WEBHOOK_DEFAULTS = {
+    /** Default port for webhook server */
+    PORT: 3000,
+    /** Default host binding — loopback only; opt into 0.0.0.0 explicitly. */
+    HOST: '127.0.0.1',
+    /** Default timeout for wait steps (5 minutes in ms) */
+    DEFAULT_TIMEOUT_MS: 300000,
+    /** Cleanup interval for expired registrations (1 minute in ms) */
+    CLEANUP_INTERVAL_MS: 60000,
+    /** Maximum accepted request body size in bytes (1 MiB) */
+    MAX_BODY_BYTES: 1024 * 1024,
+    /** Idle socket timeout in ms; drops slow-drip connections */
+    SOCKET_TIMEOUT_MS: 30000,
+};
+// ============================================
+// Store Configuration
+// ============================================
+/**
+ * Default store configuration
+ */
+export const STORE_DEFAULTS = {
+    /** Default base directory for file stores */
+    DATA_DIR: '.reqon-data',
+    /** Default subdirectory for executions */
+    EXECUTIONS_DIR: 'executions',
+    /** Default subdirectory for sync state */
+    SYNC_DIR: 'sync',
+};
+// ============================================
+// Scheduler Configuration
+// ============================================
+/**
+ * Default scheduler configuration
+ */
+export const SCHEDULER_DEFAULTS = {
+    /** Default retry configuration for failed scheduled missions */
+    MAX_RETRIES: 3,
+    /** Default delay between retries in seconds */
+    RETRY_DELAY_SECONDS: 60,
+};
+// ============================================
+// Execution Configuration
+// ============================================
+/**
+ * Default execution configuration
+ */
+export const EXECUTION_DEFAULTS = {
+    /**
+     * Whether development mode is enabled by default. When true, sql/nosql
+     * stores fall back to local JSON files; default false so a mission that
+     * declares `store sql`/`nosql` errors loudly instead of silently writing
+     * to disk.
+     */
+    DEVELOPMENT_MODE: false,
+    /** Whether to persist execution state by default */
+    PERSIST_STATE: false,
+};

package/dist/config/index.d.ts

@@ -0,0 +1,4 @@
+/**
+ * Configuration module exports
+ */
+export * from './constants.js';

package/dist/config/index.js

@@ -0,0 +1,4 @@
+/**
+ * Configuration module exports
+ */
+export * from './constants.js';

package/dist/control/index.d.ts

@@ -0,0 +1,2 @@
+export { ControlServer } from './server.js';
+export type { ControlServerConfig, ControlServerCallbacks, StatusResponse, ControlResponse, } from './types.js';

package/dist/control/index.js

@@ -0,0 +1 @@
+export { ControlServer } from './server.js';

package/dist/control/server.d.ts

@@ -0,0 +1,105 @@
+/**
+ * Control Server
+ *
+ * HTTP server for runtime control of mission execution.
+ * Provides pause/resume commands and live status queries.
+ */
+import type { ExecutionState, LiveProgress } from '../execution/index.js';
+import type { ControlServerConfig, ControlServerCallbacks } from './types.js';
+/**
+ * Control Server
+ *
+ * Provides HTTP endpoints for controlling mission execution:
+ * - POST /pause - Request graceful pause
+ * - POST /resume - Clear pause request
+ * - GET /status - Get current execution state and progress
+ * - GET /health - Health check
+ */
+export declare class ControlServer {
+    private config;
+    private callbacks;
+    private server?;
+    private running;
+    private startTime;
+    private pauseRequested;
+    private executionState?;
+    private liveProgress?;
+    constructor(config?: ControlServerConfig, callbacks?: ControlServerCallbacks);
+    /**
+     * Start the control server
+     */
+    start(): Promise<void>;
+    /**
+     * Stop the control server
+     */
+    stop(): Promise<void>;
+    /**
+     * Check if pause has been requested
+     */
+    isPauseRequested(): boolean;
+    /**
+     * Clear pause request (called after pause is handled)
+     */
+    clearPauseRequest(): void;
+    /**
+     * Update execution state (called by executor)
+     */
+    updateState(state: ExecutionState): void;
+    /**
+     * Update live progress (called by executor)
+     */
+    updateProgress(progress: LiveProgress): void;
+    /**
+     * Check if the server is running
+     */
+    isRunning(): boolean;
+    /**
+     * Get the server port
+     */
+    getPort(): number;
+    /**
+     * Handle incoming HTTP request
+     */
+    private handleRequest;
+    /** True if a host string is a loopback address. */
+    private isLoopback;
+    /** True if the request carries an Origin header pointing at another origin. */
+    private hasCrossOriginHeader;
+    /**
+     * Enforce the shared-secret token on protected endpoints. When no token is
+     * configured, allow (the loopback bind + CSRF check are the baseline) but
+     * warn so operators know /status state is exposed locally.
+     */
+    private authorized;
+    /**
+     * Constant-time string comparison. Avoids the timing oracle of `a !== b`,
+     * which short-circuits on the first differing byte and can leak the token
+     * prefix. Length is compared first (and non-constant-time), which only
+     * reveals the token length — not its contents.
+     */
+    private safeEqual;
+    /**
+     * Handle health check
+     */
+    private handleHealth;
+    /**
+     * Handle status query
+     */
+    private handleStatus;
+    /**
+     * Handle pause request
+     */
+    private handlePause;
+    /**
+     * Handle resume request
+     */
+    private handleResume;
+    /**
+     * Send JSON response
+     */
+    private sendJson;
+    /**
+     * Log message if verbose mode enabled
+     */
+    private log;
+}

package/dist/control/server.js

@@ -0,0 +1,315 @@
+/**
+ * Control Server
+ *
+ * HTTP server for runtime control of mission execution.
+ * Provides pause/resume commands and live status queries.
+ */
+import { createServer } from 'node:http';
+import { parse as parseUrl } from 'node:url';
+import { timingSafeEqual } from 'node:crypto';
+const DEFAULTS = {
+    PORT: 3001,
+    HOST: 'localhost',
+};
+/**
+ * Control Server
+ *
+ * Provides HTTP endpoints for controlling mission execution:
+ * - POST /pause - Request graceful pause
+ * - POST /resume - Clear pause request
+ * - GET /status - Get current execution state and progress
+ * - GET /health - Health check
+ */
+export class ControlServer {
+    config;
+    callbacks;
+    server;
+    running = false;
+    startTime = Date.now();
+    // State managed by the control server
+    pauseRequested = false;
+    executionState;
+    liveProgress;
+    constructor(config = {}, callbacks = {}) {
+        this.config = {
+            port: config.port ?? DEFAULTS.PORT,
+            host: config.host ?? DEFAULTS.HOST,
+            verbose: config.verbose ?? false,
+            authToken: config.authToken ?? '',
+        };
+        this.callbacks = callbacks;
+    }
+    /**
+     * Start the control server
+     */
+    async start() {
+        if (this.running)
+            return;
+        // Hard-refuse to expose a state-changing server beyond loopback without a
+        // shared secret. /pause, /resume, and /status would otherwise be reachable
+        // by anyone who can route to this host. Bind to loopback or set authToken.
+        if (!this.isLoopback(this.config.host) && !this.config.authToken) {
+            throw new Error(`[Control] Refusing to start: binding to non-loopback host "${this.config.host}" ` +
+                `with no authToken would expose /pause, /resume, and /status without authentication. ` +
+                `Set an authToken or bind to localhost.`);
+        }
+        return new Promise((resolve, reject) => {
+            this.server = createServer((req, res) => this.handleRequest(req, res));
+            this.server.setTimeout(30000);
+            this.server.on('error', (error) => {
+                reject(error);
+            });
+            this.server.listen(this.config.port, this.config.host, () => {
+                this.running = true;
+                this.startTime = Date.now();
+                this.log(`Control server listening on ${this.config.host}:${this.config.port}`);
+                resolve();
+            });
+        });
+    }
+    /**
+     * Stop the control server
+     */
+    async stop() {
+        if (!this.running)
+            return;
+        return new Promise((resolve) => {
+            if (this.server) {
+                this.server.close(() => {
+                    this.running = false;
+                    this.log('Control server stopped');
+                    resolve();
+                });
+            }
+            else {
+                resolve();
+            }
+        });
+    }
+    /**
+     * Check if pause has been requested
+     */
+    isPauseRequested() {
+        return this.pauseRequested;
+    }
+    /**
+     * Clear pause request (called after pause is handled)
+     */
+    clearPauseRequest() {
+        this.pauseRequested = false;
+    }
+    /**
+     * Update execution state (called by executor)
+     */
+    updateState(state) {
+        this.executionState = state;
+    }
+    /**
+     * Update live progress (called by executor)
+     */
+    updateProgress(progress) {
+        this.liveProgress = progress;
+    }
+    /**
+     * Check if the server is running
+     */
+    isRunning() {
+        return this.running;
+    }
+    /**
+     * Get the server port
+     */
+    getPort() {
+        return this.config.port;
+    }
+    /**
+     * Handle incoming HTTP request
+     */
+    async handleRequest(req, res) {
+        const url = parseUrl(req.url ?? '/', true);
+        const path = url.pathname ?? '/';
+        const method = req.method ?? 'GET';
+        // No wildcard CORS. Same-origin reads only; we never reflect ACAO so a
+        // browser on another origin can't read /status.
+        res.setHeader('Vary', 'Origin');
+        // Handle preflight
+        if (method === 'OPTIONS') {
+            res.writeHead(204);
+            res.end();
+            return;
+        }
+        // CSRF defense: reject any request that carries a cross-origin Origin
+        // header (server-to-server clients and curl send none). Combined with the
+        // loopback bind, this stops a web page the operator visits from POSTing
+        // /pause or /resume to their local control server.
+        if (this.hasCrossOriginHeader(req)) {
+            this.sendJson(res, 403, { error: 'Cross-origin request rejected' });
+            return;
+        }
+        try {
+            // Route requests
+            if (path === '/health' || path === '/_health') {
+                this.handleHealth(res);
+            }
+            else if (path === '/status') {
+                if (!this.authorized(req, res))
+                    return;
+                this.handleStatus(res);
+            }
+            else if (path === '/pause' && method === 'POST') {
+                if (!this.authorized(req, res))
+                    return;
+                this.handlePause(res);
+            }
+            else if (path === '/resume' && method === 'POST') {
+                if (!this.authorized(req, res))
+                    return;
+                this.handleResume(res);
+            }
+            else {
+                this.sendJson(res, 404, { error: 'Not found', path });
+            }
+        }
+        catch (error) {
+            this.sendJson(res, 500, { error: error.message });
+        }
+    }
+    /** True if a host string is a loopback address. */
+    isLoopback(host) {
+        return host === 'localhost' || host === '127.0.0.1' || host === '::1';
+    }
+    /** True if the request carries an Origin header pointing at another origin. */
+    hasCrossOriginHeader(req) {
+        const origin = req.headers.origin;
+        if (!origin || typeof origin !== 'string')
+            return false;
+        const host = req.headers.host;
+        try {
+            const originHost = new URL(origin).host;
+            return originHost !== host;
+        }
+        catch {
+            // Unparseable Origin — treat as cross-origin (reject).
+            return true;
+        }
+    }
+    /**
+     * Enforce the shared-secret token on protected endpoints. When no token is
+     * configured, allow (the loopback bind + CSRF check are the baseline) but
+     * warn so operators know /status state is exposed locally.
+     */
+    authorized(req, res) {
+        if (!this.config.authToken) {
+            return true;
+        }
+        const header = req.headers.authorization;
+        const expected = `Bearer ${this.config.authToken}`;
+        if (typeof header !== 'string' || !this.safeEqual(header, expected)) {
+            this.sendJson(res, 401, { error: 'Unauthorized' });
+            return false;
+        }
+        return true;
+    }
+    /**
+     * Constant-time string comparison. Avoids the timing oracle of `a !== b`,
+     * which short-circuits on the first differing byte and can leak the token
+     * prefix. Length is compared first (and non-constant-time), which only
+     * reveals the token length — not its contents.
+     */
+    safeEqual(a, b) {
+        const bufA = Buffer.from(a);
+        const bufB = Buffer.from(b);
+        if (bufA.length !== bufB.length) {
+            return false;
+        }
+        return timingSafeEqual(bufA, bufB);
+    }
+    /**
+     * Handle health check
+     */
+    handleHealth(res) {
+        this.sendJson(res, 200, {
+            status: 'ok',
+            timestamp: new Date().toISOString(),
+            uptime: Date.now() - this.startTime,
+        });
+    }
+    /**
+     * Handle status query
+     */
+    handleStatus(res) {
+        this.callbacks.onStatusQueried?.();
+        const response = {
+            execution: this.executionState,
+            progress: this.liveProgress,
+            pauseRequested: this.pauseRequested,
+            uptime: Date.now() - this.startTime,
+            timestamp: new Date().toISOString(),
+        };
+        this.sendJson(res, 200, response);
+    }
+    /**
+     * Handle pause request
+     */
+    handlePause(res) {
+        if (this.pauseRequested) {
+            const response = {
+                success: true,
+                message: 'Pause already requested',
+                pauseRequested: true,
+            };
+            this.sendJson(res, 200, response);
+            return;
+        }
+        this.pauseRequested = true;
+        this.callbacks.onPauseRequested?.();
+        this.log('Pause requested');
+        const response = {
+            success: true,
+            message: 'Pause requested. Execution will pause at next safe point.',
+            pauseRequested: true,
+        };
+        this.sendJson(res, 200, response);
+    }
+    /**
+     * Handle resume request
+     */
+    handleResume(res) {
+        if (!this.pauseRequested) {
+            const response = {
+                success: true,
+                message: 'No pause was requested',
+                pauseRequested: false,
+            };
+            this.sendJson(res, 200, response);
+            return;
+        }
+        this.pauseRequested = false;
+        this.callbacks.onResumeRequested?.();
+        this.log('Pause request cleared');
+        const response = {
+            success: true,
+            message: 'Pause request cleared. Use --resume flag to resume execution.',
+            pauseRequested: false,
+        };
+        this.sendJson(res, 200, response);
+    }
+    /**
+     * Send JSON response
+     */
+    sendJson(res, status, data) {
+        // Close the connection after each response. This localhost admin server has
+        // no need for keep-alive, and avoiding pooled sockets removes a client-side
+        // socket-reuse race (intermittent ECONNRESET on rapid sequential requests).
+        res.writeHead(status, { 'Content-Type': 'application/json', Connection: 'close' });
+        res.end(JSON.stringify(data, null, 2));
+    }
+    /**
+     * Log message if verbose mode enabled
+     */
+    log(message) {
+        if (this.config.verbose) {
+            console.log(`[Control] ${message}`);
+        }
+    }
+}

package/dist/control/types.d.ts

@@ -0,0 +1,61 @@
+/**
+ * Control Server Types
+ *
+ * Types for the HTTP control server that enables
+ * pause/resume and live status queries.
+ */
+import type { ExecutionState, LiveProgress } from '../execution/index.js';
+/**
+ * Configuration for the control server
+ */
+export interface ControlServerConfig {
+    /** Port to listen on (default: 3001) */
+    port?: number;
+    /** Host to bind to (default: localhost) */
+    host?: string;
+    /** Enable verbose logging */
+    verbose?: boolean;
+    /**
+     * Shared secret required on state-changing endpoints (/pause, /resume) and
+     * /status. When set, requests must present `Authorization: Bearer <secret>`
+     * or they are rejected with 401.
+     */
+    authToken?: string;
+}
+/**
+ * Callbacks for control server events
+ */
+export interface ControlServerCallbacks {
+    /** Called when pause is requested */
+    onPauseRequested?: () => void;
+    /** Called when resume is requested */
+    onResumeRequested?: () => void;
+    /** Called when status is queried */
+    onStatusQueried?: () => void;
+}
+/**
+ * Response for status endpoint
+ */
+export interface StatusResponse {
+    /** Execution state (if available) */
+    execution?: ExecutionState;
+    /** Live progress (if available) */
+    progress?: LiveProgress;
+    /** Whether pause has been requested */
+    pauseRequested: boolean;
+    /** Server uptime in milliseconds */
+    uptime: number;
+    /** Timestamp of this response */
+    timestamp: string;
+}
+/**
+ * Response for pause/resume endpoints
+ */
+export interface ControlResponse {
+    /** Whether the operation succeeded */
+    success: boolean;
+    /** Optional message */
+    message?: string;
+    /** Whether pause is currently requested */
+    pauseRequested: boolean;
+}

package/dist/control/types.js

@@ -0,0 +1,7 @@
+/**
+ * Control Server Types
+ *
+ * Types for the HTTP control server that enables
+ * pause/resume and live status queries.
+ */
+export {};

package/dist/debug/cli-debugger.d.ts

@@ -0,0 +1,17 @@
+/**
+ * CLI Debugger - Interactive readline-based debugger for terminal use
+ */
+import type { DebugCommand, DebugSnapshot } from './controller.js';
+import { BaseDebugController } from './controller.js';
+export declare class CLIDebugger extends BaseDebugController {
+    private rl;
+    private closed;
+    constructor();
+    pause(snapshot: DebugSnapshot): Promise<DebugCommand>;
+    private printSnapshot;
+    private formatValue;
+    private promptCommand;
+    private parseCommand;
+    private printHelp;
+    close(): void;
+}