reqon-dsl 0.3.0 → 0.4.0

package/dist/trace/store.js

@@ -5,6 +5,7 @@
  * enabling replay and step-by-step inspection of past runs.
  */
 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 trace store
@@ -13,12 +14,15 @@ import { ensureDirectory, writeJsonFile, readJsonFile, listFiles, deleteFile, re
 export class FileTraceStore {
     baseDir;
     initialized;
+    /** Per-trace append serialization to prevent concurrent index collisions. */
+    appendChain = new Map();
     constructor(baseDir = '.reqon-data/traces') {
         this.baseDir = baseDir;
         this.initialized = ensureDirectory(this.baseDir);
     }
     getTraceDir(id) {
-        return join(this.baseDir, id);
+        // Confine the (DSL-influenced) trace id to the traces base directory.
+        return safeJoin(this.baseDir, id);
     }
     getMetadataPath(id) {
         return join(this.getTraceDir(id), 'metadata.json');
@@ -53,13 +57,23 @@ export class FileTraceStore {
             metadata: trace.metadata,
             snapshotCount: trace.snapshots.length,
         };
-        await writeJsonFile(this.getMetadataPath(trace.id), metadata);
-        // Save each snapshot separately for efficient random access
+        // Write all snapshots first, then metadata last. Metadata's snapshotCount
+        // acts as a commit pointer: a crash mid-save leaves either no metadata or
+        // the previous one, never a metadata that claims more snapshots than exist.
         for (let i = 0; i < trace.snapshots.length; i++) {
-            await writeJsonFile(this.getSnapshotPath(trace.id, i), trace.snapshots[i]);
+            await writeJsonFile(this.getSnapshotPath(trace.id, i), trace.snapshots[i], true, 0o600);
         }
+        await writeJsonFile(this.getMetadataPath(trace.id), metadata, true, 0o600);
     }
     async appendSnapshot(traceId, snapshot) {
+        // Serialize appends per trace so two concurrent calls can't compute the
+        // same next index and clobber each other's snapshot file.
+        const run = (this.appendChain.get(traceId) ?? Promise.resolve()).then(() => this.doAppendSnapshot(traceId, snapshot));
+        // Keep the chain alive even if this append rejects.
+        this.appendChain.set(traceId, run.catch(() => { }));
+        return run;
+    }
+    async doAppendSnapshot(traceId, snapshot) {
         await this.initialized;
         const traceDir = this.getTraceDir(traceId);
         await ensureDirectory(traceDir);
@@ -70,32 +84,34 @@ export class FileTraceStore {
         if (metadata && typeof metadata.snapshotCount === 'number') {
             snapshotCount = metadata.snapshotCount;
         }
-        // Save the new snapshot
-        await writeJsonFile(this.getSnapshotPath(traceId, snapshotCount), snapshot);
-        // Update metadata with new count
+        // Write the snapshot first, then commit the new count to metadata so a
+        // crash between the two leaves an uncommitted (ignored) snapshot, never a
+        // count that points past what's on disk.
+        await writeJsonFile(this.getSnapshotPath(traceId, snapshotCount), snapshot, true, 0o600);
         if (metadata) {
             metadata.snapshotCount = snapshotCount + 1;
-            await writeJsonFile(metadataPath, metadata);
+            await writeJsonFile(metadataPath, metadata, true, 0o600);
         }
     }
     async load(id) {
         await this.initialized;
-        const metadata = await this.getMetadata(id);
-        if (!metadata)
+        const raw = await this.readMetadataRaw(id);
+        if (!raw)
             return null;
-        // Load all snapshots
+        const { snapshotCount, metadata } = raw;
+        // Load exactly the committed number of snapshots, by index. Globbing
+        // snapshot_*.json would silently include a half-written extra file or
+        // miss nothing about a gap; loading by the committed count guarantees the
+        // replayed trace matches what save/append actually committed.
         const snapshots = [];
-        const snapshotFiles = await listFiles(this.getTraceDir(id), '.json');
-        for (const file of snapshotFiles) {
-            if (file.includes('snapshot_')) {
-                const parsed = await readJsonFile(file);
-                if (parsed) {
-                    snapshots.push(this.deserializeSnapshot(parsed));
-                }
+        for (let i = 0; i < snapshotCount; i++) {
+            const parsed = await readJsonFile(this.getSnapshotPath(id, i));
+            if (!parsed) {
+                throw new Error(`Trace ${id} is inconsistent: metadata claims ${snapshotCount} snapshots ` +
+                    `but snapshot ${i} is missing.`);
             }
+            snapshots.push(this.deserializeSnapshot(parsed));
         }
-        // Sort by index
-        snapshots.sort((a, b) => a.index - b.index);
         return {
             ...metadata,
             snapshots,
@@ -144,13 +160,22 @@ export class FileTraceStore {
         return traces[0] ?? null;
     }
     async getMetadata(id) {
+        const raw = await this.readMetadataRaw(id);
+        return raw ? raw.metadata : null;
+    }
+    /** Read the metadata file, returning the committed snapshot count and the
+     * trace metadata (snapshotCount stripped). */
+    async readMetadataRaw(id) {
         await this.initialized;
         const parsed = await readJsonFile(this.getMetadataPath(id));
         if (!parsed)
             return null;
         restoreDates(parsed, ['startedAt', 'completedAt']);
-        const { snapshotCount: _snapshotCount, ...rest } = parsed;
-        return rest;
+        const { snapshotCount, ...rest } = parsed;
+        return {
+            snapshotCount: typeof snapshotCount === 'number' ? snapshotCount : 0,
+            metadata: rest,
+        };
     }
 }
 /**

package/dist/utils/deep-merge.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Deep-merge for store upserts.
+ *
+ * A shallow `{ ...existing, ...incoming }` clobbers nested objects: merging
+ * `{ profile: { city: 'LA' } }` over `{ profile: { name: 'Alice' } }` drops
+ * `name`. deepMerge recurses into plain objects so sibling nested fields
+ * survive. Arrays and primitives are replaced wholesale (the incoming value
+ * wins), and neither input is mutated.
+ */
+export declare function deepMerge(target: Record<string, unknown>, source: Record<string, unknown>): Record<string, unknown>;

package/dist/utils/deep-merge.js

@@ -0,0 +1,23 @@
+/**
+ * Deep-merge for store upserts.
+ *
+ * A shallow `{ ...existing, ...incoming }` clobbers nested objects: merging
+ * `{ profile: { city: 'LA' } }` over `{ profile: { name: 'Alice' } }` drops
+ * `name`. deepMerge recurses into plain objects so sibling nested fields
+ * survive. Arrays and primitives are replaced wholesale (the incoming value
+ * wins), and neither input is mutated.
+ */
+function isPlainObject(value) {
+    if (typeof value !== 'object' || value === null || Array.isArray(value))
+        return false;
+    const proto = Object.getPrototypeOf(value);
+    return proto === Object.prototype || proto === null;
+}
+export function deepMerge(target, source) {
+    const out = { ...target };
+    for (const [key, value] of Object.entries(source)) {
+        const existing = out[key];
+        out[key] = isPlainObject(existing) && isPlainObject(value) ? deepMerge(existing, value) : value;
+    }
+    return out;
+}

package/dist/utils/file.d.ts

@@ -11,12 +11,21 @@ export declare function ensureParentDirectory(filePath: string): Promise<void>;
  */
 export declare function serialize(data: unknown, pretty?: boolean): string;
 /**
- * Write JSON data to a file
+ * Atomically write a file: write to a temp file, fsync it, then rename over
+ * the target. A crash or full disk mid-write leaves the original file intact
+ * rather than truncating it (the rename is atomic on POSIX/NTFS).
  */
-export declare function writeJsonFile(filePath: string, data: unknown, pretty?: boolean): Promise<void>;
+export declare function writeFileAtomic(filePath: string, content: string, mode?: number): Promise<void>;
+/** Synchronous counterpart to {@link writeFileAtomic} for flush/exit paths. */
+export declare function writeFileAtomicSync(filePath: string, content: string): void;
 /**
- * Read JSON data from a file
- * Returns null if file doesn't exist or is corrupted
+ * Write JSON data to a file atomically (durable against mid-write crashes).
+ */
+export declare function writeJsonFile(filePath: string, data: unknown, pretty?: boolean, mode?: number): Promise<void>;
+/**
+ * Read JSON data from a file.
+ * Returns null only if the file is absent; throws if it exists but is corrupt
+ * so a truncated/partial file is never silently treated as "empty".
  */
 export declare function readJsonFile<T>(filePath: string): Promise<T | null>;
 /**

package/dist/utils/file.js

@@ -1,5 +1,8 @@
-import { mkdir, readFile, writeFile, access, readdir, unlink } from 'node:fs/promises';
+import { mkdir, readFile, access, readdir, unlink, rename, open } from 'node:fs/promises';
+import { openSync, writeSync, fsyncSync, closeSync, renameSync, unlinkSync } from 'node:fs';
 import { dirname, join } from 'node:path';
+// Monotonic counter to keep concurrent temp-file names unique within a process.
+let tmpCounter = 0;
 /**
  * Ensure a directory exists, creating it if necessary
  */
@@ -24,22 +27,79 @@ export function serialize(data, pretty = true) {
     return pretty ? JSON.stringify(data, null, 2) : JSON.stringify(data);
 }
 /**
- * Write JSON data to a file
+ * Atomically write a file: write to a temp file, fsync it, then rename over
+ * the target. A crash or full disk mid-write leaves the original file intact
+ * rather than truncating it (the rename is atomic on POSIX/NTFS).
  */
-export async function writeJsonFile(filePath, data, pretty = true) {
-    await writeFile(filePath, serialize(data, pretty), 'utf-8');
+export async function writeFileAtomic(filePath, content, mode) {
+    const tmpPath = `${filePath}.${process.pid}.${tmpCounter++}.tmp`;
+    const handle = await open(tmpPath, 'w', mode);
+    try {
+        await handle.writeFile(content, 'utf-8');
+        await handle.sync();
+    }
+    finally {
+        await handle.close();
+    }
+    try {
+        await rename(tmpPath, filePath);
+    }
+    catch (err) {
+        await unlink(tmpPath).catch(() => { });
+        throw err;
+    }
+}
+/** Synchronous counterpart to {@link writeFileAtomic} for flush/exit paths. */
+export function writeFileAtomicSync(filePath, content) {
+    const tmpPath = `${filePath}.${process.pid}.${tmpCounter++}.tmp`;
+    const fd = openSync(tmpPath, 'w');
+    try {
+        writeSync(fd, content);
+        fsyncSync(fd);
+    }
+    finally {
+        closeSync(fd);
+    }
+    try {
+        renameSync(tmpPath, filePath);
+    }
+    catch (err) {
+        try {
+            unlinkSync(tmpPath);
+        }
+        catch {
+            // best-effort cleanup
+        }
+        throw err;
+    }
+}
+/**
+ * Write JSON data to a file atomically (durable against mid-write crashes).
+ */
+export async function writeJsonFile(filePath, data, pretty = true, mode) {
+    await writeFileAtomic(filePath, serialize(data, pretty), mode);
 }
 /**
- * Read JSON data from a file
- * Returns null if file doesn't exist or is corrupted
+ * Read JSON data from a file.
+ * Returns null only if the file is absent; throws if it exists but is corrupt
+ * so a truncated/partial file is never silently treated as "empty".
  */
 export async function readJsonFile(filePath) {
+    let content;
+    try {
+        content = await readFile(filePath, 'utf-8');
+    }
+    catch (err) {
+        if (err.code === 'ENOENT') {
+            return null;
+        }
+        throw err;
+    }
     try {
-        const content = await readFile(filePath, 'utf-8');
         return JSON.parse(content);
     }
-    catch {
-        return null;
+    catch (err) {
+        throw new Error(`Corrupt JSON in ${filePath}: ${err.message}`, { cause: err });
     }
 }
 /**
@@ -48,9 +108,7 @@ export async function readJsonFile(filePath) {
 export async function listFiles(dir, extension) {
     try {
         const entries = await readdir(dir);
-        const filtered = extension
-            ? entries.filter((f) => f.endsWith(extension))
-            : entries;
+        const filtered = extension ? entries.filter((f) => f.endsWith(extension)) : entries;
         return filtered.map((f) => join(dir, f));
     }
     catch {

package/dist/utils/index.d.ts

@@ -1,5 +1,5 @@
 export { sleep } from './async.js';
-export { extractNestedValue, traversePath } from './path.js';
+export { extractNestedValue, traversePath, safeJoin, sanitizeSegment, PathTraversalError, } from './path.js';
 export { type Logger, ConsoleLogger, SilentLogger, createLogger } from './logger.js';
 export { ensureDirectory, ensureParentDirectory, serialize, writeJsonFile, readJsonFile, listFiles, deleteFile, restoreDates, restoreDatesInArray, } from './file.js';
 export { isRecord, isObject, isArrayOf, isString, isNumber, isBoolean, isDefined, isPresent, getProperty, getNestedProperty, hasProperty, hasTypedProperty, } from './type-guards.js';

package/dist/utils/index.js

@@ -1,5 +1,5 @@
 export { sleep } from './async.js';
-export { extractNestedValue, traversePath } from './path.js';
+export { extractNestedValue, traversePath, safeJoin, sanitizeSegment, PathTraversalError, } from './path.js';
 export { ConsoleLogger, SilentLogger, createLogger } from './logger.js';
 export { ensureDirectory, ensureParentDirectory, serialize, writeJsonFile, readJsonFile, listFiles, deleteFile, restoreDates, restoreDatesInArray, } from './file.js';
 export { isRecord, isObject, isArrayOf, isString, isNumber, isBoolean, isDefined, isPresent, getProperty, getNestedProperty, hasProperty, hasTypedProperty, } from './type-guards.js';

package/dist/utils/long-timeout.d.ts

@@ -0,0 +1,19 @@
+/**
+ * Timers for delays beyond Node's 32-bit setTimeout limit.
+ *
+ * Node stores the delay in a 32-bit signed int: anything over 2_147_483_647 ms
+ * (~24.8 days) overflows and the callback fires almost immediately. A multi-week
+ * webhook wait or pause would therefore time out at once. `setLongTimeout`
+ * chains native timeouts so arbitrarily long delays fire at the right time.
+ */
+/** Largest delay (ms) Node's setTimeout handles without overflowing. */
+export declare const MAX_TIMEOUT_MS = 2147483647;
+export interface LongTimeout {
+    /** Cancel the pending timeout. */
+    clear(): void;
+}
+/**
+ * Schedule `callback` to run after `delayMs`, correctly handling delays larger
+ * than {@link MAX_TIMEOUT_MS} by chaining native timeouts.
+ */
+export declare function setLongTimeout(callback: () => void, delayMs: number): LongTimeout;

package/dist/utils/long-timeout.js

@@ -0,0 +1,33 @@
+/**
+ * Timers for delays beyond Node's 32-bit setTimeout limit.
+ *
+ * Node stores the delay in a 32-bit signed int: anything over 2_147_483_647 ms
+ * (~24.8 days) overflows and the callback fires almost immediately. A multi-week
+ * webhook wait or pause would therefore time out at once. `setLongTimeout`
+ * chains native timeouts so arbitrarily long delays fire at the right time.
+ */
+/** Largest delay (ms) Node's setTimeout handles without overflowing. */
+export const MAX_TIMEOUT_MS = 2_147_483_647;
+/**
+ * Schedule `callback` to run after `delayMs`, correctly handling delays larger
+ * than {@link MAX_TIMEOUT_MS} by chaining native timeouts.
+ */
+export function setLongTimeout(callback, delayMs) {
+    let remaining = Math.max(0, delayMs);
+    let timer;
+    const schedule = () => {
+        if (remaining <= MAX_TIMEOUT_MS) {
+            timer = setTimeout(callback, remaining);
+        }
+        else {
+            remaining -= MAX_TIMEOUT_MS;
+            timer = setTimeout(schedule, MAX_TIMEOUT_MS);
+        }
+    };
+    schedule();
+    return {
+        clear() {
+            clearTimeout(timer);
+        },
+    };
+}

package/dist/utils/path.d.ts

@@ -7,6 +7,27 @@
  */
 export declare function extractNestedValue(data: Record<string, unknown>, path: string): unknown;
 /**
- * Traverse an object path and return the value, with fallback lookup
+ * Error thrown when a path segment would escape its base directory.
  */
+export declare class PathTraversalError extends Error {
+    readonly segment: string;
+    readonly baseDir: string;
+    constructor(segment: string, baseDir: string);
+}
+/**
+ * Safely join an untrusted path segment under a base directory, asserting the
+ * result stays confined inside that base. Guards against `../`, absolute paths,
+ * and embedded separators in store names / IDs.
+ *
+ * @throws {PathTraversalError} if the resolved path escapes baseDir
+ */
+export declare function safeJoin(baseDir: string, ...segments: string[]): string;
+/**
+ * Sanitize a single untrusted path segment (e.g. a store name or record ID) so
+ * it cannot traverse directories. Rejects empty, separator-bearing, or
+ * traversal segments rather than silently mangling them.
+ *
+ * @throws {PathTraversalError} if the segment is unsafe
+ */
+export declare function sanitizeSegment(segment: string, baseDir?: string): string;
 export declare function traversePath(parts: string[], current: unknown, fallbackLookup?: (key: string) => unknown): unknown;

package/dist/utils/path.js

@@ -1,6 +1,7 @@
 /**
  * Utility functions for path traversal and value extraction
  */
+import { join, resolve, sep } from 'node:path';
 /**
  * Extract a nested value from an object using dot notation path
  * @example extractNestedValue({ a: { b: 1 } }, 'a.b') // => 1
@@ -19,8 +20,52 @@ export function extractNestedValue(data, path) {
     return value;
 }
 /**
- * Traverse an object path and return the value, with fallback lookup
+ * Error thrown when a path segment would escape its base directory.
  */
+export class PathTraversalError extends Error {
+    segment;
+    baseDir;
+    constructor(segment, baseDir) {
+        super(`Path segment "${segment}" escapes base directory "${baseDir}"`);
+        this.segment = segment;
+        this.baseDir = baseDir;
+        this.name = 'PathTraversalError';
+    }
+}
+/**
+ * Safely join an untrusted path segment under a base directory, asserting the
+ * result stays confined inside that base. Guards against `../`, absolute paths,
+ * and embedded separators in store names / IDs.
+ *
+ * @throws {PathTraversalError} if the resolved path escapes baseDir
+ */
+export function safeJoin(baseDir, ...segments) {
+    const base = resolve(baseDir);
+    const joined = resolve(base, ...segments);
+    // Confined if it equals the base or sits inside it (base + separator prefix).
+    if (joined !== base && !joined.startsWith(base + sep)) {
+        throw new PathTraversalError(join(...segments), baseDir);
+    }
+    return joined;
+}
+/**
+ * Sanitize a single untrusted path segment (e.g. a store name or record ID) so
+ * it cannot traverse directories. Rejects empty, separator-bearing, or
+ * traversal segments rather than silently mangling them.
+ *
+ * @throws {PathTraversalError} if the segment is unsafe
+ */
+export function sanitizeSegment(segment, baseDir = '.') {
+    if (segment.length === 0 ||
+        segment === '.' ||
+        segment === '..' ||
+        segment.includes('/') ||
+        segment.includes('\\') ||
+        segment.includes('\0')) {
+        throw new PathTraversalError(segment, baseDir);
+    }
+    return segment;
+}
 export function traversePath(parts, current, fallbackLookup) {
     let value = current;
     for (let i = 0; i < parts.length; i++) {

package/dist/utils/redact.d.ts

@@ -0,0 +1,22 @@
+/**
+ * Secret redaction for logs, error messages, and durable trace files.
+ *
+ * Uses a denylist of sensitive key-name patterns: any object property whose
+ * key looks like a credential is replaced with {@link REDACTED}. This is a
+ * best-effort guard — it cannot catch a raw secret stored under an innocuous
+ * key — so callers should also avoid persisting cleartext credentials.
+ */
+export declare const REDACTED = "[REDACTED]";
+/** True when a key name looks like it holds a credential. */
+export declare function isSensitiveKey(key: string): boolean;
+/**
+ * Return a deep copy of `value` with any credential-looking properties
+ * replaced by {@link REDACTED}. Non-objects are returned unchanged. Cycles are
+ * handled, and the input is never mutated.
+ */
+export declare function redactSecrets<T>(value: T, seen?: WeakSet<object>): T;
+/**
+ * Redact a named value for logging: if the name itself looks sensitive the
+ * whole value is hidden; otherwise nested credential properties are redacted.
+ */
+export declare function redactNamedValue(name: string, value: unknown): unknown;

package/dist/utils/redact.js

@@ -0,0 +1,42 @@
+/**
+ * Secret redaction for logs, error messages, and durable trace files.
+ *
+ * Uses a denylist of sensitive key-name patterns: any object property whose
+ * key looks like a credential is replaced with {@link REDACTED}. This is a
+ * best-effort guard — it cannot catch a raw secret stored under an innocuous
+ * key — so callers should also avoid persisting cleartext credentials.
+ */
+export const REDACTED = '[REDACTED]';
+/** Key names that should never have their value logged or persisted in clear. */
+const SENSITIVE_KEY = /(pass(word|wd)?|secret|token|auth(orization)?|api[-_]?key|access[-_]?key|client[-_]?secret|credential|cookie|session|bearer|private[-_]?key)/i;
+/** True when a key name looks like it holds a credential. */
+export function isSensitiveKey(key) {
+    return SENSITIVE_KEY.test(key);
+}
+/**
+ * Return a deep copy of `value` with any credential-looking properties
+ * replaced by {@link REDACTED}. Non-objects are returned unchanged. Cycles are
+ * handled, and the input is never mutated.
+ */
+export function redactSecrets(value, seen = new WeakSet()) {
+    if (value === null || typeof value !== 'object')
+        return value;
+    if (seen.has(value))
+        return value;
+    seen.add(value);
+    if (Array.isArray(value)) {
+        return value.map((item) => redactSecrets(item, seen));
+    }
+    const out = {};
+    for (const [key, val] of Object.entries(value)) {
+        out[key] = isSensitiveKey(key) ? REDACTED : redactSecrets(val, seen);
+    }
+    return out;
+}
+/**
+ * Redact a named value for logging: if the name itself looks sensitive the
+ * whole value is hidden; otherwise nested credential properties are redacted.
+ */
+export function redactNamedValue(name, value) {
+    return isSensitiveKey(name) ? REDACTED : redactSecrets(value);
+}

package/dist/webhook/server.d.ts

@@ -45,6 +45,8 @@ export declare class WebhookServer {
      * Wait for webhook events
      */
     waitForEvents(registrationId: string, timeout?: number): Promise<WaitResult>;
+    /** Remove a single waiter, dropping the registration's set when empty. */
+    private removePendingWait;
     /**
      * Unregister a webhook endpoint
      */
@@ -69,6 +71,13 @@ export declare class WebhookServer {
      * Read request body
      */
     private readBody;
+    /** True if a host string is a loopback address. */
+    private isLoopback;
+    /**
+     * Validate the shared secret from Authorization bearer, X-Webhook-Token
+     * header, or a `token` query param.
+     */
+    private authorized;
     /**
      * Extract headers from request
      */