@plitzi/sdk-server 0.37.1 → 0.37.3

package/dist/modules/mysql/jobs/jobQueue.js

@@ -0,0 +1,375 @@
+import { execute, selectOne, selectRows } from "../query.js";
+import { NOW_MS, ensureJobTables, jobTables } from "./schema.js";
+import { createStoreClock } from "../../actions/jobs/storeClock.js";
+//#region src/modules/mysql/jobs/jobQueue.ts
+var TERMINAL = [
+	"succeeded",
+	"failed",
+	"dead",
+	"cancelled"
+];
+var DAY_MS = 864e5;
+/** How often finished jobs past their retention are removed — at most once a minute per process, on a write. */
+var PURGE_EVERY_MS = 6e4;
+/**
+* A row as the contract shapes it.
+*
+* `BIGINT` arrives as a number or as a string depending on how the deployment configured its pool
+* (`bigNumberStrings`), so every numeric column goes through `Number`. The text columns hold only what this queue
+* wrote into them — a status, an environment, a trigger — which is why they can be read back as those types.
+*/
+var toJob = (row) => ({
+	id: row.id,
+	spaceId: Number(row.space_id),
+	actionId: row.action_id,
+	environment: row.environment,
+	trigger: row.trigger_type,
+	input: JSON.parse(row.input),
+	dueAt: Number(row.due_at),
+	maxAttempts: Number(row.max_attempts),
+	...row.missed === null ? {} : { missed: Number(row.missed) },
+	status: row.status,
+	runAt: Number(row.run_at),
+	attempts: Number(row.attempts),
+	...row.lease_until === null ? {} : { leaseUntil: Number(row.lease_until) },
+	...row.worker_id === null ? {} : { workerId: row.worker_id },
+	...row.run_id === null ? {} : { runId: row.run_id },
+	...Number(row.cancel_requested) === 1 ? { cancelRequested: true } : {},
+	createdAt: Number(row.created_at),
+	updatedAt: Number(row.updated_at),
+	...row.error === null ? {} : { error: row.error },
+	history: JSON.parse(row.history)
+});
+var toSchedule = (row) => ({
+	spaceId: Number(row.space_id),
+	actionId: row.action_id,
+	cron: row.cron,
+	...row.timezone === null ? {} : { timezone: row.timezone },
+	environment: row.environment,
+	enabled: Number(row.enabled) === 1,
+	nextRunAt: Number(row.next_run_at),
+	...row.last_fire_at === null ? {} : { lastFireAt: Number(row.last_fire_at) },
+	missed: Number(row.missed),
+	maxAttempts: Number(row.max_attempts),
+	updatedAt: Number(row.updated_at)
+});
+/** MySQL's answer when two transactions wait on each other: one is rolled back, and is meant to be run again. */
+var DEADLOCK = "ER_LOCK_DEADLOCK";
+var TRANSACTION_ATTEMPTS = 3;
+/** Claim rounds per call: a worker that lost every row it read to other workers looks once more, then waits a poll. */
+var CLAIM_ROUNDS = 3;
+/**
+* One connection, one transaction: what a settlement or a schedule write needs so the rows it read stay locked until
+* it writes. A deadlock is retried — MySQL picks a victim and expects it to try again, which is what two replicas
+* reconciling the same space at boot will occasionally make it do.
+*/
+var transaction = async (pool, work) => {
+	for (let attempt = 1;; attempt += 1) {
+		const connection = await pool.getConnection();
+		try {
+			await connection.beginTransaction();
+			const result = await work(connection);
+			await connection.commit();
+			return result;
+		} catch (error) {
+			await connection.rollback();
+			if (error.code !== DEADLOCK || attempt >= TRANSACTION_ATTEMPTS) throw error;
+		} finally {
+			connection.release();
+		}
+	}
+};
+/** MySQL's code for a primary key that refused a second row with the same value. */
+var DUPLICATE_ENTRY = "ER_DUP_ENTRY";
+/**
+* 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.
+*/
+var createMysqlJobQueue = ({ pool, tablePrefix = "", createTables = true, retentionDays = 90 }) => {
+	const t = jobTables(tablePrefix);
+	const ready = ensureJobTables(pool, tablePrefix, createTables);
+	const clock = createStoreClock(async () => {
+		const row = await selectOne(pool, `SELECT ${NOW_MS} AS now`);
+		return row ? Number(row.now) : Date.now();
+	});
+	const db = async () => {
+		await ready();
+		return pool;
+	};
+	const expiryOf = (at) => at + retentionDays * DAY_MS;
+	let purgedAt = 0;
+	const purge = async (at) => {
+		if (at - purgedAt < PURGE_EVERY_MS) return;
+		purgedAt = at;
+		await execute(pool, `DELETE FROM ${t.jobs} WHERE expires_at IS NOT NULL AND expires_at < ? LIMIT 1000`, [at]);
+	};
+	const inSpaces = (spaceIds) => spaceIds.length > 0;
+	return {
+		resyncClock: clock.resync,
+		now: async () => new Date(await clock.now()),
+		enqueue: async (job) => {
+			const conn = await db();
+			const at = await clock.now();
+			try {
+				await execute(conn, `INSERT INTO ${t.jobs} (id, space_id, action_id, environment, trigger_type, input, due_at, max_attempts,
+            missed, status, run_at, attempts, created_at, updated_at, history)
+          VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, 'pending', ?, 0, ?, ?, '[]')`, [
+					job.id,
+					job.spaceId,
+					job.actionId,
+					job.environment,
+					job.trigger,
+					JSON.stringify(job.input),
+					job.dueAt,
+					job.maxAttempts,
+					job.missed ?? null,
+					job.dueAt,
+					at,
+					at
+				]);
+				return true;
+			} catch (error) {
+				if (error.code === DUPLICATE_ENTRY) return false;
+				throw error;
+			}
+		},
+		claim: async ({ workerId, leaseMs, limit }) => {
+			const conn = await db();
+			const at = await clock.now();
+			const taken = [];
+			/**
+			* Read, then take each job with ONE single-row update that only lands if the row is still the version that was
+			* read — due, unclaimed or with its lease still lapsed, and not written since. Two workers reading the same
+			* candidates each get the rows they win and skip the rest.
+			*
+			* Not `SELECT … FOR UPDATE SKIP LOCKED` in a transaction: the locks that takes on the status index cross with
+			* the ones the updates need, and two replicas claiming at once deadlock. A single-row update by primary key
+			* holds one lock and cannot.
+			*/
+			for (let round = 0; round < CLAIM_ROUNDS && taken.length < limit; round += 1) {
+				const rows = await selectRows(conn, `SELECT * FROM ${t.jobs}
+          WHERE (status = 'pending' AND run_at <= ?) OR (status = 'running' AND lease_until < ?)
+          ORDER BY run_at LIMIT ?`, [
+					at,
+					at,
+					limit - taken.length
+				]);
+				if (rows.length === 0) break;
+				for (const row of rows) {
+					const job = toJob(row);
+					const history = job.status === "running" ? [...job.history, {
+						attempt: job.history.length + 1,
+						status: "lost",
+						startedAt: job.updatedAt,
+						endedAt: at,
+						workerId: job.workerId ?? "unknown",
+						error: "the worker holding this job stopped reporting"
+					}] : job.history;
+					if ((await execute(conn, `UPDATE ${t.jobs} SET status = 'running', worker_id = ?, lease_until = ?, updated_at = ?,
+              attempts = attempts + 1, history = ?
+            WHERE id = ? AND status = ? AND updated_at = ? AND attempts = ?
+              AND ((status = 'pending' AND run_at <= ?) OR (status = 'running' AND lease_until < ?))`, [
+						workerId,
+						at + leaseMs,
+						at,
+						JSON.stringify(history),
+						job.id,
+						job.status,
+						job.updatedAt,
+						job.attempts,
+						at,
+						at
+					])).affectedRows !== 1) continue;
+					taken.push({
+						...job,
+						status: "running",
+						workerId,
+						leaseUntil: at + leaseMs,
+						updatedAt: at,
+						attempts: job.attempts + 1,
+						history
+					});
+				}
+			}
+			return taken;
+		},
+		heartbeat: async ({ jobIds, workerId, leaseMs }) => {
+			if (jobIds.length === 0) return [];
+			const conn = await db();
+			const at = await clock.now();
+			await execute(conn, `UPDATE ${t.jobs} SET lease_until = ? WHERE id IN (?) AND worker_id = ? AND status = 'running'`, [
+				at + leaseMs,
+				jobIds,
+				workerId
+			]);
+			return (await selectRows(conn, `SELECT id FROM ${t.jobs} WHERE id IN (?) AND worker_id = ? AND status = 'running' AND cancel_requested = 1`, [jobIds, workerId])).map((row) => row.id);
+		},
+		settle: async ({ jobId, workerId, status, delayMs, runId, error, attempt }) => {
+			await db();
+			const at = await clock.now();
+			await transaction(pool, async (connection) => {
+				const row = await selectOne(connection, `SELECT * FROM ${t.jobs} WHERE id = ? AND worker_id = ? FOR UPDATE`, [jobId, workerId]);
+				if (!row) return;
+				const job = toJob(row);
+				const history = attempt ? [...job.history, {
+					...attempt,
+					attempt: job.history.length + 1,
+					startedAt: job.updatedAt,
+					endedAt: at
+				}] : job.history;
+				const pending = status === "pending";
+				const attempts = pending && !attempt ? Math.max(0, job.attempts - 1) : job.attempts;
+				await execute(connection, `UPDATE ${t.jobs} SET status = ?, updated_at = ?, lease_until = NULL, error = ?, run_id = COALESCE(?, run_id),
+            run_at = ?, worker_id = ?, attempts = ?, history = ?, expires_at = ? WHERE id = ?`, [
+					status,
+					at,
+					error ?? null,
+					runId ?? null,
+					pending ? at + (delayMs ?? 0) : job.runAt,
+					pending ? null : workerId,
+					attempts,
+					JSON.stringify(history),
+					TERMINAL.includes(status) ? expiryOf(at) : null,
+					jobId
+				]);
+			});
+			await purge(at);
+		},
+		dueSchedules: async (limit) => {
+			const conn = await db();
+			const at = await clock.now();
+			return (await selectRows(conn, `SELECT * FROM ${t.schedules} WHERE enabled = 1 AND next_run_at <= ? ORDER BY next_run_at LIMIT ?`, [at, limit])).map(toSchedule);
+		},
+		advanceSchedule: async ({ spaceId, actionId, from, to, missed }) => {
+			const conn = await db();
+			const at = await clock.now();
+			return (await execute(conn, `UPDATE ${t.schedules} SET next_run_at = ?, last_fire_at = ?, updated_at = ?, missed = missed + ?
+        WHERE space_id = ? AND action_id = ? AND next_run_at = ?`, [
+				to,
+				from,
+				at,
+				missed,
+				spaceId,
+				actionId,
+				from
+			])).affectedRows === 1;
+		},
+		putSchedules: async ({ spaceId, schedules: incoming }) => {
+			await db();
+			const at = await clock.now();
+			await transaction(pool, async (connection) => {
+				for (const schedule of incoming)
+ /**
+				* `next_run_at` FIRST: MySQL applies these assignments left to right, each seeing the ones before it, so
+				* the comparison has to read the old expression before `cron` is overwritten. A fire already promised for
+				* an unchanged expression is kept — recomputing it on every save would push a busy space's schedule forward
+				* forever. `VALUES()` rather than a row alias, which MariaDB does not have.
+				*/
+				await execute(connection, `INSERT INTO ${t.schedules} (space_id, action_id, cron, timezone, environment, enabled, next_run_at,
+              missed, max_attempts, updated_at)
+            VALUES (?, ?, ?, ?, ?, ?, ?, 0, ?, ?)
+            ON DUPLICATE KEY UPDATE
+              next_run_at = IF(cron = VALUES(cron) AND timezone <=> VALUES(timezone)
+                AND environment = VALUES(environment), next_run_at, VALUES(next_run_at)),
+              cron = VALUES(cron), timezone = VALUES(timezone), environment = VALUES(environment),
+              enabled = VALUES(enabled), max_attempts = VALUES(max_attempts), updated_at = VALUES(updated_at)`, [
+					spaceId,
+					schedule.actionId,
+					schedule.cron,
+					schedule.timezone ?? null,
+					schedule.environment,
+					schedule.enabled ? 1 : 0,
+					schedule.nextRunAt,
+					schedule.maxAttempts,
+					at
+				]);
+				const kept = incoming.map((schedule) => schedule.actionId);
+				await execute(connection, kept.length > 0 ? `DELETE FROM ${t.schedules} WHERE space_id = ? AND action_id NOT IN (?)` : `DELETE FROM ${t.schedules} WHERE space_id = ?`, kept.length > 0 ? [spaceId, kept] : [spaceId]);
+			});
+		},
+		listJobs: async ({ spaceIds, actionId, status, limit, offset }) => {
+			if (!inSpaces(spaceIds)) return {
+				jobs: [],
+				total: 0
+			};
+			const conn = await db();
+			const where = [
+				"space_id IN (?)",
+				...actionId ? ["action_id = ?"] : [],
+				...status ? ["status = ?"] : []
+			].join(" AND ");
+			const params = [
+				spaceIds,
+				...actionId ? [actionId] : [],
+				...status ? [status] : []
+			];
+			const [rows, count] = await Promise.all([selectRows(conn, `SELECT * FROM ${t.jobs} WHERE ${where} ORDER BY updated_at DESC, id DESC LIMIT ? OFFSET ?`, [
+				...params,
+				limit,
+				offset
+			]), selectOne(conn, `SELECT COUNT(*) AS total FROM ${t.jobs} WHERE ${where}`, params)]);
+			return {
+				jobs: rows.map(toJob),
+				total: Number(count?.total ?? 0)
+			};
+		},
+		getJob: async (spaceIds, jobId) => {
+			if (!inSpaces(spaceIds)) return;
+			const row = await selectOne(await db(), `SELECT * FROM ${t.jobs} WHERE id = ? AND space_id IN (?)`, [jobId, spaceIds]);
+			return row ? toJob(row) : void 0;
+		},
+		listSchedules: async (spaceIds) => {
+			if (!inSpaces(spaceIds)) return [];
+			return (await selectRows(await db(), `SELECT * FROM ${t.schedules} WHERE space_id IN (?) ORDER BY next_run_at`, [spaceIds])).map(toSchedule);
+		},
+		requeue: async (spaceIds, jobId) => {
+			if (!inSpaces(spaceIds)) return false;
+			const conn = await db();
+			const at = await clock.now();
+			return (await execute(conn, `UPDATE ${t.jobs} SET status = 'pending', run_at = ?, attempts = 0, updated_at = ?, cancel_requested = 0,
+          worker_id = NULL, lease_until = NULL, error = NULL, expires_at = NULL
+        WHERE id = ? AND space_id IN (?) AND status IN (?)`, [
+				at,
+				at,
+				jobId,
+				spaceIds,
+				TERMINAL
+			])).affectedRows === 1;
+		},
+		cancel: async (spaceIds, jobId) => {
+			if (!inSpaces(spaceIds)) return false;
+			const conn = await db();
+			const at = await clock.now();
+			if ((await execute(conn, `UPDATE ${t.jobs} SET status = 'cancelled', updated_at = ?, expires_at = ?, worker_id = NULL
+        WHERE id = ? AND space_id IN (?) AND status = 'pending'`, [
+				at,
+				expiryOf(at),
+				jobId,
+				spaceIds
+			])).affectedRows === 1) return true;
+			return (await execute(conn, `UPDATE ${t.jobs} SET cancel_requested = 1, updated_at = ? WHERE id = ? AND space_id IN (?) AND status = 'running'`, [
+				at,
+				jobId,
+				spaceIds
+			])).affectedRows === 1;
+		}
+	};
+};
+//#endregion
+export { createMysqlJobQueue };

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

