@akterjs/effect 0.0.0-stage → 0.1.0

package/dist/host/job/job-durables.sql.mjs

@@ -0,0 +1,136 @@
+import { jobAddress } from "../../contract/job/job-id.pure.mjs";
+import { readStored, storeExit, storedExit, writeStored } from "./job-journal.sql.mjs";
+import { resume, trackedClock } from "./job-runs.pure.mjs";
+import { Array, Clock, Deferred, Duration, Effect, Exit, FiberMap, MutableHashMap, Option } from "effect";
+import { WorkflowEngine } from "effect/workflow";
+// src/host/job/job-durables.sql.ts
+const noWait = 0;
+const located = (engine, executionId) => Option.match(jobAddress(executionId), {
+	onNone: () => Effect.die(`${executionId} is not an Akter job id: start jobs with Akter.start in a command`),
+	onSome: (address) => Effect.flatMap(Deferred.await(engine.locator), (locate) => locate(address))
+});
+const storeOf = ({ engine, executionId }) => Effect.suspend(() => Option.match(MutableHashMap.get(engine.executions, executionId), {
+	onNone: () => Effect.orDie(located(engine, executionId)),
+	onSome: (running) => Effect.succeed(running.store)
+}));
+const executionOf = (engine) => WorkflowEngine.WorkflowInstance.use((instance) => Option.match(MutableHashMap.get(engine.executions, instance.executionId), {
+	onNone: () => Effect.die(`job ${instance.executionId} is not running here`),
+	onSome: Effect.succeed
+}));
+const isCurrent = (executionId) => Effect.map(Effect.serviceOption(WorkflowEngine.WorkflowInstance), (current) => Option.exists(current, (instance) => instance.executionId === executionId));
+const wakeDeferred = (engine, { deferredName, executionId }) => Effect.gen(function* waking() {
+	const wake = Effect.andThen(engine.deferreds.deferredDone(executionId, deferredName), resume({
+		executionId,
+		mode: "automatic",
+		runs: engine
+	}));
+	if (yield* isCurrent(executionId)) return yield* Effect.asVoid(Effect.forkIn(wake, engine.scope));
+	return yield* wake;
+});
+const completed = (engine, store, done) => store.authority(Effect.gen(function* completeWhileOwned() {
+	const { executionId, exit } = done;
+	const entry = `deferred/${done.deferredName}`;
+	const found = yield* readStored({
+		entry,
+		executionId,
+		store
+	});
+	if (Option.isNone(found)) {
+		yield* storeExit({
+			entry,
+			executionId,
+			exit,
+			store
+		});
+		yield* wakeDeferred(engine, done);
+	}
+}));
+/**
+* A signal comes from outside the job, so it locates the actor's current session and keeps it resident until the
+* result is stored, instead of trusting the store a running execution was started with, whose session can close
+* between the lookup and the write. `deferredDone` has no error channel, so a signal this host can't deliver dies
+* with the locator's `ActorUnavailableError`, which names the actor and what to do.
+*/
+const doneDeferred = (engine) => (done) => {
+	const store = Effect.orDie(located(engine, done.executionId));
+	return Effect.scoped(Effect.flatMap(store, (found) => completed(engine, found, done)));
+};
+/** A clock fires inside its own session, which interrupts it on close, so it completes on that session's store. */
+const fireClock = (engine, store, { clock, executionId }) => completed(engine, store, {
+	deferredName: clock.deferred.name,
+	executionId,
+	exit: Exit.void
+});
+const clockDue = (clocked, store) => Effect.gen(function* dueAt() {
+	const { clock, executionId } = clocked;
+	const now = yield* Clock.currentTimeMillis;
+	const entry = `clock/${clock.name}`;
+	const planned = String(now + Duration.toMillis(clock.duration));
+	yield* writeStored({
+		entry,
+		executionId,
+		store,
+		value: planned
+	});
+	const stored = yield* readStored({
+		entry,
+		executionId,
+		store
+	});
+	return {
+		at: Number(Option.getOrElse(stored, () => planned)),
+		now
+	};
+});
+const scheduleClock = (engine) => (_workflow, clocked) => Effect.gen(function* scheduling() {
+	const { clock, executionId } = clocked;
+	const store = yield* storeOf({
+		engine,
+		executionId
+	});
+	const fired = yield* readStored({
+		entry: `deferred/${clock.deferred.name}`,
+		executionId,
+		store
+	});
+	if (Option.isSome(fired)) return;
+	const { at, now } = yield* clockDue(clocked, store);
+	const delay = Duration.millis(Math.max(at - now, noWait));
+	const firing = store.authority(Effect.delay(fireClock(engine, store, clocked), delay));
+	const key = yield* trackedClock({
+		executionId,
+		name: clock.name,
+		runs: engine
+	});
+	yield* FiberMap.run(engine.clocks, key, firing, { onlyIfMissing: true });
+}).pipe(Effect.scoped);
+const deferredResult = (engine) => (deferred) => Effect.flatMap(executionOf(engine), (execution) => execution.store.authority(storedExit({
+	entry: `deferred/${deferred.name}`,
+	executionId: execution.executionId,
+	store: execution.store
+})).pipe(Effect.tap((found) => Effect.sync(() => {
+	if (Option.isNone(found)) execution.waiting.add(deferred.name);
+}))));
+/**
+* Wakes this store's runs that wait on a deferred a committed command has since stored a result for (`Akter.signal`
+* writes it with the command), once the command commits. Only the deferreds a run found empty are checked.
+*/
+const wakeSignalled = ({ engine, store }) => Effect.suspend(() => {
+	const waiting = Array.flatMap(Array.fromIterable(engine.owned.get(store) ?? []), ({ executionId, waiting: names }) => Array.map(Array.fromIterable(names), (deferredName) => ({
+		deferredName,
+		executionId
+	})));
+	return Effect.forEach(waiting, ({ deferredName, executionId }) => Effect.flatMap(readStored({
+		entry: `deferred/${deferredName}`,
+		executionId,
+		store
+	}), (found) => {
+		if (Option.isNone(found)) return Effect.void;
+		return wakeDeferred(engine, {
+			deferredName,
+			executionId,
+			exit: Exit.void
+		});
+	}), { discard: true });
+});
+export { deferredResult, doneDeferred, executionOf, scheduleClock, storeOf, wakeSignalled };

