Skip to content

The open-source app everyone uses to manage agents at work

21.2 KB
Raw Blame
import fs from "node:fs";
import os from "node:os";
import path from "node:path";
import postgres from "postgres";
import { afterEach, describe, expect, it } from "vitest";
import { inspectMigrations } from "./client.js";
import {
  __embeddedPostgresStartMaxAttemptsForTests as MAX_ATTEMPTS,
  __embeddedPostgresTemplateRootDirForTests as templateRootDir,
  __isUsableEmbeddedPostgresTemplateForTests as isUsableTemplate,
  __lastEmbeddedPostgresStartModeForTests as lastStartMode,
  __resetEmbeddedPostgresTemplateStateForTests as resetTemplateState,
  __setEmbeddedPostgresCtorProviderForTests,
  __startEmbeddedPostgresWithRetryForTests as startWithRetry,
  computeEmbeddedPostgresTemplateKey,
  EMBEDDED_POSTGRES_TEST_TIMEOUT_MS,
  getEmbeddedPostgresTestSupport,
  startEmbeddedPostgresTestDatabase,
} from "./test-embedded-postgres.js";

// A fake embedded-postgres constructor. It records every constructed instance so
// the test can assert the retry uses a fresh port and a fresh data directory each
// attempt. `start()` emits the same output the real cluster writes for a port
// conflict, then rejects with an empty message (the real rejection shape). The
// option type matches the real constructor so no type cast is needed.
type FakeOptions = {
  databaseDir: string;
  user: string;
  password: string;
  port: number;
  persistent: boolean;
  initdbFlags?: string[];
  onLog?: (message: unknown) => void;
  onError?: (message: unknown) => void;
};

const BIND_CONFLICT_LOG = 'could not bind IPv4 address "127.0.0.1": Address already in use';

function makeFakeCtor(failFirst: number) {
  const constructed: FakeOptions[] = [];
  let started = 0;

  class FakeEmbeddedPostgres {
    private readonly options: FakeOptions;
    constructor(options: FakeOptions) {
      this.options = options;
      constructed.push(options);
    }
    async initialise(): Promise<void> {}
    async start(): Promise<void> {
      started += 1;
      if (started <= failFirst) {
        // Mirror the real failure: Postgres logs the reason, then `start()`
        // rejects with an Error whose message is empty.
        this.options.onLog?.(BIND_CONFLICT_LOG);
        throw new Error();
      }
    }
    async stop(): Promise<void> {}
  }

  return { ctor: FakeEmbeddedPostgres, constructed };
}

describe("startEmbeddedPostgresWithRetry", () => {
  afterEach(() => {
    __setEmbeddedPostgresCtorProviderForTests(null);
  });

  it("recovers from a transient port conflict and returns on a later attempt", async () => {
    const { ctor, constructed } = makeFakeCtor(2);
    __setEmbeddedPostgresCtorProviderForTests(async () => ctor);

    const started = await startWithRetry("paperclip-retry-recover-");

    // The first two attempts fail, the third succeeds.
    expect(constructed).toHaveLength(3);

    // Each attempt uses a fresh data directory. The two failed directories are
    // removed. The returned directory still exists.
    const dataDirs = constructed.map((options) => options.databaseDir);
    expect(new Set(dataDirs).size).toBe(3);
    expect(fs.existsSync(dataDirs[0])).toBe(false);
    expect(fs.existsSync(dataDirs[1])).toBe(false);
    expect(started.dataDir).toBe(dataDirs[2]);
    expect(fs.existsSync(started.dataDir)).toBe(true);

    // Each attempt allocates a port.
    for (const options of constructed) {
      expect(Number.isInteger(options.port)).toBe(true);
      expect(options.port).toBeGreaterThan(0);
    }

    // Clean up the returned attempt.
    await started.instance.stop();
    fs.rmSync(started.dataDir, { recursive: true, force: true });
  });

  it("throws with the real Postgres output after the attempt bound", async () => {
    const { ctor, constructed } = makeFakeCtor(Number.POSITIVE_INFINITY);
    __setEmbeddedPostgresCtorProviderForTests(async () => ctor);

    await expect(startWithRetry("paperclip-retry-fail-")).rejects.toThrow(/after \d+ attempts/);

    // The retry stops at the bound and does not loop forever.
    expect(constructed).toHaveLength(MAX_ATTEMPTS);

    // Every failed attempt removes its data directory.
    for (const options of constructed) {
      expect(fs.existsSync(options.databaseDir)).toBe(false);
    }
  });

  it("keeps the real failure reason instead of a generic fallback", async () => {
    const { ctor } = makeFakeCtor(Number.POSITIVE_INFINITY);
    __setEmbeddedPostgresCtorProviderForTests(async () => ctor);

    const error = await startWithRetry("paperclip-retry-reason-").catch((caught: unknown) => caught);

    expect(error).toBeInstanceOf(Error);
    // The thrown message carries the captured Postgres output, not only the
    // generic "embedded Postgres startup failed" text.
    expect((error as Error).message).toContain("Address already in use");
  });
});

