Add MariaDB queue table. Fix Bugs

2026-10-18 15:58:02 +01:00
parent d872c3661a
commit f9ba5f8657
28 changed files with 785 additions and 49 deletions
@@ -235,6 +235,87 @@ export const DefaultFields = [
        fieldDescription: "The time when the record was updated. (Unix Timestamp)",
    },
 ];
+/**
+ * Lifecycle of a queue row. Only `pending` jobs are claimed.
+ * - `done`: acknowledged, kept because of `keep_completed` (otherwise deleted)
+ * - `failed`: used up its attempts (dead letter)
+ * - `cancelled`: removed from the queue with `queue.cancel`
+ */
+export const QueueStatuses = [
+    "pending",
+    "processing",
+    "done",
+    "failed",
+    "cancelled",
+];
+/**
+ * Fields added to every table with `queue_table: true`.
+ */
+export const QueueFields = [
+    {
+        fieldName: "queue_status",
+        dataType: "ENUM",
+        options: [...QueueStatuses],
+        notNullValue: true,
+        defaultValue: "pending",
+        fieldDescription: "Queue state of the job.",
+    },
+    {
+        fieldName: "queue_available_at",
+        dataType: "BIGINT",
+        notNullValue: true,
+        defaultValue: 0,
+        fieldDescription: "The job cannot be claimed before this time. (Unix Timestamp, ms)",
+    },
+    {
+        fieldName: "queue_attempts",
+        dataType: "INT",
+        notNullValue: true,
+        defaultValue: 0,
+        fieldDescription: "How many times the job has been claimed.",
+    },
+    {
+        fieldName: "queue_lease_expires_at",
+        dataType: "BIGINT",
+        fieldDescription: "When the current claim expires and the job can be reclaimed. (Unix Timestamp, ms)",
+    },
+    {
+        fieldName: "queue_lock_token",
+        dataType: "VARCHAR",
+        dataLength: 64,
+        fieldDescription: "Token of the current claim. Required to ack, fail or extend the job.",
+    },
+    {
+        fieldName: "queue_last_error",
+        dataType: "TEXT",
+        fieldDescription: "Error message from the last failed attempt.",
+    },
+];
+/**
+ * Queue fields only the queue API may write. `queue_available_at` can be set
+ * on insert and update.
+ */
+export const QueueProtectedFields = [
+    "queue_status",
+    "queue_attempts",
+    "queue_lease_expires_at",
+    "queue_lock_token",
+    "queue_last_error",
+];
+/**
+ * Indexes added to queue tables. Claims scan `idx_queue_claim` in order, so
+ * `LIMIT` stops the scan early and only the claimed rows get locked.
+ */
+export const QueueIndexes = [
+    {
+        indexName: "idx_queue_claim",
+        indexTableFields: ["queue_status", "queue_available_at"],
+    },
+    {
+        indexName: "idx_queue_lease",
+        indexTableFields: ["queue_status", "queue_lease_expires_at"],
+    },
+];
 export const RequiredENVs = [
    "BUN_MARIADB_SERVER_HOST",
    "BUN_MARIADB_SERVER_PORT",