package/dist/host/job/job-engine.adapter.d.mts

@@ -0,0 +1,33 @@
+import { JobStore, Parked } from "./job-runs.pure.mjs";
+import { Locate } from "./job-durables.sql.mjs";
+import { Context, Effect, Layer, Option } from "effect";
+import { WorkflowEngine } from "effect/workflow";
+interface JobEngineService {
+  readonly bind: (locate: Locate) => Effect.Effect<void>;
+  /**
+   * When the oldest activity executing now in this session's jobs started; none while every job is waiting, suspended
+   * or between steps.
+   */
+  readonly busySince: (store: JobStore) => Effect.Effect<Option.Option<number>>;
+  /** Stops and forgets the jobs running on a closing session; the next session's start replays them from the journal. */
+  readonly detach: (store: JobStore) => Effect.Effect<void>;
+  readonly drain: (store: JobStore) => Effect.Effect<boolean>;
+  readonly engine: WorkflowEngine.WorkflowEngine["Service"];
+  /**
+   * This session's jobs with nothing to run now: those that wait on a signal or a clock, until one is stored, and those
+   * whose activity executes, with no waits, until it ends. The session is busy while an activity executes.
+   */
+  readonly parked: (store: JobStore) => Effect.Effect<readonly Parked[]>;
+  /** Jobs held in memory: those running or suspended on an open session. Finished jobs answer from the journal. */
+  readonly retained: Effect.Effect<number>;
+  readonly start: (store: JobStore) => Effect.Effect<void>;
+}
+declare const JobEngine_base: Context.ServiceClass<JobEngine, "@akterjs/effect/host/job/job-engine.adapter/JobEngine", JobEngineService> & {
+  readonly make: Effect.Effect<JobEngineService, never, import("effect/Scope").Scope>;
+};
+export declare class JobEngine extends JobEngine_base {
+  static readonly layer: Layer.Layer<JobEngine, never, never>;
+  static readonly layerShared: Layer.Layer<JobEngine, never, never>;
+  static readonly layerWorkflow: Layer.Layer<JobEngine | WorkflowEngine.WorkflowEngine, never, never>;
+}
+export type { JobStore, Parked };

package/dist/host/job/job-engine.adapter.mjs