describe("computeEmbeddedPostgresTemplateKey", () => {
  function writeMigrations(dir: string, files: Record<string, string>) {
    fs.mkdirSync(path.join(dir, "meta"), { recursive: true });
    fs.writeFileSync(path.join(dir, "meta", "_journal.json"), JSON.stringify({ entries: Object.keys(files) }));
    for (const [name, content] of Object.entries(files)) {
      fs.writeFileSync(path.join(dir, name), content);
    }
  }

  it("is stable for identical inputs and changes with any migration, flag, or version", () => {
    const root = fs.mkdtempSync(path.join(os.tmpdir(), "paperclip-template-key-"));
    try {
      const a = path.join(root, "a");
      const b = path.join(root, "b");
      writeMigrations(a, { "0000_one.sql": "create table one();", "0001_two.sql": "create table two();" });
      writeMigrations(b, { "0000_one.sql": "create table one();", "0001_two.sql": "create table two();" });
      const fixed = { packageVersion: "18.1.0", initdbFlags: ["--locale=C"], user: "paperclip" };

      const keyA = computeEmbeddedPostgresTemplateKey(a, fixed);
      expect(keyA).toMatch(/^[0-9a-f]{24}$/);
      expect(computeEmbeddedPostgresTemplateKey(a, fixed)).toBe(keyA);
      expect(computeEmbeddedPostgresTemplateKey(b, fixed)).toBe(keyA);

      // Content change, new file, flags, version, and user each change the key.
      fs.writeFileSync(path.join(b, "0001_two.sql"), "create table two(id int);");
      const contentChanged = computeEmbeddedPostgresTemplateKey(b, fixed);
      expect(contentChanged).not.toBe(keyA);
      fs.writeFileSync(path.join(b, "0002_three.sql"), "create table three();");
      expect(computeEmbeddedPostgresTemplateKey(b, fixed)).not.toBe(contentChanged);
      expect(computeEmbeddedPostgresTemplateKey(a, { ...fixed, initdbFlags: ["--locale=C", "--encoding=UTF8"] })).not.toBe(keyA);
      expect(computeEmbeddedPostgresTemplateKey(a, { ...fixed, packageVersion: "18.2.0" })).not.toBe(keyA);
      expect(computeEmbeddedPostgresTemplateKey(a, { ...fixed, user: "other" })).not.toBe(keyA);
    } finally {
      fs.rmSync(root, { recursive: true, force: true });
    }
  });

  it("hashes the real migrations directory of this package", () => {
    const key = computeEmbeddedPostgresTemplateKey();
    expect(key).toMatch(/^[0-9a-f]{24}$/);
    expect(computeEmbeddedPostgresTemplateKey()).toBe(key);
  });
});

const describeOnPosix = process.platform === "win32" ? describe.skip : describe;

describe("isUsableTemplate", () => {
  let root: string;

  function writeCluster(dir: string): void {
    fs.mkdirSync(dir, { recursive: true, mode: 0o700 });
    fs.writeFileSync(path.join(dir, "PG_VERSION"), "18\n");
  }

  afterEach(() => {
    fs.rmSync(root, { recursive: true, force: true });
  });

  it("accepts a private directory that holds a cleanly stopped cluster", () => {
    root = fs.mkdtempSync(path.join(os.tmpdir(), "paperclip-template-usable-"));
    const template = path.join(root, "template");
    writeCluster(template);
    expect(isUsableTemplate(template)).toBe(true);

    // A running or crashed cluster leaves `postmaster.pid` behind.
    fs.writeFileSync(path.join(template, "postmaster.pid"), "1\n");
    expect(isUsableTemplate(template)).toBe(false);
    fs.rmSync(path.join(template, "postmaster.pid"));
    expect(isUsableTemplate(template)).toBe(true);

    // A directory without a cluster, or no directory at all.
    fs.rmSync(path.join(template, "PG_VERSION"));
    expect(isUsableTemplate(template)).toBe(false);
    expect(isUsableTemplate(path.join(root, "missing"))).toBe(false);
  });

  it("rejects a symbolic link even when it points at a usable cluster", () => {
    root = fs.mkdtempSync(path.join(os.tmpdir(), "paperclip-template-usable-"));
    const template = path.join(root, "template");
    writeCluster(template);
    const link = path.join(root, "link");
    fs.symlinkSync(template, link, "dir");
    expect(isUsableTemplate(template)).toBe(true);
    expect(isUsableTemplate(link)).toBe(false);
  });

  describeOnPosix("on POSIX", () => {
    it("rejects a cluster directory that group or others can write", () => {
      root = fs.mkdtempSync(path.join(os.tmpdir(), "paperclip-template-usable-"));
      const template = path.join(root, "template");
      writeCluster(template);
      for (const mode of [0o720, 0o702, 0o777]) {
        fs.chmodSync(template, mode);
        expect(isUsableTemplate(template), `mode ${mode.toString(8)}`).toBe(false);
      }
      // Read bits for others are not a write path; Postgres narrows the copy
      // to 0700 before it starts anyway.
      fs.chmodSync(template, 0o755);
      expect(isUsableTemplate(template)).toBe(true);
      fs.chmodSync(template, 0o700);
      expect(isUsableTemplate(template)).toBe(true);
    });
  });
});

