@astrale-os/sdk 0.6.0-beta.4 → 0.6.0-beta.41

package/dist/testing/durable/engine.js

@@ -0,0 +1,619 @@
+import { bindProviders } from '../../application/integration/index.js';
+import { runtimeCallables } from '../../application/runtime/callables.js';
+import { admitWorkflows } from '../../application/runtime/workflows.js';
+import { durableServing } from '../../execution/workflows/options.js';
+import { durableHandlers } from '../../execution/workflows/run.js';
+import { issuer } from '../../platform/auth/index.js';
+import { NodeId as nodeId } from '../../platform/graph/node/index.js';
+import { testSteps } from './steps.js';
+/** Kernel every test Execution names; Steps never reach it. */
+const TEST_KERNEL = issuer.accept('https://kernel.test.astrale.invalid');
+/** Microtask turns without progress after which a blocked attempt counts as suspended. */
+const QUIET_TURNS = 64;
+/** Metadata the Kernel reads a declared failure from. */
+const FAILURE = 'astrale.failure';
+/** Metadata a failed Step attempt's journal entry records it under. */
+const ATTEMPT = 'astrale.attempt';
+/** Name prefix of the wait a Step's code failure prescribes before its next attempt. */
+const BACKOFF = 'retry:';
+class TerminalError extends Error {
+    code;
+    metadata;
+    constructor(message, options) {
+        super(message);
+        this.name = 'TerminalError';
+        this.code = options?.errorCode ?? 500;
+        if (options?.metadata !== undefined)
+            this.metadata = Object.freeze({ ...options.metadata });
+    }
+}
+class CancelledError extends TerminalError {
+    constructor() {
+        super('Cancelled', { errorCode: 409 });
+        this.name = 'CancelledError';
+    }
+}
+class TimeoutError extends TerminalError {
+    constructor() {
+        super('Timeout occurred', { errorCode: 408 });
+        this.name = 'TimeoutError';
+    }
+}
+class RetryableError extends Error {
+    retryAfter;
+    constructor(message, options) {
+        super(message, options?.cause === undefined ? undefined : { cause: options.cause });
+        this.name = 'RetryableError';
+        if (options?.retryAfter !== undefined)
+            this.retryAfter = options.retryAfter;
+    }
+}
+/** The attempt lost its Step result on purpose; the engine retries it. */
+class Interruption extends Error {
+    constructor(step) {
+        super(`Test interruption after Step ${step}, before the journal recorded it.`);
+        this.name = 'Interruption';
+    }
+}
+/** The Workflow did not do what its journal recorded at this position. */
+class JournalMismatch extends Error {
+    constructor(index, recorded, requested) {
+        super(`Journal entry ${index} recorded ${recorded}, but the Workflow requested ${requested}: ` +
+            'code between Steps must be deterministic.');
+        this.name = 'JournalMismatch';
+    }
+}
+/** The promises the test workflow engine's `run` returned: the only ones its combinator accepts. */
+const RUNS = new WeakSet();
+const ENGINE = Object.freeze({
+    createEndpointHandler: () => () => Promise.reject(new Error('A test workflow engine serves no HTTP.')),
+    workflow: (definition) => definition,
+    TerminalError,
+    CancelledError,
+    RetryableError,
+    TimeoutError,
+    RestatePromise: Object.freeze({
+        allSettled(values) {
+            // As the engine refuses a promise it did not create: only its own runs combine.
+            values.forEach((value, index) => {
+                if (!RUNS.has(value)) {
+                    throw new TypeError(`Promise index ${index} used inside the combinator is not a run.`);
+                }
+            });
+            return Promise.allSettled(values);
+        },
+    }),
+});
+/** Create an in-memory workflow engine for tests. */
+export function createTestWorkflowEngine(options = {}) {
+    const serving = durableServing({
+        engine: ENGINE,
+        ...(options.retry === undefined ? {} : { retry: options.retry }),
+    });
+    const maxAttempts = serving.retryPolicy.maxAttempts;
+    let now = options.now ?? Date.now();
+    if (!Number.isFinite(now))
+        throw new TypeError('Test workflow engine now must be finite.');
+    let sequence = 0;
+    const runs = new Set();
+    const clock = { now: () => now };
+    return Object.freeze({
+        get now() {
+            return now;
+        },
+        async start(workflow, input) {
+            sequence += 1;
+            const run = new TestRun(workflow, input, clock, serving, maxAttempts, sequence);
+            runs.add(run);
+            await run.settle();
+            return run.execution;
+        },
+        async advance(durationMs) {
+            if (!Number.isSafeInteger(durationMs) || durationMs < 0) {
+                throw new TypeError('Test workflow engine advance takes a non-negative integer of milliseconds.');
+            }
+            now += durationMs;
+            for (const run of runs)
+                if (run.state === 'waiting')
+                    await run.settle();
+        },
+    });
+}
+class TestRun {
+    clock;
+    maxAttempts;
+    state = 'running';
+    outcome;
+    failure;
+    attempts = 0;
+    journal = [];
+    signals = new Map();
+    interruptions = new Set();
+    cancellation = 'none';
+    /** The waits after a Step's own failures the run did not wait out, which its Steps still spent. */
+    skipped = 0;
+    failures = 0;
+    handlers;
+    envelope;
+    execution;
+    constructor(workflow, input, clock, serving, maxAttempts, sequence) {
+        this.clock = clock;
+        this.maxAttempts = maxAttempts;
+        const domain = input.schema;
+        const [admitted] = admitWorkflows(runtimeCallables(domain), [workflow]);
+        if (admitted === undefined || !admitted.durable) {
+            throw new TypeError(`Workflow ${workflow.address} is not durable: its callable must declare execution: { durable: true }.`);
+        }
+        const providers = (input.providers ?? {});
+        const integrations = Object.fromEntries(Object.entries(providers).map(([name, provider]) => [name, provider.integration]));
+        this.handlers = durableHandlers({
+            kernel: TEST_KERNEL,
+            workflow: admitted,
+            domain,
+            serving,
+            now: () => this.clock.now() + this.skipped,
+            steps: testSteps({
+                domain,
+                capabilities: (input.capabilities ?? {}),
+                integrations: bindProviders(integrations, providers),
+            }),
+        });
+        const id = input.id ?? nodeId(`execution-test-${String(sequence).padStart(6, '0')}`);
+        this.envelope = Object.freeze({
+            execution: id,
+            function: { id: `function-test-${admitted.address}`, version: `sha256:${'0'.repeat(64)}` },
+            kernel: TEST_KERNEL,
+            initiator: input.initiator ?? { principal: 'principal-test', caller: 'caller-test' },
+            input: input.input,
+            ...(input.self === undefined ? {} : { receiver: input.self }),
+        });
+        for (const step of (input.interruptAfter ?? [])) {
+            this.interruptions.add(`step:${step}`);
+        }
+        this.execution = this.view(id);
+    }
+    /** Attempt the run until it ends, waits, or pauses. */
+    async settle() {
+        if (this.ended || this.state === 'paused')
+            return;
+        this.state = 'running';
+        for (;;) {
+            const attempted = await this.attempt('run');
+            if (attempted.kind === 'suspended') {
+                this.state = 'waiting';
+                return;
+            }
+            if (attempted.kind === 'completed') {
+                this.end({ kind: 'completed', value: attempted.value });
+                return;
+            }
+            if (attempted.kind === 'retried') {
+                this.failure = attempted.error;
+                continue;
+            }
+            const { error } = attempted;
+            if (error instanceof TerminalError) {
+                this.end(outcomeOf(error));
+                return;
+            }
+            this.failure = error;
+            this.failures += 1;
+            if (this.failures >= this.maxAttempts) {
+                this.state = 'paused';
+                return;
+            }
+        }
+    }
+    get ended() {
+        return this.state === 'completed' || this.state === 'failed' || this.state === 'cancelled';
+    }
+    end(outcome) {
+        this.outcome = Object.freeze(outcome);
+        this.state = outcome.kind;
+    }
+    /** One attempt of the run: replay the journal, then run on until it ends or blocks. */
+    attempt(mode) {
+        this.attempts += 1;
+        const attempt = new Attempt(this, mode);
+        const running = Promise.resolve()
+            .then(() => this.handlers.run(attempt.context, this.envelope))
+            .then((value) => ({ kind: 'completed', value }), (error) => ({ kind: 'failed', error }))
+            .finally(() => attempt.finish());
+        return Promise.race([running, attempt.suspended(), attempt.ended]).finally(() => attempt.finish());
+    }
+    async signal(name, value) {
+        if (this.ended)
+            throw new Error(`Execution ${String(this.envelope.execution)} has ended.`);
+        const shared = {
+            promise: (promise) => ({
+                resolve: async (resolved) => {
+                    if (this.signals.has(promise))
+                        throw new TerminalError('Promise already resolved.');
+                    this.signals.set(promise, resolved);
+                },
+            }),
+        };
+        const { accepted } = (await this.handlers.signal(shared, { name, value }));
+        if (this.state === 'waiting')
+            await this.settle();
+        return accepted;
+    }
+    async cancel() {
+        if (this.ended)
+            return;
+        if (this.cancellation === 'none')
+            this.cancellation = 'requested';
+        if (this.state === 'paused') {
+            this.failures = 0;
+            this.state = 'running';
+        }
+        await this.settle();
+    }
+    async resume() {
+        if (this.state !== 'paused') {
+            throw new Error(`Execution ${String(this.envelope.execution)} is not paused.`);
+        }
+        this.failures = 0;
+        this.state = 'running';
+        await this.settle();
+    }
+    async replay() {
+        if (this.state === 'paused' || this.state === 'running') {
+            throw new Error('Replay an Execution that ended or waits; resume a paused one first.');
+        }
+        const attempted = await this.attempt('replay');
+        if (this.state === 'waiting') {
+            if (attempted.kind !== 'suspended')
+                throw divergence('ended instead of waiting', attempted);
+            return;
+        }
+        const outcome = attempted.kind === 'completed'
+            ? { kind: 'completed', value: attempted.value }
+            : attempted.kind === 'failed' && attempted.error instanceof TerminalError
+                ? outcomeOf(attempted.error)
+                : undefined;
+        if (outcome === undefined || JSON.stringify(outcome) !== JSON.stringify(this.outcome)) {
+            throw divergence(`did not reach ${JSON.stringify(this.outcome)}`, attempted);
+        }
+    }
+    view(id) {
+        const live = (read) => ({ enumerable: true, get: read });
+        return Object.freeze(Object.defineProperties({
+            id,
+            signal: (name, value) => this.signal(name, value),
+            cancel: () => this.cancel(),
+            resume: () => this.resume(),
+            replay: () => this.replay(),
+            interruptAfter: (step) => {
+                this.interruptions.add(`step:${step}`);
+            },
+        }, {
+            state: live(() => this.state),
+            outcome: live(() => this.outcome),
+            failure: live(() => this.failure),
+            attempts: live(() => this.attempts),
+            journal: live(() => Object.freeze(this.journal.map(snapshot))),
+        }));
+    }
+}
+/**
+ * The engine context of one attempt. Every operation takes the next journal position: a settled
+ * entry answers as it did, a pending one waits, and a new one runs. A replay records nothing new.
+ */
+class Attempt {
+    run;
+    mode;
+    cursor = 0;
+    active = 0;
+    blocked = 0;
+    progress = 0;
+    done = false;
+    controller = new AbortController();
+    end;
+    /** Settles when a Step ends the attempt without reaching the Workflow, as a retry or a crash. */
+    ended = new Promise((resolve) => {
+        this.end = resolve;
+    });
+    context;
+    constructor(run, mode) {
+        this.run = run;
+        this.mode = mode;
+        this.context = Object.freeze({
+            run: (name, action) => {
+                const run = this.journalRun(name, action);
+                RUNS.add(run);
+                return run;
+            },
+            sleep: (durationMs, name) => this.sleep(durationMs, name ?? ''),
+            promise: (name) => ({ get: () => this.promise(name) }),
+            request: () => ({ attemptCompletedSignal: this.controller.signal }),
+        });
+    }
+    finish() {
+        if (this.done)
+            return;
+        this.done = true;
+        this.controller.abort();
+    }
+    /** Resolves once the attempt waits on a pending entry and nothing else can move it. */
+    async suspended() {
+        for (;;) {
+            if (this.done)
+                return new Promise(() => { });
+            if (this.active > 0) {
+                await macrotask();
+                continue;
+            }
+            const before = this.progress;
+            for (let turn = 0; turn < QUIET_TURNS && this.progress === before; turn++) {
+                await Promise.resolve();
+            }
+            if (this.done)
+                return new Promise(() => { });
+            if (this.progress !== before)
+                continue;
+            if (this.blocked > 0)
+                return { kind: 'suspended' };
+            await macrotask();
+        }
+    }
+    take(kind, name) {
+        this.progress += 1;
+        const index = this.cursor++;
+        const recorded = this.run.journal[index];
+        if (recorded !== undefined) {
+            if (recorded.kind !== kind || recorded.name !== name) {
+                throw new JournalMismatch(index, describe(recorded), describe({ kind, name }));
+            }
+            return recorded;
+        }
+        if (this.mode === 'replay') {
+            throw new JournalMismatch(index, 'nothing', describe({ kind, name }));
+        }
+        const entry = { kind, name, settled: false };
+        this.run.journal.push(entry);
+        return entry;
+    }
+    /** Deliver a requested cancellation to the first entry that is not settled yet. */
+    cancelled(entry) {
+        if (this.mode === 'replay' || this.run.cancellation !== 'requested')
+            return false;
+        this.run.cancellation = 'delivered';
+        entry.settled = true;
+        entry.error = new CancelledError();
+        if (entry.kind === 'race')
+            entry.outcome = 'cancelled';
+        return true;
+    }
+    answer(entry) {
+        return entry.error === undefined
+            ? Promise.resolve(entry.value)
+            : Promise.reject(entry.error);
+    }
+    block() {
+        this.blocked += 1;
+        this.progress += 1;
+        return new Promise(() => { });
+    }
+    /**
+     * One journaled `run`. A `TerminalError` settles the entry; any other failure reaches the
+     * Workflow unjournaled, so the `run` runs again on the next attempt.
+     */
+    journalRun(name, action) {
+        let entry;
+        try {
+            entry = this.take('run', name);
+        }
+        catch (cause) {
+            return Promise.reject(cause);
+        }
+        if (entry.settled)
+            return this.answer(entry);
+        if (this.cancelled(entry))
+            return this.answer(entry);
+        if (this.mode === 'replay') {
+            return Promise.reject(new JournalMismatch(this.cursor - 1, 'a pending entry', `${name} to run again`));
+        }
+        this.active += 1;
+        entry.attempts = (entry.attempts ?? 0) + 1;
+        return (async () => {
+            try {
+                const value = await action();
+                // A Step that completes once its attempt ended, as a parallel sibling may, is lost with it.
+                if (this.done)
+                    return this.block();
+                if (this.run.interruptions.delete(name)) {
+                    // A crash after the effect: the run is attempted again, and the Step with it.
+                    this.end({ kind: 'failed', error: new Interruption(name.replace(/^step:/u, '')) });
+                    return this.block();
+                }
+                entry.settled = true;
+                entry.value = value;
+                return value;
+            }
+            catch (cause) {
+                if (this.done)
+                    return this.block();
+                if (cause instanceof TerminalError) {
+                    entry.settled = true;
+                    entry.error = cause;
+                    // A failed Step attempt keeps what it threw on the live error, which tests inspect.
+                    if (cause.metadata?.[ATTEMPT] !== undefined) {
+                        this.run.failure = cause.cause ?? cause;
+                    }
+                    throw cause;
+                }
+                this.run.failure = cause;
+                throw cause;
+            }
+            finally {
+                this.active -= 1;
+                this.progress += 1;
+            }
+        })();
+    }
+    /**
+     * A durable timer on the virtual clock. The wait after a Step's own failure is not waited out: it
+     * settles at once and ends the attempt, as a timer that suspends the run does, and the time it
+     * skipped counts toward the Step's `maxDurationMs`.
+     */
+    sleep(durationMs, name) {
+        let entry;
+        try {
+            entry = this.take('sleep', name);
+        }
+        catch (cause) {
+            return Promise.reject(cause);
+        }
+        entry.until ??= this.run.clock.now() + durationMs;
+        if (entry.settled)
+            return this.answer(entry);
+        if (this.mode === 'run' && name.startsWith(BACKOFF)) {
+            entry.settled = true;
+            // An attempt takes time too: a zero delay still spends a duration budget, by a millisecond.
+            this.run.skipped += Math.max(1, durationMs);
+            this.end({ kind: 'retried', error: this.run.failure });
+            return this.block();
+        }
+        if (this.run.clock.now() >= entry.until) {
+            if (this.mode === 'run')
+                entry.settled = true;
+            return Promise.resolve();
+        }
+        if (this.cancelled(entry))
+            return this.answer(entry);
+        return this.block();
+    }
+    /**
+     * The engine promise of signal `name`. Awaited, it waits for the signal; `orTimeout` races it
+     * against a timer instead, so only one of the two takes a journal position.
+     */
+    promise(name) {
+        let raced = false;
+        const awaited = Promise.resolve().then(() => (raced ? new Promise(() => { }) : this.wait(name)));
+        return Object.assign(awaited, {
+            orTimeout: (millis) => {
+                raced = true;
+                return this.race(name, millis);
+            },
+        });
+    }
+    wait(name) {
+        let entry;
+        try {
+            entry = this.take('signal', name);
+        }
+        catch (cause) {
+            return Promise.reject(cause);
+        }
+        if (entry.settled)
+            return this.answer(entry);
+        if (this.run.signals.has(name))
+            return this.settle(entry, this.run.signals.get(name));
+        if (this.cancelled(entry))
+            return this.answer(entry);
+        return this.block();
+    }
+    race(name, millis) {
+        let entry;
+        try {
+            entry = this.take('race', name);
+        }
+        catch (cause) {
+            return Promise.reject(cause);
+        }
+        entry.until ??= this.run.clock.now() + millis;
+        if (entry.settled)
+            return this.answer(entry);
+        if (this.run.signals.has(name)) {
+            if (this.mode === 'run')
+                entry.outcome = 'signal';
+            return this.settle(entry, this.run.signals.get(name));
+        }
+        if (this.run.clock.now() >= entry.until) {
+            if (this.mode === 'run') {
+                entry.settled = true;
+                entry.outcome = 'timeout';
+                entry.error = new TimeoutError();
+            }
+            return Promise.reject(new TimeoutError());
+        }
+        if (this.cancelled(entry))
+            return this.answer(entry);
+        return this.block();
+    }
+    settle(entry, value) {
+        if (this.mode === 'run') {
+            entry.settled = true;
+            entry.value = value;
+        }
+        return Promise.resolve(value);
+    }
+}
+function outcomeOf(error) {
+    const declared = error.metadata?.[FAILURE];
+    if (declared !== undefined) {
+        const failure = JSON.parse(declared);
+        return {
+            kind: 'failed',
+            error: Object.freeze({
+                ...(failure.family === undefined ? {} : { family: failure.family }),
+                code: failure.code,
+                message: failure.message,
+                ...(failure.details === undefined ? {} : { details: failure.details }),
+            }),
+        };
+    }
+    // As the Kernel decodes it: a bare 409 is the engine's cancellation.
+    if (error.code === 409)
+        return { kind: 'cancelled' };
+    return {
+        kind: 'failed',
+        error: Object.freeze({ code: String(error.code), message: error.message }),
+    };
+}
+function snapshot(entry) {
+    switch (entry.kind) {
+        case 'run':
+            return Object.freeze({
+                kind: 'run',
+                name: entry.name,
+                settled: entry.settled,
+                attempts: entry.attempts ?? 0,
+                ...(entry.settled && entry.error === undefined ? { value: entry.value } : {}),
+                ...(entry.error === undefined ? {} : { error: entry.error }),
+            });
+        case 'sleep':
+            return Object.freeze({
+                kind: 'sleep',
+                ...(entry.name === '' ? {} : { name: entry.name }),
+                until: entry.until,
+                settled: entry.settled,
+            });
+        case 'signal':
+            return Object.freeze({
+                kind: 'signal',
+                name: entry.name,
+                settled: entry.settled,
+                ...(entry.settled && entry.error === undefined ? { value: entry.value } : {}),
+            });
+        case 'race':
+            return Object.freeze({
+                kind: 'race',
+                name: entry.name,
+                until: entry.until,
+                settled: entry.settled,
+                ...(entry.outcome === undefined ? {} : { outcome: entry.outcome }),
+            });
+    }
+}
+function describe(entry) {
+    return entry.name === '' ? entry.kind : `${entry.kind} ${entry.name}`;
+}
+function divergence(reason, attempted) {
+    const cause = attempted.kind === 'failed' ? attempted.error : undefined;
+    return new Error(`Replay diverged: the Workflow ${reason}.`, { cause });
+}
+function macrotask() {
+    return new Promise((resolve) => setTimeout(resolve, 0));
+}