@@ -0,0 +1,18 @@
+import { ActionKvAdapter } from '../../actions/types';
+import { Pool } from 'mysql2/promise';
+export type MysqlKvOptions = {
+    /** A pool the deployment opened. Never ended here. */
+    pool: Pool;
+    /** Same prefix as the job queue's, when both are used: the three tables are created together. */
+    tablePrefix?: string;
+    /** Create the tables on first use. Default true. */
+    createTables?: boolean;
+};
+/**
+ * An {@link ActionKvAdapter} over a table in a MySQL 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. The increment is one `INSERT … ON DUPLICATE KEY UPDATE`, which
+ * MySQL applies to the row under its lock — so two replicas counting at once both count.
+ */
+export declare const createMysqlKv: ({ pool, tablePrefix, createTables }: MysqlKvOptions) => ActionKvAdapter;

package/dist/modules/mysql/jobs/kv.js

@@ -0,0 +1,108 @@
+import { execute, selectOne } from "../query.js";
+import { NOW_MS, ensureJobTables, jobTables } from "./schema.js";
+//#region src/modules/mysql/jobs/kv.ts
+/** Alive by the SERVER's clock: a key past its lifetime answers nothing, whether or not it has been removed yet. */
+var LIVE = `(expires_at IS NULL OR expires_at > ${NOW_MS})`;
+/**
+* An {@link ActionKvAdapter} over a table in a MySQL 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. The increment is one `INSERT … ON DUPLICATE KEY UPDATE`, which
+* MySQL applies to the row under its lock — so two replicas counting at once both count.
+*/
+var createMysqlKv = ({ pool, tablePrefix = "", createTables = true }) => {
+	const { kv } = jobTables(tablePrefix);
+	const ready = ensureJobTables(pool, tablePrefix, createTables);
+	const db = async () => {
+		await ready();
+		return pool;
+	};
+	/** Expired rows are removed as they are overwritten or read past; a table of used-once keys is swept here too. */
+	let sweptAt = 0;
+	const sweep = async () => {
+		if (Date.now() - sweptAt < 6e4) return;
+		sweptAt = Date.now();
+		await execute(pool, `DELETE FROM ${kv} WHERE expires_at IS NOT NULL AND expires_at <= ${NOW_MS} LIMIT 1000`);
+	};
+	return {
+		get: async (key) => {
+			return (await selectOne(await db(), `SELECT v FROM ${kv} WHERE k = ? AND ${LIVE}`, [key]))?.v;
+		},
+		set: async (key, value, ttlSeconds) => {
+			const expiry = ttlSeconds === void 0 ? "NULL" : `${NOW_MS} + ?`;
+			await execute(await db(), `INSERT INTO ${kv} (k, v, expires_at) VALUES (?, ?, ${expiry})
+        ON DUPLICATE KEY UPDATE v = VALUES(v), expires_at = VALUES(expires_at)`, ttlSeconds === void 0 ? [key, value] : [
+				key,
+				value,
+				ttlSeconds * 1e3
+			]);
+			await sweep();
+		},
+		delete: async (key) => {
+			await execute(await db(), `DELETE FROM ${kv} WHERE k = ?`, [key]);
+		},
+		increment: async (key, amount) => {
+			const connection = await (await db()).getConnection();
+			try {
+				await connection.beginTransaction();
+				/**
+				* `v` FIRST: the assignments run left to right and each sees the ones before it, so the value has to be
+				* computed while `expires_at` still says whether the old one is alive. A lapsed counter starts again from
+				* zero, and without the lifetime it had. `+ 0` reads the text as a number, as Redis reads its strings.
+				*/
+				await execute(connection, `INSERT INTO ${kv} (k, v, expires_at) VALUES (?, CAST(? AS CHAR), NULL)
+          ON DUPLICATE KEY UPDATE
+            v = CAST(IF(${LIVE}, (v + 0) + ?, ?) AS CHAR),
+            expires_at = IF(${LIVE}, expires_at, NULL)`, [
+					key,
+					amount,
+					amount,
+					amount
+				]);
+				const row = await selectOne(connection, `SELECT v FROM ${kv} WHERE k = ?`, [key]);
+				await connection.commit();
+				return Number(row?.v ?? amount);
+			} catch (error) {
+				await connection.rollback();
+				throw error;
+			} finally {
+				connection.release();
+			}
+		},
+		expire: async (key, ttlSeconds) => {
+			await execute(await db(), `UPDATE ${kv} SET expires_at = ${NOW_MS} + ? WHERE k = ? AND ${LIVE}`, [ttlSeconds * 1e3, key]);
+		},
+		/**
+		* Each branch is ONE statement MySQL applies under the row's lock, so two writers racing for the same key cannot
+		* both win. `affectedRows` counts the rows MATCHED because mysql2 connects with `FOUND_ROWS`: without it, writing
+		* back the value a key already holds would read as a refusal. The comparison is on bytes — the table's collation
+		* ignores case and trailing spaces, and "unchanged" has to mean the same bytes.
+		*/
+		swap: async (key, expected, next, ttlSeconds) => {
+			const expiry = ttlSeconds === void 0 ? "NULL" : `${NOW_MS} + ?`;
+			const lifetime = ttlSeconds === void 0 ? [] : [ttlSeconds * 1e3];
+			const pool = await db();
+			if (expected !== void 0) return (await execute(pool, `UPDATE ${kv} SET v = ?, expires_at = ${expiry}
+          WHERE k = ? AND ${LIVE} AND CAST(v AS BINARY) = CAST(? AS BINARY)`, [
+				next,
+				...lifetime,
+				key,
+				expected
+			])).affectedRows === 1;
+			if ((await execute(pool, `UPDATE ${kv} SET v = ?, expires_at = ${expiry} WHERE k = ? AND NOT ${LIVE}`, [
+				next,
+				...lifetime,
+				key
+			])).affectedRows === 1) return true;
+			const inserted = await execute(pool, `INSERT IGNORE INTO ${kv} (k, v, expires_at) VALUES (?, ?, ${expiry})`, [
+				key,
+				next,
+				...lifetime
+			]);
+			await sweep();
+			return inserted.affectedRows === 1;
+		}
+	};
+};
+//#endregion
+export { createMysqlKv };

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

