Skip to content

Garry's Opinionated OpenClaw/Hermes Agent Brain

TypeScript
8.3 KB
Raw Blame
/**
 * Unit tests for the pg_resetwal port (src/core/pglite-resetwal.ts).
 *
 * Everything here runs on SYNTHETIC PG17 layouts (hand-built pg_control
 * buffers) — fast, parallel-safe, no PGLite. The real-engine proof (corrupt a
 * real brain's WAL → reopen → row readable) lives in
 * test/pglite-wal-repair.serial.test.ts.
 */
import { describe, test, expect } from 'bun:test';
import { mkdtempSync, mkdirSync, writeFileSync, existsSync, readFileSync, readdirSync, statSync } from 'node:fs';
import { tmpdir } from 'node:os';
import { join } from 'node:path';
import {
  resetWal,
  crc32c,
  parseWalSegNo,
  xlogFileName,
  WalResetUnsupportedError,
} from '../src/core/pglite-resetwal.ts';

const SEG_SIZE = 1024 * 1024; // 1MB — valid (power of two, divides 2^32), fast to write

const OFF = {
  systemIdentifier: 0,
  pgControlVersion: 8,
  state: 16,
  checkPoint: 32,
  checkPointCopyRedo: 40,
  checkPointCopyThisTimeLineID: 48,
  xlogBlcksz: 224,
  xlogSegSize: 228,
  crc: 288,
} as const;

function makeControl(opts?: { version?: number; segSize?: number; blcksz?: number; tli?: number; redoSegNo?: bigint }): Buffer {
  const control = Buffer.alloc(8192);
  control.writeBigUInt64LE(0x1122334455667788n, OFF.systemIdentifier);
  control.writeUInt32LE(opts?.version ?? 1700, OFF.pgControlVersion);
  control.writeUInt32LE(opts?.tli ?? 1, OFF.checkPointCopyThisTimeLineID);
  control.writeUInt32LE(opts?.blcksz ?? 8192, OFF.xlogBlcksz);
  control.writeUInt32LE(opts?.segSize ?? SEG_SIZE, OFF.xlogSegSize);
  const redoSegNo = opts?.redoSegNo ?? 3n;
  control.writeBigUInt64LE(redoSegNo * BigInt(opts?.segSize ?? SEG_SIZE) + 40n, OFF.checkPointCopyRedo);
  control.writeUInt32LE(crc32c([control.subarray(0, OFF.crc)]), OFF.crc); // valid CRC
  return control;
}

function makeLayout(opts?: Parameters<typeof makeControl>[0] & { pgVersion?: string; segments?: string[] }): string {
  const dir = mkdtempSync(join(tmpdir(), 'resetwal-'));
  writeFileSync(join(dir, 'PG_VERSION'), `${opts?.pgVersion ?? '17'}\n`);
  mkdirSync(join(dir, 'global'), { recursive: true });
  writeFileSync(join(dir, 'global', 'pg_control'), makeControl(opts));
  mkdirSync(join(dir, 'base'), { recursive: true });
  mkdirSync(join(dir, 'pg_wal', 'archive_status'), { recursive: true });
  for (const seg of opts?.segments ?? []) {
    writeFileSync(join(dir, 'pg_wal', seg), Buffer.alloc(1024, 0xaa));
  }
  return dir;
}

describe('resetWal — validation refusals (fail-closed)', () => {
  test('refuses PG_VERSION 16', async () => {
    const dir = makeLayout({ pgVersion: '16' });
    await expect(resetWal(dir)).rejects.toThrow(WalResetUnsupportedError);
  });

  test('refuses missing PG_VERSION', async () => {
    const dir = mkdtempSync(join(tmpdir(), 'resetwal-'));
    await expect(resetWal(dir)).rejects.toThrow(WalResetUnsupportedError);
  });

  test('refuses wrong pg_control size', async () => {
    const dir = makeLayout();
    writeFileSync(join(dir, 'global', 'pg_control'), Buffer.alloc(100));
    await expect(resetWal(dir)).rejects.toThrow(/pg_control size/);
  });

  test('refuses wrong pg_control version', async () => {
    const dir = makeLayout({ version: 1600 });
    await expect(resetWal(dir)).rejects.toThrow(/pg_control version/);
  });

  test('refuses non-power-of-two WAL segment size', async () => {
    const dir = makeLayout({ segSize: 3 * 1024 * 1024 });
    await expect(resetWal(dir)).rejects.toThrow(/segment size/);
  });

  test('refuses unsupported WAL block size', async () => {
    const dir = makeLayout({ blcksz: 4096 });
    await expect(resetWal(dir)).rejects.toThrow(/block size/);
  });

  test('refuses a pg_control whose stored CRC does not verify (F6: no laundering corrupt counters)', async () => {
    const dir = makeLayout();
    // A structurally-valid control (right size/version/seg/block) but with a
    // damaged checkpoint copy and a STALE crc — real pg_resetwal refuses this.
    const control = readFileSync(join(dir, 'global', 'pg_control'));
    control.writeBigUInt64LE(0xdeadbeefn, 56); // trash a checkpointCopy field
    // leave the old CRC in place → mismatch
    writeFileSync(join(dir, 'global', 'pg_control'), control);
    await expect(resetWal(dir)).rejects.toThrow(/CRC mismatch/);
  });
});

