postgresai 0.15.0-rc.2 → 0.15.0-rc.4

package/lib/instances.ts

@@ -0,0 +1,245 @@
+/**
+ * Helpers for managing instances.yml (the pgwatch monitoring target list)
+ * and for opening pg connections that honor libpq sslmode semantics.
+ *
+ * These helpers exist as a single source of truth so that `mon targets
+ * add/remove/test` and `mon local-install` (which has its own inline copies
+ * of the same logic) stay consistent — and so unit tests exercise the same
+ * code path the CLI actually runs.
+ */
+
+import * as fs from "fs";
+import * as yaml from "js-yaml";
+import { parse as parseConnString } from "pg-connection-string";
+import type { ClientConfig } from "pg";
+
+export interface Instance {
+  name: string;
+  conn_str?: string;
+  preset_metrics?: string;
+  custom_metrics?: any;
+  is_enabled?: boolean;
+  group?: string;
+  custom_tags?: Record<string, any>;
+}
+
+export class InstancesParseError extends Error {
+  constructor(file: string, cause: unknown) {
+    const causeMsg = cause instanceof Error ? cause.message : String(cause);
+    super(`Failed to parse ${file}: ${causeMsg}`);
+    this.name = "InstancesParseError";
+  }
+}
+
+/**
+ * Read instances.yml as an array of Instance.
+ *
+ * Returns `[]` for a missing/empty file (this is normal — fresh installs and
+ * just-after-`remove` states). Throws InstancesParseError on a corrupted file
+ * so callers can surface the corruption to the user instead of silently
+ * overwriting it (the previous append-text behavior could erase several
+ * targets — including their conn_strs with credentials — if the file had a
+ * partial write or hand-edit problem).
+ */
+export function loadInstances(file: string): Instance[] {
+  if (!fs.existsSync(file)) return [];
+  if (fs.lstatSync(file).isDirectory()) return [];
+  const text = fs.readFileSync(file, "utf8");
+  if (text.trim() === "") return [];
+  let parsed: unknown;
+  try {
+    parsed = yaml.load(text);
+  } catch (err) {
+    throw new InstancesParseError(file, err);
+  }
+  if (parsed === null || parsed === undefined) return [];
+  if (!Array.isArray(parsed)) {
+    throw new InstancesParseError(file, "expected a YAML list at the document root");
+  }
+  return parsed as Instance[];
+}
+
+export function buildInstance(name: string, connStr: string): Instance {
+  return {
+    name,
+    conn_str: connStr,
+    preset_metrics: "full",
+    custom_metrics: null,
+    is_enabled: true,
+    group: "default",
+    custom_tags: {
+      env: "production",
+      cluster: "default",
+      node_name: name,
+      // Sed-substituted placeholder by config/scripts/generate-pgwatch-sources.sh.
+      // js-yaml emits this unquoted on dump (~ is only special at the start of a
+      // scalar in the right context); sed s/~sink_type~/.../g still hits it as
+      // raw text regardless.
+      sink_type: "~sink_type~",
+    },
+  };
+}
+
+/**
+ * Parse → mutate → serialize: load existing list, append, dump back.
+ *
+ * Replaces the previous text-append code path which corrupted instances.yml
+ * after `remove` had left the empty marker `[]` in the file (the append
+ * produced two YAML documents in one file → parse error on every subsequent
+ * read).
+ *
+ * Replaces files where the previous code path treated the directory created
+ * by Docker's bind-mount-into-missing-path as a target.
+ */
+export function addInstanceToFile(file: string, instance: Instance): void {
+  if (fs.existsSync(file) && fs.lstatSync(file).isDirectory()) {
+    fs.rmSync(file, { recursive: true, force: true });
+  }
+  const existing = loadInstances(file);
+  if (existing.some((i) => i.name === instance.name)) {
+    throw new Error(`Monitoring target '${instance.name}' already exists`);
+  }
+  existing.push(instance);
+  fs.writeFileSync(file, yaml.dump(existing), "utf8");
+}
+
+/**
+ * Remove a named instance from the file. Returns true if removed.
+ */
+export function removeInstanceFromFile(file: string, name: string): boolean {
+  const instances = loadInstances(file);
+  const filtered = instances.filter((i) => i.name !== name);
+  if (filtered.length === instances.length) return false;
+  fs.writeFileSync(file, yaml.dump(filtered), "utf8");
+  return true;
+}
+
+/**
+ * Extract `sslmode` (lowercased) from a postgresql:// URL. Returns `""` for
+ * unset or unparseable.
+ */
+export function extractSslmode(connStr: string): string {
+  try {
+    return (new URL(connStr).searchParams.get("sslmode") || "").toLowerCase();
+  } catch {
+    return "";
+  }
+}
+
+/**
+ * Map libpq sslmode values to node-postgres' `ssl` option.
+ *
+ * libpq:                     node-postgres ssl:
+ *   disable                    false
+ *   allow / prefer / require   { rejectUnauthorized: false }   (encrypt, no chain check)
+ *   verify-ca                  { rejectUnauthorized: true, checkServerIdentity: () => undefined }
+ *   verify-full                { rejectUnauthorized: true }
+ *   no-verify (pg extension)   { rejectUnauthorized: false }
+ *
+ * Default for unset: prefer-like → no chain verification, matches what
+ * pgwatch (Go pgx) does and what users pass to psql every day.
+ */
+export type SslOption = false | { rejectUnauthorized: boolean; checkServerIdentity?: () => undefined };
+
+export function sslOptionFromConnString(connStr: string): SslOption {
+  return sslOptionFromSslmode(extractSslmode(connStr));
+}
+
+function sslOptionFromSslmode(sslmode: string): SslOption {
+  switch (sslmode) {
+    case "disable":
+      return false;
+    case "verify-ca":
+      return { rejectUnauthorized: true, checkServerIdentity: () => undefined };
+    case "verify-full":
+      return { rejectUnauthorized: true };
+    case "allow":
+    case "prefer":
+    case "require":
+    case "no-verify":
+    case "":
+    default:
+      return { rejectUnauthorized: false };
+  }
+}
+
+/**
+ * The set of sslmode values for which we DO NOT verify the certificate chain.
+ * Exposed so callers can warn users about the lax security posture.
+ */
+export const LAX_SSLMODES = new Set(["", "allow", "prefer", "require"]);
+
+export function isLaxSslmode(sslmode: string): boolean {
+  return LAX_SSLMODES.has(sslmode);
+}
+
+/**
+ * Print a stderr warning when the connection string uses an sslmode that
+ * skips certificate-chain verification. Centralises the message so the
+ * three Client-construction sites stay consistent.
+ */
+export function warnIfLaxSslmode(connStr: string): void {
+  const sslmode = extractSslmode(connStr);
+  if (!isLaxSslmode(sslmode)) return;
+  const shown = sslmode || "(unset)";
+  console.error(
+    `⚠ sslmode=${shown}: TLS chain is NOT verified (matches libpq/psql semantics). ` +
+      `Use sslmode=verify-full for full chain+hostname verification.`,
+  );
+}
+
+/**
+ * Build a `pg.Client` config from a connection string that ACTUALLY honors
+ * libpq sslmode semantics.
+ *
+ * This is non-trivial because node-postgres' `Client` constructor, given a
+ * `connectionString`, runs `Object.assign({}, config, parse(connectionString))`
+ * — meaning the parsed sslmode-derived `ssl` value REPLACES any explicit
+ * `ssl` you passed alongside `connectionString`. So setting
+ * `{ connectionString, ssl: { rejectUnauthorized: false } }` does not work
+ * when the URL contains `sslmode=require` (the parsed value `{}` wins, and
+ * `{}` defaults to chain verification → "self-signed certificate in
+ * certificate chain" against managed Postgres).
+ *
+ * The fix: parse the URL ourselves, pass discrete host/port/user/etc., and
+ * include our explicit `ssl` — never pass `connectionString` so nothing
+ * overrides us.
+ *
+ * We strip `sslmode` from the URL before handing it to `pg-connection-string`'s
+ * `parse()` so that:
+ *   1. its `process.emitWarning("SECURITY WARNING: SSL modes 'prefer'/'require'/
+ *      'verify-ca' are treated as aliases for 'verify-full'…")` doesn't fire
+ *      on every CLI invocation against a Supabase-shaped URL, and
+ *   2. its `verify-ca` compatibility branch doesn't *throw* on us (requires
+ *      sslrootcert which we don't have).
+ *
+ * We don't use the parser's `ssl` output anyway — we compute our own from
+ * `sslOptionFromSslmode(extractSslmode(originalConnStr))` — so removing the
+ * sslmode parameter before parsing is a no-op for the fields we actually use.
+ */
+export function buildClientConfig(
+  connStr: string,
+  extra: { connectionTimeoutMillis?: number } = {},
+): ClientConfig {
+  const sslmode = extractSslmode(connStr);
+  const parsed = parseConnString(withoutSslmode(connStr));
+  return {
+    host: parsed.host || undefined,
+    port: parsed.port ? Number(parsed.port) : undefined,
+    user: parsed.user,
+    password: parsed.password,
+    database: parsed.database || undefined,
+    ssl: sslOptionFromSslmode(sslmode),
+    ...extra,
+  };
+}
+
+function withoutSslmode(connStr: string): string {
+  try {
+    const u = new URL(connStr);
+    u.searchParams.delete("sslmode");
+    return u.toString();
+  } catch {
+    return connStr;
+  }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "postgresai",
-  "version": "0.15.0-rc.2",
+  "version": "0.15.0-rc.4",
   "description": "postgres_ai CLI",
   "license": "Apache-2.0",
   "private": false,

package/test/monitoring.test.ts

@@ -2,6 +2,20 @@ import { describe, test, expect, beforeEach, afterEach, mock, spyOn } from "bun:
 import * as fs from "fs";
 import * as path from "path";
 import * as os from "os";
+import * as yaml from "js-yaml";
+import { Client } from "pg";
+import {
+  addInstanceToFile,
+  removeInstanceFromFile,
+  loadInstances,
+  buildInstance,
+  buildClientConfig,
+  sslOptionFromConnString,
+  warnIfLaxSslmode,
+  isLaxSslmode,
+  extractSslmode,
+  InstancesParseError,
+} from "../lib/instances";
 
 /**
  * Test updatePgwatchConfig function behavior.
@@ -337,3 +351,266 @@ describe("demo mode instances.demo.yml", () => {
     }
   });
 });
+
+describe("docker-compose: default network has IPv6 enabled", () => {
+  const repoRoot = path.resolve(import.meta.dir, "..", "..");
+
+  test("root docker-compose.yml declares networks.default with enable_ipv6", () => {
+    const composePath = path.join(repoRoot, "docker-compose.yml");
+    const content = fs.readFileSync(composePath, "utf8");
+
+    // Use string match so we also catch the env-overridable form
+    // `enable_ipv6: ${PGAI_ENABLE_IPV6:-true}`, which Compose interpolates
+    // before the YAML strict-bool check.
+    expect(content).toMatch(/^networks:/m);
+    expect(content).toMatch(/^\s*default:/m);
+    expect(content).toMatch(/enable_ipv6:\s*(true|\$\{PGAI_ENABLE_IPV6:-true\})/);
+
+    // Also assert the YAML is parseable (catches indentation regressions).
+    const parsed = yaml.load(content) as any;
+    expect(parsed?.networks?.default).toBeDefined();
+  });
+
+  test("env override default resolves to 'true' when PGAI_ENABLE_IPV6 is unset", () => {
+    // Mirror Compose's `${VAR:-default}` interpolation rule. Verifies that the
+    // template's default value matches the documented one.
+    const composePath = path.join(repoRoot, "docker-compose.yml");
+    const content = fs.readFileSync(composePath, "utf8");
+    const m = content.match(/enable_ipv6:\s*\$\{PGAI_ENABLE_IPV6:-(\w+)\}/);
+    expect(m).not.toBeNull();
+    expect(m![1]).toBe("true");
+  });
+});
+
+describe("addInstanceToFile / removeInstanceFromFile round-trip", () => {
+  let tempDir: string;
+  let instancesFile: string;
+
+  beforeEach(() => {
+    tempDir = fs.mkdtempSync(path.join(os.tmpdir(), "instances-test-"));
+    instancesFile = path.join(tempDir, "instances.yml");
+  });
+
+  afterEach(() => {
+    if (tempDir && fs.existsSync(tempDir)) {
+      fs.rmSync(tempDir, { recursive: true, force: true });
+    }
+  });
+
+  test("add to empty file produces a valid YAML list", () => {
+    addInstanceToFile(instancesFile, buildInstance("t1", "postgresql://u:p@h:5432/db"));
+    const list = loadInstances(instancesFile);
+    expect(list.length).toBe(1);
+    expect(list[0].name).toBe("t1");
+  });
+
+  test("add → remove → add cycle keeps file parseable (regression)", () => {
+    // The previous bug: after `remove` left `[]` in the file, `add` appended a
+    // list-item next to it, producing two YAML documents in one file.
+    addInstanceToFile(instancesFile, buildInstance("t1", "postgresql://u:p@h:5432/db"));
+    removeInstanceFromFile(instancesFile, "t1");
+    expect(loadInstances(instancesFile)).toEqual([]);
+
+    addInstanceToFile(instancesFile, buildInstance("t2", "postgresql://u:p@h:5432/db2"));
+
+    // Must NOT throw "end of the stream or a document separator is expected".
+    const list = loadInstances(instancesFile);
+    expect(list.length).toBe(1);
+    expect(list[0].name).toBe("t2");
+  });
+
+  test("sink_type placeholder survives the round-trip", () => {
+    addInstanceToFile(instancesFile, buildInstance("t1", "postgresql://u:p@h:5432/db"));
+    const content = fs.readFileSync(instancesFile, "utf8");
+    // js-yaml emits ~sink_type~ unquoted (it's only special when standalone);
+    // sed s/~sink_type~/.../g still hits it as raw text regardless.
+    expect(content).toContain("~sink_type~");
+  });
+
+  test("add throws InstancesParseError on a corrupted file (no silent overwrite)", () => {
+    // Silent overwrite would discard credentials in conn_str values. Refuse.
+    fs.writeFileSync(instancesFile, "key: [unclosed\nfoo: bar\n", "utf8");
+
+    expect(() =>
+      addInstanceToFile(instancesFile, buildInstance("t1", "postgresql://u:p@h:5432/db")),
+    ).toThrow(InstancesParseError);
+
+    // File contents are unchanged.
+    expect(fs.readFileSync(instancesFile, "utf8")).toBe("key: [unclosed\nfoo: bar\n");
+  });
+
+  test("add rejects duplicate name", () => {
+    addInstanceToFile(instancesFile, buildInstance("t1", "postgresql://u:p@h:5432/db"));
+    expect(() =>
+      addInstanceToFile(instancesFile, buildInstance("t1", "postgresql://u:p@h:5432/db")),
+    ).toThrow(/already exists/);
+  });
+
+  test("add replaces a directory at the target path (Docker bind-mount artifact)", () => {
+    fs.mkdirSync(instancesFile);
+    expect(fs.statSync(instancesFile).isDirectory()).toBe(true);
+    addInstanceToFile(instancesFile, buildInstance("t1", "postgresql://u:p@h:5432/db"));
+    expect(fs.statSync(instancesFile).isFile()).toBe(true);
+    expect(loadInstances(instancesFile).length).toBe(1);
+  });
+});
+
+describe("sslOptionFromConnString — libpq semantics", () => {
+  test("sslmode=require → SSL without chain verification", () => {
+    expect(sslOptionFromConnString("postgresql://u:p@h/db?sslmode=require"))
+      .toEqual({ rejectUnauthorized: false });
+  });
+
+  test("sslmode unset → SSL without chain verification", () => {
+    expect(sslOptionFromConnString("postgresql://u:p@h/db"))
+      .toEqual({ rejectUnauthorized: false });
+  });
+
+  test("sslmode=disable → no SSL", () => {
+    expect(sslOptionFromConnString("postgresql://u:p@h/db?sslmode=disable")).toBe(false);
+  });
+
+  test("sslmode=verify-ca → chain verification, no hostname check", () => {
+    const opt = sslOptionFromConnString("postgresql://u:p@h/db?sslmode=verify-ca");
+    expect(opt).toMatchObject({ rejectUnauthorized: true });
+    expect(typeof (opt as any).checkServerIdentity).toBe("function");
+  });
+
+  test("sslmode=verify-full → chain + hostname verification", () => {
+    expect(sslOptionFromConnString("postgresql://u:p@h/db?sslmode=verify-full"))
+      .toEqual({ rejectUnauthorized: true });
+  });
+
+  test("sslmode=prefer → SSL without chain verification", () => {
+    expect(sslOptionFromConnString("postgresql://u:p@h/db?sslmode=prefer"))
+      .toEqual({ rejectUnauthorized: false });
+  });
+
+  test("malformed connection string → safe default (no chain verification)", () => {
+    expect(sslOptionFromConnString("not-a-url")).toEqual({ rejectUnauthorized: false });
+  });
+});
+
+describe("buildClientConfig — actual node-postgres Client gets the intended ssl (regression)", () => {
+  // The previous code passed `{ connectionString, ssl }` to `new Client(...)`.
+  // node-postgres' ConnectionParameters internally does
+  // `Object.assign({}, config, parse(connectionString))`, so the parsed
+  // `connectionString.ssl` REPLACES the explicit `ssl`. Net effect:
+  //   `?sslmode=require` + `ssl: { rejectUnauthorized: false }` → `ssl: {}`
+  //                                                              (chain verified)
+  // — exactly the bug the MR claims to fix. This integration test asserts
+  // against `client.connectionParameters.ssl`, so the bug cannot return.
+
+  test("require: actual Client.connectionParameters.ssl has rejectUnauthorized:false", () => {
+    const c = new Client(buildClientConfig("postgresql://u:p@h/db?sslmode=require"));
+    expect(c.connectionParameters.ssl).toEqual({ rejectUnauthorized: false });
+  });
+
+  test("verify-full: actual Client.connectionParameters.ssl has rejectUnauthorized:true", () => {
+    const c = new Client(buildClientConfig("postgresql://u:p@h/db?sslmode=verify-full"));
+    expect(c.connectionParameters.ssl).toEqual({ rejectUnauthorized: true });
+  });
+
+  test("disable: actual Client.connectionParameters.ssl is false", () => {
+    const c = new Client(buildClientConfig("postgresql://u:p@h/db?sslmode=disable"));
+    expect(c.connectionParameters.ssl).toBe(false);
+  });
+
+  test("unset: actual Client.connectionParameters.ssl has rejectUnauthorized:false", () => {
+    const c = new Client(buildClientConfig("postgresql://u:p@h/db"));
+    expect(c.connectionParameters.ssl).toEqual({ rejectUnauthorized: false });
+  });
+
+  test("connectionTimeoutMillis is forwarded (exact value, not just truthy)", () => {
+    const c = new Client(buildClientConfig("postgresql://u:p@h/db?sslmode=require", { connectionTimeoutMillis: 5000 }));
+    // node-postgres v8 stores it on `_connectionTimeoutMillis`. Asserting the
+    // exact value catches regressions that would silently swap in the default.
+    expect((c as any)._connectionTimeoutMillis).toBe(5000);
+  });
+});
+
+describe("warnIfLaxSslmode — UX warning for lax sslmode", () => {
+  let stderrSpy: ReturnType<typeof spyOn>;
+
+  beforeEach(() => {
+    stderrSpy = spyOn(console, "error").mockImplementation(() => {});
+  });
+
+  afterEach(() => {
+    stderrSpy.mockRestore();
+  });
+
+  for (const sslmode of ["require", "prefer", "allow"]) {
+    test(`warns when sslmode=${sslmode}`, () => {
+      warnIfLaxSslmode(`postgresql://u:p@h/db?sslmode=${sslmode}`);
+      expect(stderrSpy).toHaveBeenCalledTimes(1);
+      const msg = String(stderrSpy.mock.calls[0][0]);
+      expect(msg).toContain(`sslmode=${sslmode}`);
+      expect(msg).toContain("NOT verified");
+      expect(msg).toContain("verify-full");
+    });
+  }
+
+  test("warns when sslmode is unset (uses '(unset)' label)", () => {
+    warnIfLaxSslmode("postgresql://u:p@h/db");
+    expect(stderrSpy).toHaveBeenCalledTimes(1);
+    expect(String(stderrSpy.mock.calls[0][0])).toContain("sslmode=(unset)");
+  });
+
+  test("does NOT warn when sslmode=verify-full or verify-ca or disable", () => {
+    warnIfLaxSslmode("postgresql://u:p@h/db?sslmode=verify-full");
+    warnIfLaxSslmode("postgresql://u:p@h/db?sslmode=verify-ca");
+    warnIfLaxSslmode("postgresql://u:p@h/db?sslmode=disable");
+    expect(stderrSpy).not.toHaveBeenCalled();
+  });
+});
+
+describe("buildClientConfig — silences pg-connection-string deprecation warning", () => {
+  // pg-connection-string v2.x prints `process.emitWarning("SECURITY WARNING:
+  // ... 'prefer'/'require'/'verify-ca' ...")` whenever a recognised lax
+  // sslmode appears. Without our `uselibpqcompat=true` shim, this would fire
+  // on every CLI invocation against a Supabase-shaped URL. Assert it doesn't.
+
+  let warnings: string[];
+  let origEmitWarning: typeof process.emitWarning;
+
+  beforeEach(() => {
+    warnings = [];
+    origEmitWarning = process.emitWarning;
+    (process as any).emitWarning = (warning: any) => {
+      warnings.push(typeof warning === "string" ? warning : String(warning));
+    };
+  });
+
+  afterEach(() => {
+    (process as any).emitWarning = origEmitWarning;
+  });
+
+  for (const sslmode of ["require", "prefer", "verify-ca"]) {
+    test(`no SECURITY WARNING for sslmode=${sslmode}`, () => {
+      buildClientConfig(`postgresql://u:p@h/db?sslmode=${sslmode}`);
+      const security = warnings.filter((w) => w.includes("SECURITY"));
+      expect(security).toEqual([]);
+    });
+  }
+});
+
+describe("extractSslmode / isLaxSslmode", () => {
+  test("extractSslmode returns lowercase", () => {
+    expect(extractSslmode("postgresql://u:p@h/db?sslmode=REQUIRE")).toBe("require");
+  });
+
+  test("extractSslmode returns '' for unparseable URLs", () => {
+    expect(extractSslmode("not-a-url")).toBe("");
+  });
+
+  test("isLaxSslmode covers the full set", () => {
+    expect(isLaxSslmode("")).toBe(true);
+    expect(isLaxSslmode("require")).toBe(true);
+    expect(isLaxSslmode("prefer")).toBe(true);
+    expect(isLaxSslmode("allow")).toBe(true);
+    expect(isLaxSslmode("verify-ca")).toBe(false);
+    expect(isLaxSslmode("verify-full")).toBe(false);
+    expect(isLaxSslmode("disable")).toBe(false);
+  });
+});