@@ -0,0 +1,33 @@
+import { Queryable } from '../query';
+/** The tables the job queue and the key/value store keep, backticked and prefixed. */
+export type JobTables = {
+    jobs: string;
+    schedules: string;
+    kv: string;
+};
+/**
+ * Table names under a prefix. A prefix is part of an identifier, which no driver can bind as a parameter — so it is
+ * held to the characters an unquoted identifier may use, and refused otherwise, rather than escaped and hoped for.
+ */
+export declare const jobTables: (prefix?: string) => JobTables;
+/**
+ * The tables, as SQL — for a deployment that runs its own migrations rather than letting the helpers create them.
+ *
+ * Instants are epoch milliseconds in `BIGINT`, read from the SERVER's clock; `history` and `input` are JSON kept as
+ * text, because they are only ever read whole. Separate from the account store's schema and its version: a deployment
+ * can use either without the other.
+ *
+ * A `kv` key is BYTES, as it is in Redis and in memory: under a collation `Board` and `board` — and `a` and `a ` — were
+ * one key here and two everywhere else. A value is a `MEDIUMTEXT`: a `TEXT` stops at 64 KB, and past it MySQL
+ * refuses the write, or cuts it short where it is not strict.
+ */
+export declare const mysqlJobSchemaStatements: (prefix?: string) => string[];
+/**
+ * What brings a `kv` table made before the columns above up to them — for a deployment that runs its own migrations,
+ * once. `ensureJobTables` does it by itself, and only when the table needs it: the `ALTER` copies the table.
+ */
+export declare const mysqlJobSchemaUpgrades: (prefix?: string) => string[];
+/** The server's now, in epoch ms, as an SQL expression — what every comparison reads instead of a caller's clock. */
+export declare const NOW_MS = "CAST(ROUND(UNIX_TIMESTAMP(NOW(3)) * 1000) AS SIGNED)";
+/** Creates the tables once per process, on first use; a failure is retried by the next call rather than remembered. */
+export declare const ensureJobTables: (db: Queryable, prefix: string, create: boolean) => (() => Promise<void>);

