@ftschopp/dynatable-migrations 1.2.3 → 1.2.5

package/src/core/tracker.ts

@@ -9,8 +9,10 @@ import {
 } from '@aws-sdk/lib-dynamodb';
 import { MigrationTracker, MigrationRecord, SchemaChange, MigrationConfig } from '../types';
 import { compareSemver } from './semver';
+import { MigrationAlreadyAppliedError, MigrationLockLostError } from './errors';
 
-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 +20,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 +88,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 +97,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 +120,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,124 +224,173 @@ 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)
     const existing = await this.getMigration(version);
 
-    if (existing) {
-      // Update existing record (re-applying a rolled back or failed migration)
-      // Build dynamic update expression - DynamoDB doesn't accept undefined values
-      const setParts = ['#status = :status', 'appliedAt = :appliedAt', '#name = :name'];
-      const expressionValues: Record<string, any> = {
-        ':status': 'applied',
-        ':appliedAt': now,
-        ':name': name,
-      };
-
-      if (schemaDefinition !== undefined) {
-        setParts.push('schemaDefinition = :schemaDef');
-        expressionValues[':schemaDef'] = schemaDefinition;
-      }
-      if (schemaChanges !== undefined) {
-        setParts.push('schemaChanges = :schemaChanges');
-        expressionValues[':schemaChanges'] = schemaChanges;
-      }
-      if (checksum !== undefined) {
-        setParts.push('checksum = :checksum');
-        expressionValues[':checksum'] = checksum;
-      }
-
-      await this.client.send(
-        new TransactWriteCommand({
-          TransactItems: [
-            {
-              Update: {
-                TableName: this.tableName,
-                Key: {
-                  PK: this.trackingPrefix,
-                  SK: version,
-                },
-                UpdateExpression: `SET ${setParts.join(', ')} REMOVE #error, failedAt, rolledBackAt`,
-                ExpressionAttributeNames: {
-                  '#status': 'status',
-                  '#name': 'name',
-                  '#error': 'error',
+    try {
+      if (existing) {
+        // Update existing record (re-applying a rolled back or failed migration)
+        // Build dynamic update expression - DynamoDB doesn't accept undefined values
+        const setParts = ['#status = :status', 'appliedAt = :appliedAt', '#name = :name'];
+        const expressionValues: Record<string, any> = {
+          ':status': 'applied',
+          ':appliedAt': now,
+          ':name': name,
+        };
+
+        if (schemaDefinition !== undefined) {
+          setParts.push('schemaDefinition = :schemaDef');
+          expressionValues[':schemaDef'] = schemaDefinition;
+        }
+        if (schemaChanges !== undefined) {
+          setParts.push('schemaChanges = :schemaChanges');
+          expressionValues[':schemaChanges'] = schemaChanges;
+        }
+        if (checksum !== undefined) {
+          setParts.push('checksum = :checksum');
+          expressionValues[':checksum'] = checksum;
+        }
+
+        await this.client.send(
+          new TransactWriteCommand({
+            TransactItems: [
+              this.lockOwnershipCheck(),
+              {
+                Update: {
+                  TableName: this.tableName,
+                  Key: {
+                    PK: this.trackingPrefix,
+                    SK: version,
+                  },
+                  UpdateExpression: `SET ${setParts.join(', ')} REMOVE #error, failedAt, rolledBackAt`,
+                  ExpressionAttributeNames: {
+                    '#status': 'status',
+                    '#name': 'name',
+                    '#error': 'error',
+                  },
+                  ExpressionAttributeValues: expressionValues,
+                  // Only allow re-applying if not currently applied
+                  ConditionExpression: '#status <> :status',
                 },
-                ExpressionAttributeValues: expressionValues,
-                // Only allow re-applying if not currently applied
-                ConditionExpression: '#status <> :status',
               },
-            },
-            {
-              Update: {
-                TableName: this.tableName,
-                Key: {
-                  PK: `${this.trackingPrefix}#CURRENT`,
-                  SK: `${this.trackingPrefix}#CURRENT`,
-                },
-                UpdateExpression:
-                  'SET currentVersion = :version, updatedAt = :updatedAt, GSI1SK = :gsi1sk',
-                ExpressionAttributeValues: {
-                  ':version': version,
-                  ':updatedAt': now,
-                  ':gsi1sk': version,
+              {
+                Update: {
+                  TableName: this.tableName,
+                  Key: {
+                    PK: `${this.trackingPrefix}#CURRENT`,
+                    SK: `${this.trackingPrefix}#CURRENT`,
+                  },
+                  UpdateExpression:
+                    'SET currentVersion = :version, updatedAt = :updatedAt, GSI1SK = :gsi1sk',
+                  ExpressionAttributeValues: {
+                    ':version': version,
+                    ':updatedAt': now,
+                    ':gsi1sk': version,
+                  },
                 },
               },
-            },
-          ],
-        })
-      );
-    } else {
-      // Create new migration record
-      await this.client.send(
-        new TransactWriteCommand({
-          TransactItems: [
-            {
-              Put: {
-                TableName: this.tableName,
-                Item: {
-                  PK: this.trackingPrefix,
-                  SK: version,
-                  version,
-                  name,
-                  timestamp: now,
-                  appliedAt: now,
-                  status: 'applied',
-                  schemaDefinition,
-                  schemaChanges,
-                  checksum,
-                } as MigrationRecord,
-                // Ensure migration wasn't already applied
-                ConditionExpression: 'attribute_not_exists(PK)',
-              },
-            },
-            {
-              Update: {
-                TableName: this.tableName,
-                Key: {
-                  PK: `${this.trackingPrefix}#CURRENT`,
-                  SK: `${this.trackingPrefix}#CURRENT`,
+            ],
+          })
+        );
+      } else {
+        // Create new migration record
+        await this.client.send(
+          new TransactWriteCommand({
+            TransactItems: [
+              this.lockOwnershipCheck(),
+              {
+                Put: {
+                  TableName: this.tableName,
+                  Item: {
+                    PK: this.trackingPrefix,
+                    SK: version,
+                    version,
+                    name,
+                    timestamp: now,
+                    appliedAt: now,
+                    status: 'applied',
+                    schemaDefinition,
+                    schemaChanges,
+                    checksum,
+                  } as MigrationRecord,
+                  // Ensure migration wasn't already applied (uniqueness on
+                  // SK; PK is shared across all migration rows).
+                  ConditionExpression: 'attribute_not_exists(SK)',
                 },
-                UpdateExpression:
-                  'SET currentVersion = :version, updatedAt = :updatedAt, GSI1SK = :gsi1sk',
-                ExpressionAttributeValues: {
-                  ':version': version,
-                  ':updatedAt': now,
-                  ':gsi1sk': version,
+              },
+              {
+                Update: {
+                  TableName: this.tableName,
+                  Key: {
+                    PK: `${this.trackingPrefix}#CURRENT`,
+                    SK: `${this.trackingPrefix}#CURRENT`,
+                  },
+                  UpdateExpression:
+                    'SET currentVersion = :version, updatedAt = :updatedAt, GSI1SK = :gsi1sk',
+                  ExpressionAttributeValues: {
+                    ':version': version,
+                    ':updatedAt': now,
+                    ':gsi1sk': version,
+                  },
                 },
               },
-            },
-          ],
-        })
-      );
+            ],
+          })
+        );
+      }
+    } catch (err: unknown) {
+      await this.handleMarkAsAppliedCancellation(err, version);
     }
   }
 
+  /**
+   * Inspect a `TransactionCanceledException` raised by `markAsApplied` and
+   * either swallow it (idempotent re-apply) or re-throw a typed error.
+   *
+   * The TransactWrite items are: [lockOwnershipCheck, migrationRow, currentPointer].
+   * Each item produces an entry in `CancellationReasons`.
+   *   - reasons[0] failing → the lock was lost → MigrationLockLostError.
+   *   - reasons[1] failing → the migration row already exists in a state the
+   *     write refused. Re-fetch the record:
+   *       * status === 'applied' → idempotent re-apply, return silently.
+   *       * other states         → MigrationAlreadyAppliedError with the
+   *         current state, so the caller can decide what to do.
+   */
+  private async handleMarkAsAppliedCancellation(
+    err: unknown,
+    version: string
+  ): Promise<void> {
+    const error = err as { name?: string; CancellationReasons?: Array<{ Code?: string }> } | null;
+    if (error?.name !== 'TransactionCanceledException') {
+      throw err;
+    }
+    const reasons = error.CancellationReasons ?? [];
+    const lockReason = reasons[0];
+    const migrationReason = reasons[1];
+
+    if (lockReason?.Code === 'ConditionalCheckFailed') {
+      throw new MigrationLockLostError(version);
+    }
+    if (migrationReason?.Code === 'ConditionalCheckFailed') {
+      const current = await this.getMigration(version);
+      if (current?.status === 'applied') {
+        // Either we re-tried our own write or another worker applied the same
+        // version. Either way, the desired post-state is already satisfied.
+        return;
+      }
+      throw new MigrationAlreadyAppliedError(version, current?.status);
+    }
+    throw err;
+  }
+
   /**
    * 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 +405,7 @@ export class DynamoDBMigrationTracker implements MigrationTracker {
     await this.client.send(
       new TransactWriteCommand({
         TransactItems: [
+          this.lockOwnershipCheck(),
           {
             Update: {
               TableName: this.tableName,
@@ -342,70 +445,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/index.ts

@@ -12,6 +12,7 @@ export { MigrationLoader } from './core/loader';
 export { MigrationRunner, type RunOptions } from './core/runner';
 export { ConfigLoader, loadConfig } from './core/config';
 export { createDynamoDBClient } from './core/client';
+export { MigrationAlreadyAppliedError, MigrationLockLostError } from './core/errors';
 
 // Template
 export { generateMigrationTemplate } from './templates/migration';

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
    */