@plitzi/sdk-server 0.37.1 → 0.37.2

package/dist/modules/actions/jobs/memoryQueue.js

@@ -0,0 +1,178 @@
+//#region src/modules/actions/jobs/memoryQueue.ts
+var TERMINAL = /* @__PURE__ */ new Set([
+	"succeeded",
+	"failed",
+	"dead",
+	"cancelled"
+]);
+/**
+* The default queue: one process's Maps.
+*
+* Correct for a deployment that runs ONE replica, which is most self-hosted ones, and honest about the rest — a
+* second replica running on this gets its own schedules and its own jobs, so a nightly digest goes out twice. The
+* cure is any store the replicas share, behind the same {@link ActionJobQueue} seam.
+*
+* It keeps the contract exactly, rather than approximately: enqueue is idempotent by id, a claim reaps lapsed
+* leases, and every instant is read here rather than accepted from a caller. A test that passes against this one
+* is testing the rules a shared store has to keep too.
+*/
+var createMemoryJobQueue = ({ retainFinished = 500, clock = Date.now } = {}) => {
+	const jobs = /* @__PURE__ */ new Map();
+	const schedules = /* @__PURE__ */ new Map();
+	const key = (spaceId, actionId) => `${spaceId}:${actionId}`;
+	const now = () => clock();
+	/** Oldest finished jobs first, so the bound drops history rather than anything anybody is waiting on. */
+	const evict = () => {
+		const finished = [...jobs.values()].filter((job) => TERMINAL.has(job.status)).sort((a, b) => a.updatedAt - b.updatedAt);
+		for (const job of finished.slice(0, finished.length - retainFinished)) jobs.delete(job.id);
+	};
+	const owned = (spaceIds, jobId) => {
+		const job = jobs.get(jobId);
+		return job && spaceIds.includes(job.spaceId) ? job : void 0;
+	};
+	/** Numbered by the history itself, not by `attempts`: an operator who repeats a finished job starts its attempt
+	*  count again, and the record of what has already been tried must not start again with it. */
+	const appendAttempt = (job, attempt) => {
+		job.history = [...job.history, {
+			...attempt,
+			attempt: job.history.length + 1
+		}];
+	};
+	return {
+		now: () => Promise.resolve(new Date(now())),
+		enqueue: (job) => {
+			if (jobs.has(job.id)) return Promise.resolve(false);
+			const at = now();
+			jobs.set(job.id, {
+				...job,
+				status: "pending",
+				runAt: job.dueAt,
+				attempts: 0,
+				createdAt: at,
+				updatedAt: at,
+				history: []
+			});
+			evict();
+			return Promise.resolve(true);
+		},
+		claim: ({ workerId, leaseMs, limit }) => {
+			const at = now();
+			const taken = [];
+			const candidates = [...jobs.values()].filter((job) => job.status === "pending" && job.runAt <= at || job.status === "running" && (job.leaseUntil ?? 0) < at).sort((a, b) => a.runAt - b.runAt);
+			for (const job of candidates.slice(0, limit)) {
+				if (job.status === "running") appendAttempt(job, {
+					status: "lost",
+					startedAt: job.updatedAt,
+					endedAt: at,
+					workerId: job.workerId ?? "unknown",
+					error: "the worker holding this job stopped reporting"
+				});
+				job.status = "running";
+				job.attempts += 1;
+				job.workerId = workerId;
+				job.leaseUntil = at + leaseMs;
+				job.updatedAt = at;
+				taken.push({ ...job });
+			}
+			return Promise.resolve(taken);
+		},
+		heartbeat: ({ jobIds, workerId, leaseMs }) => {
+			const at = now();
+			const cancelled = [];
+			for (const id of jobIds) {
+				const job = jobs.get(id);
+				if (!job || job.workerId !== workerId || job.status !== "running") continue;
+				job.leaseUntil = at + leaseMs;
+				if (job.cancelRequested) cancelled.push(id);
+			}
+			return Promise.resolve(cancelled);
+		},
+		settle: ({ jobId, workerId, status, delayMs, runId, error, attempt }) => {
+			const job = jobs.get(jobId);
+			if (!job || job.workerId !== workerId) return Promise.resolve();
+			const at = now();
+			if (attempt) appendAttempt(job, {
+				...attempt,
+				startedAt: job.updatedAt,
+				endedAt: at
+			});
+			job.status = status;
+			job.updatedAt = at;
+			job.leaseUntil = void 0;
+			job.error = error;
+			if (runId) job.runId = runId;
+			if (status === "pending") {
+				job.runAt = at + (delayMs ?? 0);
+				job.workerId = void 0;
+				if (!attempt) job.attempts = Math.max(0, job.attempts - 1);
+			}
+			evict();
+			return Promise.resolve();
+		},
+		dueSchedules: (limit) => {
+			const at = now();
+			return Promise.resolve([...schedules.values()].filter((schedule) => schedule.enabled && schedule.nextRunAt <= at).sort((a, b) => a.nextRunAt - b.nextRunAt).slice(0, limit).map((schedule) => ({ ...schedule })));
+		},
+		advanceSchedule: ({ spaceId, actionId, from, to, missed }) => {
+			const schedule = schedules.get(key(spaceId, actionId));
+			if (!schedule || schedule.nextRunAt !== from) return Promise.resolve(false);
+			schedule.nextRunAt = to;
+			schedule.lastFireAt = from;
+			schedule.missed += missed;
+			schedule.updatedAt = now();
+			return Promise.resolve(true);
+		},
+		putSchedules: ({ spaceId, schedules: incoming }) => {
+			const at = now();
+			const keep = new Set(incoming.map((schedule) => key(spaceId, schedule.actionId)));
+			for (const existing of schedules.keys()) if (existing.startsWith(`${spaceId}:`) && !keep.has(existing)) schedules.delete(existing);
+			for (const incomingSchedule of incoming) {
+				const id = key(spaceId, incomingSchedule.actionId);
+				const existing = schedules.get(id);
+				const unchanged = existing && existing.cron === incomingSchedule.cron && existing.timezone === incomingSchedule.timezone && existing.environment === incomingSchedule.environment;
+				schedules.set(id, {
+					...incomingSchedule,
+					missed: existing?.missed ?? 0,
+					...existing?.lastFireAt === void 0 ? {} : { lastFireAt: existing.lastFireAt },
+					nextRunAt: unchanged ? existing.nextRunAt : incomingSchedule.nextRunAt,
+					updatedAt: at
+				});
+			}
+			return Promise.resolve();
+		},
+		listJobs: ({ spaceIds, actionId, status, limit, offset }) => {
+			const matching = [...jobs.values()].filter((job) => spaceIds.includes(job.spaceId) && (actionId === void 0 || job.actionId === actionId) && (status === void 0 || job.status === status)).sort((a, b) => b.updatedAt - a.updatedAt);
+			return Promise.resolve({
+				jobs: matching.slice(offset, offset + limit).map((job) => ({ ...job })),
+				total: matching.length
+			});
+		},
+		getJob: (spaceIds, jobId) => Promise.resolve(owned(spaceIds, jobId)),
+		listSchedules: (spaceIds) => Promise.resolve([...schedules.values()].filter((schedule) => spaceIds.includes(schedule.spaceId))),
+		requeue: (spaceIds, jobId) => {
+			const job = owned(spaceIds, jobId);
+			if (!job || !TERMINAL.has(job.status)) return Promise.resolve(false);
+			job.status = "pending";
+			job.runAt = now();
+			job.attempts = 0;
+			job.workerId = void 0;
+			job.leaseUntil = void 0;
+			job.cancelRequested = false;
+			job.error = void 0;
+			job.updatedAt = now();
+			return Promise.resolve(true);
+		},
+		cancel: (spaceIds, jobId) => {
+			const job = owned(spaceIds, jobId);
+			if (!job || TERMINAL.has(job.status)) return Promise.resolve(false);
+			if (job.status === "pending") {
+				job.status = "cancelled";
+				job.workerId = void 0;
+			} else job.cancelRequested = true;
+			job.updatedAt = now();
+			return Promise.resolve(true);
+		}
+	};
+};
+//#endregion
+export { createMemoryJobQueue };

