Skip to content

Free, Open Source, Self-Hosted WhatsApp API Gateway

21.9 KB
Raw Blame
import { EventEmitter } from 'events';
import { DataSource, DataSourceOptions } from 'typeorm';
// Default import (not `import * as`) on purpose: it binds straight to pg's module.exports, so the
// constructor spy below reaches the same object pg-boot-migrations reads `Client` from at call time.
import pg, { Client as PgClient, ClientConfig } from 'pg';
import {
  AdvisoryLockClient,
  BootDataSourceDeps,
  POSTGRES_BOOT_MIGRATION_LOCK_KEYS,
  createBootDataSource,
} from './pg-boot-migrations';
import { postgresUtcExtra, utcTimestampTypes } from './postgres-utc';

// Protocol wiring of the boot-migration advisory lock: the lock must be taken BEFORE runMigrations
// starts and dropped after it finishes (on success AND on migration failure), and the DataSource
// handed back to Nest must never carry migrationsRun (it would re-run the chain unsynchronized).
// The pg client and the DataSource constructor are injected as fakes; the PG-gated companion spec
// (pg-boot-migrations.pg.spec.ts) proves the same protocol against a real Postgres.

const PG_OPTIONS: DataSourceOptions = {
  type: 'postgres',
  host: 'db',
  port: 5432,
  username: 'openwa',
  password: 'secret',
  database: 'openwa',
  // The app config still carries this; the factory takes over execution and must neutralize it.
  migrationsRun: true,
  migrationsTransactionMode: 'all',
  extra: { statement_timeout: 30000, connectionTimeoutMillis: 10000 },
};