@@ -0,0 +1,258 @@
+import { completedRun, decodePayload, openJobs, storeExit, storeResult, storedExit } from "./job-journal.sql.mjs";
+import { awaitRun, detachStore, lastExit, nameOf, parkedOn, resume, settled, startExecution } from "./job-runs.pure.mjs";
+import { deferredResult, doneDeferred, executionOf, scheduleClock, storeOf, wakeSignalled } from "./job-durables.sql.mjs";
+import { Array, Cause, Clock, Context, Deferred, Effect, Exit, Fiber, FiberMap, Layer, MutableHashMap, Option, Predicate, Ref } from "effect";
+import { Workflow, WorkflowEngine } from "effect/workflow";
+// src/host/job/job-engine.adapter.ts
+const completed = (polling) => polling.store.authority(completedRun(polling));
+const startStored = (engine, { job, store }) => Effect.suspend(() => {
+	const entry = MutableHashMap.get(engine.registered, job.job);
+	if (Option.isNone(entry)) {
+		MutableHashMap.set(engine.waiting, job.id, {
+			job,
+			store
+		});
+		return Effect.void;
+	}
+	const { workflow } = entry.value;
+	MutableHashMap.remove(engine.waiting, job.id);
+	return Effect.flatMap(decodePayload({
+		text: job.payload,
+		workflow
+	}), (payload) => startExecution({
+		executionId: job.id,
+		payload,
+		runs: engine,
+		store,
+		workflow
+	}));
+});
+const startOpen = (engine, store) => Effect.suspend(() => {
+	if (engine.detached.has(store)) return Effect.void;
+	return Clock.currentTimeMillis.pipe(Effect.flatMap((now) => store.withSql((sql) => store.exclusive(openJobs({
+		now,
+		sql
+	})))), Effect.orDie, Effect.flatMap((jobs) => Effect.forEach(Array.filter(jobs, (job) => !MutableHashMap.has(engine.executions, job.id)), (job) => startStored(engine, {
+		job,
+		store
+	}), { discard: true })), Effect.andThen(wakeSignalled({
+		engine,
+		store
+	})));
+});
+const register = (engine) => Effect.fnUntraced(function* registering(workflow, execute) {
+	const name = nameOf(workflow);
+	MutableHashMap.set(engine.registered, name, {
+		execute,
+		scope: yield* Effect.scope,
+		workflow
+	});
+	const waiting = Array.filter(Array.fromIterable(MutableHashMap.values(engine.waiting)), ({ job }) => job.job === name);
+	yield* Effect.forEach(waiting, (found) => startStored(engine, found), { discard: true });
+});
+const oneActivity = 1;
+const isInterruptOnly = (result) => Predicate.isTagged(result, "Suspended") || Exit.isFailure(result.exit) && Cause.hasInterruptsOnly(result.exit.cause);
+const runActivity = ({ executeEncoded }, instance) => {
+	const running = WorkflowEngine.WorkflowInstance.initial(instance.workflow, instance.executionId);
+	running.interrupted = instance.interrupted;
+	return executeEncoded.pipe(Workflow.intoResult, Effect.provideService(WorkflowEngine.WorkflowInstance, running));
+};
+const recordActivity = (activity, attempt, execution) => Effect.gen(function* recording() {
+	const stored = {
+		entry: `activity/${activity.name}/${attempt}`,
+		executionId: execution.executionId,
+		store: execution.store
+	};
+	const result = yield* runActivity(activity, execution.instance);
+	if (!isInterruptOnly(result) && Predicate.isTagged(result, "Complete")) yield* storeExit({
+		...stored,
+		exit: result.exit
+	});
+	return result;
+});
+/** Records an activity's start on its run while it executes, so the session's `busySince` reads it. */
+const inFlight = (execution) => (effect) => Effect.acquireUseRelease(Effect.tap(Clock.currentTimeMillis, (started) => Effect.sync(() => execution.activities.push(started))), () => effect, (started) => Effect.sync(() => {
+	execution.activities.splice(execution.activities.indexOf(started), oneActivity);
+}));
+/** When the oldest activity executing in the session's jobs started, if any is. */
+const busySince = (engine) => (store) => Effect.sync(() => {
+	const runs = Array.fromIterable(engine.owned.get(store) ?? []);
+	return Array.reduce(Array.flatMap(runs, (run) => run.activities), Option.none(), (oldest, started) => Option.some(Option.match(oldest, {
+		onNone: () => started,
+		onSome: (at) => Math.min(at, started)
+	})));
+});
+const noWaits = [];
+/**
+* A run whose activity executes now has nothing to run until the activity ends, and its end continues the run in
+* memory. Counting it as due would report it due now on every kick for as long as the activity runs.
+*/
+const activityRunning = (run) => Option.liftPredicate(noWaits, () => Array.isReadonlyArrayNonEmpty(run.activities));
+const parked = (engine) => (store) => Effect.sync(() => {
+	const runs = Array.fromIterable(engine.owned.get(store) ?? []);
+	return Array.getSomes(Array.map(runs, (run) => Option.map(Option.orElse(parkedOn(run), () => activityRunning(run)), (waits) => ({
+		id: run.executionId,
+		waits
+	}))));
+});
+const activityExecute = (engine) => (activity, attempt) => Effect.gen(function* executingActivity() {
+	const instance = yield* WorkflowEngine.WorkflowInstance;
+	const execution = yield* executionOf(engine);
+	return yield* execution.store.authority(Effect.gen(function* activityWhileOwned() {
+		const entry = `activity/${activity.name}/${attempt}`;
+		const found = yield* storedExit({
+			entry,
+			executionId: instance.executionId,
+			store: execution.store
+		});
+		if (Option.isSome(found)) return new Workflow.Complete({ exit: found.value });
+		if (execution.interrupted && !instance.interrupted) return Workflow.Suspended.make({});
+		return yield* recordActivity(activity, attempt, {
+			...execution,
+			instance
+		}).pipe(inFlight(execution));
+	}));
+});
+/** A finished job is no longer in memory, so starting it again answers from its journaled result instead of rerunning it. */
+const startUnfinished = (engine, starting) => Effect.suspend(() => {
+	if (MutableHashMap.has(engine.executions, starting.executionId)) return Effect.void;
+	return Effect.flatMap(completed(starting), Option.match({
+		onNone: () => starting.store.authority(startExecution({
+			...starting,
+			runs: engine
+		})),
+		onSome: () => Effect.void
+	}));
+});
+const poll = (engine) => (workflow, executionId) => Effect.suspend(() => Option.match(Option.flatMap(MutableHashMap.get(engine.executions, executionId), lastExit), {
+	onNone: () => Effect.flatMap(storeOf({
+		engine,
+		executionId
+	}), (store) => completed({
+		executionId,
+		store,
+		workflow
+	})),
+	onSome: (exit) => Effect.flatMap(storeOf({
+		engine,
+		executionId
+	}), (store) => store.authority(Effect.asSome(exit)))
+})).pipe(Effect.scoped);
+function executeWith(engine, workflow, options) {
+	return Effect.gen(function* executing() {
+		const { discard, executionId, parent, payload } = options;
+		if (Predicate.isNotUndefined(parent)) return yield* Effect.die(`${nameOf(workflow)}: a job can't start another job; start it from a command with Akter.start`);
+		const store = yield* storeOf({
+			engine,
+			executionId
+		});
+		const journaled = completed({
+			executionId,
+			store,
+			workflow
+		});
+		yield* startUnfinished(engine, {
+			executionId,
+			payload,
+			store,
+			workflow
+		});
+		if (discard) return yield* Effect.void;
+		return yield* Option.match(MutableHashMap.get(engine.executions, executionId), {
+			onNone: () => Effect.map(journaled, Option.getOrElse(() => Workflow.Suspended.make({}))),
+			onSome: (found) => store.authority(awaitRun(found))
+		});
+	}).pipe(Effect.scoped);
+}
+const interruptRun = (engine, execution, unsafe) => {
+	execution.interrupted = true;
+	execution.interruptedUnsafe ||= unsafe;
+	const wake = resume({
+		executionId: execution.executionId,
+		mode: "explicit",
+		runs: engine
+	});
+	if (unsafe && Option.isSome(execution.fiber)) return Effect.andThen(Fiber.interrupt(execution.fiber.value), wake);
+	return wake;
+};
+const interrupt = (engine, unsafe) => (_workflow, executionId) => Effect.suspend(() => Option.match(MutableHashMap.get(engine.executions, executionId), {
+	onNone: () => Effect.void,
+	onSome: (execution) => interruptRun(engine, execution, unsafe)
+}));
+const awaitComplete = (engine) => (_workflow, executionId) => Effect.suspend(() => Option.match(MutableHashMap.get(engine.executions, executionId), {
+	onNone: () => Effect.never,
+	onSome: (found) => found.store.authority(Deferred.await(found.done))
+}));
+const drain = (engine) => (store) => Effect.gen(function* draining() {
+	yield* startOpen(engine, store);
+	const mine = Array.fromIterable(engine.owned.get(store) ?? []);
+	const waited = yield* Effect.forEach(mine, settled);
+	return Array.some(waited, Boolean);
+});
+const encodedOf = (engine) => ({
+	activityExecute: activityExecute(engine),
+	awaitComplete: awaitComplete(engine),
+	deferredDone: doneDeferred(engine),
+	deferredResult: deferredResult(engine),
+	execute: (workflow, options) => executeWith(engine, workflow, options),
+	interrupt: interrupt(engine, false),
+	interruptUnsafe: interrupt(engine, true),
+	poll: poll(engine),
+	register: register(engine),
+	resume: (_workflow, executionId) => resume({
+		executionId,
+		mode: "explicit",
+		runs: engine
+	}),
+	scheduleClock: scheduleClock(engine)
+});
+const rebinding = Effect.fnUntraced(function* rebinding(locator) {
+	const latest = yield* Ref.make(() => Effect.die("no host has bound a job locator"));
+	const current = (address) => Effect.flatMap(Ref.get(latest), (locate) => locate(address));
+	return (locate) => Effect.andThen(Ref.set(latest, locate), Effect.asVoid(Deferred.succeed(locator, current)));
+});
+const makeEngine = Effect.gen(function* makeEngine() {
+	const engine = {
+		clocks: yield* FiberMap.make(),
+		deferreds: WorkflowEngine.makeDeferredState(),
+		detached: /* @__PURE__ */ new WeakSet(),
+		executions: MutableHashMap.empty(),
+		locator: yield* Deferred.make(),
+		owned: /* @__PURE__ */ new Map(),
+		record: ({ executionId, store, workflow }, exit) => store.authority(storeResult({
+			executionId,
+			exit,
+			store,
+			workflow
+		})),
+		registered: MutableHashMap.empty(),
+		scope: yield* Effect.scope,
+		waiting: MutableHashMap.empty(),
+		workflowEngine: yield* Deferred.make()
+	};
+	const workflowEngine = WorkflowEngine.makeUnsafe(encodedOf(engine));
+	const bind = yield* rebinding(engine.locator);
+	yield* Deferred.succeed(engine.workflowEngine, workflowEngine);
+	return {
+		bind,
+		busySince: busySince(engine),
+		detach: (store) => detachStore({
+			runs: engine,
+			store
+		}),
+		drain: drain(engine),
+		engine: workflowEngine,
+		parked: parked(engine),
+		retained: Effect.sync(() => MutableHashMap.size(engine.executions)),
+		start: (store) => startOpen(engine, store)
+	};
+});
+var JobEngine = class JobEngine extends Context.Service()("@akterjs/effect/host/job/job-engine.adapter/JobEngine", { make: makeEngine }) {
+	static layer = Layer.effect(this, this.make);
+	static layerShared = Layer.effect(this, Effect.flatMap(Effect.serviceOption(this), Option.match({
+		onNone: () => this.make,
+		onSome: Effect.succeed
+	})));
+	static layerWorkflow = Layer.effect(WorkflowEngine.WorkflowEngine, JobEngine.use((jobs) => Effect.succeed(jobs.engine))).pipe(Layer.provideMerge(JobEngine.layer));
+};
+export { JobEngine };

