reqon-dsl 0.3.0 → 0.4.0

package/dist/pause/log-store.js

@@ -0,0 +1,98 @@
+/** Coerce a value that may be a Date or an ISO string back to a Date. */
+function toDate(value) {
+    return value instanceof Date ? value : new Date(value);
+}
+function restoreDates(pause) {
+    pause.pausedAt = toDate(pause.pausedAt);
+    pause.expiresAt = toDate(pause.expiresAt);
+    if (pause.resumedAt)
+        pause.resumedAt = toDate(pause.resumedAt);
+    return pause;
+}
+export class LogBackedPauseStore {
+    log;
+    constructor(log) {
+        this.log = log;
+    }
+    async save(pause) {
+        await this.log.append({
+            executionId: pause.executionId,
+            type: 'pause.created',
+            pauseId: pause.id,
+            pause,
+        });
+    }
+    async update(id, updates) {
+        const pause = await this.load(id);
+        if (!pause)
+            throw new Error(`Pause not found: ${id}`);
+        const resumedBy = updates.resumedBy ?? 'manual';
+        await this.log.append({
+            executionId: pause.executionId,
+            type: 'pause.resumed',
+            pauseId: id,
+            resumedBy,
+            status: updates.status ?? 'resumed',
+            resumedAt: (updates.resumedAt ?? new Date()).toISOString(),
+            webhookPayload: updates.webhookPayload,
+        });
+    }
+    async load(id) {
+        const byId = this.foldPauses(await this.log.listPauses());
+        return byId.get(id) ?? null;
+    }
+    async loadByExecution(executionId) {
+        const all = this.foldPauses(await this.log.listPauses());
+        for (const pause of all.values()) {
+            if (pause.executionId === executionId && pause.status === 'waiting')
+                return pause;
+        }
+        return null;
+    }
+    async listActive() {
+        return (await this.allPauses())
+            .filter((p) => p.status === 'waiting')
+            .sort((a, b) => a.expiresAt.getTime() - b.expiresAt.getTime());
+    }
+    async listByMission(mission) {
+        return (await this.allPauses())
+            .filter((p) => p.mission === mission)
+            .sort((a, b) => b.pausedAt.getTime() - a.pausedAt.getTime());
+    }
+    async findExpired() {
+        const now = new Date();
+        return (await this.listActive()).filter((p) => p.expiresAt <= now);
+    }
+    /** Append-only: deletion is a no-op (history is retained in the log). */
+    async delete() { }
+    async allPauses() {
+        return Array.from(this.foldPauses(await this.log.listPauses()).values());
+    }
+    /**
+     * Fold pause events into the latest state per pause id. A `pause.created`
+     * seeds the state; later `pause.resumed` events apply the terminal status.
+     */
+    foldPauses(events) {
+        const byId = new Map();
+        for (const event of events) {
+            if (event.type === 'pause.created' && event.pause) {
+                byId.set(event.pauseId, restoreDates({ ...event.pause }));
+            }
+        }
+        // Apply resumptions after every create is loaded (events aren't ordered).
+        for (const event of events) {
+            if (event.type !== 'pause.resumed')
+                continue;
+            const pause = byId.get(event.pauseId);
+            if (!pause)
+                continue;
+            pause.status = event.status ?? 'resumed';
+            pause.resumedBy = event.resumedBy;
+            if (event.resumedAt)
+                pause.resumedAt = new Date(event.resumedAt);
+            if (event.webhookPayload !== undefined)
+                pause.webhookPayload = event.webhookPayload;
+        }
+        return byId;
+    }
+}

package/dist/pause/manager.d.ts