describe('createBootDataSource (postgres boot migrations)', () => {
  // Fakes keep their inferred jest.Mock types (casts live only at the injection boundary) and
  // record every step in `calls`, so ordering is asserted on one linear trace.
  function makeFakes(runMigrations: () => Promise<unknown> = jest.fn(), sessionOffsetSeconds = 0) {
    const calls: string[] = [];
    const dataSource = {
      // The UTC pin's boot assertion reads the session's effective zone. It is not part of the lock
      // protocol these tests trace, so it stays out of `calls`.
      query: jest.fn(() =>
        Promise.resolve([
          { zone: 'UTC', offset_seconds: sessionOffsetSeconds, offset_seconds_later: sessionOffsetSeconds },
        ]),
      ),
      initialize: jest.fn(() => {
        calls.push('initialize');
        return Promise.resolve();
      }),
      runMigrations: jest.fn(() => {
        calls.push('runMigrations');
        return runMigrations();
      }),
      destroy: jest.fn(() => {
        calls.push('destroy');
        return Promise.resolve();
      }),
    };
    const lockClient: AdvisoryLockClient = {
      connect: jest.fn(() => {
        calls.push('connect');
        return Promise.resolve();
      }),
      query: jest.fn((text: string) => {
        calls.push(text);
        return Promise.resolve();
      }),
      end: jest.fn(() => {
        calls.push('end');
        return Promise.resolve();
      }),
    };
    const deps: BootDataSourceDeps = {
      createDataSource: jest.fn(() => dataSource as unknown as DataSource),
      createLockClient: jest.fn(() => lockClient),
    };
    return { calls, dataSource, lockClient, deps };
  }

  it('initializes, then migrates strictly between advisory lock acquire and release', async () => {
    const { calls, dataSource, lockClient, deps } = makeFakes();

    const returned = await createBootDataSource(PG_OPTIONS, deps);

    expect(returned).toBe(dataSource);
    // One fake stands in for both the migration pool (torn down after the chain) and the runtime one.
    expect(calls).toEqual([
      'initialize',
      'connect',
      'SET idle_session_timeout = 0',
      'SELECT pg_advisory_lock($1, $2)',
      'runMigrations',
      'SELECT pg_advisory_unlock($1, $2)',
      'end',
      'destroy',
      'initialize',
    ]);
    // Same key for acquire and release, in the (key1, key2) form.
    expect(lockClient.query).toHaveBeenNthCalledWith(2, 'SELECT pg_advisory_lock($1, $2)', [
      ...POSTGRES_BOOT_MIGRATION_LOCK_KEYS,
    ]);
    expect(lockClient.query).toHaveBeenNthCalledWith(3, 'SELECT pg_advisory_unlock($1, $2)', [
      ...POSTGRES_BOOT_MIGRATION_LOCK_KEYS,
    ]);
    // Migration execution preserves the built-in migrationsRun transaction mode, and only the
    // migration pool is torn down on success.
    expect(dataSource.runMigrations).toHaveBeenCalledWith({ transaction: 'all' });
    expect(dataSource.destroy).toHaveBeenCalledTimes(1);
  });

  it('constructs the DataSource with migrationsRun disabled and never mutates the config', async () => {
    const { deps } = makeFakes();

    await createBootDataSource(PG_OPTIONS, deps);

    expect(deps.createDataSource).toHaveBeenCalledWith({
      ...PG_OPTIONS,
      migrationsRun: false,
      // The UTC pin rides along with the pool settings the config already carries, rather than
      // replacing them.
      extra: {
        ...(PG_OPTIONS.extra as Record<string, unknown>),
        types: utcTimestampTypes,
        onConnect: postgresUtcExtra().onConnect,
      },
    });
    // The resolved config object itself is untouched — the flag stays as the built-in fallback.
    expect(PG_OPTIONS.migrationsRun).toBe(true);
    expect(PG_OPTIONS.extra).toEqual({ statement_timeout: 30000, connectionTimeoutMillis: 10000 });
  });

  it('runs the chain on its own pool without the runtime statement_timeout, then returns one that keeps it', async () => {
    // pg sends statement_timeout in the startup packet, so every statement on a pool built with it
    // inherits the limit: a backfill or index build over a large table was cancelled at 30 s, the
    // whole 'all' transaction rolled back, and every retry of the boot failed the same way.
    const migrator = makeFakes();
    const runtime = makeFakes();
    const createDataSource = jest
      .fn<DataSource, [DataSourceOptions]>()
      .mockReturnValueOnce(migrator.dataSource as unknown as DataSource)
      .mockReturnValueOnce(runtime.dataSource as unknown as DataSource);

    const returned = await createBootDataSource(PG_OPTIONS, {
      createDataSource,
      createLockClient: migrator.deps.createLockClient,
    });

    expect(returned).toBe(runtime.dataSource);
    expect(migrator.calls).toEqual([
      'initialize',
      'connect',
      'SET idle_session_timeout = 0',
      'SELECT pg_advisory_lock($1, $2)',
      'runMigrations',
      'SELECT pg_advisory_unlock($1, $2)',
      'end',
      'destroy',
    ]);
    expect(runtime.calls).toEqual(['initialize']);
    const [[migratorOptions], [runtimeOptions]] = createDataSource.mock.calls;
    expect(migratorOptions.extra).not.toHaveProperty('statement_timeout');
    expect(migratorOptions.extra).toMatchObject({ connectionTimeoutMillis: 10000 });
    expect(runtimeOptions.extra).toMatchObject({ statement_timeout: 30000, connectionTimeoutMillis: 10000 });
    expect(runtime.dataSource.query).toHaveBeenCalled(); // the runtime pool's UTC pin is verified too
  });

  it('tears the runtime DataSource down when its session is not on UTC, after the chain is applied', async () => {
    const migrator = makeFakes();
    const runtime = makeFakes(jest.fn(), 25200);
    const createDataSource = jest
      .fn<DataSource, [DataSourceOptions]>()
      .mockReturnValueOnce(migrator.dataSource as unknown as DataSource)
      .mockReturnValueOnce(runtime.dataSource as unknown as DataSource);

    await expect(
      createBootDataSource(PG_OPTIONS, { createDataSource, createLockClient: migrator.deps.createLockClient }),
    ).rejects.toThrow(/not on UTC/);

    expect(runtime.calls).toEqual(['initialize', 'destroy']);
  });

  it('builds the lock client without a statement timeout (pg_advisory_lock must survive the wait)', async () => {
    const { deps } = makeFakes();

    await createBootDataSource(PG_OPTIONS, deps);

    // statement_timeout applies to any command — including the lock wait — and a config value of 0
    // is dropped by pg as falsy, so the only correct disable is the startup `options` string.
    expect(deps.createLockClient).toHaveBeenCalledWith(
      expect.objectContaining({
        host: 'db',
        port: 5432,
        user: 'openwa',
        password: 'secret',
        database: 'openwa',
        connectionTimeoutMillis: 10000,
        options: '-c statement_timeout=0',
      }),
      expect.any(Function),
    );
  });

  // The holder sits idle on its lock connection for the whole chain, so a role- or database-level
  // idle_session_timeout (PostgreSQL 14+) would end the session mid-migration on every boot retry.
  // PostgreSQL 12 and 13 do not know the setting, which is why it is not in the startup packet.
  it('turns idle_session_timeout off on the lock session before taking the lock, tolerating old servers', async () => {
    const { calls, dataSource, lockClient, deps } = makeFakes();
    (lockClient.query as jest.Mock).mockImplementation((text: string) => {
      calls.push(text);
      return text.includes('idle_session_timeout')
        ? Promise.reject(new Error('unrecognized configuration parameter "idle_session_timeout"'))
        : Promise.resolve();
    });

    const returned = await createBootDataSource(PG_OPTIONS, deps);

    expect(returned).toBe(dataSource);
    expect(calls.slice(1, 5)).toEqual([
      'connect',
      'SET idle_session_timeout = 0',
      'SELECT pg_advisory_lock($1, $2)',
      'runMigrations',
    ]);
  });

  it('releases the lock and surfaces the error when a migration fails', async () => {
    const failure = new Error('duplicate table: messages');
    const { calls, lockClient, deps } = makeFakes(jest.fn(() => Promise.reject(failure)));

    await expect(createBootDataSource(PG_OPTIONS, deps)).rejects.toBe(failure);

    // Failure semantics: the lock still gets released, the client returned, and the DataSource is
    // torn down exactly like DataSource.initialize()'s own migrate-step error path — a retrying
    // boot must not stack initialized pools of failed attempts.
    expect(calls).toEqual([
      'initialize',
      'connect',
      'SET idle_session_timeout = 0',
      'SELECT pg_advisory_lock($1, $2)',
      'runMigrations',
      'SELECT pg_advisory_unlock($1, $2)',
      'end',
      'destroy',
    ]);
    expect(lockClient.end).toHaveBeenCalledTimes(1);
  });

  it('tears the DataSource down when the lock client cannot connect', async () => {
    const { dataSource, lockClient, deps } = makeFakes();
    (lockClient.connect as jest.Mock).mockRejectedValue(new Error('connect ECONNREFUSED'));

    await expect(createBootDataSource(PG_OPTIONS, deps)).rejects.toThrow('ECONNREFUSED');

    expect(lockClient.query).not.toHaveBeenCalled();
    expect(lockClient.end).toHaveBeenCalledTimes(1);
    expect(dataSource.destroy).toHaveBeenCalledTimes(1);
  });

  it('keeps the default @nestjs/typeorm path for non-postgres options (no lock, no initialize)', async () => {
    const sqliteOptions: DataSourceOptions = { type: 'better-sqlite3', database: './data/openwa.sqlite' };
    const dataSource = {
      initialize: jest.fn(() => Promise.resolve()),
      runMigrations: jest.fn(() => Promise.resolve()),
      destroy: jest.fn(() => Promise.resolve()),
    };
    const deps: BootDataSourceDeps = {
      createDataSource: jest.fn(() => dataSource as unknown as DataSource),
      createLockClient: jest.fn(),
    };

    const returned = await createBootDataSource(sqliteOptions, deps);

    // Untouched options, uninitialized DataSource (the wrapper's initialize keeps running the
    // connection's own migrationsRun), and no advisory-lock client is ever built.
    expect(returned).toBe(dataSource);
    expect(deps.createDataSource).toHaveBeenCalledWith(sqliteOptions);
    expect(deps.createLockClient).not.toHaveBeenCalled();
    expect(dataSource.initialize).not.toHaveBeenCalled();
  });

  it('still resolves when the advisory unlock fails: end() below drops the session and the lock', async () => {
    const { calls, dataSource, lockClient, deps } = makeFakes();
    (lockClient.query as jest.Mock).mockImplementation((text: string) => {
      calls.push(text);
      // Postgres killing the connection right after the last migration statement — the unlock
      // call itself fails, which must never turn a finished boot into a failed one.
      return text.includes('unlock') ? Promise.reject(new Error('connection terminated')) : Promise.resolve();
    });

    const returned = await createBootDataSource(PG_OPTIONS, deps);

    expect(returned).toBe(dataSource);
    expect(calls).toEqual([
      'initialize',
      'connect',
      'SET idle_session_timeout = 0',
      'SELECT pg_advisory_lock($1, $2)',
      'runMigrations',
      'SELECT pg_advisory_unlock($1, $2)',
      'end',
      'destroy',
      'initialize',
    ]);
    expect(dataSource.destroy).toHaveBeenCalledTimes(1); // the migration pool only
  });

  it('still resolves when lock-client end() fails: the boot result does not depend on client teardown', async () => {
    const { calls, dataSource, lockClient, deps } = makeFakes();
    (lockClient.end as jest.Mock).mockImplementation(() => {
      calls.push('end');
      return Promise.reject(new Error('socket hang up'));
    });

    const returned = await createBootDataSource(PG_OPTIONS, deps);

    expect(returned).toBe(dataSource);
    expect(calls).toEqual([
      'initialize',
      'connect',
      'SET idle_session_timeout = 0',
      'SELECT pg_advisory_lock($1, $2)',
      'runMigrations',
      'SELECT pg_advisory_unlock($1, $2)',
      'end',
      'destroy',
      'initialize',
    ]);
    expect(dataSource.destroy).toHaveBeenCalledTimes(1); // the migration pool only
  });

  it('surfaces the migration error, not the teardown error, when destroy() rejects too', async () => {
    const migrationFailure = new Error('duplicate table: messages');
    const { calls, dataSource, lockClient, deps } = makeFakes(jest.fn(() => Promise.reject(migrationFailure)));
    (dataSource.destroy as jest.Mock).mockImplementation(() => {
      calls.push('destroy');
      return Promise.reject(new Error('pool already destroyed'));
    });

    // The original boot failure wins; the destroy() rejection it triggered is swallowed so it
    // cannot mask what actually went wrong.
    await expect(createBootDataSource(PG_OPTIONS, deps)).rejects.toBe(migrationFailure);

    expect(calls).toEqual([
      'initialize',
      'connect',
      'SET idle_session_timeout = 0',
      'SELECT pg_advisory_lock($1, $2)',
      'runMigrations',
      'SELECT pg_advisory_unlock($1, $2)',
      'end',
      'destroy',
    ]);
    expect(lockClient.end).toHaveBeenCalledTimes(1);
  });

  it('defaults the lock-client connect timeout to 10s when options carry no extra block', async () => {
    const { deps } = makeFakes();

    await createBootDataSource({ ...PG_OPTIONS, extra: undefined }, deps);

    expect(deps.createLockClient).toHaveBeenCalledWith(
      expect.objectContaining({ connectionTimeoutMillis: 10000, options: '-c statement_timeout=0' }),
      expect.any(Function),
    );
  });

  it('takes the connect timeout from extra and forwards ssl by reference', async () => {
    const ssl = { rejectUnauthorized: false };
    const { deps } = makeFakes();

    await createBootDataSource({ ...PG_OPTIONS, ssl, extra: { connectionTimeoutMillis: 2500 } }, deps);

    // A value distinct from the 10s default proves the timeout comes from extra, and identity on
    // ssl proves the TLS shape is passed through untouched — the same object the driver built.
    const createLockClient = deps.createLockClient as jest.Mock<AdvisoryLockClient, [ClientConfig]>;
    const config = createLockClient.mock.calls[0][0];
    expect(config.connectionTimeoutMillis).toBe(2500);
    expect(config.ssl).toBe(ssl);
  });

  it('bounds the UTC pin of the migration and the runtime pool with that connect timeout', async () => {
    const { deps } = makeFakes();

    await createBootDataSource({ ...PG_OPTIONS, extra: { connectionTimeoutMillis: 2500 } }, deps);

    const built = (deps.createDataSource as jest.Mock<DataSource, [DataSourceOptions]>).mock.calls;
    expect(built).toHaveLength(2);
    for (const [options] of built) {
      const query = jest.fn().mockResolvedValue({});
      await (options.extra as { onConnect: (client: never) => Promise<unknown> }).onConnect({ query } as never);
      expect(query).toHaveBeenCalledWith({ text: "SET TIME ZONE 'UTC'", query_timeout: 2500 });
    }
  });

  it('falls back to the real DataSource and pg Client constructors when no deps are injected', async () => {
    // The production path. Only the spots that would touch the outside world are stubbed — the
    // DataSource lifecycle methods (initialize would open a pool) and the pg Client constructor
    // (connect would open a socket) — so both default factories run as shipped.
    const lockClient: AdvisoryLockClient = Object.assign(new EventEmitter(), {
      connect: jest.fn(() => Promise.resolve()),
      query: jest.fn(() => Promise.resolve()),
      end: jest.fn(() => Promise.resolve()),
    });
    const clientCtor = jest.spyOn(pg, 'Client').mockImplementation(() => lockClient as unknown as PgClient);
    const initialize = jest.spyOn(DataSource.prototype, 'initialize').mockImplementation(function (this: DataSource) {
      return Promise.resolve(this);
    });
    const query = jest
      .spyOn(DataSource.prototype, 'query')
      .mockResolvedValue([{ zone: 'UTC', offset_seconds: 0, offset_seconds_later: 0 }] as never);
    const runMigrations = jest.spyOn(DataSource.prototype, 'runMigrations').mockResolvedValue([]);
    const destroy = jest.spyOn(DataSource.prototype, 'destroy').mockResolvedValue(undefined);
    try {
      const returned = await createBootDataSource(PG_OPTIONS);

      expect(returned).toBeInstanceOf(DataSource);
      // The default factory path still neutralizes migrationsRun before construction.
      expect(returned.options.migrationsRun).toBe(false);
      // The real Client constructor received the same lock-client config the fakes assert above.
      expect(clientCtor).toHaveBeenCalledWith(
        expect.objectContaining({
          host: 'db',
          user: 'openwa',
          database: 'openwa',
          options: '-c statement_timeout=0',
        }),
      );
      expect(lockClient.query).toHaveBeenNthCalledWith(2, 'SELECT pg_advisory_lock($1, $2)', [
        ...POSTGRES_BOOT_MIGRATION_LOCK_KEYS,
      ]);
      expect(lockClient.query).toHaveBeenNthCalledWith(3, 'SELECT pg_advisory_unlock($1, $2)', [
        ...POSTGRES_BOOT_MIGRATION_LOCK_KEYS,
      ]);
      expect(runMigrations).toHaveBeenCalledWith({ transaction: 'all' });
      // The migration pool is torn down; the returned runtime one keeps the statement timeout.
      expect(destroy).toHaveBeenCalledTimes(1);
      expect(returned.options.extra).toMatchObject({ statement_timeout: 30000 });
    } finally {
      clientCtor.mockRestore();
      initialize.mockRestore();
      query.mockRestore();
      runMigrations.mockRestore();
      destroy.mockRestore();
    }
  });

  // pg emits 'error' on the client when its socket drops outside the client's own end() (failover,
  // pg_terminate_backend, an idle-timeout on the silent wait inside pg_advisory_lock). With no
  // listener that emit throws from the socket handler and kills the process before the failed lock
  // query can reject into the factory's cleanup and Nest's retry loop.
  it('listens for lock-client errors so a dropped connection cannot crash the process', async () => {
    const lockClient = Object.assign(new EventEmitter(), {
      connect: jest.fn(() => Promise.resolve()),
      query: jest.fn(() => Promise.resolve()),
      end: jest.fn(() => Promise.resolve()),
    });
    const clientCtor = jest.spyOn(pg, 'Client').mockImplementation(() => lockClient as unknown as PgClient);
    const { deps } = makeFakes();
    try {
      await createBootDataSource(PG_OPTIONS, { createDataSource: deps.createDataSource });

      expect(lockClient.listenerCount('error')).toBeGreaterThan(0);
      expect(() => lockClient.emit('error', new Error('Connection terminated unexpectedly'))).not.toThrow();
    } finally {
      clientCtor.mockRestore();
    }
  });

  // The lock is session-scoped, so a holder whose lock connection drops has lost it: another replica
  // can start the same chain. The holder must stop migrating and fail the boot, which the retry loop
  // then reruns under a new lock.
  it('stops migrating and fails the boot when the held lock connection drops', async () => {
    let finishChain: () => void = () => undefined;
    const chain = new Promise<void>(resolve => (finishChain = resolve));
    const { calls, deps } = makeFakes(() => chain);
    let onLost: (error: Error) => void = () => undefined;
    const createLockClient = deps.createLockClient as jest.Mock;
    const lockClient = createLockClient.getMockImplementation()!() as AdvisoryLockClient;
    createLockClient.mockImplementation((_config: ClientConfig, lost: (error: Error) => void) => {
      onLost = lost;
      return lockClient;
    });

    const boot = createBootDataSource(PG_OPTIONS, deps);
    await new Promise(resolve => setImmediate(resolve));
    expect(calls).toContain('runMigrations');

    onLost(new Error('Connection terminated unexpectedly'));
    expect(calls.filter(c => c === 'destroy')).toHaveLength(1);
    finishChain();

    await expect(boot).rejects.toThrow(/lock connection lost while migrating/);
    // The runtime DataSource is never built on a chain that ran partly unlocked.
    expect(calls.filter(c => c === 'initialize')).toHaveLength(1);
  });

  it('refuses to migrate on a connection whose session is not on UTC', async () => {
    // A pin that did not take (a pooler dropping the SET, a server-side default re-applied after it)
    // would have the driver read every naive timestamp as UTC while the server keeps writing its own
    // zone. Migrating on that connection would bake the mismatch into the data it rewrites.
    const { calls, dataSource, deps } = makeFakes(jest.fn(), 25200);

    await expect(createBootDataSource(PG_OPTIONS, deps)).rejects.toThrow(/not on UTC/);

    expect(dataSource.runMigrations).not.toHaveBeenCalled();
    expect(deps.createLockClient).not.toHaveBeenCalled();
    expect(calls).toEqual(['initialize', 'destroy']);
  });
});