@byline/db-mysql 4.14.0 → 4.15.0

package/dist/database/schema/schema-pins.test.node.js

@@ -418,3 +418,48 @@ describe('schema pins — document-paths case-sensitive collation (project-owner
         expect(pathColumn?.getSQLType()).toBe('varchar(255) COLLATE utf8mb4_bin');
     });
 });
+describe('schema pins — scheduled publication', () => {
+    const cfg = getTableConfig(coreSchema.documentPublishSchedules);
+    it('pins one row per document and exactly the three lifecycle ownership foreign keys', () => {
+        const documentId = cfg.columns.find((column) => column.name === 'document_id');
+        expect(documentId?.primary).toBe(true);
+        const references = cfg.foreignKeys.map((foreignKey) => ({
+            name: foreignKey.getName(),
+            local: foreignKey.reference().columns.map((column) => column.name),
+            onDelete: foreignKey.onDelete,
+        }));
+        expect(references).toEqual([
+            {
+                name: 'fk_publish_schedules_document',
+                local: ['document_id'],
+                onDelete: 'cascade',
+            },
+            {
+                name: 'fk_publish_schedules_collection',
+                local: ['collection_id'],
+                onDelete: 'cascade',
+            },
+            {
+                name: 'fk_publish_schedules_target_version',
+                local: ['target_version_id'],
+                onDelete: 'cascade',
+            },
+        ]);
+    });
+    it('pins the bounded state and suspension-reason constraints', () => {
+        expect(cfg.checks.map((constraint) => constraint.name).sort()).toEqual([
+            'check_publish_schedules_state',
+            'check_publish_schedules_suspended_reason',
+        ]);
+    });
+    it('pins state as the MySQL due-index discriminator and execution-expiry recovery', () => {
+        const due = cfg.indexes.find((candidate) => candidate.config.name === 'idx_document_publish_schedules_due');
+        expect(due?.config.columns.map((column) => ('name' in column ? column.name : null))).toEqual([
+            'state',
+            'next_attempt_at',
+            'publish_at',
+        ]);
+        const expiry = cfg.indexes.find((candidate) => candidate.config.name === 'idx_document_publish_schedules_execution_expiry');
+        expect(expiry?.config.columns.map((column) => ('name' in column ? column.name : null))).toEqual(['execution_expires_at']);
+    });
+});

package/dist/index.js

@@ -13,6 +13,7 @@ import { DBManagerImpl, TXManagerImpl } from './lib/db-manager.js';
 import { createAuditCommands } from './modules/audit/audit-commands.js';
 import { createAuditQueries } from './modules/audit/audit-queries.js';
 import { createCounterCommands } from './modules/counters/counters-commands.js';
+import { createSchedulerStore } from './modules/scheduler/scheduler-store.js';
 import { classifyError } from './modules/storage/classify-error.js';
 import { createCommandBuilders } from './modules/storage/storage-commands.js';
 import { createQueryBuilders } from './modules/storage/storage-queries.js';