package/dist/host/job/job-journal.sql.d.mts

@@ -0,0 +1,85 @@
+import { StartedJob } from "../../contract/job/started-job.schema.mjs";
+import { JobSignal } from "../../contract/job/job-signal.schema.mjs";
+import { JobStore, Payload, RunResult } from "./job-runs.pure.mjs";
+import { Effect, Exit, Option } from "effect";
+import { Workflow } from "effect/workflow";
+import { SqlClient, SqlError } from "effect/sql";
+type JournalStore = Pick<JobStore, "exclusive" | "finish" | "withSql">;
+interface EntryAddress {
+  readonly entry: string;
+  readonly executionId: string;
+  readonly sql: SqlClient.SqlClient;
+}
+interface EntryWrite extends EntryAddress {
+  readonly value: string;
+}
+interface JobsWrite {
+  readonly jobs: readonly StartedJob[];
+  readonly sql: SqlClient.SqlClient;
+}
+interface SignalsWrite {
+  /** Absent from the outcome of an app built before Akter.signal, which signals nothing. */
+  readonly signals: readonly JobSignal[] | undefined;
+  readonly sql: SqlClient.SqlClient;
+}
+interface StoredEntry {
+  readonly entry: string;
+  readonly executionId: string;
+  readonly store: JournalStore;
+}
+interface WritingEntry extends StoredEntry {
+  readonly value: string;
+}
+interface StoringEntry extends StoredEntry {
+  readonly exit: AnyExit;
+}
+interface StoredResult {
+  readonly executionId: string;
+  readonly store: JournalStore;
+  readonly workflow: Workflow.Any;
+}
+interface StoringResult extends StoredResult {
+  readonly exit: AnyExit;
+}
+interface StoredPayload {
+  readonly text: string;
+  readonly workflow: Workflow.Any;
+}
+type Sql<Value> = Effect.Effect<Value, SqlError.SqlError>;
+type AnyExit = Exit.Exit<unknown, unknown>;
+declare const saveJobs: ({ jobs, sql }: JobsWrite) => Sql<void>;
+/**
+ * Stores each signal as its job's deferred result, in the command's transaction, only while the job is open and the
+ * deferred has none yet. A signal for a job that finished, never started or already has that result does nothing.
+ */
+declare const saveSignals: ({ signals, sql }: SignalsWrite) => Sql<void>;
+/**
+ * Its result check ignores an 'open' entry an older engine left behind when it saved the result. A job whose result
+ * spent a round of retries waits for its next round (its 'undelivered' entry's `next`), so it isn't run before then.
+ */
+declare const openJobs: ({ now, sql }: {
+  readonly now: number;
+  readonly sql: SqlClient.SqlClient;
+}) => Sql<readonly StartedJob[]>;
+/** Creates the open-jobs index once, marking the jobs a journal from before it still has open. */
+declare const prepareOpenJobs: (sql: SqlClient.SqlClient) => Sql<void>;
+declare const readEntry: ({ entry, executionId, sql }: EntryAddress) => Sql<Option.Option<string>>;
+declare const decodePayload: ({ text, workflow }: StoredPayload) => Effect.Effect<Payload>;
+declare const readStored: ({ entry, executionId, store }: StoredEntry) => Effect.Effect<Option.Option<string>>;
+declare const writeStored: ({ store, ...written }: WritingEntry) => Effect.Effect<void>;
+declare const storedExit: (stored: StoredEntry) => Effect.Effect<Option.Option<AnyExit>>;
+declare const storeExit: ({ exit, ...stored }: StoringEntry) => Effect.Effect<void>;
+declare const storeResult: ({ executionId, exit, store, workflow }: StoringResult) => Effect.Effect<void>;
+declare const saveResult: ({ executionId, sql, value }: Omit<EntryWrite, "entry">) => Sql<void>;
+/**
+ * While a job's result can't be stored, its journal says so in an 'undelivered' entry (`undelivered-result.pure.ts`).
+ * The inspector shows it with the job's other entries, and saving the result removes it.
+ */
+declare const markUndelivered: ({ executionId, sql, value }: Omit<EntryWrite, "entry">) => Sql<void>;
+declare const completedRun: (stored: StoredResult) => Effect.Effect<Option.Option<RunResult>>;
+/**
+ * Closes every job still open in a copied database, such as a fork's (ADR 0017): each gets an interrupted result, so
+ * the copy never runs work it inherited. Its parent keeps running its own.
+ */
+declare const cancelOpenJobs: (sql: SqlClient.SqlClient) => Sql<void>;
+export { type AnyExit, type StoredEntry, cancelOpenJobs, completedRun, decodePayload, markUndelivered, openJobs, prepareOpenJobs, readEntry, readStored, saveJobs, saveResult, saveSignals, storeExit, storeResult, storedExit, writeStored };