package/dist/modules/mysql/jobs/schema.js

@@ -0,0 +1,113 @@
+import { execute, selectRows } from "../query.js";
+//#region src/modules/mysql/jobs/schema.ts
+var PREFIX = /^[A-Za-z0-9_]*$/;
+/**
+* Table names under a prefix. A prefix is part of an identifier, which no driver can bind as a parameter — so it is
+* held to the characters an unquoted identifier may use, and refused otherwise, rather than escaped and hoped for.
+*/
+var jobTables = (prefix = "") => {
+	if (!PREFIX.test(prefix)) throw new Error(`@plitzi/sdk-server/mysql: tablePrefix "${prefix}" may only use letters, digits and underscores`);
+	return {
+		jobs: `\`${prefix}action_jobs\``,
+		schedules: `\`${prefix}action_schedules\``,
+		kv: `\`${prefix}action_kv\``
+	};
+};
+var CHARSET = "ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COLLATE=utf8mb4_unicode_ci";
+/**
+* The tables, as SQL — for a deployment that runs its own migrations rather than letting the helpers create them.
+*
+* Instants are epoch milliseconds in `BIGINT`, read from the SERVER's clock; `history` and `input` are JSON kept as
+* text, because they are only ever read whole. Separate from the account store's schema and its version: a deployment
+* can use either without the other.
+*
+* A `kv` key is BYTES, as it is in Redis and in memory: under a collation `Board` and `board` — and `a` and `a ` — were
+* one key here and two everywhere else. A value is a `MEDIUMTEXT`: a `TEXT` stops at 64 KB, and past it MySQL
+* refuses the write, or cuts it short where it is not strict.
+*/
+var mysqlJobSchemaStatements = (prefix = "") => {
+	const t = jobTables(prefix);
+	return [
+		`CREATE TABLE IF NOT EXISTS ${t.jobs} (
+      id VARCHAR(191) NOT NULL,
+      space_id BIGINT NOT NULL,
+      action_id VARCHAR(191) NOT NULL,
+      environment VARCHAR(64) NOT NULL,
+      trigger_type VARCHAR(64) NOT NULL,
+      input MEDIUMTEXT NOT NULL,
+      due_at BIGINT NOT NULL,
+      max_attempts INT NOT NULL,
+      missed INT NULL,
+      status VARCHAR(16) NOT NULL,
+      run_at BIGINT NOT NULL,
+      attempts INT NOT NULL DEFAULT 0,
+      lease_until BIGINT NULL,
+      worker_id VARCHAR(191) NULL,
+      run_id VARCHAR(191) NULL,
+      cancel_requested TINYINT(1) NOT NULL DEFAULT 0,
+      created_at BIGINT NOT NULL,
+      updated_at BIGINT NOT NULL,
+      error TEXT NULL,
+      history MEDIUMTEXT NOT NULL,
+      expires_at BIGINT NULL,
+      PRIMARY KEY (id),
+      KEY action_jobs_pending (status, run_at),
+      KEY action_jobs_lease (status, lease_until),
+      KEY action_jobs_space (space_id, updated_at),
+      KEY action_jobs_expires (expires_at)
+    ) ${CHARSET}`,
+		`CREATE TABLE IF NOT EXISTS ${t.schedules} (
+      space_id BIGINT NOT NULL,
+      action_id VARCHAR(191) NOT NULL,
+      cron VARCHAR(191) NOT NULL,
+      timezone VARCHAR(64) NULL,
+      environment VARCHAR(64) NOT NULL,
+      enabled TINYINT(1) NOT NULL,
+      next_run_at BIGINT NOT NULL,
+      last_fire_at BIGINT NULL,
+      missed INT NOT NULL DEFAULT 0,
+      max_attempts INT NOT NULL,
+      updated_at BIGINT NOT NULL,
+      PRIMARY KEY (space_id, action_id),
+      KEY action_schedules_due (enabled, next_run_at)
+    ) ${CHARSET}`,
+		`CREATE TABLE IF NOT EXISTS ${t.kv} (
+      k VARBINARY(764) NOT NULL,
+      v MEDIUMTEXT NOT NULL,
+      expires_at BIGINT NULL,
+      PRIMARY KEY (k),
+      KEY action_kv_expires (expires_at)
+    ) ${CHARSET}`
+	];
+};
+/**
+* What brings a `kv` table made before the columns above up to them — for a deployment that runs its own migrations,
+* once. `ensureJobTables` does it by itself, and only when the table needs it: the `ALTER` copies the table.
+*/
+var mysqlJobSchemaUpgrades = (prefix = "") => [`ALTER TABLE ${jobTables(prefix).kv} MODIFY k VARBINARY(764) NOT NULL, MODIFY v MEDIUMTEXT NOT NULL`];
+/** Whether the `kv` table still has the columns it was first made with. */
+var kvNeedsUpgrade = async (db, prefix) => {
+	const columns = await selectRows(db, `SELECT COLUMN_NAME AS name, DATA_TYPE AS type FROM INFORMATION_SCHEMA.COLUMNS
+    WHERE TABLE_SCHEMA = DATABASE() AND TABLE_NAME = ? AND COLUMN_NAME IN ('k', 'v')`, [`${prefix}action_kv`]);
+	const typeOf = (name) => columns.find((column) => column.name === name)?.type.toLowerCase();
+	return typeOf("k") !== "varbinary" || typeOf("v") !== "mediumtext";
+};
+/** The server's now, in epoch ms, as an SQL expression — what every comparison reads instead of a caller's clock. */
+var NOW_MS = "CAST(ROUND(UNIX_TIMESTAMP(NOW(3)) * 1000) AS SIGNED)";
+/** Creates the tables once per process, on first use; a failure is retried by the next call rather than remembered. */
+var ensureJobTables = (db, prefix, create) => {
+	let ready;
+	return async () => {
+		if (!create) return;
+		ready ??= (async () => {
+			for (const statement of mysqlJobSchemaStatements(prefix)) await execute(db, statement);
+			if (await kvNeedsUpgrade(db, prefix)) for (const statement of mysqlJobSchemaUpgrades(prefix)) await execute(db, statement);
+		})().catch((error) => {
+			ready = void 0;
+			throw error;
+		});
+		await ready;
+	};
+};
+//#endregion
+export { NOW_MS, ensureJobTables, jobTables, mysqlJobSchemaStatements, mysqlJobSchemaUpgrades };

package/dist/modules/mysql/jobs/stores.integration.test.d.ts

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