@smithers-orchestrator/scheduler 0.16.0

package/src/nowMs.js

@@ -0,0 +1,6 @@
+/**
+ * @returns {number}
+ */
+export function nowMs() {
+    return Date.now();
+}

package/src/parseStateKey.js

@@ -0,0 +1,15 @@
+/**
+ * @param {string} key
+ * @returns {{ readonly nodeId: string; readonly iteration: number; }}
+ */
+export function parseStateKey(key) {
+    const separator = key.lastIndexOf("::");
+    if (separator < 0) {
+        return { nodeId: key, iteration: 0 };
+    }
+    const iteration = Number(key.slice(separator + 2));
+    return {
+        nodeId: key.slice(0, separator),
+        iteration: Number.isFinite(iteration) ? iteration : 0,
+    };
+}

package/src/retryPolicyToSchedule.js

@@ -0,0 +1,26 @@
+import { Duration, Schedule } from "effect";
+/** @typedef {import("./RetryPolicy.ts").RetryPolicy} RetryPolicy */
+const MAX_RETRY_DELAY_MS = 5 * 60 * 1000;
+/**
+ * Convert a RetryPolicy to an Effect Schedule for use with Effect.retry.
+ *
+ * @param {RetryPolicy} policy
+ * @returns {Schedule.Schedule<unknown>}
+ */
+export function retryPolicyToSchedule(policy) {
+    const base = typeof policy.initialDelayMs === "number"
+        ? Math.max(0, Math.floor(policy.initialDelayMs))
+        : 0;
+    if (base <= 0)
+        return Schedule.stop;
+    const backoff = policy.backoff ?? "fixed";
+    const capDelay = Schedule.modifyDelay((_out, delay) => Duration.min(delay, Duration.millis(MAX_RETRY_DELAY_MS)));
+    switch (backoff) {
+        case "fixed":
+            return capDelay(Schedule.fixed(Duration.millis(base)));
+        case "linear":
+            return capDelay(Schedule.linear(Duration.millis(base)));
+        case "exponential":
+            return capDelay(Schedule.exponential(Duration.millis(base)));
+    }
+}

package/src/retryScheduleDelayMs.js

@@ -0,0 +1,23 @@
+import { Effect, Schedule, ScheduleDecision, ScheduleIntervals } from "effect";
+/**
+ * @param {Schedule.Schedule<unknown>} schedule
+ * @param {number} attempt
+ * @returns {number}
+ */
+export function retryScheduleDelayMs(schedule, attempt) {
+    const safeAttempt = Math.max(1, Math.floor(attempt));
+    let state = schedule.initial;
+    let now = 0;
+    let delayMs = 0;
+    for (let index = 0; index < safeAttempt; index++) {
+        const [nextState, , decision] = Effect.runSync(schedule.step(now, undefined, state));
+        if (ScheduleDecision.isDone(decision)) {
+            return 0;
+        }
+        const nextNow = ScheduleIntervals.start(decision.intervals);
+        delayMs = Math.max(0, nextNow - now);
+        state = nextState;
+        now = nextNow;
+    }
+    return delayMs;
+}

package/src/scheduleTasks.js

