@plitzi/sdk-server 0.37.0 → 0.37.2

package/dist/modules/mongo/jobQueue.js

@@ -0,0 +1,335 @@
+import { createStoreClock } from "../actions/jobs/storeClock.js";
+//#region src/modules/mongo/jobQueue.ts
+/** Mongo's code for a unique index that refused a second document with the same key. */
+var DUPLICATE_KEY = 11e3;
+var TERMINAL = [
+	"succeeded",
+	"failed",
+	"dead",
+	"cancelled"
+];
+var DAY_MS = 864e5;
+var resolveDb = (source) => typeof source === "function" ? source() : source;
+var scheduleId = (spaceId, actionId) => `${spaceId}:${actionId}`;
+/**
+* A stored document as the contract shapes it: an optional field is absent, never `null`.
+*
+* Mongo keeps what a `$set` wrote, and clearing a field in an update pipeline writes `null` — so a released job would
+* otherwise come back with `workerId: null`, which every reader typed as `string | undefined` gets wrong.
+*/
+var withoutNulls = (document) => Object.fromEntries(Object.entries(document).filter(([, value]) => value !== null));
+var toJob = ({ _id, expiresAt: _expiresAt, ...rest }) => withoutNulls({
+	...rest,
+	id: _id
+});
+var toSchedule = ({ _id: _unused, ...rest }) => withoutNulls(rest);
+/** The history entry a reclaim writes on behalf of a worker that never came back. */
+var lostAttempt = (at) => ({ $concatArrays: ["$history", [{
+	attempt: { $add: [{ $size: "$history" }, 1] },
+	status: "lost",
+	startedAt: "$updatedAt",
+	endedAt: at,
+	workerId: { $ifNull: ["$workerId", "unknown"] },
+	error: "the worker holding this job stopped reporting"
+}]] });
+/**
+* An {@link ActionJobQueue} over two collections of a Mongo database the deployment owns.
+*
+* The helper for a deployment that already runs Mongo: it holds no connection of its own and creates nothing but the
+* indexes its queries need, on first use. Every replica pointed at the same database shares the jobs and the
+* schedules, which is what running more than one needs.
+*
+* ```ts
+* import { createMongoJobQueue } from '@plitzi/sdk-server/mongo';
+*
+* const queue = createMongoJobQueue({ db: client.db('app') });
+* createServer({ action: { lookups, kv, jobs: { queue } } });
+* ```
+*
+* The contract's rules, as Mongo keeps them: every instant is the SERVER's (`hello.localTime`), `enqueue` is idempotent
+* by the job's `_id`, `claim` takes one document per `findOneAndUpdate` — the atomic unit — and reaps a lapsed lease in
+* the same operation, and a schedule advances by compare-and-set on the instant that was read.
+*/
+var createMongoJobQueue = ({ db, collections: names = {}, retentionDays = 90 }) => {
+	const jobsName = names.jobs ?? "action_jobs";
+	const schedulesName = names.schedules ?? "action_schedules";
+	const jobsOf = () => resolveDb(db).collection(jobsName);
+	const schedulesOf = () => resolveDb(db).collection(schedulesName);
+	const clock = createStoreClock(async () => {
+		const { localTime } = await resolveDb(db).command({ hello: 1 });
+		return localTime ? localTime.getTime() : Date.now();
+	});
+	let ready;
+	/**
+	* The indexes the queue cannot work without, built once on first use.
+	*
+	* `claim` is the one that matters: it runs on every poll of every replica, and without an index over status and the
+	* two time fields it is a collection scan several times a second. The two branches of its `$or` are answered by one
+	* index each and merged already sorted.
+	*/
+	const build = async () => {
+		await Promise.all([
+			jobsOf().createIndex({
+				status: 1,
+				runAt: 1
+			}),
+			jobsOf().createIndex({
+				status: 1,
+				leaseUntil: 1
+			}),
+			jobsOf().createIndex({
+				spaceId: 1,
+				updatedAt: -1
+			}),
+			jobsOf().createIndex({
+				spaceId: 1,
+				actionId: 1,
+				updatedAt: -1
+			}),
+			jobsOf().createIndex({ expiresAt: 1 }, { expireAfterSeconds: 0 }),
+			schedulesOf().createIndex({
+				enabled: 1,
+				nextRunAt: 1
+			}),
+			schedulesOf().createIndex({ spaceId: 1 })
+		]);
+	};
+	const collections = async () => {
+		ready ??= build().catch((error) => {
+			ready = void 0;
+			throw error;
+		});
+		await ready;
+		return {
+			jobs: jobsOf(),
+			schedules: schedulesOf()
+		};
+	};
+	const expiryOf = (at) => new Date(at + retentionDays * DAY_MS);
+	return {
+		resyncClock: clock.resync,
+		now: async () => new Date(await clock.now()),
+		enqueue: async (job) => {
+			const { jobs } = await collections();
+			const at = await clock.now();
+			const { id, ...fields } = job;
+			const document = {
+				...fields,
+				_id: id,
+				status: "pending",
+				runAt: job.dueAt,
+				attempts: 0,
+				createdAt: at,
+				updatedAt: at,
+				history: []
+			};
+			try {
+				await jobs.insertOne(document);
+				return true;
+			} catch (error) {
+				if (error.code === DUPLICATE_KEY) return false;
+				throw error;
+			}
+		},
+		claim: async ({ workerId, leaseMs, limit }) => {
+			const { jobs } = await collections();
+			const at = await clock.now();
+			const taken = [];
+			for (let slot = 0; slot < limit; slot += 1) {
+				const claimed = await jobs.findOneAndUpdate({ $or: [{
+					status: "pending",
+					runAt: { $lte: at }
+				}, {
+					status: "running",
+					leaseUntil: { $lt: at }
+				}] }, [{ $set: { history: { $cond: [
+					{ $eq: ["$status", "running"] },
+					lostAttempt(at),
+					"$history"
+				] } } }, { $set: {
+					status: "running",
+					workerId,
+					leaseUntil: at + leaseMs,
+					updatedAt: at,
+					attempts: { $add: ["$attempts", 1] }
+				} }], {
+					sort: { runAt: 1 },
+					returnDocument: "after"
+				});
+				if (!claimed) break;
+				taken.push(toJob(claimed));
+			}
+			return taken;
+		},
+		heartbeat: async ({ jobIds, workerId, leaseMs }) => {
+			const { jobs } = await collections();
+			const at = await clock.now();
+			await jobs.updateMany({
+				_id: { $in: jobIds },
+				workerId,
+				status: "running"
+			}, { $set: { leaseUntil: at + leaseMs } });
+			return (await jobs.find({
+				_id: { $in: jobIds },
+				workerId,
+				status: "running",
+				cancelRequested: true
+			}).project({ _id: 1 }).toArray()).map((job) => job._id);
+		},
+		settle: async ({ jobId, workerId, status, delayMs, runId, error, attempt }) => {
+			const { jobs } = await collections();
+			const at = await clock.now();
+			const entry = {
+				attempt: { $add: [{ $size: "$history" }, 1] },
+				startedAt: "$updatedAt",
+				endedAt: at,
+				...attempt
+			};
+			await jobs.updateOne({
+				_id: jobId,
+				workerId
+			}, [{ $set: {
+				...attempt ? { history: { $concatArrays: ["$history", [entry]] } } : {},
+				status,
+				updatedAt: at,
+				leaseUntil: null,
+				error: error ?? null,
+				...runId ? { runId } : {},
+				...status === "pending" ? {
+					runAt: at + (delayMs ?? 0),
+					workerId: null,
+					...attempt ? {} : { attempts: { $max: [0, { $subtract: ["$attempts", 1] }] } }
+				} : {},
+				expiresAt: TERMINAL.includes(status) ? expiryOf(at) : null
+			} }]);
+		},
+		dueSchedules: async (limit) => {
+			const { schedules } = await collections();
+			const at = await clock.now();
+			return (await schedules.find({
+				enabled: true,
+				nextRunAt: { $lte: at }
+			}).sort({ nextRunAt: 1 }).limit(limit).toArray()).map(toSchedule);
+		},
+		advanceSchedule: async ({ spaceId, actionId, from, to, missed }) => {
+			const { schedules } = await collections();
+			const at = await clock.now();
+			return (await schedules.updateOne({
+				_id: scheduleId(spaceId, actionId),
+				nextRunAt: from
+			}, {
+				$set: {
+					nextRunAt: to,
+					lastFireAt: from,
+					updatedAt: at
+				},
+				$inc: { missed }
+			})).matchedCount === 1;
+		},
+		putSchedules: async ({ spaceId, schedules: incoming }) => {
+			const { schedules } = await collections();
+			const at = await clock.now();
+			if (incoming.length > 0) await schedules.bulkWrite(incoming.map((schedule) => ({ updateOne: {
+				filter: { _id: scheduleId(spaceId, schedule.actionId) },
+				update: [{ $set: {
+					...schedule,
+					timezone: schedule.timezone ?? null,
+					updatedAt: at,
+					missed: { $ifNull: ["$missed", 0] },
+					nextRunAt: { $cond: [
+						{ $and: [
+							{ $eq: ["$cron", schedule.cron] },
+							{ $eq: [{ $ifNull: ["$timezone", null] }, schedule.timezone ?? null] },
+							{ $eq: ["$environment", schedule.environment] },
+							{ $ne: [{ $ifNull: ["$nextRunAt", null] }, null] }
+						] },
+						"$nextRunAt",
+						schedule.nextRunAt
+					] }
+				} }],
+				upsert: true
+			} })));
+			await schedules.deleteMany({
+				spaceId,
+				actionId: { $nin: incoming.map((schedule) => schedule.actionId) }
+			});
+		},
+		listJobs: async ({ spaceIds, actionId, status, limit, offset }) => {
+			const { jobs } = await collections();
+			const filter = {
+				spaceId: { $in: spaceIds },
+				...actionId ? { actionId } : {},
+				...status ? { status } : {}
+			};
+			const [found, total] = await Promise.all([jobs.find(filter).sort({
+				updatedAt: -1,
+				_id: -1
+			}).skip(offset).limit(limit).toArray(), jobs.countDocuments(filter)]);
+			return {
+				jobs: found.map(toJob),
+				total
+			};
+		},
+		getJob: async (spaceIds, jobId) => {
+			const { jobs } = await collections();
+			const job = await jobs.findOne({
+				_id: jobId,
+				spaceId: { $in: spaceIds }
+			});
+			return job ? toJob(job) : void 0;
+		},
+		listSchedules: async (spaceIds) => {
+			const { schedules } = await collections();
+			return (await schedules.find({ spaceId: { $in: spaceIds } }).sort({ nextRunAt: 1 }).toArray()).map(toSchedule);
+		},
+		requeue: async (spaceIds, jobId) => {
+			const { jobs } = await collections();
+			const at = await clock.now();
+			return (await jobs.updateOne({
+				_id: jobId,
+				spaceId: { $in: spaceIds },
+				status: { $in: TERMINAL }
+			}, {
+				$set: {
+					status: "pending",
+					runAt: at,
+					attempts: 0,
+					updatedAt: at,
+					cancelRequested: false
+				},
+				$unset: {
+					workerId: "",
+					leaseUntil: "",
+					error: "",
+					expiresAt: ""
+				}
+			})).matchedCount === 1;
+		},
+		cancel: async (spaceIds, jobId) => {
+			const { jobs } = await collections();
+			const at = await clock.now();
+			if ((await jobs.updateOne({
+				_id: jobId,
+				spaceId: { $in: spaceIds },
+				status: "pending"
+			}, {
+				$set: {
+					status: "cancelled",
+					updatedAt: at,
+					expiresAt: expiryOf(at)
+				},
+				$unset: { workerId: "" }
+			})).matchedCount === 1) return true;
+			return (await jobs.updateOne({
+				_id: jobId,
+				spaceId: { $in: spaceIds },
+				status: "running"
+			}, { $set: {
+				cancelRequested: true,
+				updatedAt: at
+			} })).matchedCount === 1;
+		}
+	};
+};
+//#endregion
+export { createMongoJobQueue, resolveDb };