package/dist/host/job/job-journal.sql.mjs

@@ -0,0 +1,109 @@
+import { JobCodecsOf } from "../../contract/command/command.contract.mjs";
+import { StoredExit } from "../../contract/job/job-signal.schema.mjs";
+import { nameOf } from "./job-runs.pure.mjs";
+import { Array, Context, Effect, Exit, Option, Predicate, Schema } from "effect";
+import { Workflow } from "effect/workflow";
+// src/host/job/job-journal.sql.ts
+const insertEntry = ({ entry, executionId, sql, value }) => Effect.asVoid(sql`INSERT INTO akter_workflow (execution_id, entry, value) VALUES (${executionId}, ${entry}, ${value}) ON CONFLICT (execution_id, entry) DO NOTHING`);
+/**
+* A job's 'open' entry lives from the command that starts it to the transaction that saves its result. The partial
+* index holds only those entries, so finding the open jobs costs the jobs still open, not every job the actor ran.
+*/
+const openIndex = "akter_workflow_open";
+const saveJobs = ({ jobs, sql }) => Effect.forEach(jobs, ({ id, job, payload }) => Effect.all([
+	insertEntry({
+		entry: "job",
+		executionId: id,
+		sql,
+		value: job
+	}),
+	insertEntry({
+		entry: "payload",
+		executionId: id,
+		sql,
+		value: payload
+	}),
+	insertEntry({
+		entry: "open",
+		executionId: id,
+		sql,
+		value: ""
+	})
+], { discard: true }), { discard: true });
+/**
+* Stores each signal as its job's deferred result, in the command's transaction, only while the job is open and the
+* deferred has none yet. A signal for a job that finished, never started or already has that result does nothing.
+*/
+const saveSignals = ({ signals, sql }) => Effect.forEach(signals ?? [], ({ deferred, exit, id }) => sql`INSERT INTO akter_workflow (execution_id, entry, value) SELECT ${id}, ${`deferred/${deferred}`}, ${exit} WHERE EXISTS (SELECT 1 FROM akter_workflow WHERE execution_id = ${id} AND entry = 'open') AND NOT EXISTS (SELECT 1 FROM akter_workflow WHERE execution_id = ${id} AND entry = 'result') ON CONFLICT (execution_id, entry) DO NOTHING`, { discard: true });
+/**
+* Its result check ignores an 'open' entry an older engine left behind when it saved the result. A job whose result
+* spent a round of retries waits for its next round (its 'undelivered' entry's `next`), so it isn't run before then.
+*/
+const openJobs = ({ now, sql }) => sql`SELECT open.execution_id AS id, started.value AS job, payload.value AS payload FROM akter_workflow open INDEXED BY akter_workflow_open JOIN akter_workflow started ON started.execution_id = open.execution_id AND started.entry = 'job' JOIN akter_workflow payload ON payload.execution_id = open.execution_id AND payload.entry = 'payload' WHERE open.entry = 'open' AND NOT EXISTS (SELECT 1 FROM akter_workflow result WHERE result.execution_id = open.execution_id AND result.entry = 'result') AND NOT EXISTS (SELECT 1 FROM akter_workflow stalled WHERE stalled.execution_id = open.execution_id AND stalled.entry = 'undelivered' AND json_extract(stalled.value, '$.next') > ${now}) ORDER BY started.rowid`;
+const hasOpenIndex = (sql) => Effect.map(sql`SELECT 1 FROM sqlite_master WHERE type = 'index' AND name = ${openIndex}`, Array.isReadonlyArrayNonEmpty);
+const indexOpenJobs = (sql) => sql.withTransaction(Effect.andThen(sql`CREATE INDEX akter_workflow_open ON akter_workflow (execution_id) WHERE entry = 'open'`, sql`INSERT OR IGNORE INTO akter_workflow (execution_id, entry, value) SELECT started.execution_id, 'open', '' FROM akter_workflow started WHERE started.entry = 'job' AND NOT EXISTS (SELECT 1 FROM akter_workflow result WHERE result.execution_id = started.execution_id AND result.entry = 'result')`));
+/** Creates the open-jobs index once, marking the jobs a journal from before it still has open. */
+const prepareOpenJobs = (sql) => Effect.flatMap(hasOpenIndex(sql), (indexed) => {
+	if (indexed) return Effect.void;
+	return indexOpenJobs(sql);
+});
+const readEntry = ({ entry, executionId, sql }) => Effect.map(sql`SELECT value FROM akter_workflow WHERE execution_id = ${executionId} AND entry = ${entry}`, (rows) => Option.map(Array.head(rows), (row) => row.value));
+const encodedExit = StoredExit;
+const codecsOf = (workflow) => Option.match(Context.get(workflow.annotations, JobCodecsOf), {
+	onNone: () => Effect.die(`${nameOf(workflow)} is not an Akter job: declare it in Akter.make's jobs`),
+	onSome: Effect.succeed
+});
+const decodePayload = ({ text, workflow }) => Effect.flatMap(codecsOf(workflow), (codecs) => codecs.decodePayload(text).pipe(Effect.filterOrFail(Predicate.isObject, () => `${nameOf(workflow)} has a payload that is not a struct`), Effect.orDie));
+const readStored = ({ entry, executionId, store }) => Effect.orDie(store.withSql((sql) => store.exclusive(readEntry({
+	entry,
+	executionId,
+	sql
+}))));
+const writeStored = ({ store, ...written }) => Effect.orDie(store.withSql((sql) => store.exclusive(insertEntry({
+	...written,
+	sql
+}))));
+const decodedWith = (decode) => (found) => Option.map(found, decode).pipe(Effect.transposeOption, Effect.orDie);
+const storedExit = (stored) => Effect.flatMap(readStored(stored), decodedWith(Schema.decodeEffect(encodedExit)));
+const storeExit = ({ exit, ...stored }) => Schema.encodeEffect(encodedExit)(exit).pipe(Effect.orDie, Effect.flatMap((value) => writeStored({
+	...stored,
+	value
+})));
+const storeResult = ({ executionId, exit, store, workflow }) => Effect.gen(function* storingResult() {
+	const codecs = yield* codecsOf(workflow);
+	const result = yield* Effect.orDie(codecs.encodeResult(exit));
+	yield* store.finish({
+		executionId,
+		job: nameOf(workflow),
+		result
+	});
+});
+const saveResult = ({ executionId, sql, value }) => Effect.andThen(insertEntry({
+	entry: "result",
+	executionId,
+	sql,
+	value
+}), sql`DELETE FROM akter_workflow WHERE execution_id = ${executionId} AND entry IN ('open', 'undelivered')`);
+/**
+* While a job's result can't be stored, its journal says so in an 'undelivered' entry (`undelivered-result.pure.ts`).
+* The inspector shows it with the job's other entries, and saving the result removes it.
+*/
+const markUndelivered = ({ executionId, sql, value }) => Effect.asVoid(sql`INSERT INTO akter_workflow (execution_id, entry, value) VALUES (${executionId}, 'undelivered', ${value}) ON CONFLICT (execution_id, entry) DO UPDATE SET value = excluded.value`);
+const storedResult = (stored) => Effect.gen(function* readingResult() {
+	const codecs = yield* codecsOf(stored.workflow);
+	const found = yield* readStored({
+		...stored,
+		entry: "result"
+	});
+	return yield* decodedWith(codecs.decodeResult)(found);
+});
+const completedRun = (stored) => Effect.map(storedResult(stored), Option.map((exit) => new Workflow.Complete({ exit })));
+/**
+* Closes every job still open in a copied database, such as a fork's (ADR 0017): each gets an interrupted result, so
+* the copy never runs work it inherited. Its parent keeps running its own.
+*/
+const cancelOpenJobs = (sql) => Effect.gen(function* cancelInheritedJobs() {
+	yield* sql`INSERT INTO akter_workflow (execution_id, entry, value) SELECT execution_id, 'result', ${yield* Effect.orDie(Schema.encodeEffect(encodedExit)(Exit.interrupt()))} FROM akter_workflow WHERE entry = 'open' ON CONFLICT (execution_id, entry) DO NOTHING`;
+	yield* sql`DELETE FROM akter_workflow WHERE entry = 'open'`;
+});
+export { cancelOpenJobs, completedRun, decodePayload, markUndelivered, openJobs, prepareOpenJobs, readEntry, readStored, saveJobs, saveResult, saveSignals, storeExit, storeResult, storedExit, writeStored };

