@byline/db-mysql 4.14.1 → 4.16.0

package/dist/modules/storage/publish-schedules.js

@@ -0,0 +1,406 @@
+/**
+ * This Source Code is subject to the terms of the Mozilla Public
+ * License, v. 2.0. If a copy of the MPL was not distributed with this
+ * file, You can obtain one at http://mozilla.org/MPL/2.0/.
+ *
+ * Copyright (c) Infonomic Company Limited
+ */
+import { randomUUID } from 'node:crypto';
+import { sql } from 'drizzle-orm';
+import { affectedRowCount, toDate } from './storage-utils.js';
+const LAST_ERROR_MAX_LENGTH = 2_048;
+function requiredDate(value, column) {
+    const date = toDate(value, column);
+    if (date === null)
+        throw new Error(`publish schedules: ${column} unexpectedly returned null`);
+    return date;
+}
+function toSchedule(row) {
+    return {
+        documentId: row.document_id,
+        collectionId: row.collection_id,
+        targetVersionId: row.target_version_id,
+        publishAt: requiredDate(row.publish_at, 'publish_at'),
+        state: row.state,
+        suspendedAt: toDate(row.suspended_at, 'suspended_at'),
+        suspendedReason: row.suspended_reason,
+        scheduledBy: row.scheduled_by,
+        lastAuthorizedBy: row.last_authorized_by,
+        lastAuthorizedAt: requiredDate(row.last_authorized_at, 'last_authorized_at'),
+        scheduledAt: requiredDate(row.scheduled_at, 'scheduled_at'),
+        updatedAt: requiredDate(row.updated_at, 'updated_at'),
+        executionToken: row.execution_token,
+        executionExpiresAt: toDate(row.execution_expires_at, 'execution_expires_at'),
+        lastAttemptAt: toDate(row.last_attempt_at, 'last_attempt_at'),
+        nextAttemptAt: requiredDate(row.next_attempt_at, 'next_attempt_at'),
+        attemptCount: Number(row.attempt_count),
+        lastError: row.last_error,
+    };
+}
+function resultRows(result) {
+    return result[0];
+}
+function firstRow(result) {
+    return resultRows(result)[0];
+}
+function sanitizedError(error) {
+    return error
+        .replace(/\r?\n[\s\S]*$/, '')
+        .trim()
+        .slice(0, LAST_ERROR_MAX_LENGTH);
+}
+/** MySQL scheduled-publication writes on the ambient document transaction. */
+export class DocumentPublishScheduleCommands {
+    dbManager;
+    constructor(dbManager) {
+        this.dbManager = dbManager;
+    }
+    get db() {
+        return this.dbManager.get();
+    }
+    async lockCurrentVersion(params) {
+        const document = await this.db.execute(sql `
+      SELECT id
+      FROM byline_documents
+      WHERE id = ${params.documentId}
+        AND collection_id = ${params.collectionId}
+      FOR UPDATE
+    `);
+        if (resultRows(document).length === 0)
+            return null;
+        const current = await this.db.execute(sql `
+      SELECT id
+      FROM byline_document_versions
+      WHERE document_id = ${params.documentId}
+        AND collection_id = ${params.collectionId}
+        AND is_deleted = false
+      ORDER BY id DESC
+      LIMIT 1
+    `);
+        return firstRow(current)?.id ?? null;
+    }
+    async lockSchedule(documentId) {
+        const result = await this.db.execute(sql `
+      SELECT *
+      FROM byline_document_publish_schedules
+      WHERE document_id = ${documentId}
+      FOR UPDATE
+    `);
+        const row = firstRow(result);
+        return row === undefined ? null : toSchedule(row);
+    }
+    async readSchedule(documentId) {
+        const result = await this.db.execute(sql `
+      SELECT * FROM byline_document_publish_schedules WHERE document_id = ${documentId}
+    `);
+        const row = firstRow(result);
+        if (row === undefined)
+            throw new Error('publish schedules: schedule row disappeared');
+        return toSchedule(row);
+    }
+    async schedule(params) {
+        const currentVersionId = await this.lockCurrentVersion(params);
+        if (currentVersionId === null)
+            return { status: 'document_not_found' };
+        if (currentVersionId !== params.expectedVersionId)
+            return { status: 'version_mismatch' };
+        const previous = await this.lockSchedule(params.documentId);
+        const validation = await this.db.execute(sql `
+      SELECT
+        (${params.publishAt} > CURRENT_TIMESTAMP(6)) AS publish_at_is_future,
+        (${previous?.executionToken ?? null} IS NOT NULL
+          AND ${previous?.executionExpiresAt ?? null} > CURRENT_TIMESTAMP(6)) AS execution_is_live
+    `);
+        const flags = firstRow(validation);
+        if (!flags?.publish_at_is_future)
+            return { status: 'publish_at_not_future' };
+        if (flags.execution_is_live)
+            return { status: 'execution_in_progress' };
+        if (previous === null) {
+            await this.db.execute(sql `
+        INSERT INTO byline_document_publish_schedules (
+          document_id, collection_id, target_version_id, publish_at,
+          state, suspended_at, suspended_reason,
+          scheduled_by, last_authorized_by, last_authorized_at,
+          execution_token, execution_expires_at, last_attempt_at,
+          next_attempt_at, attempt_count, last_error, updated_at
+        ) VALUES (
+          ${params.documentId},
+          ${params.collectionId},
+          ${params.expectedVersionId},
+          ${params.publishAt},
+          'armed', NULL, NULL,
+          ${params.actorId}, ${params.actorId}, CURRENT_TIMESTAMP(6),
+          NULL, NULL, NULL,
+          ${params.publishAt}, 0, NULL, CURRENT_TIMESTAMP(6)
+        )
+      `);
+        }
+        else {
+            await this.db.execute(sql `
+        UPDATE byline_document_publish_schedules SET
+          target_version_id = ${params.expectedVersionId},
+          publish_at = ${params.publishAt},
+          state = 'armed',
+          suspended_at = NULL,
+          suspended_reason = NULL,
+          last_authorized_by = ${params.actorId},
+          last_authorized_at = CURRENT_TIMESTAMP(6),
+          execution_token = NULL,
+          execution_expires_at = NULL,
+          last_attempt_at = NULL,
+          next_attempt_at = ${params.publishAt},
+          attempt_count = 0,
+          last_error = NULL,
+          updated_at = CURRENT_TIMESTAMP(6)
+        WHERE document_id = ${params.documentId}
+      `);
+        }
+        return { status: 'scheduled', schedule: await this.readSchedule(params.documentId), previous };
+    }
+    async confirm(params) {
+        const currentVersionId = await this.lockCurrentVersion(params);
+        if (currentVersionId === null || currentVersionId !== params.expectedVersionId) {
+            return { status: 'version_mismatch' };
+        }
+        const previous = await this.lockSchedule(params.documentId);
+        if (previous === null || previous.collectionId !== params.collectionId) {
+            return { status: 'schedule_not_found' };
+        }
+        if (previous.state !== 'needs_reconfirm')
+            return { status: 'not_suspended' };
+        await this.db.execute(sql `
+      UPDATE byline_document_publish_schedules SET
+        target_version_id = ${params.expectedVersionId},
+        state = 'armed',
+        suspended_at = NULL,
+        suspended_reason = NULL,
+        last_authorized_by = ${params.actorId},
+        last_authorized_at = CURRENT_TIMESTAMP(6),
+        execution_token = NULL,
+        execution_expires_at = NULL,
+        last_attempt_at = NULL,
+        next_attempt_at = publish_at,
+        attempt_count = 0,
+        last_error = NULL,
+        updated_at = CURRENT_TIMESTAMP(6)
+      WHERE document_id = ${params.documentId}
+    `);
+        return {
+            status: 'confirmed',
+            schedule: await this.readSchedule(params.documentId),
+            previousTargetVersionId: previous.targetVersionId,
+        };
+    }
+    async cancel(params) {
+        const locked = await this.lockSchedule(params.documentId);
+        if (locked === null || locked.collectionId !== params.collectionId)
+            return null;
+        const result = await this.db.execute(sql `
+      DELETE FROM byline_document_publish_schedules
+      WHERE document_id = ${params.documentId}
+        AND collection_id = ${params.collectionId}
+    `);
+        return affectedRowCount(result) === 1 ? locked : null;
+    }
+    async suspendForContentEdit(params) {
+        const locked = await this.lockSchedule(params.documentId);
+        if (locked === null || locked.collectionId !== params.collectionId) {
+            return { status: 'schedule_not_found' };
+        }
+        if (locked.state === 'needs_reconfirm')
+            return { status: 'already_suspended' };
+        await this.db.execute(sql `
+      UPDATE byline_document_publish_schedules SET
+        state = 'needs_reconfirm',
+        suspended_at = CURRENT_TIMESTAMP(6),
+        suspended_reason = 'content_edited',
+        execution_token = NULL,
+        execution_expires_at = NULL,
+        updated_at = CURRENT_TIMESTAMP(6)
+      WHERE document_id = ${params.documentId}
+    `);
+        return { status: 'suspended', schedule: await this.readSchedule(params.documentId) };
+    }
+    async claimDue(params) {
+        const batchSize = Math.max(0, Math.trunc(params.batchSize));
+        if (batchSize === 0)
+            return [];
+        return this.db.transaction(async (tx) => {
+            const selected = await tx.execute(sql `
+          SELECT document_id, execution_token
+          FROM byline_document_publish_schedules
+          WHERE state = 'armed'
+            AND publish_at <= CURRENT_TIMESTAMP(6)
+            AND next_attempt_at <= CURRENT_TIMESTAMP(6)
+            AND (execution_expires_at IS NULL OR execution_expires_at <= CURRENT_TIMESTAMP(6))
+          ORDER BY publish_at, document_id
+          LIMIT ${batchSize}
+          FOR UPDATE SKIP LOCKED
+        `);
+            const candidates = resultRows(selected);
+            const claimed = [];
+            for (const candidate of candidates) {
+                const token = randomUUID();
+                const update = await tx.execute(sql `
+            UPDATE byline_document_publish_schedules SET
+              execution_token = ${token},
+              execution_expires_at = TIMESTAMPADD(
+                MICROSECOND,
+                ${params.leaseMs} * 1000,
+                CURRENT_TIMESTAMP(6)
+              ),
+              last_attempt_at = CURRENT_TIMESTAMP(6),
+              attempt_count = attempt_count + 1,
+              updated_at = CURRENT_TIMESTAMP(6)
+            WHERE document_id = ${candidate.document_id}
+          `);
+                if (affectedRowCount(update) !== 1) {
+                    throw new Error(`publish schedules: locked row '${candidate.document_id}' disappeared`);
+                }
+                const reread = await tx.execute(sql `
+            SELECT *
+            FROM byline_document_publish_schedules
+            WHERE document_id = ${candidate.document_id}
+          `);
+                const row = firstRow(reread);
+                if (row === undefined) {
+                    throw new Error(`publish schedules: claimed row '${candidate.document_id}' disappeared`);
+                }
+                const schedule = toSchedule(row);
+                if (schedule.executionToken === null ||
+                    schedule.executionExpiresAt === null ||
+                    schedule.lastAttemptAt === null) {
+                    throw new Error('publish schedules: claimed row returned without its execution fence');
+                }
+                claimed.push({
+                    ...schedule,
+                    executionToken: schedule.executionToken,
+                    executionExpiresAt: schedule.executionExpiresAt,
+                    lastAttemptAt: schedule.lastAttemptAt,
+                    databaseNow: schedule.lastAttemptAt,
+                    recoveredExpiredClaim: candidate.execution_token !== null,
+                });
+            }
+            return claimed;
+        }, { isolationLevel: 'read committed' });
+    }
+    async lockClaim(params) {
+        const result = await this.db.execute(sql `
+      SELECT *
+      FROM byline_document_publish_schedules
+      WHERE document_id = ${params.documentId}
+        AND execution_token = ${params.executionToken}
+      FOR UPDATE
+    `);
+        const row = firstRow(result);
+        return row === undefined ? null : toSchedule(row);
+    }
+    async deleteClaim(params) {
+        const result = await this.db.execute(sql `
+      DELETE FROM byline_document_publish_schedules
+      WHERE document_id = ${params.documentId}
+        AND execution_token = ${params.executionToken}
+    `);
+        return affectedRowCount(result) === 1;
+    }
+    async suspendClaimForContentEdit(params) {
+        const result = await this.db.execute(sql `
+      UPDATE byline_document_publish_schedules SET
+        state = 'needs_reconfirm',
+        suspended_at = CURRENT_TIMESTAMP(6),
+        suspended_reason = 'content_edited',
+        execution_token = NULL,
+        execution_expires_at = NULL,
+        last_attempt_at = NULL,
+        next_attempt_at = publish_at,
+        attempt_count = 0,
+        last_error = NULL,
+        updated_at = CURRENT_TIMESTAMP(6)
+      WHERE document_id = ${params.documentId}
+        AND execution_token = ${params.executionToken}
+    `);
+        return affectedRowCount(result) === 1;
+    }
+    /**
+     * `attempt_count` is read but not assigned, so MySQL's left-to-right SET
+     * evaluation cannot shift the backoff sequence. If it is ever assigned in
+     * this statement, keep `next_attempt_at` before that assignment.
+     */
+    async releaseClaim(params) {
+        const result = await this.db.execute(sql `
+      UPDATE byline_document_publish_schedules SET
+        execution_token = NULL,
+        execution_expires_at = NULL,
+        last_error = ${sanitizedError(params.error)},
+        next_attempt_at = TIMESTAMPADD(
+          MINUTE,
+          CASE attempt_count
+            WHEN 1 THEN 1
+            WHEN 2 THEN 2
+            WHEN 3 THEN 4
+            WHEN 4 THEN 8
+            ELSE 15
+          END,
+          CURRENT_TIMESTAMP(6)
+        ),
+        updated_at = CURRENT_TIMESTAMP(6)
+      WHERE document_id = ${params.documentId}
+        AND execution_token = ${params.executionToken}
+    `);
+        return affectedRowCount(result) === 1;
+    }
+}
+/** MySQL scheduled-publication reads. */
+export class DocumentPublishScheduleQueries {
+    db;
+    constructor(db) {
+        this.db = db;
+    }
+    async get(params) {
+        const result = await this.db.execute(sql `
+      SELECT *
+      FROM byline_document_publish_schedules
+      WHERE document_id = ${params.documentId}
+        AND collection_id = ${params.collectionId}
+    `);
+        const row = firstRow(result);
+        return row === undefined ? null : toSchedule(row);
+    }
+    async list(params) {
+        if (params.collectionIds.length === 0)
+            return { schedules: [], total: 0 };
+        const collectionList = sql.join(params.collectionIds.map((id) => sql `${id}`), sql `, `);
+        const statePredicate = params.states === undefined
+            ? sql ``
+            : params.states.length === 0
+                ? sql `AND false`
+                : sql `AND state IN (${sql.join(params.states.map((state) => sql `${state}`), sql `, `)})`;
+        const actorPredicate = params.lastAuthorizedBy === undefined
+            ? sql ``
+            : sql `AND last_authorized_by = ${params.lastAuthorizedBy}`;
+        const offset = Math.max(0, (params.page - 1) * params.pageSize);
+        const pageSize = Math.max(0, Math.trunc(params.pageSize));
+        const count = await this.db.execute(sql `
+      SELECT count(*) AS total
+      FROM byline_document_publish_schedules
+      WHERE collection_id IN (${collectionList})
+      ${statePredicate}
+      ${actorPredicate}
+    `);
+        const total = Number(firstRow(count)?.total ?? 0);
+        if (pageSize === 0 || total === 0)
+            return { schedules: [], total };
+        const rows = await this.db.execute(sql `
+      SELECT *
+      FROM byline_document_publish_schedules
+      WHERE collection_id IN (${collectionList})
+      ${statePredicate}
+      ${actorPredicate}
+      ORDER BY publish_at, document_id
+      LIMIT ${pageSize}
+      OFFSET ${offset}
+    `);
+        return { schedules: resultRows(rows).map(toSchedule), total };
+    }
+}