// Real-cluster coverage of the template path. Skipped on hosts that cannot run
// embedded Postgres, like every other suite that uses the fixture.
const support = await getEmbeddedPostgresTestSupport();
const describeWithPostgres = support.supported ? describe : describe.skip;

// Points `os.tmpdir()` at a private scratch directory so a test can drive the
// cache root from an empty state. `os.tmpdir()` reads the environment on every
// call: TMPDIR on POSIX, TEMP and then TMP on Windows, so all three are set.
// Returns the scratch directory; `restore` puts the environment and the
// fixture's cached state back.
const TMPDIR_VARIABLES = ["TMPDIR", "TEMP", "TMP"] as const;

function useScratchTmpdir(prefix: string): { scratch: string; restore(): void } {
  const scratch = fs.mkdtempSync(path.join(os.tmpdir(), prefix));
  const previous = new Map(TMPDIR_VARIABLES.map((name) => [name, process.env[name]] as const));
  for (const name of TMPDIR_VARIABLES) process.env[name] = scratch;
  return {
    scratch,
    restore() {
      for (const [name, value] of previous) {
        if (value === undefined) delete process.env[name];
        else process.env[name] = value;
      }
      resetTemplateState();
      fs.rmSync(scratch, { recursive: true, force: true });
    },
  };
}