package/dist/modules/actions/jobs/memoryStores.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/modules/actions/jobs/scheduler.d.ts

@@ -0,0 +1,62 @@
+import { ActionLookups } from '../types';
+import { ActionJobQueue, Environment } from '@plitzi/sdk-shared';
+export type SchedulerOptions = {
+    queue: ActionJobQueue;
+    lookups: ActionLookups;
+    /** Which environment scheduled runs execute in. Defaults to `main`, the document the builder edits. */
+    environment?: Environment;
+    /** How often this replica looks for due schedules. Default 15s — the resolution of a cron is a minute. */
+    pollMs?: number;
+    /** Schedules swept per pass. */
+    batch?: number;
+    /** Attempts a job produced here is given. */
+    maxAttempts?: number;
+    /** How often a space's schedules are re-derived from its documents. Default 15 minutes. A deployment that
+     *  reconciles on save needs this only as a safety net. */
+    reconcileMs?: number;
+    /** The spaces to reconcile, for a server that serves a known few. `listScheduledSpaces` wins over it. */
+    spaces?: number[];
+    onError?: (error: unknown) => void;
+};
+export type SweepResult = {
+    /** Fires this pass turned into jobs. */
+    enqueued: string[];
+    /** Fires another replica had already enqueued. Not a problem: it is the guarantee working. */
+    duplicates: string[];
+    /** Fires that went by while nothing was running, by schedule. */
+    missed: {
+        spaceId: number;
+        actionId: string;
+        count: number;
+    }[];
+};
+export type Scheduler = {
+    /** One pass. Exposed because a deployment driving this from its own cron — a k8s CronJob, a queue tick — needs
+     *  a way in that is not a timer, and because a test must not have to wait for one. */
+    sweep: () => Promise<SweepResult>;
+    /** Re-derives one space's schedules from its action documents. Called by a deployment whenever they change. */
+    reconcile: (spaceId: number) => Promise<void>;
+    start: () => void;
+    stop: () => void;
+};
+/**
+ * Turns due schedules into jobs. Nothing else.
+ *
+ * **There is no leader.** Every replica sweeps, and that is safe because a fire's job id is derived from the fire's
+ * own stored instant: two replicas reaching the same fire write the same id, and the queue keeps the first. A
+ * leader lock would only add a way for the cluster to have no producer at all for a minute — which is exactly the
+ * failure a nightly digest cannot afford.
+ *
+ * **No clock is trusted but the queue's.** Which schedules are due is the queue's answer, the fire instant is the
+ * one the schedule row already held, and the next one is computed from that row. A replica in Santiago and a
+ * replica in Frankfurt produce the same fires, once each, however far apart their clocks have drifted.
+ *
+ * **A fire is enqueued BEFORE the schedule moves on.** If this process dies between the two, the schedule is still
+ * due, the next sweep enqueues the same id — a no-op — and advances. Nothing is produced twice and nothing is
+ * lost; the ordering is the whole of that guarantee.
+ *
+ * **An outage does not replay as a storm.** The overdue fire becomes one job, and the schedule then jumps to the
+ * first occurrence after now, recording how many went by. A digest missed for a day sends once and says it missed
+ * 23 — rather than sending 23 times, which is how a scheduler that "catches up" turns an outage into an incident.
+ */
+export declare const createScheduler: ({ queue, lookups, environment, pollMs, batch, maxAttempts, reconcileMs, spaces, onError }: SchedulerOptions) => Scheduler;

