@ftschopp/dynatable-migrations 1.2.3 → 1.2.4

package/src/core/lock-heartbeat.test.ts

@@ -0,0 +1,78 @@
+import { startLockHeartbeat } from './lock-heartbeat';
+import type { MigrationTracker } from '../types';
+
+beforeEach(() => {
+  jest.useFakeTimers();
+});
+
+afterEach(() => {
+  jest.useRealTimers();
+});
+
+function makeTracker(refresh: jest.Mock): MigrationTracker {
+  // Only the methods the heartbeat actually touches need to be present.
+  return {
+    refreshLock: refresh,
+  } as unknown as MigrationTracker;
+}
+
+describe('startLockHeartbeat', () => {
+  test('calls refreshLock every ~ttl/3 seconds', () => {
+    const refresh = jest.fn().mockResolvedValue(undefined);
+    const tracker = makeTracker(refresh);
+    const stop = startLockHeartbeat(tracker, 30); // every 10s
+
+    jest.advanceTimersByTime(10_000);
+    expect(refresh).toHaveBeenCalledTimes(1);
+
+    jest.advanceTimersByTime(10_000);
+    expect(refresh).toHaveBeenCalledTimes(2);
+
+    stop();
+  });
+
+  test('stop() clears the interval and prevents further refreshes', () => {
+    const refresh = jest.fn().mockResolvedValue(undefined);
+    const tracker = makeTracker(refresh);
+    const stop = startLockHeartbeat(tracker, 30);
+
+    jest.advanceTimersByTime(10_000);
+    stop();
+    jest.advanceTimersByTime(60_000);
+
+    expect(refresh).toHaveBeenCalledTimes(1);
+  });
+
+  test('clamps the interval to a 1s minimum even with absurdly small TTLs', () => {
+    const refresh = jest.fn().mockResolvedValue(undefined);
+    const tracker = makeTracker(refresh);
+    const stop = startLockHeartbeat(tracker, 0.5); // would compute < 1s
+
+    jest.advanceTimersByTime(999);
+    expect(refresh).toHaveBeenCalledTimes(0);
+    jest.advanceTimersByTime(1);
+    expect(refresh).toHaveBeenCalledTimes(1);
+
+    stop();
+  });
+
+  test('swallows refresh errors so transient failures do not crash the runner', async () => {
+    const warn = jest.spyOn(console, 'warn').mockImplementation(() => {});
+    const refresh = jest
+      .fn()
+      .mockRejectedValueOnce(Object.assign(new Error('boom'), { name: 'NetworkError' }));
+    const tracker = makeTracker(refresh);
+    const stop = startLockHeartbeat(tracker, 30);
+
+    jest.advanceTimersByTime(10_000);
+    // Let the rejected promise settle
+    await Promise.resolve();
+    await Promise.resolve();
+
+    expect(refresh).toHaveBeenCalledTimes(1);
+    expect(warn).toHaveBeenCalled();
+
+    stop();
+    warn.mockRestore();
+  });
+});

package/src/core/lock-heartbeat.ts

@@ -0,0 +1,48 @@
+import type { MigrationTracker } from '../types';
+
+/**
+ * Periodically refreshes the migration lock so that migrations longer than
+ * the lock TTL don't have their lock taken by another worker.
+ *
+ * Returns a stop function. Call it from the same `finally` that releases
+ * the lock to make sure the interval doesn't leak.
+ *
+ * The heartbeat fires every `ttlSeconds / 3` seconds. Errors from the
+ * underlying refresh are logged and swallowed: if the lock is genuinely
+ * lost, the next tracker mutation will fail its ConditionCheck and the
+ * runner will surface a clear `TransactionCanceledException` to the user.
+ */
+export function startLockHeartbeat(
+  tracker: MigrationTracker,
+  ttlSeconds: number
+): () => void {
+  // Fire well before expiry so a single missed beat doesn't drop the lock.
+  const intervalMs = Math.max(1_000, Math.floor((ttlSeconds * 1000) / 3));
+  let active = true;
+
+  const handle = setInterval(() => {
+    if (!active) return;
+    void tracker.refreshLock().catch((err: unknown) => {
+      const name = (err as { name?: string } | null)?.name;
+      const message = (err as { message?: string } | null)?.message ?? String(err);
+      if (name === 'ConditionalCheckFailedException') {
+        console.warn(
+          '⚠️  Migration lock was taken by another process. ' +
+            'Subsequent tracker writes will fail.'
+        );
+      } else {
+        console.warn(`⚠️  Failed to refresh migration lock: ${message}`);
+      }
+    });
+  }, intervalMs);
+
+  // Don't keep the Node event loop alive just for the heartbeat.
+  if (typeof handle.unref === 'function') {
+    handle.unref();
+  }
+
+  return () => {
+    active = false;
+    clearInterval(handle);
+  };
+}