package/dist/modules/mongo/kv.d.ts

@@ -0,0 +1,15 @@
+import { MongoDbSource } from './jobQueue';
+import { ActionKvAdapter } from '../actions/types';
+export type MongoKvOptions = {
+    db: MongoDbSource;
+    /** Default `action_kv`. */
+    collection?: string;
+};
+/**
+ * An {@link ActionKvAdapter} over a collection of a Mongo database the deployment owns.
+ *
+ * What the run guards' single-flight keys and the `kv` tasks' counters need from a store the replicas share: a TTL the
+ * store enforces and an increment nobody can race. Each operation is ONE document update, which Mongo applies
+ * atomically — so two replicas incrementing the same counter at once both count.
+ */
+export declare const createMongoKv: ({ db, collection }: MongoKvOptions) => ActionKvAdapter;

package/dist/modules/mongo/kv.js

@@ -0,0 +1,98 @@
+import { resolveDb } from "./jobQueue.js";
+//#region src/modules/mongo/kv.ts
+/** Mongo's code for a unique index that refused a second document with the same key. */
+var DUPLICATE_KEY = 11e3;
+/**
+* Whether a key is still alive, by the SERVER's clock.
+*
+* Mongo's TTL monitor sweeps once a minute, so a document past its lifetime can still be there to read. Expiry is
+* decided here, against `$$NOW`, rather than by whether the sweeper has been round yet — the same answer Redis gives
+* the instant a key lapses.
+*/
+var LIVE = { $or: [{ $eq: [{ $ifNull: ["$expiresAt", null] }, null] }, { $gt: ["$expiresAt", "$$NOW"] }] };
+var expiryIn = (ttlSeconds) => ({ $add: ["$$NOW", ttlSeconds * 1e3] });
+/**
+* An {@link ActionKvAdapter} over a collection of a Mongo database the deployment owns.
+*
+* What the run guards' single-flight keys and the `kv` tasks' counters need from a store the replicas share: a TTL the
+* store enforces and an increment nobody can race. Each operation is ONE document update, which Mongo applies
+* atomically — so two replicas incrementing the same counter at once both count.
+*/
+var createMongoKv = ({ db, collection = "action_kv" }) => {
+	const keys = () => resolveDb(db).collection(collection);
+	let ready;
+	const store = async () => {
+		ready ??= keys().createIndex({ expiresAt: 1 }, { expireAfterSeconds: 0 }).then(() => void 0).catch((error) => {
+			ready = void 0;
+			throw error;
+		});
+		await ready;
+		return keys();
+	};
+	/**
+	* An upsert two replicas race for can collide on `_id` before either has written; the server retries that itself
+	* from 4.2 on, and this covers the rest. Once is enough: the second attempt finds the document the first one made.
+	*/
+	const upserting = async (write) => {
+		try {
+			return await write();
+		} catch (error) {
+			if (error.code !== DUPLICATE_KEY) throw error;
+			return write();
+		}
+	};
+	return {
+		get: async (key) => {
+			return (await (await store()).findOne({
+				_id: key,
+				$expr: LIVE
+			}))?.value;
+		},
+		set: async (key, value, ttlSeconds) => {
+			const keysNow = await store();
+			await upserting(() => keysNow.updateOne({ _id: key }, [{ $set: {
+				value,
+				expiresAt: ttlSeconds === void 0 ? null : expiryIn(ttlSeconds)
+			} }], { upsert: true }));
+		},
+		delete: async (key) => {
+			await (await store()).deleteOne({ _id: key });
+		},
+		increment: async (key, amount) => {
+			const keysNow = await store();
+			const updated = await upserting(() => keysNow.findOneAndUpdate({ _id: key }, [
+				{ $set: { live: LIVE } },
+				{ $set: {
+					value: { $toString: { $add: [{ $cond: [
+						"$live",
+						{ $convert: {
+							input: "$value",
+							to: "double",
+							onError: 0,
+							onNull: 0
+						} },
+						0
+					] }, amount] } },
+					expiresAt: { $cond: [
+						"$live",
+						{ $ifNull: ["$expiresAt", null] },
+						null
+					] }
+				} },
+				{ $unset: "live" }
+			], {
+				upsert: true,
+				returnDocument: "after"
+			}));
+			return Number(updated?.value ?? amount);
+		},
+		expire: async (key, ttlSeconds) => {
+			await (await store()).updateOne({
+				_id: key,
+				$expr: LIVE
+			}, [{ $set: { expiresAt: expiryIn(ttlSeconds) } }]);
+		}
+	};
+};
+//#endregion
+export { createMongoKv };