package/dist/modules/actions/jobs/scheduler.js

@@ -0,0 +1,125 @@
+import { scheduleJobId, schedulesFor } from "./schedules.js";
+import { cronFiresBetween, cronNextFire } from "@plitzi/sdk-shared/actions";
+//#region src/modules/actions/jobs/scheduler.ts
+var MINUTE_MS = 6e4;
+/** Where a schedule is parked when its expression has no next fire at all. Four years out, which is the horizon
+*  {@link cronNextFire} searches: nothing inside it matched, so nothing inside it will. */
+var PARK_MS = 2108160 * MINUTE_MS;
+/**
+* Turns due schedules into jobs. Nothing else.
+*
+* **There is no leader.** Every replica sweeps, and that is safe because a fire's job id is derived from the fire's
+* own stored instant: two replicas reaching the same fire write the same id, and the queue keeps the first. A
+* leader lock would only add a way for the cluster to have no producer at all for a minute — which is exactly the
+* failure a nightly digest cannot afford.
+*
+* **No clock is trusted but the queue's.** Which schedules are due is the queue's answer, the fire instant is the
+* one the schedule row already held, and the next one is computed from that row. A replica in Santiago and a
+* replica in Frankfurt produce the same fires, once each, however far apart their clocks have drifted.
+*
+* **A fire is enqueued BEFORE the schedule moves on.** If this process dies between the two, the schedule is still
+* due, the next sweep enqueues the same id — a no-op — and advances. Nothing is produced twice and nothing is
+* lost; the ordering is the whole of that guarantee.
+*
+* **An outage does not replay as a storm.** The overdue fire becomes one job, and the schedule then jumps to the
+* first occurrence after now, recording how many went by. A digest missed for a day sends once and says it missed
+* 23 — rather than sending 23 times, which is how a scheduler that "catches up" turns an outage into an incident.
+*/
+var createScheduler = ({ queue, lookups, environment = "main", pollMs = 15e3, batch = 200, maxAttempts = 3, reconcileMs = 15 * MINUTE_MS, spaces, onError = (error) => console.error("[Actions] schedule sweep failed:", error) }) => {
+	let timer;
+	let reconcileTimer;
+	let running = false;
+	const produce = async (schedule, at, result) => {
+		const { spaceId, actionId, cron, timezone, nextRunAt: fireAt } = schedule;
+		const id = scheduleJobId(spaceId, actionId, fireAt);
+		(await queue.enqueue({
+			id,
+			spaceId,
+			actionId,
+			environment: schedule.environment,
+			trigger: "schedule",
+			input: {},
+			dueAt: fireAt,
+			maxAttempts: schedule.maxAttempts
+		}) ? result.enqueued : result.duplicates).push(id);
+		const lateness = Math.max(fireAt, at.getTime());
+		const missed = cronFiresBetween(cron, new Date(fireAt), new Date(lateness), timezone);
+		/**
+		* The first occurrence strictly after `lateness` — which, fires being whole minutes, is the first at or after
+		* the minute following the one `lateness` falls in. Not `lateness + 1 minute`: `cronNextFire` rounds up to a
+		* whole minute, so a sweep seven seconds late would ask from 00:02:07, get 00:03, and an every-minute schedule
+		* would fire every other minute.
+		*/
+		const next = cronNextFire(cron, /* @__PURE__ */ new Date(Math.floor(lateness / MINUTE_MS) * MINUTE_MS + MINUTE_MS), timezone);
+		await queue.advanceSchedule({
+			spaceId,
+			actionId,
+			from: fireAt,
+			to: next ? next.getTime() : lateness + PARK_MS,
+			missed
+		});
+		if (missed > 0) result.missed.push({
+			spaceId,
+			actionId,
+			count: missed
+		});
+	};
+	const sweep = async () => {
+		const result = {
+			enqueued: [],
+			duplicates: [],
+			missed: []
+		};
+		const at = await queue.now();
+		for (const schedule of await queue.dueSchedules(batch)) await produce(schedule, at, result);
+		return result;
+	};
+	const reconcile = async (spaceId) => {
+		const entries = await lookups.listActions?.(spaceId) ?? [];
+		const at = await queue.now();
+		await queue.putSchedules({
+			spaceId,
+			schedules: schedulesFor(entries, spaceId, environment, at, maxAttempts)
+		});
+	};
+	const scheduledSpaces = async () => lookups.listScheduledSpaces ? lookups.listScheduledSpaces() : spaces ?? [];
+	const reconcileAll = async () => {
+		for (const spaceId of await scheduledSpaces()) await reconcile(spaceId);
+	};
+	/** One pass at a time per replica: a sweep that outlives its interval must not have a second one land on top. */
+	const guarded = async (pass) => {
+		if (running) return;
+		running = true;
+		try {
+			await pass();
+		} catch (error) {
+			onError(error);
+		} finally {
+			running = false;
+		}
+	};
+	return {
+		sweep,
+		reconcile,
+		start: () => {
+			if (timer) return;
+			timer = setInterval(() => void guarded(sweep), pollMs + Math.floor(Math.random() * 1e3));
+			timer.unref();
+			if (!lookups.listScheduledSpaces && !spaces?.length) {
+				console.warn("[Actions] schedules are running but nothing says which spaces to watch. Name them as `action.jobs.spaces`, or answer `action.lookups.listScheduledSpaces`.");
+				return;
+			}
+			guarded(reconcileAll);
+			reconcileTimer = setInterval(() => void guarded(reconcileAll), reconcileMs);
+			reconcileTimer.unref();
+		},
+		stop: () => {
+			clearInterval(timer);
+			clearInterval(reconcileTimer);
+			timer = void 0;
+			reconcileTimer = void 0;
+		}
+	};
+};
+//#endregion
+export { createScheduler };

