@astrale-os/sdk 0.6.0-beta.36 → 0.6.0-beta.37

package/dist/execution/workflows/run.js

@@ -1,17 +1,15 @@
 import { declaredErrorFactory } from '../../application/error/index.js';
-import { bindMutation } from '../../application/mutation/execution/executor.js';
-import { bindQuery } from '../../application/query/execution/executor.js';
 import { acceptStepId } from '../../application/workflow/step/index.js';
 import { acceptStepOutput } from '../../application/workflow/step/output.js';
 import { ResponseError } from '../../platform/client/index.js';
-import { bindSession } from '../../platform/client/session/index.js';
 import { validateOutput } from '../invocation/result/index.js';
 import { decodeEnvelope } from './envelope.js';
 import { replayedFailure, terminalFailure } from './failure.js';
+import { keySequence } from './steps.js';
 /** Token of a Workflow that declares none. */
 const DEFAULT_COMPAT = '0';
 const MAXIMUM_SLEEP_MS = 365 * 24 * 60 * 60_000;
-const MAXIMUM_PROMISE_NAME = 128;
+const MAXIMUM_SIGNAL_NAME = 128;
 /** Bounds of one `result` wait and of the durable pause between two of them. */
 const AWAIT_WAIT_MS = 10_000;
 const AWAIT_MAXIMUM_PAUSE_MS = 5 * 60_000;