describeWithPostgres("startEmbeddedPostgresTestDatabase template path", () => {
  const originalTemplateSetting = process.env.PAPERCLIP_TEST_POSTGRES_TEMPLATE;

  afterEach(() => {
    if (originalTemplateSetting === undefined) delete process.env.PAPERCLIP_TEST_POSTGRES_TEMPLATE;
    else process.env.PAPERCLIP_TEST_POSTGRES_TEMPLATE = originalTemplateSetting;
  });

  it("publishes a complete template and starts suites from a copy of it", { timeout: EMBEDDED_POSTGRES_TEST_TIMEOUT_MS }, async () => {
    // This test covers the template path, so it enables the cache even when
    // the suite runs under PAPERCLIP_TEST_POSTGRES_TEMPLATE=0. The first
    // start then builds the template if the support probe did not.
    delete process.env.PAPERCLIP_TEST_POSTGRES_TEMPLATE;

    const database = await startEmbeddedPostgresTestDatabase("paperclip-template-copy-");
    try {
      expect(lastStartMode()).toBe("template");
      // The copy is fully migrated and independent of the template.
      const state = await inspectMigrations(database.connectionString);
      expect(state.status).toBe("upToDate");
      const sql = postgres(database.connectionString, { max: 1 });
      try {
        await sql`create table paperclip_template_copy_probe (id int)`;
      } finally {
        await sql.end();
      }
    } finally {
      await database.cleanup();
    }

    const rootDir = templateRootDir();
    const templateDir = path.join(rootDir, computeEmbeddedPostgresTemplateKey());
    expect(fs.existsSync(path.join(templateDir, "PG_VERSION"))).toBe(true);
    expect(fs.existsSync(path.join(templateDir, "postmaster.pid"))).toBe(false);
    expect(isUsableTemplate(templateDir)).toBe(true);
    if (process.platform !== "win32") {
      // The root is private to this user, and the template is a data
      // directory Postgres accepts: both are 0700.
      expect(path.basename(rootDir)).toBe(`paperclip-embedded-postgres-templates-${process.getuid?.()}`);
      expect(fs.statSync(rootDir).mode & 0o777).toBe(0o700);
      expect(fs.statSync(templateDir).mode & 0o777).toBe(0o700);
    }
    // Writing to the copy never touches the template, so a second copy does
    // not see the table.
    const second = await startEmbeddedPostgresTestDatabase("paperclip-template-copy-");
    try {
      expect(lastStartMode()).toBe("template");
      const sql = postgres(second.connectionString, { max: 1 });
      try {
        const rows = await sql`select to_regclass('paperclip_template_copy_probe') as name`;
        expect(rows[0]?.name).toBeNull();
      } finally {
        await sql.end();
      }
    } finally {
      await second.cleanup();
    }
  });

  it("refreshes the template's timestamp on every reuse so idle time drives pruning", { timeout: EMBEDDED_POSTGRES_TEST_TIMEOUT_MS }, async () => {
    delete process.env.PAPERCLIP_TEST_POSTGRES_TEMPLATE;
    // Make sure a template exists before ageing it: the support probe does
    // not publish one under PAPERCLIP_TEST_POSTGRES_TEMPLATE=0, and a name
    // filter can run this test on its own.
    resetTemplateState();
    const first = await startEmbeddedPostgresTestDatabase("paperclip-template-touch-");
    await first.cleanup();
    expect(lastStartMode()).toBe("template");
    const templateDir = path.join(templateRootDir(), computeEmbeddedPostgresTemplateKey());
    expect(isUsableTemplate(templateDir)).toBe(true);
    // Age the template as if it had not been used for ten days.
    const old = new Date(Date.now() - 10 * 24 * 60 * 60 * 1000);
    fs.utimesSync(templateDir, old, old);
    expect(fs.statSync(templateDir).mtimeMs).toBeLessThan(Date.now() - 9 * 24 * 60 * 60 * 1000);

    resetTemplateState();
    const database = await startEmbeddedPostgresTestDatabase("paperclip-template-touch-");
    try {
      expect(lastStartMode()).toBe("template");
    } finally {
      await database.cleanup();
    }
    expect(fs.statSync(templateDir).mtimeMs).toBeGreaterThan(Date.now() - 60 * 1000);
  });

  it("rebuilds the template when it was pruned after this process resolved it", { timeout: EMBEDDED_POSTGRES_TEST_TIMEOUT_MS }, async () => {
    delete process.env.PAPERCLIP_TEST_POSTGRES_TEMPLATE;
    const scratch = useScratchTmpdir("paperclip-template-pruned-");
    try {
      resetTemplateState();
      const first = await startEmbeddedPostgresTestDatabase("paperclip-template-pruned-copy-");
      await first.cleanup();
      expect(lastStartMode()).toBe("template");
      const templateDir = path.join(templateRootDir(), computeEmbeddedPostgresTemplateKey());
      expect(isUsableTemplate(templateDir)).toBe(true);

      // Another process prunes the template while this one still holds its path.
      fs.rmSync(templateDir, { recursive: true, force: true });
      const second = await startEmbeddedPostgresTestDatabase("paperclip-template-pruned-copy-");
      await second.cleanup();
      // This start fell back without retrying the missing path; the fallback
      // forgot the stale path, so the next start rebuilt the template.
      expect(lastStartMode()).toBe("fresh");
      const third = await startEmbeddedPostgresTestDatabase("paperclip-template-pruned-copy-");
      await third.cleanup();
      expect(lastStartMode()).toBe("template");
      expect(isUsableTemplate(templateDir)).toBe(true);
    } finally {
      scratch.restore();
    }
  });

  it("runs the fresh initdb path when PAPERCLIP_TEST_POSTGRES_TEMPLATE=0", { timeout: EMBEDDED_POSTGRES_TEST_TIMEOUT_MS }, async () => {
    process.env.PAPERCLIP_TEST_POSTGRES_TEMPLATE = "0";
    const database = await startEmbeddedPostgresTestDatabase("paperclip-template-bypass-");
    try {
      expect(lastStartMode()).toBe("fresh");
      const state = await inspectMigrations(database.connectionString);
      expect(state.status).toBe("upToDate");
    } finally {
      await database.cleanup();
    }
  });

  describeOnPosix("cache root safety", () => {
    it("uses fresh clusters when the cache root is not a private directory of this user", { timeout: EMBEDDED_POSTGRES_TEST_TIMEOUT_MS }, async () => {
      delete process.env.PAPERCLIP_TEST_POSTGRES_TEMPLATE;
      const scratch = useScratchTmpdir("paperclip-template-root-");
      const warnings: string[] = [];
      const warn = console.warn;
      console.warn = (...args: unknown[]) => {
        warnings.push(args.map(String).join(" "));
      };
      try {
        // Someone pre-created the predictable root path, world-writable, the
        // way a foreign user on a shared host would.
        const rootDir = templateRootDir();
        expect(rootDir.startsWith(scratch.scratch)).toBe(true);
        fs.mkdirSync(rootDir);
        fs.chmodSync(rootDir, 0o777);

        resetTemplateState();
        const database = await startEmbeddedPostgresTestDatabase("paperclip-template-root-copy-");
        try {
          expect(lastStartMode()).toBe("fresh");
        } finally {
          await database.cleanup();
        }
        // Nothing was published into the rejected root, and the reason was logged once.
        expect(fs.readdirSync(rootDir)).toEqual([]);
        expect(warnings.filter((line) => line.includes("template cache root"))).toHaveLength(1);
        expect(warnings[0]).toContain("writable by group or others");

        // The probe still reports support, from the throwaway cluster.
        resetTemplateState();
        expect(await getEmbeddedPostgresTestSupport()).toEqual({ supported: true });
      } finally {
        console.warn = warn;
        scratch.restore();
      }
    });

    it("uses fresh clusters when the cache root path is a symbolic link", { timeout: EMBEDDED_POSTGRES_TEST_TIMEOUT_MS }, async () => {
      delete process.env.PAPERCLIP_TEST_POSTGRES_TEMPLATE;
      const scratch = useScratchTmpdir("paperclip-template-root-");
      const warn = console.warn;
      console.warn = () => {};
      try {
        const target = path.join(scratch.scratch, "elsewhere");
        fs.mkdirSync(target, { mode: 0o700 });
        fs.symlinkSync(target, templateRootDir(), "dir");

        resetTemplateState();
        const database = await startEmbeddedPostgresTestDatabase("paperclip-template-root-copy-");
        try {
          expect(lastStartMode()).toBe("fresh");
        } finally {
          await database.cleanup();
        }
        expect(fs.readdirSync(target)).toEqual([]);
      } finally {
        console.warn = warn;
        scratch.restore();
      }
    });
  });
});

