@supabase/pg-delta 1.0.0-alpha.13 → 1.0.0-alpha.15

package/src/core/postgres-config.test.ts

@@ -0,0 +1,241 @@
+import { describe, expect, test } from "bun:test";
+import {
+  connectWithRetry,
+  isRetryableConnectError,
+} from "./postgres-config.ts";
+
+function makeError(message: string, code?: string): Error {
+  const err = new Error(message) as Error & { code?: string };
+  if (code !== undefined) err.code = code;
+  return err;
+}
+
+describe("isRetryableConnectError", () => {
+  describe("non-retryable", () => {
+    test("PG auth code 28P01", () => {
+      expect(
+        isRetryableConnectError(makeError("password auth failed", "28P01")),
+      ).toBe(false);
+    });
+
+    test("PG auth code 28000", () => {
+      expect(
+        isRetryableConnectError(
+          makeError("invalid authorization specification", "28000"),
+        ),
+      ).toBe(false);
+    });
+
+    test("ENOTFOUND (permanent DNS failure)", () => {
+      expect(
+        isRetryableConnectError(
+          makeError("getaddrinfo ENOTFOUND bogus.host", "ENOTFOUND"),
+        ),
+      ).toBe(false);
+    });
+
+    test("TLS error via code (ERR_TLS_*)", () => {
+      expect(
+        isRetryableConnectError(
+          makeError("TLS failure", "ERR_TLS_CERT_ALTNAME_INVALID"),
+        ),
+      ).toBe(false);
+    });
+
+    test("TLS error via message marker", () => {
+      expect(
+        isRetryableConnectError(
+          makeError("self-signed certificate in certificate chain"),
+        ),
+      ).toBe(false);
+    });
+
+    test("SSL error via message marker", () => {
+      expect(
+        isRetryableConnectError(
+          makeError("SSL connection has been closed unexpectedly"),
+        ),
+      ).toBe(false);
+    });
+  });
+
+  describe("retryable", () => {
+    test("ECONNRESET", () => {
+      expect(
+        isRetryableConnectError(makeError("socket hang up", "ECONNRESET")),
+      ).toBe(true);
+    });
+
+    test("ECONNREFUSED", () => {
+      expect(
+        isRetryableConnectError(
+          makeError("connect ECONNREFUSED", "ECONNREFUSED"),
+        ),
+      ).toBe(true);
+    });
+
+    test("ETIMEDOUT", () => {
+      expect(
+        isRetryableConnectError(makeError("connect ETIMEDOUT", "ETIMEDOUT")),
+      ).toBe(true);
+    });
+
+    test("EAI_AGAIN (transient DNS)", () => {
+      expect(
+        isRetryableConnectError(
+          makeError("getaddrinfo EAI_AGAIN db.host", "EAI_AGAIN"),
+        ),
+      ).toBe(true);
+    });
+
+    test("our own eager-connect timeout wrapper", () => {
+      expect(
+        isRetryableConnectError(
+          new Error(
+            "Connection to target database timed out after 2500ms. " +
+              "The server may require SSL, use an invalid certificate, or be unreachable.",
+          ),
+        ),
+      ).toBe(true);
+    });
+
+    test("unknown generic Error is transient-by-default", () => {
+      expect(isRetryableConnectError(new Error("something weird"))).toBe(true);
+    });
+
+    test("non-Error values are transient-by-default", () => {
+      expect(isRetryableConnectError("string error")).toBe(true);
+      expect(isRetryableConnectError({ reason: "x" })).toBe(true);
+      expect(isRetryableConnectError(undefined)).toBe(true);
+    });
+  });
+});
+
+describe("connectWithRetry", () => {
+  const noSleep = async (_ms: number) => {
+    // no-op sleep to keep tests fast
+  };
+
+  test("resolves on first attempt without retrying", async () => {
+    let attempts = 0;
+    const result = await connectWithRetry({
+      connect: async () => {
+        attempts++;
+        return "ok" as const;
+      },
+      sleep: noSleep,
+    });
+    expect(result).toBe("ok");
+    expect(attempts).toBe(1);
+  });
+
+  test("retries a retryable error until success", async () => {
+    let attempts = 0;
+    const result = await connectWithRetry({
+      connect: async () => {
+        attempts++;
+        if (attempts < 3) {
+          throw makeError("connect ECONNREFUSED", "ECONNREFUSED");
+        }
+        return "ok" as const;
+      },
+      maxAttempts: 5,
+      sleep: noSleep,
+    });
+    expect(result).toBe("ok");
+    expect(attempts).toBe(3);
+  });
+
+  test("honours maxAttempts and throws the last error", async () => {
+    let attempts = 0;
+    const boom = makeError("connect ECONNREFUSED", "ECONNREFUSED");
+    await expect(
+      connectWithRetry({
+        connect: async () => {
+          attempts++;
+          throw boom;
+        },
+        maxAttempts: 4,
+        sleep: noSleep,
+      }),
+    ).rejects.toBe(boom);
+    expect(attempts).toBe(4);
+  });
+
+  test("stops immediately on a non-retryable error", async () => {
+    let attempts = 0;
+    const authError = makeError("password authentication failed", "28P01");
+    await expect(
+      connectWithRetry({
+        connect: async () => {
+          attempts++;
+          throw authError;
+        },
+        maxAttempts: 10,
+        sleep: noSleep,
+      }),
+    ).rejects.toBe(authError);
+    expect(attempts).toBe(1);
+  });
+
+  test("uses exponential backoff: 250ms, 500ms (3 attempts)", async () => {
+    const delays: number[] = [];
+    let attempts = 0;
+    await expect(
+      connectWithRetry({
+        connect: async () => {
+          attempts++;
+          throw makeError("connect ECONNREFUSED", "ECONNREFUSED");
+        },
+        maxAttempts: 3,
+        baseBackoffMs: 250,
+        maxBackoffMs: 1000,
+        sleep: async (ms) => {
+          delays.push(ms);
+        },
+      }),
+    ).rejects.toBeDefined();
+    expect(attempts).toBe(3);
+    // Sleep is invoked once after attempt 1 and once after attempt 2;
+    // the final failure throws without sleeping.
+    expect(delays).toEqual([250, 500]);
+  });
+
+  test("caps backoff at maxBackoffMs", async () => {
+    const delays: number[] = [];
+    await expect(
+      connectWithRetry({
+        connect: async () => {
+          throw makeError("connect ECONNREFUSED", "ECONNREFUSED");
+        },
+        maxAttempts: 5,
+        baseBackoffMs: 250,
+        maxBackoffMs: 600,
+        sleep: async (ms) => {
+          delays.push(ms);
+        },
+      }),
+    ).rejects.toBeDefined();
+    // Uncapped would be [250, 500, 1000, 2000]; the 1000/2000 values are
+    // both capped to 600.
+    expect(delays).toEqual([250, 500, 600, 600]);
+  });
+
+  test("injected isRetryable overrides the default predicate", async () => {
+    let attempts = 0;
+    const err = new Error("custom transient");
+    const neverRetry = () => false;
+    await expect(
+      connectWithRetry({
+        connect: async () => {
+          attempts++;
+          throw err;
+        },
+        maxAttempts: 5,
+        isRetryable: neverRetry,
+        sleep: noSleep,
+      }),
+    ).rejects.toBe(err);
+    expect(attempts).toBe(1);
+  });
+});