package/dist/modules/actions/jobs/scheduler.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/modules/actions/jobs/schedules.d.ts

@@ -0,0 +1,23 @@
+import { ActionEntry, ActionScheduleInput, Environment } from '@plitzi/sdk-shared';
+/** Attempts a scheduled job is given before it is left for an operator. Overridable per deployment. */
+export declare const DEFAULT_MAX_ATTEMPTS = 3;
+/**
+ * The schedule a document declares, or nothing.
+ *
+ * The cron and the zone are read through the same fields the runner used to read at every tick — but read ONCE,
+ * when the document is saved, and written to a row. What the tick then reads is a due time, not a JSON blob: the
+ * difference between one indexed query a minute and every action document in the deployment, parsed.
+ *
+ * A zone `Intl` does not know is dropped rather than silently treated as UTC. The validator already tells the
+ * author, and a schedule that fires at the wrong hour is worse than one that visibly never fires at all.
+ */
+export declare const scheduleFor: (entry: ActionEntry, spaceId: number, environment: Environment, from: Date, maxAttempts?: number) => ActionScheduleInput | undefined;
+/** Every schedule a space's actions declare, as of one instant. */
+export declare const schedulesFor: (entries: ActionEntry[], spaceId: number, environment: Environment, from: Date, maxAttempts?: number) => ActionScheduleInput[];
+/**
+ * The id a fire gets, and the whole of the exactly-once guarantee.
+ *
+ * Derived from the STORED fire instant rather than from any node's reading of the clock, so two replicas that
+ * disagree about what time it is still write the same id — and the second one's enqueue is a no-op.
+ */
+export declare const scheduleJobId: (spaceId: number, actionId: string, fireAt: number) => string;