package/dist/modules/storage/storage-commands.d.ts

@@ -6,6 +6,7 @@
  * Copyright (c) Infonomic Company Limited
  */
 import type { CollectionDefinition, ICollectionCommands, IDocumentCommands, TreeDeleteMutationResult, TreeMutationResult } from '@byline/core';
+import { DocumentPublishScheduleCommands } from './publish-schedules.js';
 import type { DBManager } from '../../lib/db-manager.js';
 /**
  * CollectionCommands
@@ -78,6 +79,7 @@ export declare class CollectionCommands implements ICollectionCommands {
 export declare class DocumentCommands implements IDocumentCommands {
     private dbManager;
     private defaultContentLocale;
+    readonly publishSchedules: DocumentPublishScheduleCommands;
     constructor(dbManager: DBManager, defaultContentLocale: string);
     /**
      * The executor for this call — the ambient transaction when a

package/dist/modules/storage/storage-commands.js

@@ -10,6 +10,7 @@ import { and, desc, eq, inArray, ne, notInArray, sql } from 'drizzle-orm';
 import { v7 as uuidv7 } from 'uuid';
 import { booleanStore, collections, currentDocumentsView, datetimeStore, documentAvailableLocales, documentPaths, documentRelationships, documents, documentVersions, fileStore, jsonStore, metaStore, numericStore, relationStore, textStore, } from '../../database/schema/index.js';
 import { classifyError } from './classify-error.js';
+import { DocumentPublishScheduleCommands } from './publish-schedules.js';
 import { prepareFieldInsertBuckets } from './storage-insert.js';
 import { affectedRowCount, getFirstOrThrow } from './storage-utils.js';
 /**
@@ -135,9 +136,11 @@ export class CollectionCommands {
 export class DocumentCommands {
     dbManager;
     defaultContentLocale;
+    publishSchedules;
     constructor(dbManager, defaultContentLocale) {
         this.dbManager = dbManager;
         this.defaultContentLocale = defaultContentLocale;
+        this.publishSchedules = new DocumentPublishScheduleCommands(dbManager);
     }
     /**
      * The executor for this call — the ambient transaction when a

package/dist/modules/storage/storage-queries.d.ts

@@ -24,6 +24,7 @@
  */
 import type { CollectionDefinition, DocumentFilter, FieldFilterOperator, FieldSort, FlattenedStore, ICollectionQueries, IDocumentQueries, MissingLocalePolicy, ReadMode } from '@byline/core';
 import type { MySql2Database } from 'drizzle-orm/mysql2';