package/src/core/runner.ts

@@ -15,6 +15,7 @@ import { MigrationConfig, MigrationContext, MigrationFile, MigrationStatus } fro
 import { DynamoDBMigrationTracker } from './tracker';
 import { MigrationLoader } from './loader';
 import { compareSemver } from './semver';
+import { startLockHeartbeat } from './lock-heartbeat';
 
 export interface RunOptions {
   limit?: number;
@@ -50,6 +51,7 @@ export class MigrationRunner {
     await this.initialize();
 
     // Acquire lock unless dry run
+    let stopHeartbeat: (() => void) | undefined;
     if (!dryRun) {
       const lockAcquired = await this.tracker.acquireLock();
       if (!lockAcquired) {
@@ -58,6 +60,7 @@ export class MigrationRunner {
             'If you believe this is an error, wait a few minutes and try again.'
         );
       }
+      stopHeartbeat = startLockHeartbeat(this.tracker, this.tracker.lockTtlSeconds);
     }
 
     try {
@@ -133,7 +136,9 @@ export class MigrationRunner {
 
       return executed;
     } finally {
-      // Always release lock
+      // Always stop the heartbeat and release the lock — in that order, so
+      // we don't refresh a lock we're about to delete.
+      if (stopHeartbeat) stopHeartbeat();
       if (!dryRun) {
         await this.tracker.releaseLock();
       }
@@ -147,11 +152,13 @@ export class MigrationRunner {
     await this.initialize();
 
     // Acquire lock unless dry run
+    let stopHeartbeat: (() => void) | undefined;
     if (!dryRun) {
       const lockAcquired = await this.tracker.acquireLock();
       if (!lockAcquired) {
         throw new Error('Could not acquire migration lock. Another migration may be in progress.');
       }
+      stopHeartbeat = startLockHeartbeat(this.tracker, this.tracker.lockTtlSeconds);
     }
 
     try {
@@ -207,6 +214,7 @@ export class MigrationRunner {
 
       return rolledBack;
     } finally {
+      if (stopHeartbeat) stopHeartbeat();
       if (!dryRun) {
         await this.tracker.releaseLock();
       }

package/src/core/tracker.test.ts

@@ -0,0 +1,150 @@
+/* eslint-disable @typescript-eslint/no-explicit-any */
+import { DynamoDBClient } from '@aws-sdk/client-dynamodb';
+import {
+  DynamoDBDocumentClient,
+  GetCommand,
+  PutCommand,
+  UpdateCommand,
+  TransactWriteCommand,
+} from '@aws-sdk/lib-dynamodb';
+import { mockClient } from 'aws-sdk-client-mock';
+import { DynamoDBMigrationTracker, DEFAULT_LOCK_TTL_SECONDS } from './tracker';
+import type { MigrationConfig } from '../types';
+
+const ddbMock = mockClient(DynamoDBDocumentClient);
+
+const baseConfig: MigrationConfig = {
+  tableName: 'TestTable',
+  client: { region: 'us-east-1' },
+};
+
+function makeTracker(config: Partial<MigrationConfig> = {}) {
+  const client = DynamoDBDocumentClient.from(new DynamoDBClient({ region: 'us-east-1' }));
+  return new DynamoDBMigrationTracker(client, { ...baseConfig, ...config });
+}
+
+beforeEach(() => {
+  ddbMock.reset();
+});
+
+describe('DynamoDBMigrationTracker - lock TTL', () => {
+  test('uses the default 5-minute TTL when none is configured', () => {
+    const tracker = makeTracker();
+    expect(tracker.lockTtlSeconds).toBe(DEFAULT_LOCK_TTL_SECONDS);
+  });
+
+  test('honors a custom lockTtlSeconds from config', () => {
+    const tracker = makeTracker({ lockTtlSeconds: 30 });
+    expect(tracker.lockTtlSeconds).toBe(30);
+  });
+});
+
+describe('DynamoDBMigrationTracker - acquireLock', () => {
+  test('uses <= for the expiry boundary so simultaneous-ms expiries are takeable', async () => {
+    ddbMock.on(PutCommand).resolves({});
+    const tracker = makeTracker();
+
+    await tracker.acquireLock();
+
+    const calls = ddbMock.commandCalls(PutCommand);
+    expect(calls).toHaveLength(1);
+    const expr = (calls[0]!.args[0].input as any).ConditionExpression as string;
+    expect(expr).toContain('expiresAt <= :now');
+  });
+
+  test('returns false when the lock row exists and has not expired', async () => {
+    const err = Object.assign(new Error('cond failed'), {
+      name: 'ConditionalCheckFailedException',
+    });
+    ddbMock.on(PutCommand).rejects(err);
+    const tracker = makeTracker();
+
+    await expect(tracker.acquireLock()).resolves.toBe(false);
+  });
+});
+
+describe('DynamoDBMigrationTracker - refreshLock', () => {
+  test('extends the lock with a ConditionExpression on the current lockId', async () => {
+    ddbMock.on(PutCommand).resolves({});
+    ddbMock.on(UpdateCommand).resolves({});
+
+    const tracker = makeTracker({ lockTtlSeconds: 60 });
+    await tracker.acquireLock();
+    await tracker.refreshLock();
+
+    const updates = ddbMock.commandCalls(UpdateCommand);
+    expect(updates).toHaveLength(1);
+    const input = updates[0]!.args[0].input as any;
+    expect(input.ConditionExpression).toBe('lockId = :lockId');
+    expect(typeof input.ExpressionAttributeValues[':lockId']).toBe('string');
+    expect(typeof input.ExpressionAttributeValues[':exp']).toBe('number');
+  });
+
+  test('throws when the lockId no longer matches (lost race)', async () => {
+    ddbMock.on(PutCommand).resolves({});
+    const err = Object.assign(new Error('cond failed'), {
+      name: 'ConditionalCheckFailedException',
+    });
+    ddbMock.on(UpdateCommand).rejects(err);
+
+    const tracker = makeTracker();
+    await tracker.acquireLock();
+
+    await expect(tracker.refreshLock()).rejects.toMatchObject({
+      name: 'ConditionalCheckFailedException',
+    });
+  });
+
+  test('is a silent no-op when no lock has been acquired yet', async () => {
+    const tracker = makeTracker();
+    await expect(tracker.refreshLock()).resolves.toBeUndefined();
+    expect(ddbMock.commandCalls(UpdateCommand)).toHaveLength(0);
+  });
+});
+
+describe('DynamoDBMigrationTracker - tracker writes are gated by lock ownership', () => {
+  test('markAsApplied (new record path) emits a ConditionCheck on the lock row', async () => {
+    ddbMock.on(PutCommand).resolves({}); // acquireLock
+    ddbMock.on(TransactWriteCommand).resolves({});
+    // getMigration returns no existing record → take the Put branch
+    ddbMock.on(GetCommand).resolves({ Item: undefined });
+
+    const tracker = makeTracker();
+    await tracker.acquireLock();
+    await tracker.markAsApplied('0.1.0', 'init');
+
+    const tx = ddbMock.commandCalls(TransactWriteCommand);
+    expect(tx).toHaveLength(1);
+    const items = (tx[0]!.args[0].input as any).TransactItems as any[];
+    // First item should be the lock-row ConditionCheck
+    expect(items[0].ConditionCheck).toBeDefined();
+    expect(items[0].ConditionCheck.ConditionExpression).toBe('lockId = :lockId');
+    expect(items[0].ConditionCheck.Key).toEqual({
+      PK: '_SCHEMA#VERSION#LOCK',
+      SK: '_SCHEMA#VERSION#LOCK',
+    });
+  });
+
+  test('markAsApplied throws when no lock has been acquired', async () => {
+    const tracker = makeTracker();
+    await expect(tracker.markAsApplied('0.1.0', 'init')).rejects.toThrow(
+      /Tracker has no active lock/i
+    );
+  });
+
+  test('markAsApplied (new record path) uses attribute_not_exists(SK), not (PK)', async () => {
+    ddbMock.on(PutCommand).resolves({});
+    ddbMock.on(TransactWriteCommand).resolves({});
+    ddbMock.on(GetCommand).resolves({ Item: undefined });
+
+    const tracker = makeTracker();
+    await tracker.acquireLock();
+    await tracker.markAsApplied('0.1.0', 'init');
+
+    const tx = ddbMock.commandCalls(TransactWriteCommand);
+    const items = (tx[0]!.args[0].input as any).TransactItems as any[];
+    // The Put is the second item (index 1) after the ConditionCheck
+    const put = items.find((i) => i.Put);
+    expect(put.Put.ConditionExpression).toBe('attribute_not_exists(SK)');
+  });
+});

package/src/core/tracker.ts

@@ -10,7 +10,8 @@ import {
 import { MigrationTracker, MigrationRecord, SchemaChange, MigrationConfig } from '../types';
 import { compareSemver } from './semver';
 
-const LOCK_TTL_SECONDS = 300; // 5 minutes
+/** Default lock TTL in seconds. Configurable via MigrationConfig.lockTtlSeconds. */
+export const DEFAULT_LOCK_TTL_SECONDS = 300; // 5 minutes
 
 export class DynamoDBMigrationTracker implements MigrationTracker {
   private client: DynamoDBDocumentClient;
@@ -18,12 +19,47 @@ export class DynamoDBMigrationTracker implements MigrationTracker {
   private trackingPrefix: string;
   private gsi1Name: string;
   private lockId: string | null = null;
+  /** TTL for newly-acquired or refreshed locks. */
+  public readonly lockTtlSeconds: number;
 
   constructor(client: DynamoDBDocumentClient, config: MigrationConfig) {
     this.client = client;
     this.tableName = config.tableName;
     this.trackingPrefix = config.trackingPrefix || '_SCHEMA#VERSION';
     this.gsi1Name = config.gsi1Name || 'GSI1';
+    this.lockTtlSeconds = config.lockTtlSeconds ?? DEFAULT_LOCK_TTL_SECONDS;
+  }
+
+  private get lockKey() {
+    return {
+      PK: `${this.trackingPrefix}#LOCK`,
+      SK: `${this.trackingPrefix}#LOCK`,
+    };
+  }
+
+  /** Throws if there is no active lock. Call before any tracker write. */
+  private requireLock(): void {
+    if (!this.lockId) {
+      throw new Error(
+        'Tracker has no active lock; refusing to issue tracker mutations. ' +
+          'Call acquireLock() first.'
+      );
+    }
+  }
+
+  /** Builds a TransactWrite ConditionCheck that asserts we still own the lock. */
+  private lockOwnershipCheck() {
+    this.requireLock();
+    return {
+      ConditionCheck: {
+        TableName: this.tableName,
+        Key: this.lockKey,
+        ConditionExpression: 'lockId = :lockId',
+        ExpressionAttributeValues: {
+          ':lockId': this.lockId,
+        },
+      },
+    };
   }
 
   async initialize(): Promise<void> {
@@ -51,13 +87,8 @@ export class DynamoDBMigrationTracker implements MigrationTracker {
    * Acquire a distributed lock to prevent concurrent migrations
    */
   async acquireLock(): Promise<boolean> {
-    const lockKey = {
-      PK: `${this.trackingPrefix}#LOCK`,
-      SK: `${this.trackingPrefix}#LOCK`,
-    };
-
     const now = Date.now();
-    const expiresAt = now + LOCK_TTL_SECONDS * 1000;
+    const expiresAt = now + this.lockTtlSeconds * 1000;
     this.lockId = `lock-${now}-${Math.random().toString(36).substring(7)}`;
 
     try {
@@ -65,13 +96,14 @@ export class DynamoDBMigrationTracker implements MigrationTracker {
         new PutCommand({
           TableName: this.tableName,
           Item: {
-            ...lockKey,
+            ...this.lockKey,
             lockId: this.lockId,
             acquiredAt: new Date().toISOString(),
             expiresAt,
           },
-          // Only succeed if lock doesn't exist or has expired
-          ConditionExpression: 'attribute_not_exists(PK) OR expiresAt < :now',
+          // Only succeed if lock doesn't exist or has expired. The `<=`
+          // covers the boundary where two clocks read the exact ms.
+          ConditionExpression: 'attribute_not_exists(PK) OR expiresAt <= :now',
           ExpressionAttributeValues: {
             ':now': now,
           },
@@ -87,22 +119,42 @@ export class DynamoDBMigrationTracker implements MigrationTracker {
     }
   }
 
+  /**
+   * Extend the lock's expiration by another `lockTtlSeconds`. Throws
+   * `ConditionalCheckFailedException` if another worker has already taken
+   * the lock — callers should treat that as "we lost the race; stop
+   * making writes". Silent no-op if no lock is currently held.
+   */
+  async refreshLock(): Promise<void> {
+    if (!this.lockId) return;
+
+    const newExpiresAt = Date.now() + this.lockTtlSeconds * 1000;
+
+    await this.client.send(
+      new UpdateCommand({
+        TableName: this.tableName,
+        Key: this.lockKey,
+        UpdateExpression: 'SET expiresAt = :exp',
+        ConditionExpression: 'lockId = :lockId',
+        ExpressionAttributeValues: {
+          ':exp': newExpiresAt,
+          ':lockId': this.lockId,
+        },
+      })
+    );
+  }
+
   /**
    * Release the distributed lock
    */
   async releaseLock(): Promise<void> {
     if (!this.lockId) return;
 
-    const lockKey = {
-      PK: `${this.trackingPrefix}#LOCK`,
-      SK: `${this.trackingPrefix}#LOCK`,
-    };
-
     try {
       await this.client.send(
         new DeleteCommand({
           TableName: this.tableName,
-          Key: lockKey,
+          Key: this.lockKey,
           // Only delete if we own the lock
           ConditionExpression: 'lockId = :lockId',
           ExpressionAttributeValues: {
@@ -171,6 +223,7 @@ export class DynamoDBMigrationTracker implements MigrationTracker {
     schemaChanges?: SchemaChange[],
     checksum?: string
   ): Promise<void> {
+    this.requireLock();
     const now = new Date().toISOString();
 
     // Check if migration record already exists (e.g., rolled back or failed)
@@ -202,6 +255,7 @@ export class DynamoDBMigrationTracker implements MigrationTracker {
       await this.client.send(
         new TransactWriteCommand({
           TransactItems: [
+            this.lockOwnershipCheck(),
             {
               Update: {
                 TableName: this.tableName,
@@ -244,6 +298,7 @@ export class DynamoDBMigrationTracker implements MigrationTracker {
       await this.client.send(
         new TransactWriteCommand({
           TransactItems: [
+            this.lockOwnershipCheck(),
             {
               Put: {
                 TableName: this.tableName,
@@ -259,8 +314,9 @@ export class DynamoDBMigrationTracker implements MigrationTracker {
                   schemaChanges,
                   checksum,
                 } as MigrationRecord,
-                // Ensure migration wasn't already applied
-                ConditionExpression: 'attribute_not_exists(PK)',
+                // Ensure migration wasn't already applied (uniqueness on
+                // SK; PK is shared across all migration rows).
+                ConditionExpression: 'attribute_not_exists(SK)',
               },
             },
             {
@@ -289,6 +345,7 @@ export class DynamoDBMigrationTracker implements MigrationTracker {
    * Mark migration as rolled back using TransactWrite for atomicity
    */
   async markAsRolledBack(version: string): Promise<void> {
+    this.requireLock();
     const now = new Date().toISOString();
 
     // Find previous version
@@ -303,6 +360,7 @@ export class DynamoDBMigrationTracker implements MigrationTracker {
     await this.client.send(
       new TransactWriteCommand({
         TransactItems: [
+          this.lockOwnershipCheck(),
           {
             Update: {
               TableName: this.tableName,
@@ -342,70 +400,95 @@ export class DynamoDBMigrationTracker implements MigrationTracker {
   }
 
   async markAsFailed(version: string, error: string): Promise<void> {
+    this.requireLock();
     // Check if the migration record exists first
     const existing = await this.getMigration(version);
+    const now = new Date().toISOString();
 
     if (existing) {
-      // Update existing record
+      // Update existing record, gated by lock ownership
       await this.client.send(
-        new UpdateCommand({
-          TableName: this.tableName,
-          Key: {
-            PK: this.trackingPrefix,
-            SK: version,
-          },
-          UpdateExpression: 'SET #status = :status, #error = :error, failedAt = :timestamp',
-          ExpressionAttributeNames: {
-            '#status': 'status',
-            '#error': 'error',
-          },
-          ExpressionAttributeValues: {
-            ':status': 'failed',
-            ':error': error,
-            ':timestamp': new Date().toISOString(),
-          },
+        new TransactWriteCommand({
+          TransactItems: [
+            this.lockOwnershipCheck(),
+            {
+              Update: {
+                TableName: this.tableName,
+                Key: {
+                  PK: this.trackingPrefix,
+                  SK: version,
+                },
+                UpdateExpression:
+                  'SET #status = :status, #error = :error, failedAt = :timestamp',
+                ExpressionAttributeNames: {
+                  '#status': 'status',
+                  '#error': 'error',
+                },
+                ExpressionAttributeValues: {
+                  ':status': 'failed',
+                  ':error': error,
+                  ':timestamp': now,
+                },
+              },
+            },
+          ],
         })
       );
     } else {
-      // Create new record for failed migration
+      // Create new record for failed migration, gated by lock ownership
       await this.client.send(
-        new PutCommand({
-          TableName: this.tableName,
-          Item: {
-            PK: this.trackingPrefix,
-            SK: version,
-            version,
-            name: 'unknown',
-            status: 'failed',
-            error,
-            failedAt: new Date().toISOString(),
-            timestamp: new Date().toISOString(),
-          },
+        new TransactWriteCommand({
+          TransactItems: [
+            this.lockOwnershipCheck(),
+            {
+              Put: {
+                TableName: this.tableName,
+                Item: {
+                  PK: this.trackingPrefix,
+                  SK: version,
+                  version,
+                  name: 'unknown',
+                  status: 'failed',
+                  error,
+                  failedAt: now,
+                  timestamp: now,
+                },
+              },
+            },
+          ],
         })
       );
     }
   }
 
   async recordSchemaChange(change: SchemaChange): Promise<void> {
+    this.requireLock();
     const currentVersion = await this.getCurrentVersion();
     if (!currentVersion || currentVersion === 'v0000') {
       throw new Error('Cannot record schema change: No migration has been applied yet');
     }
 
-    // Append to schemaChanges array
+    // Append to schemaChanges array, gated by lock ownership
     await this.client.send(
-      new UpdateCommand({
-        TableName: this.tableName,
-        Key: {
-          PK: this.trackingPrefix,
-          SK: currentVersion,
-        },
-        UpdateExpression:
-          'SET schemaChanges = list_append(if_not_exists(schemaChanges, :empty_list), :change)',
-        ExpressionAttributeValues: {
-          ':empty_list': [],
-          ':change': [change],
-        },
+      new TransactWriteCommand({
+        TransactItems: [
+          this.lockOwnershipCheck(),
+          {
+            Update: {
+              TableName: this.tableName,
+              Key: {
+                PK: this.trackingPrefix,
+                SK: currentVersion,
+              },
+              UpdateExpression:
+                'SET schemaChanges = list_append(if_not_exists(schemaChanges, :empty_list), :change)',
+              ExpressionAttributeValues: {
+                ':empty_list': [],
+                ':change': [change],
+              },
+            },
+          },
+        ],
       })
     );
   }

package/src/types/index.ts

@@ -117,6 +117,12 @@ export interface MigrationConfig {
   migrationsDir?: string;
   trackingPrefix?: string; // Default: "_SCHEMA#VERSION"
   gsi1Name?: string; // Default: "GSI1"
+  /**
+   * How long an acquired migration lock stays valid before another worker
+   * can take it over, in seconds. The runner sends a heartbeat every
+   * `lockTtlSeconds / 3` to extend it. Default: 300 (5 minutes).
+   */
+  lockTtlSeconds?: number;
 }
 
 /**
@@ -148,6 +154,12 @@ export interface MigrationTracker {
    */
   releaseLock(): Promise<void>;
 
+  /**
+   * Extend the lock's expiration. Throws `ConditionalCheckFailedException`
+   * if the lock has already been taken by someone else.
+   */
+  refreshLock(): Promise<void>;
+
   /**
    * Mark migration as applied
    */