@@ -46,6 +46,8 @@ export declare class PauseManager {
     private config;
     private pollTimer?;
     private isRunning;
+    private resuming;
+    private isCheckingExpired;
     constructor(config: PauseManagerConfig);
     /**
      * Create a new pause and persist state
@@ -91,6 +93,16 @@ export declare class PauseManager {
      * Get pause status summary
      */
     getStatus(): Promise<PauseStatus>;
+    /**
+     * Transition a pause to `resumed` and fire `onResume` exactly once.
+     *
+     * Returns the resumed pause, or `null` if this call lost the race (another
+     * resume already claimed it, or it is no longer waiting). The claim on
+     * `this.resuming` is synchronous — taken before any `await` — so two
+     * concurrent callers (e.g. the timeout poller and an inbound webhook) can't
+     * both pass the status check and double-fire the side-effecting tail. The
+     * persisted-status re-check makes resume idempotent across poll cycles too.
+     */
     private markResumed;
     private registerWebhookTrigger;
     private cleanupWebhooks;

package/dist/pause/manager.js

@@ -12,6 +12,11 @@ export class PauseManager {
     config;
     pollTimer;
     isRunning = false;
+    // Pause ids currently being resumed. Claimed synchronously before any await
+    // so a timeout poll and an inbound webhook can't both resume the same pause.
+    resuming = new Set();
+    // Prevents a slow resume cycle from overlapping the next poll tick.
+    isCheckingExpired = false;
     constructor(config) {
         this.config = config;
     }
@@ -64,7 +69,15 @@ export class PauseManager {
         if (pause.status !== 'waiting') {
             throw new Error(`Pause ${pauseId} is not waiting (status: ${pause.status})`);
         }
-        return this.markResumed(pause, 'manual');
+        const resumed = await this.markResumed(pause, 'manual');
+        if (!resumed) {
+            // Lost a race with another resume trigger; return the resolved state.
+            const current = await this.config.store.load(pauseId);
+            if (!current)
+                throw new Error(`Pause not found: ${pauseId}`);
+            return current;
+        }
+        return resumed;
     }
     /**
      * Resume a pause by execution ID
@@ -109,9 +122,9 @@ export class PauseManager {
         if (!webhookTrigger) {
             return false;
         }
-        // Mark resumed with webhook payload
-        await this.markResumed(pause, 'webhook', payload);
-        return true;
+        // Mark resumed with webhook payload; false if another trigger won the race.
+        const resumed = await this.markResumed(pause, 'webhook', payload);
+        return resumed !== null;
     }
     /**
      * Start monitoring for expired pauses
@@ -141,13 +154,25 @@ export class PauseManager {
      * Check for and process expired pauses
      */
     async checkExpiredPauses() {
-        const expired = await this.config.store.findExpired();
-        const resumed = [];
-        for (const pause of expired) {
-            const updated = await this.markResumed(pause, 'timeout');
-            resumed.push(updated);
+        // Overlap guard: if a prior cycle's resume callbacks are still running when
+        // the next poll fires, skip rather than reprocessing the same pauses.
+        if (this.isCheckingExpired)
+            return [];
+        this.isCheckingExpired = true;
+        try {
+            const expired = await this.config.store.findExpired();
+            const resumed = [];
+            for (const pause of expired) {
+                const updated = await this.markResumed(pause, 'timeout');
+                // null means another trigger already resumed this pause — skip it.
+                if (updated)
+                    resumed.push(updated);
+            }
+            return resumed;
+        }
+        finally {
+            this.isCheckingExpired = false;
         }
-        return resumed;
     }
     /**
      * Get all active pauses
@@ -184,28 +209,52 @@ export class PauseManager {
             })),
         };
     }
+    /**
+     * Transition a pause to `resumed` and fire `onResume` exactly once.
+     *
+     * Returns the resumed pause, or `null` if this call lost the race (another
+     * resume already claimed it, or it is no longer waiting). The claim on
+     * `this.resuming` is synchronous — taken before any `await` — so two
+     * concurrent callers (e.g. the timeout poller and an inbound webhook) can't
+     * both pass the status check and double-fire the side-effecting tail. The
+     * persisted-status re-check makes resume idempotent across poll cycles too.
+     */
     async markResumed(pause, resumedBy, webhookPayload) {
-        const updates = {
-            status: 'resumed',
-            resumedAt: new Date(),
-            resumedBy,
-        };
-        if (webhookPayload !== undefined) {
-            updates.webhookPayload = webhookPayload;
+        if (this.resuming.has(pause.id)) {
+            return null; // another resume is already in flight for this pause
         }
-        await this.config.store.update(pause.id, updates);
-        // Cleanup webhook registrations
-        await this.cleanupWebhooks(pause);
-        const updated = await this.config.store.load(pause.id);
-        if (!updated) {
-            throw new Error(`Failed to load updated pause: ${pause.id}`);
+        this.resuming.add(pause.id);
+        try {
+            // Re-read the source of truth: a prior cycle may already have resumed it.
+            const current = await this.config.store.load(pause.id);
+            if (!current || current.status !== 'waiting') {
+                return null;
+            }
+            const updates = {
+                status: 'resumed',
+                resumedAt: new Date(),
+                resumedBy,
+            };
+            if (webhookPayload !== undefined) {
+                updates.webhookPayload = webhookPayload;
+            }
+            await this.config.store.update(pause.id, updates);
+            // Cleanup webhook registrations
+            await this.cleanupWebhooks(current);
+            const updated = await this.config.store.load(pause.id);
+            if (!updated) {
+                throw new Error(`Failed to load updated pause: ${pause.id}`);
+            }
+            this.log(`Pause ${pause.id} resumed by ${resumedBy}`);
+            // Trigger callback (the side-effecting pipeline tail) exactly once.
+            if (this.config.onResume) {
+                await this.config.onResume(updated);
+            }
+            return updated;
         }
-        this.log(`Pause ${pause.id} resumed by ${resumedBy}`);
-        // Trigger callback
-        if (this.config.onResume) {
-            await this.config.onResume(updated);
+        finally {
+            this.resuming.delete(pause.id);
         }
-        return updated;
     }
     async registerWebhookTrigger(executionId, path, timeout) {
         if (!this.config.webhookServer) {

package/dist/pause/store.js

@@ -4,7 +4,7 @@
  * Stores pause state for resource-free long pauses,
  * enabling resumption after extended periods.
  */
-import { join } from 'node:path';
+import { safeJoin } from '../utils/path.js';
 import { ensureDirectory, writeJsonFile, readJsonFile, listFiles, deleteFile, restoreDates, } from '../utils/file.js';
 /**
  * File-based pause store
@@ -17,7 +17,7 @@ export class FilePauseStore {
         this.initialized = ensureDirectory(this.baseDir);
     }
     getFilePath(id) {
-        return join(this.baseDir, `${id}.json`);
+        return safeJoin(this.baseDir, `${id}.json`);
     }
     deserialize(parsed) {
         restoreDates(parsed, ['pausedAt', 'expiresAt', 'resumedAt']);
@@ -25,7 +25,9 @@ export class FilePauseStore {
     }
     async save(pause) {
         await this.initialized;
-        await writeJsonFile(this.getFilePath(pause.id), pause);
+        // Pause files hold the captured variables needed to resume (so they can't
+        // be redacted); write owner-only (0o600) so they aren't world-readable.
+        await writeJsonFile(this.getFilePath(pause.id), pause, true, 0o600);
     }
     async load(id) {
         await this.initialized;

package/dist/scheduler/cron-parser.d.ts

@@ -3,7 +3,7 @@ import type { ScheduleDefinition, IntervalSchedule } from '../ast/nodes.js';
  * Parse a cron expression and calculate the next run time
  *
  * Cron format: "minute hour day-of-month month day-of-week"
- * Supports: numbers, ranges (1-5), steps (*​/5), lists (1,3,5), and wildcards (*)
+ * Supports: numbers, ranges (1-5), steps (* /5), lists (1,3,5), and wildcards (*)
  */
 export declare function parseCronExpression(expression: string): CronSchedule;
 interface CronSchedule {
@@ -12,11 +12,18 @@ interface CronSchedule {
     dayOfMonth: number[];
     month: number[];
     dayOfWeek: number[];
+    /** True when day-of-month is not `*` (used for POSIX OR matching). */
+    dayOfMonthRestricted: boolean;
+    /** True when day-of-week is not `*` (used for POSIX OR matching). */
+    dayOfWeekRestricted: boolean;
 }
 /**
- * Calculate the next run time for a cron schedule
+ * Calculate the next run time for a cron schedule, evaluated against
+ * wall-clock time in `timeZone` (default UTC, so DST never shifts the result).
+ * Day-of-month and day-of-week follow POSIX: when both are restricted the
+ * match is their union (OR), not their intersection.
  */
-export declare function getNextCronRun(schedule: CronSchedule, after?: Date): Date;
+export declare function getNextCronRun(schedule: CronSchedule, after?: Date, timeZone?: string): Date;
 /**
  * Convert interval schedule to milliseconds
  */