@ftschopp/dynatable-migrations 1.2.3 → 1.2.5

package/dist/types/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/types/index.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/types/index.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ftschopp/dynatable-migrations",
-  "version": "1.2.3",
+  "version": "1.2.5",
   "description": "DynamoDB migration tool for single table design with schema versioning",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
@@ -28,6 +28,7 @@
     "@repo/typescript-config": "*",
     "@types/jest": "^30.0.0",
     "@types/node": "^25.0.3",
+    "aws-sdk-client-mock": "^4.1.0",
     "jest": "^30.2.0",
     "ts-jest": "^29.4.6",
     "typescript": "5.9.3"

package/src/core/errors.ts

@@ -0,0 +1,55 @@
+/**
+ * Thrown by `markAsApplied` when the version already has a tracking record
+ * in a non-applied state (e.g. `failed`, `rolled_back`) and therefore
+ * cannot be silently treated as an idempotent re-apply. Surfaces the
+ * existing state so the caller can decide whether to retry, recover, or
+ * roll back.
+ */
+export class MigrationAlreadyAppliedError extends Error {
+  public readonly version: string;
+  public readonly currentStatus: string | undefined;
+
+  constructor(version: string, currentStatus: string | undefined) {
+    super(
+      `Migration "${version}" already has a tracking record in state ` +
+        `"${currentStatus ?? 'unknown'}" — cannot mark as applied. ` +
+        `If you want to re-apply this version, roll it back first ` +
+        `(or recover the failed run) and try again.`
+    );
+    this.name = 'MigrationAlreadyAppliedError';
+    this.version = version;
+    this.currentStatus = currentStatus;
+    if (typeof (Error as unknown as { captureStackTrace?: unknown }).captureStackTrace === 'function') {
+      (
+        Error as unknown as { captureStackTrace: (target: object, ctor: unknown) => void }
+      ).captureStackTrace(this, MigrationAlreadyAppliedError);
+    }
+  }
+}
+
+/**
+ * Thrown when a tracker write is cancelled because the migration lock was
+ * taken by another process between `acquireLock()` and the write itself
+ * (e.g. the original lock TTL expired and a second worker took over).
+ *
+ * The transaction was rolled back atomically — no partial state was
+ * written. The safe action is to stop the current `up()` / `down()` run.
+ */
+export class MigrationLockLostError extends Error {
+  public readonly version: string;
+
+  constructor(version: string) {
+    super(
+      `Migration lock was lost during markAsApplied("${version}"). ` +
+        `Another worker may have taken over. The transaction was rolled ` +
+        `back atomically; no partial state was written.`
+    );
+    this.name = 'MigrationLockLostError';
+    this.version = version;
+    if (typeof (Error as unknown as { captureStackTrace?: unknown }).captureStackTrace === 'function') {
+      (
+        Error as unknown as { captureStackTrace: (target: object, ctor: unknown) => void }
+      ).captureStackTrace(this, MigrationLockLostError);
+    }
+  }
+}

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,281 @@
+/* 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)');
+  });
+});
+
+describe('DynamoDBMigrationTracker - markAsApplied idempotency (#10)', () => {
+  function cancelledTransactError(reasons: Array<{ Code?: string }>) {
+    return Object.assign(new Error('Transaction cancelled'), {
+      name: 'TransactionCanceledException',
+      CancellationReasons: reasons,
+    });
+  }
+
+  test('returns silently when the cancellation is because the row is already in status=applied', async () => {
+    ddbMock.on(PutCommand).resolves({}); // acquireLock
+    // First getMigration → no record (so we take the Put branch)
+    // Second getMigration (after cancellation) → already applied
+    ddbMock
+      .on(GetCommand)
+      .resolvesOnce({ Item: undefined })
+      .resolvesOnce({
+        Item: {
+          PK: '_SCHEMA#VERSION',
+          SK: '0.1.0',
+          version: '0.1.0',
+          status: 'applied',
+          name: 'init',
+        },
+      });
+
+    // Migration row condition fails (reasons[1]); lock check passed (reasons[0] = None)
+    ddbMock.on(TransactWriteCommand).rejects(
+      cancelledTransactError([{ Code: 'None' }, { Code: 'ConditionalCheckFailed' }])
+    );
+
+    const tracker = makeTracker();
+    await tracker.acquireLock();
+
+    await expect(tracker.markAsApplied('0.1.0', 'init')).resolves.toBeUndefined();
+  });
+
+  test('throws MigrationAlreadyAppliedError when the row exists in a non-applied state', async () => {
+    ddbMock.on(PutCommand).resolves({});
+    ddbMock
+      .on(GetCommand)
+      .resolvesOnce({ Item: undefined })
+      .resolvesOnce({
+        Item: {
+          PK: '_SCHEMA#VERSION',
+          SK: '0.1.0',
+          version: '0.1.0',
+          status: 'failed',
+          name: 'init',
+        },
+      });
+
+    ddbMock.on(TransactWriteCommand).rejects(
+      cancelledTransactError([{ Code: 'None' }, { Code: 'ConditionalCheckFailed' }])
+    );
+
+    const tracker = makeTracker();
+    await tracker.acquireLock();
+
+    await expect(tracker.markAsApplied('0.1.0', 'init')).rejects.toMatchObject({
+      name: 'MigrationAlreadyAppliedError',
+      version: '0.1.0',
+      currentStatus: 'failed',
+    });
+  });
+
+  test('throws MigrationLockLostError when the lock-row ConditionCheck is what failed', async () => {
+    ddbMock.on(PutCommand).resolves({});
+    ddbMock.on(GetCommand).resolves({ Item: undefined });
+
+    ddbMock.on(TransactWriteCommand).rejects(
+      cancelledTransactError([{ Code: 'ConditionalCheckFailed' }, { Code: 'None' }])
+    );
+
+    const tracker = makeTracker();
+    await tracker.acquireLock();
+
+    await expect(tracker.markAsApplied('0.1.0', 'init')).rejects.toMatchObject({
+      name: 'MigrationLockLostError',
+      version: '0.1.0',
+    });
+  });
+
+  test('re-throws unexpected errors unchanged', async () => {
+    ddbMock.on(PutCommand).resolves({});
+    ddbMock.on(GetCommand).resolves({ Item: undefined });
+
+    const boom = Object.assign(new Error('upstream blew up'), { name: 'InternalServerError' });
+    ddbMock.on(TransactWriteCommand).rejects(boom);
+
+    const tracker = makeTracker();
+    await tracker.acquireLock();
+
+    await expect(tracker.markAsApplied('0.1.0', 'init')).rejects.toBe(boom);
+  });
+
+  test('idempotent path also covers the Update branch (existing record was rolled_back, applied by a racing worker)', async () => {
+    ddbMock.on(PutCommand).resolves({});
+    // First getMigration → existing rolled_back record (so we take the Update branch)
+    // Second getMigration (after cancellation) → already applied (race)
+    ddbMock
+      .on(GetCommand)
+      .resolvesOnce({
+        Item: {
+          PK: '_SCHEMA#VERSION',
+          SK: '0.1.0',
+          version: '0.1.0',
+          status: 'rolled_back',
+          name: 'init',
+        },
+      })
+      .resolvesOnce({
+        Item: {
+          PK: '_SCHEMA#VERSION',
+          SK: '0.1.0',
+          version: '0.1.0',
+          status: 'applied',
+          name: 'init',
+        },
+      });
+
+    ddbMock.on(TransactWriteCommand).rejects(
+      cancelledTransactError([{ Code: 'None' }, { Code: 'ConditionalCheckFailed' }])
+    );
+
+    const tracker = makeTracker();
+    await tracker.acquireLock();
+
+    await expect(tracker.markAsApplied('0.1.0', 'init')).resolves.toBeUndefined();
+  });
+});