package/src/core/postgres-config.ts

@@ -4,6 +4,7 @@
 
 import type { ClientBase, PoolClient, PoolConfig } from "pg";
 import { escapeIdentifier, Pool, types } from "pg";
+import { normalizeConnectionUrl } from "./connection-url.ts";
 import { parseSslConfig } from "./plan/ssl-config.ts";
 
 // ============================================================================
@@ -109,6 +110,104 @@ const DEFAULT_CONNECTION_TIMEOUT_MS =
   Number(process.env.PGDELTA_CONNECTION_TIMEOUT_MS) || 3_000;
 const DEFAULT_CONNECT_TIMEOUT_MS =
   Number(process.env.PGDELTA_CONNECT_TIMEOUT_MS) || 2_500;
+const DEFAULT_CONNECT_MAX_ATTEMPTS =
+  Number(process.env.PGDELTA_CONNECT_MAX_ATTEMPTS) || 3;
+const DEFAULT_CONNECT_BASE_BACKOFF_MS =
+  Number(process.env.PGDELTA_CONNECT_BASE_BACKOFF_MS) || 250;
+const DEFAULT_CONNECT_MAX_BACKOFF_MS =
+  Number(process.env.PGDELTA_CONNECT_MAX_BACKOFF_MS) || 1_000;
+
+// PostgreSQL auth-class SQLSTATE codes: not retryable.
+const NON_RETRYABLE_PG_CODES = new Set([
+  "28000", // invalid_authorization_specification
+  "28P01", // invalid_password
+  "28P02", // pgdelta: alias reserved here to future-proof against new auth codes
+]);
+
+// Non-retryable TLS/SSL markers. The `pg` driver surfaces TLS failures as
+// either plain Node `Error` instances with a code on `ERR_TLS_*` or error
+// messages that include well-known cert/TLS terminology; we match both
+// because node-pg normalises some of these.
+const TLS_MESSAGE_MARKERS = [
+  "self-signed certificate",
+  "self signed certificate",
+  "unable to verify the first certificate",
+  "certificate has expired",
+  "tls",
+  "ssl",
+];
+
+/**
+ * Return true when `err` represents a transient connect failure that makes
+ * sense to retry with backoff (e.g. refused connections, DNS blips, our own
+ * eager-connect timeout wrapper). Returns false for permanent failures such
+ * as authentication errors, TLS negotiation errors, and `ENOTFOUND`.
+ *
+ * Unknown errors are treated as retryable on purpose: transient-by-default
+ * is safer here because a duplicated retry is strictly cheaper than a spurious
+ * hard failure during catalog extraction.
+ */
+export function isRetryableConnectError(err: unknown): boolean {
+  if (!(err instanceof Error)) return true;
+  const code = (err as NodeJS.ErrnoException & { code?: string }).code;
+
+  if (code && NON_RETRYABLE_PG_CODES.has(code)) return false;
+  if (code === "ENOTFOUND") return false;
+  if (code && typeof code === "string" && code.startsWith("ERR_TLS")) {
+    return false;
+  }
+
+  const message = err.message?.toLowerCase() ?? "";
+  // Our own eager-connect timeout wrapper is retryable (flaky network).
+  if (message.includes("timed out after")) return true;
+  for (const marker of TLS_MESSAGE_MARKERS) {
+    if (message.includes(marker)) return false;
+  }
+  return true;
+}
+
+/**
+ * Retry an async `connect` operation with bounded exponential backoff.
+ * Stops immediately on a non-retryable error. On exhausted attempts, throws
+ * the last observed error.
+ *
+ * Exposed for testing — production call sites always go through
+ * {@link createManagedPool}.
+ */
+export async function connectWithRetry<T>(opts: {
+  connect: (attempt: number) => Promise<T>;
+  isRetryable?: (err: unknown) => boolean;
+  maxAttempts?: number;
+  baseBackoffMs?: number;
+  maxBackoffMs?: number;
+  sleep?: (ms: number) => Promise<void>;
+}): Promise<T> {
+  const maxAttempts = opts.maxAttempts ?? DEFAULT_CONNECT_MAX_ATTEMPTS;
+  const baseBackoffMs = opts.baseBackoffMs ?? DEFAULT_CONNECT_BASE_BACKOFF_MS;
+  const maxBackoffMs = opts.maxBackoffMs ?? DEFAULT_CONNECT_MAX_BACKOFF_MS;
+  const isRetryable = opts.isRetryable ?? isRetryableConnectError;
+  const sleep =
+    opts.sleep ?? ((ms: number) => new Promise((r) => setTimeout(r, ms)));
+
+  let lastError: unknown;
+  for (let attempt = 1; attempt <= maxAttempts; attempt++) {
+    try {
+      return await opts.connect(attempt);
+    } catch (err) {
+      lastError = err;
+      if (attempt >= maxAttempts || !isRetryable(err)) {
+        throw err;
+      }
+      const backoff = Math.min(
+        baseBackoffMs * 2 ** (attempt - 1),
+        maxBackoffMs,
+      );
+      await sleep(backoff);
+    }
+  }
+  // Unreachable: loop either returns or throws.
+  throw lastError;
+}
 
 /**
  * Options for creating a Pool with event listeners.
@@ -227,7 +326,14 @@ export async function createManagedPool(
   url: string,
   options?: { role?: string; label?: "source" | "target" },
 ): Promise<{ pool: Pool; close: () => Promise<void> }> {
-  const sslConfig = await parseSslConfig(url, options?.label ?? "target");
+  // Normalize percent-encoded IPv6 hosts (e.g. `2406%3A...%3Ab3c9`) into the
+  // canonical bracketed form before the URL reaches `parseSslConfig` or pg.
+  // Non-IPv6 hosts are returned unchanged.
+  const normalizedUrl = normalizeConnectionUrl(url);
+  const sslConfig = await parseSslConfig(
+    normalizedUrl,
+    options?.label ?? "target",
+  );
   const pool = createPool(sslConfig.cleanedUrl, {
     ...(sslConfig.ssl !== undefined ? { ssl: sslConfig.ssl } : {}),
     onError: (err: Error & { code?: string }) => {
@@ -245,25 +351,30 @@ export async function createManagedPool(
 
   // Eagerly validate connectivity so SSL/auth failures surface immediately
   // instead of hanging on the first real query. node-pg's connectionTimeoutMillis
-  // is not reliably enforced under Bun when SSL negotiation hangs.
+  // is not reliably enforced under Bun when SSL negotiation hangs. Transient
+  // failures (refused connections, flaky DNS, our own timeout wrapper) are
+  // retried with bounded exponential backoff; auth/TLS/ENOTFOUND fail fast.
   const label = options?.label ?? "target";
   const timeoutMs = DEFAULT_CONNECT_TIMEOUT_MS;
   try {
-    const client = await Promise.race([
-      pool.connect(),
-      new Promise<never>((_, reject) =>
-        setTimeout(
-          () =>
-            reject(
-              new Error(
-                `Connection to ${label} database timed out after ${timeoutMs}ms. ` +
-                  `The server may require SSL, use an invalid certificate, or be unreachable.`,
-              ),
+    const client = await connectWithRetry({
+      connect: () =>
+        Promise.race([
+          pool.connect(),
+          new Promise<never>((_, reject) =>
+            setTimeout(
+              () =>
+                reject(
+                  new Error(
+                    `Connection to ${label} database timed out after ${timeoutMs}ms. ` +
+                      `The server may require SSL, use an invalid certificate, or be unreachable.`,
+                  ),
+                ),
+              timeoutMs,
             ),
-          timeoutMs,
-        ),
-      ),
-    ]);
+          ),
+        ]),
+    });
     client.release();
   } catch (err) {
     await pool.end().catch(() => {});