package/dist/modules/mongo/stores.integration.test.d.ts

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

package/dist/modules/mysql/jobs/index.d.ts

@@ -0,0 +1,5 @@
+export { createMysqlJobQueue } from './jobQueue';
+export { createMysqlKv } from './kv';
+export { mysqlJobSchemaStatements } from './schema';
+export type { MysqlJobQueue, MysqlJobQueueOptions } from './jobQueue';
+export type { MysqlKvOptions } from './kv';

package/dist/modules/mysql/jobs/jobQueue.d.ts

@@ -0,0 +1,40 @@
+import { ActionJobQueue } from '@plitzi/sdk-shared';
+import { Pool } from 'mysql2/promise';
+export type MysqlJobQueueOptions = {
+    /** A pool the deployment opened. The helper borrows connections from it and never ends it. */
+    pool: Pool;
+    /** Prefix for the three tables — `action_jobs`, `action_schedules`, `action_kv`. Default none. */
+    tablePrefix?: string;
+    /**
+     * Create the tables on first use (`CREATE TABLE IF NOT EXISTS`). Default true; false for a deployment that runs
+     * {@link mysqlJobSchemaStatements} through its own migrations.
+     */
+    createTables?: boolean;
+    /** How long a finished job stays readable. A waiting or running one never expires. Default 90 days. */
+    retentionDays?: number;
+};
+export type MysqlJobQueue = ActionJobQueue & {
+    /** Takes the store's clock again on the next call — after a failover to another primary. */
+    resyncClock: () => void;
+};
+/**
+ * An {@link ActionJobQueue} over tables in a MySQL database the deployment owns. Tested on MySQL 8; nothing in it
+ * needs more than 5.7.
+ *
+ * The helper for a deployment that already runs MySQL: it borrows connections from the pool it is handed, and creates
+ * its three tables on first use unless told not to. Every replica pointed at the same database shares the jobs and the
+ * schedules.
+ *
+ * ```ts
+ * import mysql from 'mysql2/promise';
+ * import { createMysqlJobQueue, createMysqlKv } from '@plitzi/sdk-server/mysql';
+ *
+ * const pool = mysql.createPool(process.env.DATABASE_URL);
+ * createServer({ action: { lookups, kv: createMysqlKv({ pool }), jobs: { queue: createMysqlJobQueue({ pool }) } } });
+ * ```
+ *
+ * The contract's rules, as MySQL keeps them: every instant is the SERVER's (`NOW(3)`), `enqueue` is idempotent by the
+ * primary key, `claim` takes each job with a single-row compare-and-set — so two workers never take the same one —
+ * and reaps a lapsed lease in the same write, and a schedule advances by compare-and-set too.
+ */
+export declare const createMysqlJobQueue: ({ pool, tablePrefix, createTables, retentionDays }: MysqlJobQueueOptions) => MysqlJobQueue;