@ftschopp/dynatable-migrations 1.2.2 → 1.2.4

package/src/core/semver.test.ts

@@ -0,0 +1,33 @@
+import { compareSemver } from './semver';
+
+describe('compareSemver', () => {
+  test('returns -1 when a < b across the minor digit boundary (the original bug)', () => {
+    expect(compareSemver('0.9.0', '0.10.0')).toBe(-1);
+  });
+
+  test('returns 1 when a > b across the minor digit boundary', () => {
+    expect(compareSemver('0.10.0', '0.9.0')).toBe(1);
+  });
+
+  test('returns -1 when a < b across the patch digit boundary', () => {
+    expect(compareSemver('0.1.0', '0.1.10')).toBe(-1);
+  });
+
+  test('handles major beats minor', () => {
+    expect(compareSemver('1.0.0', '0.99.99')).toBe(1);
+  });
+
+  test('returns 0 for equal versions', () => {
+    expect(compareSemver('1.2.3', '1.2.3')).toBe(0);
+  });
+
+  test('sorts a list of versions ascending in the correct order', () => {
+    const sorted = ['0.10.0', '1.0.0', '0.1.0', '0.9.0'].sort(compareSemver);
+    expect(sorted).toEqual(['0.1.0', '0.9.0', '0.10.0', '1.0.0']);
+  });
+
+  test('sorts a list of versions descending when the comparator is inverted', () => {
+    const sorted = ['0.10.0', '1.0.0', '0.1.0', '0.9.0'].sort((a, b) => compareSemver(b, a));
+    expect(sorted).toEqual(['1.0.0', '0.10.0', '0.9.0', '0.1.0']);
+  });
+});

package/src/core/semver.ts

@@ -0,0 +1,26 @@
+/**
+ * Compare two semver versions of the form `MAJOR.MINOR.PATCH`.
+ *
+ * Returns:
+ *   -1 if `a < b`
+ *    0 if `a === b`
+ *    1 if `a > b`
+ *
+ * Designed for migration filenames (`0.1.0_name.ts`) which the loader
+ * already validates as strict three-segment semver — prerelease and build
+ * metadata are not handled.
+ */
+export function compareSemver(a: string, b: string): number {
+  const partsA = a.split('.').map((n) => parseInt(n, 10));
+  const partsB = b.split('.').map((n) => parseInt(n, 10));
+
+  for (let i = 0; i < 3; i++) {
+    const numA = partsA[i] || 0;
+    const numB = partsB[i] || 0;
+
+    if (numA > numB) return 1;
+    if (numA < numB) return -1;
+  }
+
+  return 0;
+}

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

@@ -8,8 +8,10 @@ import {
   TransactWriteCommand,
 } from '@aws-sdk/lib-dynamodb';
 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;
@@ -17,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> {
@@ -50,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 {
@@ -64,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,
           },
@@ -86,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: {
@@ -170,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)
@@ -201,6 +255,7 @@ export class DynamoDBMigrationTracker implements MigrationTracker {
       await this.client.send(
         new TransactWriteCommand({
           TransactItems: [
+            this.lockOwnershipCheck(),
             {
               Update: {
                 TableName: this.tableName,
@@ -243,6 +298,7 @@ export class DynamoDBMigrationTracker implements MigrationTracker {
       await this.client.send(
         new TransactWriteCommand({
           TransactItems: [
+            this.lockOwnershipCheck(),
             {
               Put: {
                 TableName: this.tableName,
@@ -258,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)',
               },
             },
             {
@@ -288,13 +345,14 @@ 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
     const migrations = await this.getAppliedMigrations();
     const appliedMigrations = migrations
       .filter((m) => m.status === 'applied' && m.version !== version)
-      .sort((a, b) => b.version.localeCompare(a.version));
+      .sort((a, b) => compareSemver(b.version, a.version));
 
     const previousVersion = appliedMigrations[0]?.version || 'v0000';
 
@@ -302,6 +360,7 @@ export class DynamoDBMigrationTracker implements MigrationTracker {
     await this.client.send(
       new TransactWriteCommand({
         TransactItems: [
+          this.lockOwnershipCheck(),
           {
             Update: {
               TableName: this.tableName,
@@ -341,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
    */