describe('resetWal — byte surgery on a synthetic PG17 layout', () => {
  test('resets WAL: pid removed, old segments gone, fresh checkpoint segment + CRC-valid control', async () => {
    const oldSegs = [xlogFileName(1, 3n, SEG_SIZE), xlogFileName(1, 4n, SEG_SIZE)];
    const dir = makeLayout({ redoSegNo: 3n, segments: oldSegs });
    writeFileSync(join(dir, 'postmaster.pid'), '12345\n');
    writeFileSync(join(dir, 'pg_wal', 'archive_status', `${oldSegs[0]}.ready`), '');
    mkdirSync(join(dir, 'pg_wal', 'summaries'), { recursive: true });
    writeFileSync(join(dir, 'pg_wal', 'summaries', `${'0'.repeat(40)}.summary`), '');

    const result = await resetWal(dir);

    // Stale run state + old WAL removed.
    expect(existsSync(join(dir, 'postmaster.pid'))).toBe(false);
    for (const seg of oldSegs) {
      expect(existsSync(join(dir, 'pg_wal', seg))).toBe(false);
    }
    expect(readdirSync(join(dir, 'pg_wal', 'archive_status'))).toEqual([]);
    expect(readdirSync(join(dir, 'pg_wal', 'summaries'))).toEqual([]);

    // newSegNo = max(redo=3, existing max=4) + 1 = 5.
    expect(result.resetSegment).toBe(xlogFileName(1, 5n, SEG_SIZE));
    expect(result.timelineId).toBe(1);
    expect(result.walSegSize).toBe(SEG_SIZE);

    const segPath = join(dir, 'pg_wal', result.resetSegment);
    expect(existsSync(segPath)).toBe(true);
    expect(statSync(segPath).size).toBe(SEG_SIZE);
    const wal = readFileSync(segPath);
    expect(wal.readUInt16LE(0)).toBe(0xd116); // XLOG_PAGE_MAGIC
    expect(wal.readUInt16LE(2) & 0x0002).toBe(0x0002); // XLP_LONG_HEADER

    // Control: shutdown state + self-consistent CRC32C over bytes 0..288.
    const control = readFileSync(join(dir, 'global', 'pg_control'));
    expect(control.length).toBe(8192);
    expect(control.readInt32LE(OFF.state)).toBe(1); // DB_SHUTDOWNED
    expect(control.readUInt32LE(OFF.crc)).toBe(crc32c([control.subarray(0, OFF.crc)]));
    // checkPoint points into the new segment.
    const checkPoint = control.readBigUInt64LE(OFF.checkPoint);
    expect(checkPoint / BigInt(SEG_SIZE)).toBe(5n);

    // No torn tmp files left behind (atomic-write hygiene).
    expect(readdirSync(join(dir, 'pg_wal')).filter((f) => f.includes('.tmp-'))).toEqual([]);
    expect(readdirSync(join(dir, 'global')).filter((f) => f.includes('.tmp-'))).toEqual([]);
  });

  test('works on an EMPTY pg_wal (the whole-dir-rename backup path) and numbers off pg_control alone', async () => {
    const dir = makeLayout({ redoSegNo: 7n, segments: [] });
    const result = await resetWal(dir);
    // No existing segments — newSegNo = redo(7) + 1.
    expect(result.resetSegment).toBe(xlogFileName(1, 8n, SEG_SIZE));
    expect(existsSync(join(dir, 'pg_wal', 'archive_status'))).toBe(true);
  });

  test('is idempotent: a second run converges (numbering keeps moving forward)', async () => {
    const dir = makeLayout({ redoSegNo: 3n });
    const first = await resetWal(dir);
    const second = await resetWal(dir);
    const firstNo = parseWalSegNo(first.resetSegment, SEG_SIZE)!;
    const secondNo = parseWalSegNo(second.resetSegment, SEG_SIZE)!;
    expect(secondNo).toBeGreaterThan(firstNo);
    // Exactly one segment remains after each run.
    const segs = readdirSync(join(dir, 'pg_wal')).filter((f) => /^[0-9A-F]{24}$/.test(f));
    expect(segs).toEqual([second.resetSegment]);
  });
});

describe('WAL segment name helpers', () => {
  test('parseWalSegNo / xlogFileName round-trip', () => {
    for (const segNo of [0n, 1n, 255n, 4096n, 0x1_0000_0000n / BigInt(SEG_SIZE) + 7n]) {
      const name = xlogFileName(1, segNo, SEG_SIZE);
      expect(name).toMatch(/^[0-9A-F]{24}$/);
      expect(parseWalSegNo(name, SEG_SIZE)).toBe(segNo);
    }
  });

  test('parseWalSegNo rejects non-segment names', () => {
    expect(parseWalSegNo('archive_status', SEG_SIZE)).toBeNull();
    expect(parseWalSegNo('000000010000000000000001.partial', SEG_SIZE)).toBeNull();
    expect(parseWalSegNo('lowercase0000000000000001', SEG_SIZE)).toBeNull();
  });

  test('crc32c matches a known vector', () => {
    // CRC-32C of ASCII "123456789" is 0xE3069283 (Castagnoli test vector).
    expect(crc32c([Buffer.from('123456789')])).toBe(0xe3069283);
  });
});