package/dist/testing/durable/index.d.ts

@@ -0,0 +1,3 @@
+export { createTestWorkflowEngine } from './engine.js';
+export type { TestExecution, TestJournalEntry, TestStartOptions, TestWorkflowEngine, TestWorkflowEngineOptions, } from './engine.js';
+export type { TestStepCapabilities } from './steps.js';

package/dist/testing/durable/index.js

@@ -0,0 +1 @@
+export { createTestWorkflowEngine } from './engine.js';

package/dist/testing/durable/steps.d.ts

@@ -0,0 +1,30 @@
+import type { IntegrationClientFactory, Integrations } from '../../application/integration/index.js';
+import type { StepAuthorities } from '../../execution/workflows/steps.js';
+import type { BoundClientSession } from '../../platform/client/session/index.js';
+import type { Domain } from '../../platform/schema/index.js';
+/**
+ * What the Steps of a test Execution reach instead of a Kernel. Each answers the calls a Step makes
+ * through its capabilities; an absent one fails the call that needs it.
+ */
+export interface TestStepCapabilities {
+    /** Answers each Query a Step runs, through `query`, `graph.query` or `step.query`. */
+    readonly query?: (query: object, input: unknown) => unknown;
+    /**
+     * Answers each Mutation a Step runs, through `mutate`, `graph.mutate` or `step.mutate`. `call`
+     * carries the key the Host engine sends, so a retried Step presents the same one.
+     */
+    readonly mutate?: (mutation: object, input: unknown, call: {
+        readonly idempotencyKey: string;
+    }) => unknown;
+    /**
+     * The Kernel Session of a Step. `kernel.invoke` and every `dependencies` call reach its `invoke`,
+     * with the Step's next key in `options.idempotencyKey` when the callee is durable.
+     */
+    readonly kernel?: Partial<BoundClientSession>;
+}
+/** Bind each Step attempt of a test Execution to the test's capabilities, keyed as on a Host. */
+export declare function testSteps(input: {
+    readonly domain: Domain;
+    readonly capabilities: TestStepCapabilities;
+    readonly integrations: IntegrationClientFactory<Integrations>;
+}): StepAuthorities;