package/dist/modules/actions/jobs/schedules.js

@@ -0,0 +1,47 @@
+import { findTriggerNode, triggerParams } from "../runtime/triggers.js";
+import { cronNextFire, isKnownTimeZone } from "@plitzi/sdk-shared/actions";
+//#region src/modules/actions/jobs/schedules.ts
+/** Attempts a scheduled job is given before it is left for an operator. Overridable per deployment. */
+var DEFAULT_MAX_ATTEMPTS = 3;
+/**
+* The schedule a document declares, or nothing.
+*
+* The cron and the zone are read through the same fields the runner used to read at every tick — but read ONCE,
+* when the document is saved, and written to a row. What the tick then reads is a due time, not a JSON blob: the
+* difference between one indexed query a minute and every action document in the deployment, parsed.
+*
+* A zone `Intl` does not know is dropped rather than silently treated as UTC. The validator already tells the
+* author, and a schedule that fires at the wrong hour is worse than one that visibly never fires at all.
+*/
+var scheduleFor = (entry, spaceId, environment, from, maxAttempts = 3) => {
+	const node = findTriggerNode(entry.document.nodes, "schedule");
+	if (!node) return;
+	const params = triggerParams(node);
+	const cron = params.cron?.trim();
+	if (!cron) return;
+	const zone = params.timezone?.trim();
+	const timezone = zone && isKnownTimeZone(zone) ? zone : void 0;
+	const nextRunAt = cronNextFire(cron, from, timezone);
+	if (!nextRunAt) return;
+	return {
+		spaceId,
+		actionId: entry.id,
+		cron,
+		...timezone ? { timezone } : {},
+		environment,
+		enabled: node.enabled,
+		nextRunAt: nextRunAt.getTime(),
+		maxAttempts
+	};
+};
+/** Every schedule a space's actions declare, as of one instant. */
+var schedulesFor = (entries, spaceId, environment, from, maxAttempts = 3) => entries.map((entry) => scheduleFor(entry, spaceId, environment, from, maxAttempts)).filter((schedule) => schedule !== void 0);
+/**
+* The id a fire gets, and the whole of the exactly-once guarantee.
+*
+* Derived from the STORED fire instant rather than from any node's reading of the clock, so two replicas that
+* disagree about what time it is still write the same id — and the second one's enqueue is a no-op.
+*/
+var scheduleJobId = (spaceId, actionId, fireAt) => `schedule:${spaceId}:${actionId}:${fireAt}`;
+//#endregion
+export { DEFAULT_MAX_ATTEMPTS, scheduleFor, scheduleJobId, schedulesFor };