@@ -0,0 +1,330 @@
+import { buildStateKey } from "./buildStateKey.js";
+/** @typedef {import("./TaskState.ts").TaskState} TaskState */
+
+/** @typedef {import("./PlanNode.ts").PlanNode} PlanNode */
+/** @typedef {import("./RalphStateMap.ts").RalphStateMap} RalphStateMap */
+/** @typedef {import("./RetryWaitMap.ts").RetryWaitMap} RetryWaitMap */
+/** @typedef {import("./ScheduleResult.ts").ScheduleResult} ScheduleResult */
+/** @typedef {import("@smithers-orchestrator/graph").TaskDescriptor} TaskDescriptor */
+/** @typedef {import("./TaskStateMap.ts").TaskStateMap} TaskStateMap */
+
+/**
+ * @param {TaskState} state
+ * @param {TaskDescriptor} descriptor
+ * @returns {boolean}
+ */
+function isTerminal(state, descriptor) {
+    if (state === "finished" || state === "skipped")
+        return true;
+    if (state === "failed")
+        return descriptor.continueOnFail;
+    return false;
+}
+/**
+ * @param {TaskState} state
+ * @param {TaskDescriptor} descriptor
+ * @returns {boolean}
+ */
+function isTraversalTerminal(state, descriptor) {
+    if (isTerminal(state, descriptor))
+        return true;
+    return Boolean(descriptor.waitAsync &&
+        (state === "waiting-approval" || state === "waiting-event"));
+}
+/**
+ * @param {TaskDescriptor} descriptor
+ * @param {TaskStateMap} states
+ * @param {Map<string, TaskDescriptor>} descriptors
+ * @returns {boolean}
+ */
+function dependenciesSatisfied(descriptor, states, descriptors) {
+    if (!descriptor.dependsOn || descriptor.dependsOn.length === 0)
+        return true;
+    for (const dependencyId of descriptor.dependsOn) {
+        const dependency = descriptors.get(dependencyId);
+        if (!dependency)
+            return false;
+        const state = states.get(buildStateKey(dependency.nodeId, dependency.iteration));
+        if (!state || !isTerminal(state, dependency)) {
+            return false;
+        }
+    }
+    return true;
+}
+/**
+ * @param {PlanNode | null} plan
+ * @param {TaskStateMap} states
+ * @param {Map<string, TaskDescriptor>} descriptors
+ * @param {RalphStateMap} ralphState
+ * @param {RetryWaitMap} retryWait
+ * @param {number} nowMs
+ * @returns {ScheduleResult}
+ */
+export function scheduleTasks(plan, states, descriptors, ralphState, retryWait, nowMs) {
+    const runnable = [];
+    let pendingExists = false;
+    let waitingApprovalExists = false;
+    let waitingEventExists = false;
+    let waitingTimerExists = false;
+    const readyRalphs = [];
+    let continuation;
+    let nextRetryAtMs;
+    let fatalError;
+    const groupUsage = new Map();
+    for (const [stateKey, state] of states) {
+        if (state !== "in-progress")
+            continue;
+        const separator = stateKey.lastIndexOf("::");
+        const nodeId = separator >= 0 ? stateKey.slice(0, separator) : stateKey;
+        const descriptor = descriptors.get(nodeId);
+        if (!descriptor)
+            continue;
+        const groupId = descriptor.parallelGroupId;
+        const cap = descriptor.parallelMaxConcurrency;
+        if (groupId && cap != null) {
+            groupUsage.set(groupId, (groupUsage.get(groupId) ?? 0) + 1);
+        }
+    }
+    /**
+   * @param {PlanNode} node
+   * @returns {{ readonly terminal: boolean; readonly failed: boolean }}
+   */
+    function inspect(node) {
+        switch (node.kind) {
+            case "task": {
+                const descriptor = descriptors.get(node.nodeId);
+                if (!descriptor)
+                    return { terminal: true, failed: false };
+                const state = states.get(buildStateKey(descriptor.nodeId, descriptor.iteration)) ??
+                    "pending";
+                const terminal = state === "finished" ||
+                    state === "skipped" ||
+                    state === "failed" ||
+                    Boolean(descriptor.waitAsync &&
+                        (state === "waiting-approval" || state === "waiting-event"));
+                return { terminal, failed: state === "failed" };
+            }
+            case "sequence":
+            case "group": {
+                for (const child of node.children) {
+                    const result = inspect(child);
+                    if (!result.terminal)
+                        return { terminal: false, failed: false };
+                    if (result.failed)
+                        return { terminal: true, failed: true };
+                }
+                return { terminal: true, failed: false };
+            }
+            case "parallel": {
+                let terminal = true;
+                let failed = false;
+                for (const child of node.children) {
+                    const result = inspect(child);
+                    if (!result.terminal)
+                        terminal = false;
+                    if (result.failed)
+                        failed = true;
+                }
+                return { terminal, failed: terminal && failed };
+            }
+            case "saga": {
+                for (const child of node.actionChildren) {
+                    const result = inspect(child);
+                    if (!result.terminal)
+                        return { terminal: false, failed: false };
+                    if (result.failed)
+                        return { terminal: true, failed: true };
+                }
+                return { terminal: true, failed: false };
+            }
+            case "try-catch-finally": {
+                for (const child of node.tryChildren) {
+                    const result = inspect(child);
+                    if (!result.terminal)
+                        return { terminal: false, failed: false };
+                    if (result.failed)
+                        return { terminal: true, failed: true };
+                }
+                return { terminal: true, failed: false };
+            }
+            default:
+                return { terminal: true, failed: false };
+        }
+    }
+    /**
+   * @param {readonly PlanNode[]} children
+   */
+    function walkSequence(children) {
+        for (const child of children) {
+            const result = walk(child);
+            if (!result.terminal)
+                return { terminal: false };
+        }
+        return { terminal: true };
+    }
+    /**
+   * @param {PlanNode} node
+   * @returns {{ readonly terminal: boolean }}
+   */
+    function walk(node) {
+        switch (node.kind) {
+            case "task": {
+                const descriptor = descriptors.get(node.nodeId);
+                if (!descriptor)
+                    return { terminal: true };
+                const state = states.get(buildStateKey(descriptor.nodeId, descriptor.iteration)) ??
+                    "pending";
+                if (state === "waiting-approval")
+                    waitingApprovalExists = true;
+                if (state === "waiting-event")
+                    waitingEventExists = true;
+                if (state === "waiting-timer")
+                    waitingTimerExists = true;
+                if (state === "pending" || state === "cancelled")
+                    pendingExists = true;
+                const terminal = isTraversalTerminal(state, descriptor);
+                if (!terminal && (state === "pending" || state === "cancelled")) {
+                    if (!dependenciesSatisfied(descriptor, states, descriptors)) {
+                        return { terminal };
+                    }
+                    const retryAt = retryWait.get(buildStateKey(descriptor.nodeId, descriptor.iteration));
+                    if (retryAt && retryAt > nowMs) {
+                        pendingExists = true;
+                        nextRetryAtMs =
+                            nextRetryAtMs == null ? retryAt : Math.min(nextRetryAtMs, retryAt);
+                        return { terminal };
+                    }
+                    const groupId = descriptor.parallelGroupId;
+                    const cap = descriptor.parallelMaxConcurrency;
+                    if (groupId && cap != null) {
+                        const used = groupUsage.get(groupId) ?? 0;
+                        if (used >= cap) {
+                            return { terminal };
+                        }
+                        groupUsage.set(groupId, used + 1);
+                    }
+                    runnable.push(descriptor);
+                }
+                return { terminal };
+            }
+            case "sequence":
+                return walkSequence(node.children);
+            case "parallel": {
+                let terminal = true;
+                for (const child of node.children) {
+                    const result = walk(child);
+                    if (!result.terminal)
+                        terminal = false;
+                }
+                return { terminal };
+            }
+            case "ralph": {
+                const state = ralphState.get(node.id);
+                const done = node.until || state?.done;
+                if (done)
+                    return { terminal: true };
+                let terminal = true;
+                for (const child of node.children) {
+                    const result = walk(child);
+                    if (!result.terminal)
+                        terminal = false;
+                }
+                if (terminal) {
+                    readyRalphs.push({
+                        id: node.id,
+                        until: node.until,
+                        maxIterations: node.maxIterations,
+                        onMaxReached: node.onMaxReached,
+                        continueAsNewEvery: node.continueAsNewEvery,
+                    });
+                }
+                return { terminal: false };
+            }
+            case "continue-as-new":
+                continuation = { stateJson: node.stateJson };
+                return { terminal: false };
+            case "saga": {
+                let completedActions = 0;
+                let failed = false;
+                for (const child of node.actionChildren) {
+                    const status = inspect(child);
+                    if (!status.terminal)
+                        return walk(child);
+                    if (status.failed) {
+                        failed = true;
+                        break;
+                    }
+                    completedActions += 1;
+                }
+                if (!failed)
+                    return { terminal: true };
+                if (node.onFailure === "fail") {
+                    fatalError ??= `Saga ${node.id} failed`;
+                    return { terminal: true };
+                }
+                for (let index = completedActions - 1; index >= 0; index -= 1) {
+                    const compensation = node.compensationChildren[index];
+                    if (!compensation)
+                        continue;
+                    const result = walk(compensation);
+                    if (!result.terminal)
+                        return { terminal: false };
+                }
+                if (node.onFailure === "compensate-and-fail") {
+                    fatalError ??= `Saga ${node.id} failed`;
+                }
+                return { terminal: true };
+            }
+            case "try-catch-finally": {
+                let tryFailed = false;
+                for (const child of node.tryChildren) {
+                    const status = inspect(child);
+                    if (!status.terminal)
+                        return walk(child);
+                    if (status.failed) {
+                        tryFailed = true;
+                        break;
+                    }
+                }
+                if (tryFailed) {
+                    if (node.catchChildren.length > 0) {
+                        const catchResult = walkSequence(node.catchChildren);
+                        if (!catchResult.terminal)
+                            return catchResult;
+                    }
+                    else {
+                        fatalError ??= `TryCatchFinally ${node.id} failed`;
+                    }
+                }
+                const finallyResult = walkSequence(node.finallyChildren);
+                if (!finallyResult.terminal)
+                    return finallyResult;
+                return { terminal: true };
+            }
+            case "group": {
+                let terminal = true;
+                for (const child of node.children) {
+                    const result = walk(child);
+                    if (!result.terminal)
+                        terminal = false;
+                }
+                return { terminal };
+            }
+            default:
+                return { terminal: true };
+        }
+    }
+    if (plan)
+        walk(plan);
+    return {
+        runnable,
+        pendingExists,
+        waitingApprovalExists,
+        waitingEventExists,
+        waitingTimerExists,
+        readyRalphs,
+        continuation,
+        nextRetryAtMs,
+        fatalError,
+    };
+}