+import { DocumentPublishScheduleQueries } from './publish-schedules.js';
 import type * as schema from '../../database/schema/index.js';
 import type { DBManager } from '../../lib/db-manager.js';
 type DatabaseConnection = MySql2Database<typeof schema>;
@@ -74,6 +75,7 @@ export declare class CollectionQueries implements ICollectionQueries {
  * DocumentQueries
  */
 export declare class DocumentQueries implements IDocumentQueries {
+    readonly publishSchedules: DocumentPublishScheduleQueries;
     private db;
     private transactionDb;
     private collections;

package/dist/modules/storage/storage-queries.js

@@ -25,6 +25,7 @@
 import { ERR_DATABASE, ERR_NOT_FOUND, extractFlattenedFieldValue, getLogger, orderByContentLocale, resolveIdentityField, resolveStoreTypes, restoreFieldSetData, } from '@byline/core';
 import { and, desc, eq, inArray, isNotNull, isNull, sql } from 'drizzle-orm';
 import { collections, currentDocumentsView, currentPublishedDocumentsView, documentAvailableLocales, documentPaths, documentRelationships, documents, documentVersionLocales, documentVersions, metaStore, } from '../../database/schema/index.js';
+import { DocumentPublishScheduleQueries } from './publish-schedules.js';
 import { normalizeRow } from './normalize-row.js';
 import { allStoreTypes, storeSelectList, storeTableNames, } from './storage-store-manifest.js';
 import { toDate } from './storage-utils.js';
@@ -61,12 +62,14 @@ export class CollectionQueries {
  * DocumentQueries
  */
 export class DocumentQueries {
+    publishSchedules;
     db;
     transactionDb;
     collections;
     defaultContentLocale;
     collectionPathCache = new Map();
     constructor(db, collections, defaultContentLocale, transactionDb) {
+        this.publishSchedules = new DocumentPublishScheduleQueries(db);
         this.db = db;
         this.transactionDb = transactionDb;
         this.collections = collections;

package/package.json

@@ -2,7 +2,7 @@
   "name": "@byline/db-mysql",
   "private": false,
   "license": "MPL-2.0",
-  "version": "4.14.1",
+  "version": "4.16.0",
   "engines": {
     "node": ">=20.9.0"
   },
@@ -50,8 +50,8 @@
     "drizzle-orm": "^0.45.2",
     "mysql2": "^3.23.4",
     "uuid": "^14.0.2",
-    "@byline/admin": "4.14.1",
-    "@byline/core": "4.14.1"
+    "@byline/admin": "4.16.0",
+    "@byline/core": "4.16.0"
   },
   "devDependencies": {
     "@biomejs/biome": "2.5.9",
@@ -65,9 +65,9 @@
     "tsx": "^4.23.12",
     "typescript": "^7.0.2",
     "vitest": "^4.1.11",
-    "@byline/client": "4.14.1",
-    "@byline/auth": "4.14.1",
-    "@byline/db-conformance": "0.0.10"
+    "@byline/client": "4.16.0",
+    "@byline/db-conformance": "0.0.10",
+    "@byline/auth": "4.16.0"
   },
   "publishConfig": {
     "access": "public",