package/dist/modules/actions/jobs/storeClock.d.ts

@@ -0,0 +1,16 @@
+/**
+ * The clock of the store a queue lives in, read cheaply.
+ *
+ * Every comparison a queue makes — is this due, has this lease lapsed — is made against ONE clock, and a cluster whose
+ * replicas sit in different countries only agrees on the store's. Reading it on every call would put a round trip on
+ * the path of every claim and every heartbeat, so it is read once and then trusted for the ELAPSED time only: the one
+ * thing a wrong local clock still gets right is how long thirty seconds is.
+ */
+export type StoreClock = {
+    /** The store's now, in epoch ms. */
+    now: () => Promise<number>;
+    /** Forgets the reading, so the next call takes it again — after a failover to another primary, or in a test. */
+    resync: () => void;
+};
+/** `read` answers the store's own time in epoch ms: `hello.localTime` on Mongo, `NOW(3)` on MySQL. */
+export declare const createStoreClock: (read: () => Promise<number>, resyncMs?: number) => StoreClock;

package/dist/modules/actions/jobs/storeClock.js

@@ -0,0 +1,32 @@
+//#region src/modules/actions/jobs/storeClock.ts
+/** How long a reading is trusted before it is taken again. */
+var RESYNC_MS = 3e4;
+/** `read` answers the store's own time in epoch ms: `hello.localTime` on Mongo, `NOW(3)` on MySQL. */
+var createStoreClock = (read, resyncMs = RESYNC_MS) => {
+	let offset = 0;
+	let readAt = Number.NEGATIVE_INFINITY;
+	let pending;
+	const sync = async () => {
+		const before = Date.now();
+		const storeTime = await read();
+		const after = Date.now();
+		offset = storeTime - Math.round((before + after) / 2);
+		readAt = after;
+	};
+	return {
+		now: async () => {
+			if (Date.now() - readAt >= resyncMs) {
+				pending ??= sync().finally(() => {
+					pending = void 0;
+				});
+				await pending;
+			}
+			return Date.now() + offset;
+		},
+		resync: () => {
+			readAt = Number.NEGATIVE_INFINITY;
+		}
+	};
+};
+//#endregion
+export { createStoreClock };

package/dist/modules/actions/jobs/testing/jobQueueContract.d.ts

