reqon-dsl 0.3.0 → 0.4.0

package/dist/config/constants.js

@@ -20,6 +20,8 @@ export const HTTP_RETRY_DEFAULTS = {
     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
@@ -81,12 +83,16 @@ export const CIRCUIT_BREAKER_DEFAULTS = {
 export const WEBHOOK_DEFAULTS = {
     /** Default port for webhook server */
     PORT: 3000,
-    /** Default host binding */
-    HOST: '0.0.0.0',
+    /** 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
@@ -121,8 +127,13 @@ export const SCHEDULER_DEFAULTS = {
  * Default execution configuration
  */
 export const EXECUTION_DEFAULTS = {
-    /** Whether development mode is enabled by default (uses file stores) */
-    DEVELOPMENT_MODE: true,
+    /**
+     * 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/control/server.d.ts

@@ -61,6 +61,23 @@ export declare class ControlServer {
      * 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
      */

package/dist/control/server.js

@@ -6,6 +6,7 @@
  */
 import { createServer } from 'node:http';
 import { parse as parseUrl } from 'node:url';
+import { timingSafeEqual } from 'node:crypto';
 const DEFAULTS = {
     PORT: 3001,
     HOST: 'localhost',
@@ -34,6 +35,7 @@ export class ControlServer {
             port: config.port ?? DEFAULTS.PORT,
             host: config.host ?? DEFAULTS.HOST,
             verbose: config.verbose ?? false,
+            authToken: config.authToken ?? '',
         };
         this.callbacks = callbacks;
     }
@@ -43,8 +45,17 @@ export class ControlServer {
     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);
             });
@@ -118,28 +129,41 @@ export class ControlServer {
         const url = parseUrl(req.url ?? '/', true);
         const path = url.pathname ?? '/';
         const method = req.method ?? 'GET';
-        // Set CORS headers for flexibility
-        res.setHeader('Access-Control-Allow-Origin', '*');
-        res.setHeader('Access-Control-Allow-Methods', 'GET, POST, OPTIONS');
-        res.setHeader('Access-Control-Allow-Headers', 'Content-Type');
+        // 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 {
@@ -150,6 +174,56 @@ export class ControlServer {
             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
      */
@@ -224,7 +298,10 @@ export class ControlServer {
      * Send JSON response
      */
     sendJson(res, status, data) {
-        res.writeHead(status, { 'Content-Type': 'application/json' });
+        // 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));
     }
     /**

package/dist/control/types.d.ts

@@ -15,6 +15,12 @@ export interface ControlServerConfig {
     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

package/dist/debug/cli-debugger.js

@@ -36,17 +36,22 @@ export class CLIDebugger extends BaseDebugController {
         // Print variables summary
         const varKeys = Object.keys(s.variables);
         if (varKeys.length > 0) {
-            const preview = varKeys.slice(0, 3).map(k => `${k}: ${this.formatValue(s.variables[k])}`).join(', ');
+            const preview = varKeys
+                .slice(0, 3)
+                .map((k) => `${k}: ${this.formatValue(s.variables[k])}`)
+                .join(', ');
             const more = varKeys.length > 3 ? ` (+${varKeys.length - 3} more)` : '';
             console.log(`  Variables: { ${preview}${more} }`);
         }
         // Print stores summary
         const storeEntries = Object.entries(s.stores);
         if (storeEntries.length > 0) {
-            const storeInfo = storeEntries.map(([name, info]) => {
+            const storeInfo = storeEntries
+                .map(([name, info]) => {
                 const count = info.count >= 0 ? ` (${info.count} items)` : '';
                 return `${name}: ${info.type}${count}`;
-            }).join(', ');
+            })
+                .join(', ');
             console.log(`  Stores: { ${storeInfo} }`);
         }
         // Print response summary

package/dist/execution/store.js

@@ -1,4 +1,4 @@
-import { join } from 'node:path';
+import { safeJoin } from '../utils/path.js';
 import { ensureDirectory, writeJsonFile, readJsonFile, listFiles, deleteFile, restoreDates, restoreDatesInArray, } from '../utils/file.js';
 /**
  * File-based execution state store
@@ -12,7 +12,7 @@ export class FileExecutionStore {
         this.initialized = ensureDirectory(this.baseDir);
     }
     getFilePath(id) {
-        return join(this.baseDir, `${id}.json`);
+        return safeJoin(this.baseDir, `${id}.json`);
     }
     deserialize(parsed) {
         // Restore Date objects

package/dist/execution-log/events.d.ts

@@ -0,0 +1,125 @@
+/**
+ * Execution event log — the durable, append-only record of a mission run.
+ *
+ * Every step's start, completion, and side effect is appended as it happens.
+ * Resume becomes "replay the log and fold to last state" (see {@link ./fold}),
+ * and trace/time-travel, audit, and idempotent resume all derive from this one
+ * structure. Recorded values (timestamps, effect ids, outputs) are read back on
+ * replay rather than re-derived, so replay is deterministic.
+ */
+export type ExecutionEventType = 'mission.started' | 'step.started' | 'step.completed' | 'effect.applied' | 'page.completed' | 'checkpoint.advanced' | 'pause.created' | 'pause.resumed' | 'mission.completed' | 'mission.failed';
+interface BaseEvent {
+    /** The run this event belongs to. */
+    executionId: string;
+    /** Event kind (discriminant). */
+    type: ExecutionEventType;
+}
+export interface MissionStartedEvent extends BaseEvent {
+    type: 'mission.started';
+    mission: string;
+}
+export interface StepStartedEvent extends BaseEvent {
+    type: 'step.started';
+    stepId: string;
+    action: string;
+    stepType: string;
+    attempt: number;
+}
+export interface StepCompletedEvent extends BaseEvent {
+    type: 'step.completed';
+    stepId: string;
+    attempt: number;
+}
+/**
+ * A side effect (a fetch or a store write) was applied. The {@link effectId}
+ * is the stable identity used to skip already-applied effects on replay.
+ */
+export interface EffectAppliedEvent extends BaseEvent {
+    type: 'effect.applied';
+    stepId: string;
+    attempt: number;
+    effectType: 'fetch' | 'store';
+    effectId: string;
+}
+/**
+ * A page of a resumable (backfill) paginated fetch finished — its data is
+ * fetched and persisted. Carries the position to resume from: the next page
+ * index and/or cursor. `done` marks the natural end of pagination (the API had
+ * no more), distinct from stopping early on a per-run item cap, so a resume
+ * knows whether to continue or skip.
+ */
+export interface PageCompletedEvent extends BaseEvent {
+    type: 'page.completed';
+    stepId: string;
+    /** Zero-based index of the next page to fetch on resume. */
+    page: number;
+    /** Cursor to resume from (cursor-based pagination). */
+    cursor?: string;
+    /**
+     * Records *fetched* on this page. NOTE: this is the fetched count, not the
+     * persisted count — the page's data is still only in memory when this event is
+     * recorded; the downstream store step persists it afterwards. A crash between
+     * this event and the store's `effect.applied` advances the resume cursor past a
+     * page whose data was never stored. See the known crash-window note in
+     * CODE_REVIEW.md (C2); a full fix defers this advance until after persistence.
+     */
+    recordCount?: number;
+    /** True once pagination has reached its natural end. */
+    done: boolean;
+}
+export interface CheckpointAdvancedEvent extends BaseEvent {
+    type: 'checkpoint.advanced';
+    key: string;
+    syncedAt: string;
+    /** Records fetched in the sync that advanced this checkpoint. */
+    recordCount?: number;
+    /** Opaque pagination cursor to resume from (cursor-based incremental sync). */
+    cursor?: string;
+    /** Mission that advanced the checkpoint (lets a shared log filter by mission). */
+    mission?: string;
+}
+export interface PauseCreatedEvent extends BaseEvent {
+    type: 'pause.created';
+    pauseId: string;
+    /**
+     * The full durable pause state (expiry, resume triggers, captured checkpoint).
+     * Carried in the log so a paused run — and the timer/webhook it waits on — can
+     * be reconstructed from the log alone, no separate pause file. Opaque to the
+     * log layer (typed `unknown` to avoid coupling it to the pause domain).
+     */
+    pause?: unknown;
+}
+export interface PauseResumedEvent extends BaseEvent {
+    type: 'pause.resumed';
+    pauseId: string;
+    resumedBy: string;
+    /** Terminal status of the pause: resumed (default), cancelled, or expired. */
+    status?: 'resumed' | 'cancelled' | 'expired';
+    /** Recorded resume time (ISO 8601). */
+    resumedAt?: string;
+    /** Payload delivered by a webhook resume. */
+    webhookPayload?: unknown;
+}
+export interface MissionCompletedEvent extends BaseEvent {
+    type: 'mission.completed';
+}
+export interface MissionFailedEvent extends BaseEvent {
+    type: 'mission.failed';
+    error: string;
+}
+/** An event as appended by a caller (the log assigns seq + timestamp). */
+export type ExecutionEvent = MissionStartedEvent | StepStartedEvent | StepCompletedEvent | EffectAppliedEvent | PageCompletedEvent | CheckpointAdvancedEvent | PauseCreatedEvent | PauseResumedEvent | MissionCompletedEvent | MissionFailedEvent;
+/** A persisted event: the appended event plus the log's assigned metadata. */
+export type StoredEvent = ExecutionEvent & {
+    /** Monotonic sequence within the execution, starting at 0. */
+    seq: number;
+    /** Recorded wall-clock time (ISO 8601); read back on replay, never re-derived. */
+    at: string;
+};
+/**
+ * Stable identity for a side effect: `(executionId, stepId, attempt, effectType)`
+ * plus a caller-supplied discriminator (e.g. the request signature or record
+ * key). Replay uses this to skip effects already recorded as applied.
+ */
+export declare function effectId(executionId: string, stepId: string, attempt: number, effectType: 'fetch' | 'store', discriminator: string): string;
+export {};

package/dist/execution-log/events.js

@@ -0,0 +1,17 @@
+/**
+ * Execution event log — the durable, append-only record of a mission run.
+ *
+ * Every step's start, completion, and side effect is appended as it happens.
+ * Resume becomes "replay the log and fold to last state" (see {@link ./fold}),
+ * and trace/time-travel, audit, and idempotent resume all derive from this one
+ * structure. Recorded values (timestamps, effect ids, outputs) are read back on
+ * replay rather than re-derived, so replay is deterministic.
+ */
+/**
+ * Stable identity for a side effect: `(executionId, stepId, attempt, effectType)`
+ * plus a caller-supplied discriminator (e.g. the request signature or record
+ * key). Replay uses this to skip effects already recorded as applied.
+ */
+export function effectId(executionId, stepId, attempt, effectType, discriminator) {
+    return `${executionId}::${stepId}::${attempt}::${effectType}::${discriminator}`;
+}

package/dist/execution-log/fold.d.ts

@@ -0,0 +1,38 @@
+/**
+ * Fold an execution event log down to current state.
+ *
+ * This is the heart of replay-based resume: replaying the log and folding it
+ * yields the exact state the run was in, including which effects already
+ * applied (so replay skips them) and which pause it is waiting on.
+ */
+import type { StoredEvent } from './events.js';
+export type FoldedStatus = 'pending' | 'running' | 'paused' | 'completed' | 'failed';
+export interface FoldedState {
+    status: FoldedStatus;
+    /** Sequence of the last event folded (-1 for an empty log). */
+    lastSeq: number;
+    /** Step ids that have completed (replay skips re-running them). */
+    completedSteps: Set<string>;
+    /** Effect ids already applied (replay skips re-applying them). */
+    appliedEffects: Set<string>;
+    /** Latest synced-at per checkpoint key. */
+    checkpoints: Map<string, string>;
+    /** Resume position per backfill step id (last persisted page + cursor). */
+    pageProgress: Map<string, {
+        page: number;
+        cursor?: string;
+        done: boolean;
+    }>;
+    /** The pause this run is currently waiting on, if any. */
+    pendingPauseId?: string;
+    /**
+     * The last pause marked resumed in the log. A resume trigger (webhook/timeout)
+     * can record `pause.resumed` before the executor re-runs, so this lets the
+     * executor recognise it must continue past that pause rather than create a new
+     * one. Cleared once the run completes or fails.
+     */
+    resumedPauseId?: string;
+    /** Error message if the run failed. */
+    error?: string;
+}
+export declare function foldLog(events: StoredEvent[]): FoldedState;

package/dist/execution-log/fold.js

@@ -0,0 +1,54 @@
+export function foldLog(events) {
+    const state = {
+        status: 'pending',
+        lastSeq: -1,
+        completedSteps: new Set(),
+        appliedEffects: new Set(),
+        checkpoints: new Map(),
+        pageProgress: new Map(),
+    };
+    for (const event of events) {
+        state.lastSeq = event.seq;
+        switch (event.type) {
+            case 'mission.started':
+                state.status = 'running';
+                break;
+            case 'step.completed':
+                state.completedSteps.add(event.stepId);
+                break;
+            case 'effect.applied':
+                state.appliedEffects.add(event.effectId);
+                break;
+            case 'page.completed':
+                state.pageProgress.set(event.stepId, {
+                    page: event.page,
+                    cursor: event.cursor,
+                    done: event.done,
+                });
+                break;
+            case 'checkpoint.advanced':
+                state.checkpoints.set(event.key, event.syncedAt);
+                break;
+            case 'pause.created':
+                state.status = 'paused';
+                state.pendingPauseId = event.pauseId;
+                break;
+            case 'pause.resumed':
+                state.status = 'running';
+                state.pendingPauseId = undefined;
+                state.resumedPauseId = event.pauseId;
+                break;
+            case 'mission.completed':
+                state.status = 'completed';
+                state.resumedPauseId = undefined;
+                break;
+            case 'mission.failed':
+                state.status = 'failed';
+                state.error = event.error;
+                state.resumedPauseId = undefined;
+                break;
+            // step.started carries no folded state on its own.
+        }
+    }
+    return state;
+}

package/dist/execution-log/index.d.ts

@@ -0,0 +1,18 @@
+/**
+ * Execution event log — the append-only foundation for durable execution.
+ *
+ * A running mission is modelled as an ordered log of events; resume is replay +
+ * fold (see {@link foldLog}), and idempotent effects fall out of recording an
+ * `effect.applied` event per side effect. This module is the seam the rest of
+ * the durable-execution work (transactional backend, exactly-once effects,
+ * trace/sync/pause as log views) builds on.
+ */
+export type { ExecutionEvent, StoredEvent, ExecutionEventType, MissionStartedEvent, StepStartedEvent, StepCompletedEvent, EffectAppliedEvent, CheckpointAdvancedEvent, PauseCreatedEvent, PauseResumedEvent, MissionCompletedEvent, MissionFailedEvent, } from './events.js';
+export { effectId } from './events.js';
+export type { ExecutionLogStore, CheckpointRecord } from './store.js';
+export { MemoryExecutionLog, FileExecutionLog, reduceCheckpoints } from './store.js';
+export { SqliteExecutionLog } from './sqlite-store.js';
+export { PostgresExecutionLog, type PostgresExecutionLogOptions } from './postgres-store.js';
+export type { FoldedState, FoldedStatus } from './fold.js';
+export { foldLog } from './fold.js';
+export { loadState } from './resume.js';

package/dist/execution-log/index.js

@@ -0,0 +1,6 @@
+export { effectId } from './events.js';
+export { MemoryExecutionLog, FileExecutionLog, reduceCheckpoints } from './store.js';
+export { SqliteExecutionLog } from './sqlite-store.js';
+export { PostgresExecutionLog } from './postgres-store.js';
+export { foldLog } from './fold.js';
+export { loadState } from './resume.js';

package/dist/execution-log/postgres-store.d.ts

@@ -0,0 +1,36 @@
+/**
+ * Postgres-backed execution log — a transactional, multi-node durable backend.
+ *
+ * Like the SQLite backend, `pg` is an *optional* peer dependency imported lazily
+ * via a non-literal specifier, so the core package carries no database driver
+ * and a missing one yields a clear, actionable error.
+ *
+ * Multi-writer safety: `seq` is assigned inside the INSERT under a
+ * `(execution_id, seq)` primary key. If two appenders race and compute the same
+ * next seq, one wins and the other gets a unique-violation (SQLSTATE 23505) and
+ * retries against the now-higher max — so concurrent appenders always land on
+ * distinct, contiguous sequence numbers.
+ */
+import type { ExecutionEvent, StoredEvent } from './events.js';
+import type { CheckpointRecord, ExecutionLogStore } from './store.js';
+export interface PostgresExecutionLogOptions {
+    /** Table to store events in. Default `reqon_execution_events`. */
+    table?: string;
+}
+export declare class PostgresExecutionLog implements ExecutionLogStore {
+    private connectionString;
+    private pool?;
+    private ready?;
+    private readonly table;
+    constructor(connectionString: string, options?: PostgresExecutionLogOptions);
+    private ensure;
+    private init;
+    append(event: ExecutionEvent): Promise<StoredEvent>;
+    read(executionId: string): Promise<StoredEvent[]>;
+    listCheckpoints(mission?: string): Promise<CheckpointRecord[]>;
+    listPauses(): Promise<StoredEvent[]>;
+    /** Drop all rows. Intended for test setup, not production use. */
+    reset(): Promise<void>;
+    /** Release the connection pool. */
+    close(): Promise<void>;
+}