@@ -81,17 +79,16 @@ function durableContext(input, context, envelope) {
     const execution = envelope.execution;
     const signal = context.request().attemptCompletedSignal;
     const steps = new Set();
-    /** One journaled unit of work acting as the Domain, with keys derived from its name. */
+    /**
+     * One journaled unit of work holding the capabilities of an Action as the Domain alone. Its
+     * Mutations, durable calls and Integration calls share one key sequence derived from its name.
+     */
     const journal = (name, execute) => Promise.resolve(context.run(name, async () => {
-        const deadline = Date.now() + serving.stepTimeoutMs;
-        const session = input.executor(execution.kernel, execution.id, { deadline, signal });
+        const lifetime = { deadline: Date.now() + serving.stepTimeoutMs, signal };
+        const next = await keySequence(execution.id, name);
+        const step = input.steps({ name, execution, next, lifetime });
         try {
-            const kernel = keyed(bindSessionOf(session, deadline, signal), domain, await keySequence(execution.id, name));
-            const output = await execute(Object.freeze({
-                kernel,
-                query: bindQuery(kernel, domain),
-                mutate: bindMutation(kernel, domain),
-            }));
+            const output = await execute(step.authority);
             try {
                 return acceptStepOutput(output);
             }
@@ -103,7 +100,7 @@ function durableContext(input, context, envelope) {
             throw terminalFailure(engine, cause, definition) ?? cause;
         }
         finally {
-            session.close();
+            step.close();
         }
     })).catch((cause) => {
         throw replayedFailure(engine, cause, definition) ?? cause;
@@ -128,6 +125,7 @@ function durableContext(input, context, envelope) {
         error: declaredErrorFactory(definition),
         step: Object.freeze({
             run: step,
+            query: (id, query, value) => step(id, (authority) => authority.query(query, value)),
             mutate: (id, mutation, value) => step(id, (authority) => authority.mutate(mutation, value)),
         }),
         async sleep(durationMs) {
@@ -136,11 +134,26 @@ function durableContext(input, context, envelope) {
             }
             await context.sleep(durationMs);
         },
-        async promise(name) {
-            if (typeof name !== 'string' || name.length === 0 || name.length > MAXIMUM_PROMISE_NAME) {
-                throw new TypeError('Durable promise name must have 1 to 128 characters.');
+        async awaitSignal(name, options) {
+            if (typeof name !== 'string' || name.length === 0 || name.length > MAXIMUM_SIGNAL_NAME) {
+                throw new TypeError('Durable signal name must have 1 to 128 characters.');
+            }
+            if (options === undefined)
+                return (await context.promise(name).get());
+            const timeoutMs = options?.timeoutMs;
+            if (!Number.isSafeInteger(timeoutMs) || timeoutMs < 0 || timeoutMs > MAXIMUM_SLEEP_MS) {
+                throw new TypeError(`Durable signal timeout must be an integer between 0 and ${MAXIMUM_SLEEP_MS} ms.`);
+            }
+            // The engine journals the race between the signal and the timer: a replay settles it alike.
+            try {
+                const value = await context.promise(name).get().orTimeout(timeoutMs);
+                return Object.freeze({ kind: 'signal', value });
+            }
+            catch (cause) {
+                if (cause instanceof engine.TimeoutError)
+                    return Object.freeze({ kind: 'timeout' });
+                throw cause;
             }
-            return (await context.promise(name).get());
         },
         cancelled: (error) => error instanceof engine.CancelledError,
         async awaitExecution(target) {
@@ -167,47 +180,6 @@ function durableContext(input, context, envelope) {
         ...(execution.receiver === undefined ? {} : { self: execution.receiver }),
     });
 }
-function bindSessionOf(session, deadline, signal) {
-    return bindSession(session, { deadline, signal });
-}
-/**
- * Every Mutation and every `invoke` of a durable callable of one Step without its own key carries
- * the next key of the Step's sequence. The sequence restarts with every attempt, so a retried Step
- * replays the same keys: the Kernel answers a Mutation with its receipt and a durable call with the
- * Execution it started, or refuses a request that changed under its key. Any other `invoke` carries
- * no key, because the Kernel accepts one only for a durable Function, and runs again with the Step.
- */
-function keyed(session, domain, next) {
-    const invokeSource = session.invoke;
-    const mutateSource = session.mutate;
-    const invoke = ((reference, value, options) => invokeSource(reference, value, declaredDurable(domain, reference) ? withKey(options, next) : options));
-    const mutate = ((author, options) => mutateSource(author, withKey(options, next)));
-    return Object.freeze({ ...session, invoke, mutate });
-}
-/**
- * Whether the Domain's Schema closure declares the referenced callable durable. An untyped Path
- * names no declaration and a callable outside the closure has none here: both need their own key.
- */
-function declaredDurable(domain, reference) {
-    if (reference === null || typeof reference !== 'object')
-        return false;
-    const key = reference.callable;
-    return (typeof key === 'string' && domain.callable(key)?.execution?.durable === true);
-}
-function withKey(options, next) {
-    if (options?.idempotencyKey !== undefined || options?.body !== undefined)
-        return options;
-    return { ...options, idempotencyKey: next() };
-}
-async function keySequence(execution, name) {
-    const digest = new Uint8Array(await crypto.subtle.digest('SHA-256', new TextEncoder().encode(name)));
-    const prefix = `${execution}.${Array.from(digest.subarray(0, 12), hex).join('')}`;
-    let position = 0;
-    return () => `${prefix}.${++position}`;
-}
-function hex(byte) {
-    return byte.toString(16).padStart(2, '0');
-}
 function signalRequest(input) {
     if (input === null ||
         typeof input !== 'object' ||
@@ -216,7 +188,7 @@ function signalRequest(input) {
         throw new TypeError('Durable signal request is invalid.');
     }
     const { name, value } = input;
-    if (name.length === 0 || name.length > MAXIMUM_PROMISE_NAME) {
+    if (name.length === 0 || name.length > MAXIMUM_SIGNAL_NAME) {
         throw new TypeError('Durable signal name must have 1 to 128 characters.');
     }
     return { name, value: value ?? null };

package/dist/execution/workflows/steps.d.ts

@@ -0,0 +1,42 @@
+import type { IntegrationClientFactory, Integrations } from '../../application/integration/index.js';
+import type { DurableExecution, DurableStepAuthority } from '../../application/workflow/index.js';
+import type { BoundClientSession } from '../../platform/client/session/index.js';
+import type { Domain } from '../../platform/schema/index.js';
+import type { Identity } from '../identity/index.js';
+import type { Lifetime } from '../invocation/lifecycle/index.js';
+type Executor = NonNullable<Identity['executor']>;
+/** One attempt of one Step: its journal name, its Execution, its key sequence and its bounds. */
+export interface StepAttempt {
+    readonly name: string;
+    readonly execution: DurableExecution;
+    /** The next key of the Step's sequence; the sequence restarts with every attempt. */
+    readonly next: () => string;
+    readonly lifetime: Lifetime;
+}
+/** What one Step attempt holds, released once the attempt ends. */
+export interface StepAuthorityBinding {
+    readonly authority: DurableStepAuthority;
+    close(): void;
+}
+/** Bind the capabilities one Step attempt holds. */
+export type StepAuthorities = (attempt: StepAttempt) => StepAuthorityBinding;
+/**
+ * Steps acting as the Domain through a Session of the Execution they belong to: the capabilities of
+ * an Action over the keyed Session, and the Runtime's Integration clients over the same keys.
+ */
+export declare function sessionSteps(input: {
+    readonly executor: Executor;
+    readonly domain: Domain;
+    readonly integrations: IntegrationClientFactory<Integrations>;
+}): StepAuthorities;
+/**
+ * Every Mutation and every `invoke` of a durable callable of one Step without its own key carries
+ * the next key of the Step's sequence. The sequence restarts with every attempt, so a retried Step
+ * replays the same keys: the Kernel answers a Mutation with its receipt and a durable call with the
+ * Execution it started, or refuses a request that changed under its key. Any other `invoke` carries
+ * no key, because the Kernel accepts one only for a durable Function, and runs again with the Step.
+ */
+export declare function keyed<Session extends Pick<BoundClientSession, 'invoke' | 'mutate'>>(session: Session, domain: Domain, next: () => string): Session;
+/** The key sequence of one Step of one Execution: `<execution>.<digest of the name>.<position>`. */
+export declare function keySequence(execution: DurableExecution['id'], name: string): Promise<() => string>;
+export {};

package/dist/execution/workflows/steps.js

@@ -0,0 +1,67 @@
+import { bindSession } from '../../platform/client/session/index.js';
+import { bindCapabilities } from '../invocation/capabilities/index.js';
+import { bindIntegrationAuthentication } from '../invocation/integration/index.js';
+import { stepCalls } from './integrations.js';
+/**
+ * Steps acting as the Domain through a Session of the Execution they belong to: the capabilities of
+ * an Action over the keyed Session, and the Runtime's Integration clients over the same keys.
+ */
+export function sessionSteps(input) {
+    const { executor, domain, integrations } = input;
+    return ({ execution, next, lifetime }) => {
+        const session = executor(execution.kernel, execution.id, lifetime);
+        try {
+            const bound = bindSession(session, lifetime);
+            const self = keyed(bound, domain, next);
+            const auth = bindIntegrationAuthentication(lifetime, bound);
+            const authority = Object.freeze({
+                ...bindCapabilities(domain, { self }),
+                integrations: integrations(stepCalls({ next, lifetime, auth })),
+            });
+            return Object.freeze({ authority, close: () => session.close() });
+        }
+        catch (cause) {
+            session.close();
+            throw cause;
+        }
+    };
+}
+/**
+ * Every Mutation and every `invoke` of a durable callable of one Step without its own key carries
+ * the next key of the Step's sequence. The sequence restarts with every attempt, so a retried Step
+ * replays the same keys: the Kernel answers a Mutation with its receipt and a durable call with the
+ * Execution it started, or refuses a request that changed under its key. Any other `invoke` carries
+ * no key, because the Kernel accepts one only for a durable Function, and runs again with the Step.
+ */
+export function keyed(session, domain, next) {
+    const invokeSource = session.invoke;
+    const mutateSource = session.mutate;
+    const invoke = ((reference, value, options) => invokeSource(reference, value, declaredDurable(domain, reference) ? withKey(options, next) : options));
+    const mutate = ((author, options) => mutateSource(author, withKey(options, next)));
+    return Object.freeze({ ...session, invoke, mutate });
+}
+/**
+ * Whether the Domain's Schema closure declares the referenced callable durable. An untyped Path
+ * names no declaration and a callable outside the closure has none here: both need their own key.
+ */
+function declaredDurable(domain, reference) {
+    if (reference === null || typeof reference !== 'object')
+        return false;
+    const key = reference.callable;
+    return (typeof key === 'string' && domain.callable(key)?.execution?.durable === true);
+}
+function withKey(options, next) {
+    if (options?.idempotencyKey !== undefined || options?.body !== undefined)
+        return options;
+    return { ...options, idempotencyKey: next() };
+}
+/** The key sequence of one Step of one Execution: `<execution>.<digest of the name>.<position>`. */
+export async function keySequence(execution, name) {
+    const digest = new Uint8Array(await crypto.subtle.digest('SHA-256', new TextEncoder().encode(name)));
+    const prefix = `${execution}.${Array.from(digest.subarray(0, 12), hex).join('')}`;
+    let position = 0;
+    return () => `${prefix}.${++position}`;
+}
+function hex(byte) {
+    return byte.toString(16).padStart(2, '0');
+}

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

@@ -0,0 +1,111 @@
+import type { ActionOutputOf, ResolvedDomainOf } from '../../application/action/index.js';
+import type { DeclaredErrors } from '../../application/error/index.js';
+import type { Integrations, Providers } from '../../application/integration/index.js';
+import type { CallableAtWorkflowAddress, WorkflowAddress, WorkflowDefinition } from '../../application/workflow/index.js';
+import type { ExecutionOutcome, ExecutionState } from '../../platform/client/session/index.js';
+import type { NodeId } from '../../platform/graph/node/index.js';
+import type { CallableInputOf, ResolvedMethod, schema } from '../../platform/schema/index.js';
+import type { Value } from '../../platform/value/index.js';
+import type { TestStepCapabilities } from './steps.js';
+export interface TestEngineOptions {
+    /** Start of the virtual clock, in Unix milliseconds; the current time by default. */
+    readonly now?: number;
+    /** Attempts of a run before it pauses; 20 by default, as on a Host. */
+    readonly maxAttempts?: number;
+}
+/**
+ * An in-memory workflow engine that runs durable Workflows with the receiver a Host serves: it
+ * journals each Step, replays the journal on every attempt, retries failed attempts, keeps timers
+ * on a virtual clock, buffers signals, pauses after the last attempt and cancels cooperatively.
+ */
+export interface TestEngine {
+    /** The virtual clock, in Unix milliseconds. */
+    readonly now: number;
+    /** Start one durable Execution and settle it: it ends, waits, or pauses. */
+    start<Schema extends schema.DomainSchema, Address extends WorkflowAddress<Schema>, Definitions extends Integrations, Errors extends DeclaredErrors>(workflow: WorkflowDefinition<Schema, Address, Definitions, Errors>, options: TestStartOptions<CallableAtWorkflowAddress<Schema, Address>, ResolvedDomainOf<Schema>, Definitions>): Promise<TestExecution<ActionOutputOf<CallableAtWorkflowAddress<Schema, Address>>>>;
+    /** Move the virtual clock forward and settle every waiting Execution. */
+    advance(durationMs: number): Promise<void>;
+}
+export type TestStartOptions<Callable, DomainValue, Definitions extends Integrations> = {
+    /** The resolved Schema the Workflow belongs to. */
+    readonly schema: DomainValue;
+    readonly input: CallableInputOf<Callable>;
+    /** The `K.Execution` id; a fresh one by default. */
+    readonly id?: NodeId;
+    /** Who started the Execution; test Identities by default. */
+    readonly initiator?: {
+        readonly principal: NodeId;
+        readonly caller: NodeId;
+    };
+    readonly capabilities?: TestStepCapabilities;
+    /** Steps whose first completion is lost before the journal records it; see `interruptAfter`. */
+    readonly interruptAfter?: readonly string[];
+} & ReceiverOf<Callable> & ProvidersOf<Definitions>;
+type ReceiverOf<Callable> = Callable extends ResolvedMethod<unknown, unknown, false> ? {
+    readonly self: NodeId;
+} : {
+    readonly self?: never;
+};
+type ProvidersOf<Definitions extends Integrations> = keyof Definitions extends never ? {
+    readonly providers?: never;
+} : {
+    readonly providers: Providers<Definitions>;
+};
+/** One durable Execution on a test engine. */
+export interface TestExecution<Output> {
+    readonly id: NodeId;
+    readonly state: Extract<ExecutionState, 'running' | 'waiting' | 'paused' | 'completed' | 'failed' | 'cancelled'>;
+    /** Present once the Execution ended, as `Execution.result` answers it. */
+    readonly outcome: ExecutionOutcome<Output> | undefined;
+    /** What the last failed attempt threw; it is why a paused Execution paused. */
+    readonly failure: unknown;
+    /** Attempts made so far, replays included. */
+    readonly attempts: number;
+    /** The run's journal, in order. */
+    readonly journal: readonly TestJournalEntry[];
+    /**
+     * Deliver `Execution.signal({ name, value })`, then settle. False when a signal already resolved
+     * that name.
+     */
+    signal(name: string, value?: Value): Promise<boolean>;
+    /** Request cooperative cancellation, as `Execution.cancel()`, then settle. */
+    cancel(): Promise<void>;
+    /** Attempt a paused Execution again, as `Execution.resume()`, then settle. */
+    resume(): Promise<void>;
+    /**
+     * Run the Workflow once more from its journal alone, as a restart does, and fail if it runs a Step
+     * again, diverges from the journal, or reaches another outcome.
+     */
+    replay(): Promise<void>;
+    /**
+     * The next time Step `id` completes, lose its result before the journal records it, as a crash
+     * between its effect and the journal does. The engine then retries the Step.
+     */
+    interruptAfter(id: string): void;
+}
+/** One entry of a run's journal. */
+export type TestJournalEntry = {
+    readonly kind: 'run';
+    readonly name: string;
+    readonly settled: boolean;
+    readonly value?: unknown;
+    readonly error?: unknown;
+} | {
+    readonly kind: 'sleep';
+    readonly until: number;
+    readonly settled: boolean;
+} | {
+    readonly kind: 'signal';
+    readonly name: string;
+    readonly settled: boolean;
+    readonly value?: unknown;
+} | {
+    readonly kind: 'race';
+    readonly name: string;
+    readonly until: number;
+    readonly settled: boolean;
+    readonly outcome?: 'signal' | 'timeout' | 'cancelled';
+};
+/** Create an in-memory workflow engine for tests. */
+export declare function createTestEngine(options?: TestEngineOptions): TestEngine;
+export {};