@@ -85,6 +86,7 @@ export const mysqlAdapter = ({ connectionString, collections, defaultContentLoca
     const counterCommands = createCounterCommands(pool);
     const auditCommands = createAuditCommands(dbManager);
     const auditQueries = createAuditQueries(db);
+    const schedulerStore = createSchedulerStore(db);
     // Boot check: run lazily on the pool's first physical connection rather
     // than eagerly here, because `mysqlAdapter` is synchronous (mirroring
     // `pgAdapter`) and cannot await a round trip before returning. mysql2
@@ -144,6 +146,7 @@ export const mysqlAdapter = ({ connectionString, collections, defaultContentLoca
             audit: auditQueries,
         },
         withTransaction: (fn) => txManager.withTransaction(fn),
+        scheduler: schedulerStore,
         classifyError,
         drizzle: db,
         pool,

package/dist/modules/scheduler/scheduler-store.d.ts

@@ -0,0 +1,13 @@
+/**
+ * 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 type { ISchedulerStore } from '@byline/core';
+import type { MySql2Database } from 'drizzle-orm/mysql2';
+import type * as schema from '../../database/schema/index.js';
+type DatabaseConnection = MySql2Database<typeof schema>;
+export declare function createSchedulerStore(db: DatabaseConnection): ISchedulerStore;
+export {};

package/dist/modules/scheduler/scheduler-store.js

@@ -0,0 +1,237 @@
+/**
+ * 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
+ */
+/**
+ * MySQL implementation of `ISchedulerStore` (specs/2026-08-22-scheduler.md).
+ * Every due and lease comparison uses database UTC time, and every write after
+ * a claim is fenced by the claim's token.
+ *
+ * MySQL has no `UPDATE ... RETURNING`, so `claim()` locks the eligible row,
+ * updates it, and returns the pre-claim schedule from one READ COMMITTED
+ * transaction. The transaction is deliberately store-owned rather than ambient:
+ * scheduler claims must not inherit a caller's longer transaction boundary.
+ */
+import { randomUUID } from 'node:crypto';
+import { MAX_BACKOFF_MS } from '@byline/core/scheduler';
+import { sql } from 'drizzle-orm';
+import { affectedRowCount, toDate } from '../storage/storage-utils.js';
+/** Doc comment on `ISchedulerStore.fail`: 2048 characters, never a stack trace. */
+const LAST_ERROR_MAX_LENGTH = 2048;
+/** Doc comment on `ISchedulerStore.health`: `lease_owner` capped at 255 characters. */
+const LEASE_OWNER_MAX_LENGTH = 255;
+const MAX_BACKOFF_SECONDS = MAX_BACKOFF_MS / 1000;
+function requiredDate(value, context) {
+    const date = toDate(value, context);
+    if (date === null) {
+        throw new Error(`scheduler store: ${context} unexpectedly returned null`);
+    }
+    return date;
+}
+class SchedulerStore {
+    db;
+    constructor(db) {
+        this.db = db;
+    }
+    /**
+     * One conflict-tolerant upsert per definition. `interval_ms` always follows
+     * code, while an unleased `next_run_at` is only pulled earlier when the new
+     * interval would otherwise leave the task waiting too long.
+     */
+    async reconcile(tasks) {
+        for (const task of tasks) {
+            await this.db.execute(sql `
+        INSERT INTO byline_recurring_tasks (name, interval_ms, next_run_at, last_status)
+        VALUES (
+          ${task.name},
+          ${task.intervalMs},
+          TIMESTAMPADD(MICROSECOND, ${task.intervalMs} * 1000, CURRENT_TIMESTAMP(6)),
+          'never_run'
+        )
+        ON DUPLICATE KEY UPDATE
+          next_run_at = CASE
+            WHEN lease_token IS NULL
+             AND next_run_at > TIMESTAMPADD(
+               MICROSECOND,
+               ${task.intervalMs} * 1000,
+               CURRENT_TIMESTAMP(6)
+             )
+            THEN TIMESTAMPADD(MICROSECOND, ${task.intervalMs} * 1000, CURRENT_TIMESTAMP(6))
+            ELSE next_run_at
+          END,
+          interval_ms = ${task.intervalMs},
+          updated_at = CURRENT_TIMESTAMP(6)
+      `);
+        }
+    }
+    /**
+     * Atomic claim through a locking read and fenced update on one physical
+     * connection. Under READ COMMITTED, contenders blocked on `FOR UPDATE`
+     * re-check the eligibility predicate after the winner commits and return
+     * null instead of observing the stale due row.
+     */
+    async claim(params) {
+        return this.db.transaction(async (tx) => {
+            const selected = (await tx.execute(sql `
+          SELECT
+            name,
+            next_run_at AS scheduled_for,
+            CURRENT_TIMESTAMP(6) AS database_now,
+            (lease_expires_at IS NOT NULL) AS recovered_expired_lease
+          FROM byline_recurring_tasks
+          WHERE name = ${params.name}
+            AND next_run_at <= CURRENT_TIMESTAMP(6)
+            AND (lease_expires_at IS NULL OR lease_expires_at <= CURRENT_TIMESTAMP(6))
+          FOR UPDATE
+        `));
+            const row = selected[0][0];
+            if (row === undefined)
+                return null;
+            const leaseToken = randomUUID();
+            const result = await tx.execute(sql `
+          UPDATE byline_recurring_tasks SET
+            lease_token = ${leaseToken},
+            lease_owner = ${params.owner.slice(0, LEASE_OWNER_MAX_LENGTH)},
+            lease_expires_at = TIMESTAMPADD(
+              MICROSECOND,
+              ${params.leaseMs} * 1000,
+              CURRENT_TIMESTAMP(6)
+            ),
+            last_started_at = CURRENT_TIMESTAMP(6),
+            last_status = 'running',
+            updated_at = CURRENT_TIMESTAMP(6)
+          WHERE name = ${params.name}
+        `);
+            if (affectedRowCount(result) !== 1) {
+                throw new Error(`scheduler store: locked claim row '${params.name}' disappeared`);
+            }
+            return {
+                name: row.name,
+                leaseToken,
+                scheduledFor: requiredDate(row.scheduled_for, 'scheduled_for'),
+                databaseNow: requiredDate(row.database_now, 'database_now'),
+                recoveredExpiredLease: Boolean(row.recovered_expired_lease),
+            };
+        }, { isolationLevel: 'read committed' });
+    }
+    /**
+     * Do not add an expiry predicate: expiry makes a row claimable but does not
+     * invalidate the current token until another claimant replaces it.
+     */
+    async renew(params) {
+        const result = await this.db.execute(sql `
+      UPDATE byline_recurring_tasks SET
+        lease_expires_at = TIMESTAMPADD(
+          MICROSECOND,
+          ${params.leaseMs} * 1000,
+          CURRENT_TIMESTAMP(6)
+        ),
+        updated_at = CURRENT_TIMESTAMP(6)
+      WHERE name = ${params.name} AND lease_token = ${params.leaseToken}
+    `);
+        return affectedRowCount(result) === 1;
+    }
+    /**
+     * Complete a token-matched run and schedule from the persisted cadence.
+     * `interval_ms` is read but not assigned here, so assignment order is
+     * currently irrelevant. If a future change adds it to this SET list, keep
+     * that assignment after `next_run_at` so the persisted pre-update cadence is
+     * retained; see `fail()` for MySQL's left-to-right assignment rule.
+     */
+    async complete(params) {
+        const nextRunAt = params.workRemaining
+            ? sql `CURRENT_TIMESTAMP(6)`
+            : sql `TIMESTAMPADD(MICROSECOND, interval_ms * 1000, CURRENT_TIMESTAMP(6))`;
+        const result = await this.db.execute(sql `
+      UPDATE byline_recurring_tasks SET
+        last_succeeded_at = CURRENT_TIMESTAMP(6),
+        last_status = 'succeeded',
+        last_duration_ms = ${params.durationMs},
+        consecutive_failures = 0,
+        last_error = NULL,
+        lease_token = NULL,
+        lease_owner = NULL,
+        lease_expires_at = NULL,
+        next_run_at = ${nextRunAt},
+        updated_at = CURRENT_TIMESTAMP(6)
+      WHERE name = ${params.name} AND lease_token = ${params.leaseToken}
+    `);
+        return affectedRowCount(result) === 1;
+    }
+    /**
+     * Record a token-matched failure with 1, 2, 4, 8, then 15 minute backoff.
+     * MySQL evaluates single-table UPDATE assignments from left to right, so
+     * `next_run_at` intentionally reads the old `consecutive_failures` before
+     * the following assignment increments it.
+     */
+    async fail(params) {
+        const result = await this.db.execute(sql `
+      UPDATE byline_recurring_tasks SET
+        last_failed_at = CURRENT_TIMESTAMP(6),
+        last_status = 'failed',
+        last_duration_ms = ${params.durationMs},
+        last_error = ${params.error.slice(0, LAST_ERROR_MAX_LENGTH)},
+        lease_token = NULL,
+        lease_owner = NULL,
+        lease_expires_at = NULL,
+        next_run_at = TIMESTAMPADD(
+          SECOND,
+          LEAST(
+            60 * CAST(POWER(2, LEAST(consecutive_failures, 4)) AS UNSIGNED),
+            ${MAX_BACKOFF_SECONDS}
+          ),
+          CURRENT_TIMESTAMP(6)
+        ),
+        consecutive_failures = consecutive_failures + 1,
+        updated_at = CURRENT_TIMESTAMP(6)
+      WHERE name = ${params.name} AND lease_token = ${params.leaseToken}
+    `);
+        return affectedRowCount(result) === 1;
+    }
+    /** Return selected health rows, or every row when names is omitted. */
+    async health(names) {
+        if (names?.length === 0)
+            return [];
+        const whereClause = names === undefined
+            ? sql ``
+            : sql `WHERE name IN (${sql.join(names.map((name) => sql `${name}`), sql `, `)})`;
+        const result = (await this.db.execute(sql `
+      SELECT
+        name,
+        interval_ms,
+        next_run_at,
+        last_status,
+        last_started_at,
+        last_succeeded_at,
+        last_failed_at,
+        last_duration_ms,
+        consecutive_failures,
+        last_error,
+        (lease_expires_at IS NOT NULL AND lease_expires_at <= CURRENT_TIMESTAMP(6)) AS lease_expired,
+        CURRENT_TIMESTAMP(6) AS database_now
+      FROM byline_recurring_tasks
+      ${whereClause}
+      ORDER BY name
+    `));
+        return result[0].map((row) => ({
+            name: row.name,
+            intervalMs: Number(row.interval_ms),
+            nextRunAt: requiredDate(row.next_run_at, 'next_run_at'),
+            lastStatus: row.last_status,
+            lastStartedAt: toDate(row.last_started_at, 'last_started_at'),
+            lastSucceededAt: toDate(row.last_succeeded_at, 'last_succeeded_at'),
+            lastFailedAt: toDate(row.last_failed_at, 'last_failed_at'),
+            lastDurationMs: row.last_duration_ms === null ? null : Number(row.last_duration_ms),
+            consecutiveFailures: Number(row.consecutive_failures),
+            lastError: row.last_error,
+            leaseExpired: Boolean(row.lease_expired),
+            databaseNow: requiredDate(row.database_now, 'database_now'),
+        }));
+    }
+}
+export function createSchedulerStore(db) {
+    return new SchedulerStore(db);
+}

package/dist/modules/storage/publish-schedules.d.ts

@@ -0,0 +1,85 @@
+/**
+ * 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 type { ClaimedDocumentPublishSchedule, ConfirmDocumentPublishScheduleResult, DocumentPublishSchedule, DocumentPublishSchedulePage, DocumentPublishScheduleState, IDocumentPublishScheduleCommands, IDocumentPublishScheduleQueries, ScheduleDocumentPublishResult, SuspendDocumentPublishScheduleResult } from '@byline/core';
+import type { MySql2Database } from 'drizzle-orm/mysql2';
+import type * as schema from '../../database/schema/index.js';
+import type { DBManager } from '../../lib/db-manager.js';
+type DatabaseConnection = MySql2Database<typeof schema>;
+/** MySQL scheduled-publication writes on the ambient document transaction. */
+export declare class DocumentPublishScheduleCommands implements IDocumentPublishScheduleCommands {
+    private dbManager;
+    constructor(dbManager: DBManager);
+    private get db();
+    private lockCurrentVersion;
+    private lockSchedule;
+    private readSchedule;
+    schedule(params: {
+        documentId: string;
+        collectionId: string;
+        expectedVersionId: string;
+        publishAt: Date;
+        actorId: string | null;
+    }): Promise<ScheduleDocumentPublishResult>;
+    confirm(params: {
+        documentId: string;
+        collectionId: string;
+        expectedVersionId: string;
+        actorId: string | null;
+    }): Promise<ConfirmDocumentPublishScheduleResult>;
+    cancel(params: {
+        documentId: string;
+        collectionId: string;
+    }): Promise<DocumentPublishSchedule | null>;
+    suspendForContentEdit(params: {
+        documentId: string;
+        collectionId: string;
+    }): Promise<SuspendDocumentPublishScheduleResult>;
+    claimDue(params: {
+        batchSize: number;
+        leaseMs: number;
+    }): Promise<ClaimedDocumentPublishSchedule[]>;
+    lockClaim(params: {
+        documentId: string;
+        executionToken: string;
+    }): Promise<DocumentPublishSchedule | null>;
+    deleteClaim(params: {
+        documentId: string;
+        executionToken: string;
+    }): Promise<boolean>;
+    suspendClaimForContentEdit(params: {
+        documentId: string;
+        executionToken: string;
+    }): Promise<boolean>;
+    /**
+     * `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.
+     */
+    releaseClaim(params: {
+        documentId: string;
+        executionToken: string;
+        error: string;
+    }): Promise<boolean>;
+}
+/** MySQL scheduled-publication reads. */
+export declare class DocumentPublishScheduleQueries implements IDocumentPublishScheduleQueries {
+    private db;
+    constructor(db: DatabaseConnection);
+    get(params: {
+        documentId: string;
+        collectionId: string;
+    }): Promise<DocumentPublishSchedule | null>;
+    list(params: {
+        collectionIds: readonly string[];
+        states?: readonly DocumentPublishScheduleState[];
+        lastAuthorizedBy?: string;
+        page: number;
+        pageSize: number;
+    }): Promise<DocumentPublishSchedulePage>;
+}
+export {};