describe("support probe when the template cannot be built", () => {
  afterEach(() => {
    __setEmbeddedPostgresCtorProviderForTests(null);
    resetTemplateState();
  });

  it("falls through to the fresh probe instead of reporting the host as unsupported", { timeout: EMBEDDED_POSTGRES_TEST_TIMEOUT_MS }, async () => {
    const originalTemplateSetting = process.env.PAPERCLIP_TEST_POSTGRES_TEMPLATE;
    delete process.env.PAPERCLIP_TEST_POSTGRES_TEMPLATE;
    const scratch = useScratchTmpdir("paperclip-template-build-fail-");
    const warnings: string[] = [];
    const warn = console.warn;
    console.warn = (...args: unknown[]) => {
      warnings.push(args.map(String).join(" "));
    };
    try {
      // This test runs on every platform, so check the redirect took effect
      // before asserting on paths under it.
      expect(os.tmpdir()).toBe(scratch.scratch);
      // The fake cluster "starts" without listening, so the template build
      // fails after the start, at the migration step, the way a broken
      // migration would. A real broken migration then fails the suite on
      // the fresh path instead of being hidden by `describe.skip`.
      const { ctor, constructed } = makeFakeCtor(0);
      __setEmbeddedPostgresCtorProviderForTests(async () => ctor);
      resetTemplateState();

      expect(await getEmbeddedPostgresTestSupport()).toEqual({ supported: true });
      // One build attempt, then the throwaway probe, both under the scratch root.
      expect(constructed).toHaveLength(2);
      for (const options of constructed) expect(options.databaseDir.startsWith(scratch.scratch)).toBe(true);
      expect(constructed[0]?.databaseDir).toContain("paperclip-embedded-postgres-template-build-");
      expect(constructed[1]?.databaseDir).toContain("paperclip-embedded-postgres-probe-");
      expect(warnings.filter((line) => line.includes("template build failed"))).toHaveLength(1);
      // Nothing was published.
      const rootDir = templateRootDir();
      expect(fs.existsSync(rootDir) ? fs.readdirSync(rootDir) : []).toEqual([]);
    } finally {
      console.warn = warn;
      scratch.restore();
      if (originalTemplateSetting === undefined) delete process.env.PAPERCLIP_TEST_POSTGRES_TEMPLATE;
      else process.env.PAPERCLIP_TEST_POSTGRES_TEMPLATE = originalTemplateSetting;
    }
  });
});