package/dist/host/job/job-results.service.d.mts

@@ -0,0 +1,37 @@
+import { CommandRunner } from "../command/command-runner.service.mjs";
+import { Finishing, Guard, Stalling, Unstored } from "./undelivered-result.pure.mjs";
+import { Context, Effect, Layer } from "effect";
+import { SqlError } from "effect/sql";
+declare const JobResults_base: Context.ServiceClass<JobResults, "@akterjs/effect/host/job/job-results.service/JobResults", {
+  /**
+   * Stores the result and runs its command in one transaction. Past the storage ceiling a result command that grows
+   * the database is refused, and the result rolls back with it, so a retry delivers it once the store has room.
+   */
+  readonly deliver: (finishing: Finishing) => Effect.Effect<void, Unstored>;
+  /**
+   * Delivers with retries: a failed attempt waits out a capped backoff, and the job's journal shows it as
+   * undelivered. After the last retry the job stays open and is due again later, on a longer capped backoff.
+   */
+  readonly settle: (finishing: Finishing, guard: Guard) => Effect.Effect<void>;
+  /** Records a run that ended before its result was stored as a spent round, so the job is due at its next. */
+  readonly stall: (stalled: Stalling, guard: Guard) => Effect.Effect<void, SqlError.SqlError>;
+}> & {
+  readonly make: Effect.Effect<{
+    /**
+     * Stores the result and runs its command in one transaction. Past the storage ceiling a result command that grows
+     * the database is refused, and the result rolls back with it, so a retry delivers it once the store has room.
+     */
+    readonly deliver: (finishing: Finishing) => Effect.Effect<void, Unstored>;
+    /**
+     * Delivers with retries: a failed attempt waits out a capped backoff, and the job's journal shows it as
+     * undelivered. After the last retry the job stays open and is due again later, on a longer capped backoff.
+     */
+    readonly settle: (finishing: Finishing, guard: Guard) => Effect.Effect<void>;
+    /** Records a run that ended before its result was stored as a spent round, so the job is due at its next. */
+    readonly stall: (stalled: Stalling, guard: Guard) => Effect.Effect<void, SqlError.SqlError>;
+  }, never, CommandRunner>;
+};
+export declare class JobResults extends JobResults_base {
+  static readonly layer: Layer.Layer<JobResults, never, never>;
+}
+export {};