@@ -0,0 +1,25 @@
+import { ActionKvAdapter } from '../../types';
+import { ActionJobQueue } from '@plitzi/sdk-shared';
+/**
+ * What every {@link ActionJobQueue} must do, written once and run against each one this package ships.
+ *
+ * The memory queue, the Mongo helper and the MySQL helper are three implementations of one contract, and the contract
+ * is where a scheduling bug lives: a claim that is not atomic runs a job twice, a heartbeat that does not renew hands a
+ * running job to another replica, a settlement from a worker that lost its lease overwrites a live attempt. Asserting
+ * those once per store is what makes "swap the store" a one-line change rather than a new set of bugs.
+ *
+ * Real time, real stores: leases are tens of milliseconds and the tests wait them out, because the store's own clock
+ * is part of what is being tested.
+ */
+export type QueueSubject = {
+    queue: ActionJobQueue;
+    /** Empties whatever the queue keeps, between tests. */
+    clear: () => Promise<void>;
+};
+export declare const describeJobQueue: (name: string, open: () => Promise<QueueSubject>, enabled?: boolean) => void;
+export type KvSubject = {
+    kv: ActionKvAdapter;
+    clear: () => Promise<void>;
+};
+/** What every {@link ActionKvAdapter} must do: strings, a TTL the store enforces, and an increment nobody can race. */
+export declare const describeKv: (name: string, open: () => Promise<KvSubject>, enabled?: boolean) => void;

package/dist/modules/actions/jobs/worker.d.ts

@@ -0,0 +1,62 @@
+import { ActionsModule } from '../index';
+import { ActionLookups } from '../types';
+import { ActionJobQueue } from '@plitzi/sdk-shared';
+export type JobWorkerOptions = {
+    queue: ActionJobQueue;
+    lookups: ActionLookups;
+    module: ActionsModule;
+    /**
+     * How many jobs this replica runs AT ONCE.
+     *
+     * The number that decides whether five hundred queued jobs take five minutes or an hour, and it is a deployment's
+     * to set because only it knows what its jobs do: flows that wait on somebody else's API are cheap to hold many of,
+     * flows that render or transform are not. Zero makes this replica a producer only — which is how a deployment
+     * dedicates a pod to running jobs and leaves the ones serving pages alone.
+     *
+     * It does not widen the run guards. A replica whose `concurrency.perSpace` is 10 will hold 10 runs for one space
+     * however many workers it has, and the rest go back to the queue and come round again.
+     */
+    workers?: number;
+    /** How often a worker with a free slot looks for work. Default 1s. */
+    pollMs?: number;
+    /**
+     * How long a claim is held before another worker may take the job over.
+     *
+     * The failover window, in other words: a replica that is killed has its jobs picked up this long afterwards. It
+     * is renewed every third of its length while a job runs, so a long flow keeps its claim and a dead process does
+     * not. Shorter is a faster recovery and a higher chance of taking a job away from a worker that was merely
+     * stalled; the single-flight key is what makes that safe rather than doubled.
+     */
+    leaseMs?: number;
+    /** First retry delay, doubling per attempt, and the ceiling it doubles up to. */
+    backoff?: {
+        baseMs?: number;
+        maxMs?: number;
+    };
+    /** Names this replica in the job history, so a bad one is identifiable. Defaults to the process and a random id. */
+    workerId?: string;
+    onError?: (error: unknown) => void;
+};
+export type JobWorker = {
+    /** One pass: claim what fits in the free slots and start it. Exposed for a deployment that drives its own loop. */
+    poll: () => Promise<number>;
+    /**
+     * Renews every claim this worker holds, and aborts the ones an operator asked to cancel.
+     *
+     * Exposed beside `poll` for the same reason: a deployment driving its own loop owns both halves, and a worker
+     * that polls without beating loses its jobs to the next replica halfway through them.
+     */
+    beat: () => Promise<void>;
+    start: () => void;
+    /**
+     * Stops claiming, then waits for every job this worker is running to FINISH — however long past its lease that is.
+     *
+     * The heartbeat keeps renewing their claims meanwhile, so no other replica takes a job over while this one is still
+     * running it, and an operator's cancel still reaches it. Each wait is bounded by the run's own timeout, which is
+     * the number an orchestrator's grace period has to cover: a pod killed before that loses the run to a lease that
+     * lapses, and another replica runs it again.
+     */
+    stop: () => Promise<void>;
+    inFlight: () => number;
+};
+export declare const createJobWorker: ({ queue, lookups, module, workers, pollMs, leaseMs, backoff, workerId, onError }: JobWorkerOptions) => JobWorker;