@bastani/atomic-storage-postgres 0.9.89 → 0.9.90

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/CHANGELOG.md CHANGED
@@ -2,6 +2,31 @@
2
2
 
3
3
  ## [Unreleased]
4
4
 
5
+ ## [0.9.90] - 2026-11-19
6
+
7
+ ### Added
8
+
9
+ - Connections through an HTTP proxy: where the only way out is a proxy that opens `CONNECT` tunnels, such as a sandbox's, every connection to PostgreSQL (the pool's, the wake-ups connection and cancel requests, and their reconnects) tunnels through the proxy `HTTPS_PROXY` names, then `ALL_PROXY` or `HTTP_PROXY`, unless `NO_PROXY` exempts the database host, as for Atomic's other HTTPS clients; a database on this machine is reached directly. The new `proxy` option, an `http://` or `https://` URL or `"none"`, overrides the environment, and SDK callers can pass `socket`, a function that opens each connection, for a custom transport. TLS still runs end to end with the server: with the default `verify-full` (or `require` without `sslrootcert`) it checks the certificate against the database's host name, so the proxy sees only encrypted traffic, cancel requests included. `verify-ca` does not check the host name, so it keeps the proxy out only with an `sslrootcert` CA that signs your database servers alone; `prefer`, `allow` and `disable` let a proxy read the traffic. A proxy that refuses the tunnel fails the open with `StorageUnavailableError` naming the proxy, without its credentials, and the `host:port` it refused, and the warning an open prints while it retries a proxy that cannot be reached names the proxy rather than the database server. If you already set `HTTPS_PROXY` (or Atomic's `httpProxy` setting) and reach a remote database directly, its connections now go through that proxy: add the database host to `NO_PROXY`, or set the `proxy` option to `"none"`, to keep them direct ([#5473](https://github.com/bastani-inc/atomic/issues/5473))
10
+
11
+ ### Fixed
12
+
13
+ - A URL that names no host, used with `PGHOST`, now gets the same default `sslmode=verify-full` as a URL naming that host when `PGHOST` is not this machine, instead of connecting without TLS. A URL that names this machine in another spelling, such as `127.1`, `localhost.` or `[::ffff:127.0.0.1]`, no longer gets a default `sslmode=verify-full`, which a local server without TLS refused: it is treated as this machine, like `localhost` and `127.0.0.1` ([#5473](https://github.com/bastani-inc/atomic/issues/5473))
14
+ - Wake-ups no longer turn off for the rest of the process when the check of the listening connection had to open a new pool connection that took longer than 2 seconds, as through a slow proxy or while a cloud identity issues its first token. The check now waits for its notification only once it was sent ([#5473](https://github.com/bastani-inc/atomic/issues/5473))
15
+ - Proxy tunnels no longer fail when the proxy sends an informational reply such as `103 Early Hints` before the final `200`. The 16 KiB header limit and 8-second timeout cover all replies together, not the database traffic that follows. A proxy whose connection ends right after a CR byte of its answer is reported as closed, which the open retries, instead of as an answer that is not HTTP, which it never retries. A CR inside a header field that no LF follows is read as a space, so the answer's final status decides. A CR in a status line is still refused, and a CR where `HTTP/` should start an answer is now refused at once instead of after the 8-second deadline ([#5565](https://github.com/bastani-inc/atomic/issues/5565), [#5670](https://github.com/bastani-inc/atomic/issues/5670))
16
+
17
+ ## [0.9.90-alpha.1] - 2026-11-19
18
+
19
+ ### Added
20
+
21
+ - Connections through an HTTP proxy: where the only way out is a proxy that opens `CONNECT` tunnels, such as a sandbox's, every connection to PostgreSQL (the pool's, the wake-ups connection and cancel requests, and their reconnects) tunnels through the proxy `HTTPS_PROXY` names, then `ALL_PROXY` or `HTTP_PROXY`, unless `NO_PROXY` exempts the database host, as for Atomic's other HTTPS clients; a database on this machine is reached directly. The new `proxy` option, an `http://` or `https://` URL or `"none"`, overrides the environment, and SDK callers can pass `socket`, a function that opens each connection, for a custom transport. TLS still runs end to end with the server: with the default `verify-full` (or `require` without `sslrootcert`) it checks the certificate against the database's host name, so the proxy sees only encrypted traffic, cancel requests included. `verify-ca` does not check the host name, so it keeps the proxy out only with an `sslrootcert` CA that signs your database servers alone; `prefer`, `allow` and `disable` let a proxy read the traffic. A proxy that refuses the tunnel fails the open with `StorageUnavailableError` naming the proxy, without its credentials, and the `host:port` it refused, and the warning an open prints while it retries a proxy that cannot be reached names the proxy rather than the database server. If you already set `HTTPS_PROXY` (or Atomic's `httpProxy` setting) and reach a remote database directly, its connections now go through that proxy: add the database host to `NO_PROXY`, or set the `proxy` option to `"none"`, to keep them direct ([#5473](https://github.com/bastani-inc/atomic/issues/5473))
22
+
23
+ ### Fixed
24
+
25
+ - A URL that names no host, used with `PGHOST`, now gets the same default `sslmode=verify-full` as a URL naming that host when `PGHOST` is not this machine, instead of connecting without TLS ([#5473](https://github.com/bastani-inc/atomic/issues/5473))
26
+ - A URL that names this machine in another spelling, such as `127.1`, `localhost.` or `[::ffff:127.0.0.1]`, no longer gets a default `sslmode=verify-full`, which a local server without TLS refused: it is treated as this machine, like `localhost` and `127.0.0.1` ([#5473](https://github.com/bastani-inc/atomic/issues/5473))
27
+ - Wake-ups no longer turn off for the rest of the process when the check of the listening connection had to open a new pool connection that took longer than 2 seconds, as through a slow proxy or while a cloud identity issues its first token. The check now waits for its notification only once it was sent ([#5473](https://github.com/bastani-inc/atomic/issues/5473))
28
+ - Proxy tunnels no longer fail when the proxy sends an informational reply such as `103 Early Hints` before the final `200`. The 16 KiB header limit and 8-second timeout cover all replies together, not the database traffic that follows. A proxy whose connection ends right after a CR byte of its answer is reported as closed, which the open retries, instead of as an answer that is not HTTP, which it never retries. A CR inside a header field that no LF follows is read as a space, so the answer's final status decides. A CR in a status line is still refused, and a CR where `HTTP/` should start an answer is now refused at once instead of after the 8-second deadline ([#5565](https://github.com/bastani-inc/atomic/issues/5565), [#5670](https://github.com/bastani-inc/atomic/issues/5670))
29
+
5
30
  ## [0.9.88] - 2026-11-16
6
31
 
7
32
  ### Added
package/README.md CHANGED
@@ -38,8 +38,11 @@ chmod 600 ~/.atomic/postgres-password
38
38
  | `statementTimeoutMs` | no | How long one statement may run before the server cancels it. Default 30000. |
39
39
  | `listenUrl` | no | A direct (session) endpoint for the connection that listens for wake-ups, when `url` goes through a transaction pooler. Default `url`. |
40
40
  | `schema` | no | The schema Atomic's tables live in, a lowercase name. Default `atomic`, which the first store that sets up its tables creates when the role may. A database whose `public` schema holds an earlier release's tables, and has no `atomic` schema, keeps using `public` until `atomic storage migrate` moves them. Every transaction sets it with `SET LOCAL search_path`. |
41
+ | `proxy` | no | An `http://` or `https://` proxy every connection tunnels through with `CONNECT`, or `"none"` to connect directly. Default: the environment's, as below. |
41
42
 
42
- PostgreSQL 14 or newer is required. A URL that names no `sslmode` gets `sslmode=verify-full` when its host is not this machine, so the connection is encrypted and the server certificate is checked. Name a CA with `sslrootcert=/path/to/ca.pem` when the server's certificate is not signed by a CA Node trusts, or set `sslmode` yourself. `sslmode` follows libpq: `verify-ca` checks the certificate's CA (`sslrootcert`, or else the CAs Node trusts) but not its host name, for a server reached by an address its certificate does not name; `prefer` and `allow` encrypt without checking the certificate; `disable` turns TLS off. `require` with `sslrootcert` acts as `verify-ca`; without it, `require` checks the certificate and its host name, as `verify-full` does, which is stricter than libpq. Parameter names are case-sensitive, as in libpq: a TLS parameter that is not lowercase, or an unknown `sslmode`, is refused.
43
+ Where the only way out is an HTTP proxy, such as a sandbox's, every connection (the pool's, the one that listens for wake-ups, cancel requests, and their reconnects) tunnels through the proxy `HTTPS_PROXY` (or `https_proxy`) names, then `ALL_PROXY` when it names an HTTP proxy, then `HTTP_PROXY`, unless `NO_PROXY` exempts the database host. `HTTPS_PROXY`, `HTTP_PROXY` and `NO_PROXY` are read as Atomic's other HTTPS clients read them; those clients do not read `ALL_PROXY`. A database on this machine (a loopback host or a socket directory) is reached directly whatever the environment says; the `proxy` option overrides all of this, except that a socket directory is always reached directly. Credentials in the proxy URL are sent as `Proxy-Authorization` and never appear in messages. TLS still runs end to end with the server through the tunnel. With the default `verify-full` (or `require` without `sslrootcert`), the certificate must name the database host, so the proxy sees only encrypted traffic. `verify-ca` (and `require` with `sslrootcert`) accepts any certificate the CA signed, whatever host it names: it keeps the proxy out only when `sslrootcert` names a CA that signs your database servers alone, and with the CAs Node trusts, a proxy holding any certificate they issued could read and change the traffic. `prefer` and `allow` do not check the certificate, so a proxy could read and change the traffic, and `disable` does not encrypt it. A proxy that refuses the tunnel fails the open with `StorageUnavailableError`, whose message names the proxy and the refused `host:port`; while an open retries a proxy that cannot be reached, its warning names the proxy too.
44
+
45
+ PostgreSQL 14 or newer is required. A URL that names no `sslmode` gets `sslmode=verify-full` when its host (for a URL that names no host, `PGHOST`) is not this machine, so the connection is encrypted and the server certificate is checked. Name a CA with `sslrootcert=/path/to/ca.pem` when the server's certificate is not signed by a CA Node trusts, or set `sslmode` yourself. `sslmode` follows libpq: `verify-ca` checks the certificate's CA (`sslrootcert`, or else the CAs Node trusts) but not its host name, for a server reached by an address its certificate does not name; `prefer` and `allow` encrypt without checking the certificate; `disable` turns TLS off. `require` with `sslrootcert` acts as `verify-ca`; without it, `require` checks the certificate and its host name, as `verify-full` does, which is stricter than libpq. Parameter names are case-sensitive, as in libpq: a TLS parameter that is not lowercase, or an unknown `sslmode`, is refused.
43
46
 
44
47
  The adapter works through a transaction-mode connection pooler (PgBouncer, Supavisor, and the poolers of managed services): it sets nothing outside a transaction, takes no session locks, and uses no named prepared statements.
45
48
 
@@ -165,6 +168,8 @@ const database = await openPostgresDatabase({
165
168
 
166
169
  `password` is a string or a function called for each new connection. The returned `SqliteDatabase` can be passed as SDK `sessionStore: { kind: "database", database }` or workflow `journal: { database }`.
167
170
 
171
+ For a custom transport, pass `socket`, a function that opens a connection to `{ host, port }` and returns a stream (or a promise of one) that carries the PostgreSQL protocol there; the adapter negotiates TLS over it as over a socket. It is used instead of a proxy from the environment; passing it with `proxy` is refused with `StorageConfigError` reason `conflicting-transport`, and a socket directory is still reached directly. `{ host, port }` is the endpoint pg connects to: the URL's, else `PGHOST` and `PGPORT`.
172
+
168
173
  The package ships plain ESM JavaScript with TypeScript declarations. This import works in supported Node versions without a TypeScript loader.
169
174
 
170
175
  ## License
package/listen.js CHANGED
@@ -125,12 +125,17 @@ export function createPostgresListener(options) {
125
125
  const nonce = randomBytes(8).toString("hex");
126
126
  /** @type {NodeJS.Timeout | undefined} */
127
127
  let timer;
128
+ /** @type {(arrived: boolean) => void} */
129
+ let settle = () => {};
128
130
  const arrived = new Promise((resolve) => {
131
+ settle = resolve;
129
132
  probes.set(nonce, () => resolve(true));
130
- timer = setTimeout(() => resolve(false), probeTimeoutMs);
131
133
  });
132
134
  try {
133
135
  await options.send(probeChannel, nonce);
136
+ // The wait starts once the notification was sent: opening a pool connection for it first, which through a
137
+ // proxy tunnel can take longer than the wait, says nothing of whether notifications arrive (#5473).
138
+ timer = setTimeout(() => settle(false), probeTimeoutMs);
134
139
  return /** @type {boolean} */ (await arrived);
135
140
  } finally {
136
141
  clearTimeout(timer);
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@bastani/atomic-storage-postgres",
3
- "version": "0.9.89",
3
+ "version": "0.9.90",
4
4
  "description": "PostgreSQL storage adapter for Atomic sessions, workflow journals, and Intercom.",
5
5
  "contributors": [
6
6
  "Norin Lavaee",
@@ -27,6 +27,8 @@
27
27
  "auth.d.ts",
28
28
  "listen.js",
29
29
  "listen.d.ts",
30
+ "proxy.js",
31
+ "proxy.d.ts",
30
32
  "README.md",
31
33
  "CHANGELOG.md",
32
34
  "LICENSE"
package/postgres.d.ts CHANGED
@@ -1,4 +1,7 @@
1
1
  import type { AdapterOptions, SqliteDatabase, StorageOpenContext } from "@bastani/atomic/storage";
2
+ import type { PostgresSocketFactory } from "./proxy.js";
3
+
4
+ export type { PostgresSocketFactory, ProxyTarget } from "./proxy.js";
2
5
 
3
6
  export interface PostgresDatabaseOptions {
4
7
  /** A `postgres://` or `postgresql://` URL without a password. */
@@ -30,6 +33,21 @@ export interface PostgresDatabaseOptions {
30
33
  * `openDatabase` passes `<agentDir>/npm`, where `atomic install npm:<package>` installs user packages.
31
34
  */
32
35
  sdkSearchPaths?: readonly string[];
36
+ /**
37
+ * The HTTP proxy connections tunnel through with `CONNECT` (#5473): an `http://` or `https://` URL, with credentials
38
+ * sent as `Proxy-Authorization` when it has them, or `"none"` for direct connections. It overrides the environment
39
+ * and applies to this machine too: without it, a connection to a host other than this machine tunnels through
40
+ * `HTTPS_PROXY` (or `ALL_PROXY`, then `HTTP_PROXY`) unless `NO_PROXY` exempts the host. A socket directory is always
41
+ * reached directly. TLS still runs end to end with the server. A proxy can read the traffic with `sslmode` `prefer`,
42
+ * `allow` or `disable`, and with `verify-ca` when it holds a certificate from the CA the connection trusts, for any
43
+ * host: `verify-full` (the default) checks the certificate's host name.
44
+ */
45
+ proxy?: string;
46
+ /**
47
+ * Opens each connection to the server for a custom transport, in place of a socket or a proxy tunnel; passing it
48
+ * with `proxy` is refused (`conflicting-transport`). A socket directory is always reached directly.
49
+ */
50
+ socket?: PostgresSocketFactory;
33
51
  }
34
52
 
35
53
  export const DEFAULT_MAX_CONNECTIONS: 8;
package/postgres.js CHANGED
@@ -1,6 +1,7 @@
1
1
  // @ts-check
2
- import { connect as connectSocket } from "node:net";
2
+ import { connect as connectSocket, isIP } from "node:net";
3
3
  import { join } from "node:path";
4
+ import { connect as connectTls } from "node:tls";
4
5
  import {
5
6
  createSqliteDatabase,
6
7
  postgresDialect,
@@ -11,6 +12,14 @@ import {
11
12
  } from "@bastani/atomic/storage";
12
13
  import { createCloudPasswordProvider } from "./auth.js";
13
14
  import { createPostgresListener } from "./listen.js";
15
+ import {
16
+ isLocalTarget,
17
+ OpenedSocket,
18
+ ProxySettingError,
19
+ ProxyTunnelError,
20
+ postgresTransport,
21
+ socketOpener,
22
+ } from "./proxy.js";
14
23
 
15
24
  /**
16
25
  * @typedef {import("@bastani/atomic/storage").SqliteDriverResult} SqliteDriverResult
@@ -28,6 +37,8 @@ import { createPostgresListener } from "./listen.js";
28
37
  * listenUrl?: string,
29
38
  * schema?: string,
30
39
  * sdkSearchPaths?: readonly string[],
40
+ * proxy?: string,
41
+ * socket?: import("./proxy.js").PostgresSocketFactory,
31
42
  * }} PostgresDatabaseOptions
32
43
  */
33
44
 
@@ -101,6 +112,21 @@ function tlsVerificationFailure(cause) {
101
112
  return undefined;
102
113
  }
103
114
 
115
+ /**
116
+ * The tunnel a proxy did not open along `cause`'s chain (#5473), or undefined when the failure is not a proxy's.
117
+ * @param {unknown} cause
118
+ * @returns {ProxyTunnelError | undefined}
119
+ */
120
+ function proxyTunnelFailure(cause) {
121
+ /** @type {unknown} */
122
+ let current = cause;
123
+ for (let depth = 0; depth < MAX_CAUSE_DEPTH && typeof current === "object" && current !== null; depth++) {
124
+ if (current instanceof ProxyTunnelError) return current;
125
+ current = /** @type {{ cause?: unknown }} */ (current).cause;
126
+ }
127
+ return undefined;
128
+ }
129
+
104
130
  /** The SQLSTATEs of a refused password or token: `28P01`, and `28000`, which Azure sends for a malformed token. */
105
131
  const REFUSED_TOKEN_SQLSTATES = new Set(["28P01", "28000"]);
106
132
  /** The schema Atomic's tables, indexes, triggers and functions live in when the options name none (#5218). */
@@ -167,18 +193,6 @@ function missingPrivilege(cause, role, schema, database, sql = "") {
167
193
  );
168
194
  }
169
195
 
170
- /** Whether `host` reaches this machine without a network: a socket directory, a loopback name or address. */
171
- function isLocalHost(/** @type {string} */ host) {
172
- const name = host.replace(/^\[|\]$/g, "").toLowerCase();
173
- return (
174
- name === "" ||
175
- name.startsWith("/") ||
176
- name === "localhost" ||
177
- name === "::1" ||
178
- /^127(?:\.\d{1,3}){3}$/.test(name)
179
- );
180
- }
181
-
182
196
  /**
183
197
  * The `sslmode` values libpq knows.
184
198
  * @type {ReadonlySet<string>}
@@ -192,7 +206,7 @@ function isTlsParameter(/** @type {string} */ name) {
192
206
 
193
207
  /**
194
208
  * The URL pg connects with: a `postgres:` or `postgresql:` URL without a password, which gets `sslmode=verify-full`
195
- * when it names none and its host is not this machine. A TLS parameter whose name is not lowercase, or an `sslmode`
209
+ * when it names none and its host, or `PGHOST` for a URL that names no host, is not this machine. A TLS parameter whose name is not lowercase, or an `sslmode`
196
210
  * libpq does not know, is refused.
197
211
  * @param {unknown} url
198
212
  * @param {"url" | "listenUrl"} [field] The option that holds the URL, which a refusal names.
@@ -224,8 +238,10 @@ function connectionUrl(url, field = "url") {
224
238
  if (mode !== null && !SSL_MODES.has(mode))
225
239
  throw configError("url", "unsupported-sslmode", `Use an sslmode of ${[...SSL_MODES].join(", ")}`);
226
240
  if (mode !== null) return /** @type {string} */ (url);
227
- const host = parsed.searchParams.get("host") ?? parsed.hostname;
228
- if (isLocalHost(host)) return /** @type {string} */ (url);
241
+ // The host pg connects to: a URL that names none falls back to PGHOST, as pg does. This machine is told by the rule
242
+ // that keeps it out of a proxy, so every spelling of it is treated alike (#5473).
243
+ const host = parsed.searchParams.get("host") ?? (parsed.hostname || process.env.PGHOST || "");
244
+ if (isLocalTarget(host)) return /** @type {string} */ (url);
229
245
  parsed.searchParams.set("sslmode", "verify-full");
230
246
  return parsed.href;
231
247
  }
@@ -550,7 +566,8 @@ const TRANSIENT_SQLSTATES = new Map([
550
566
 
551
567
  /**
552
568
  * The failure, as one that passes, read from the server's SQLSTATE when the server answered, else from whether a
553
- * connection could be had or broke during the call; never from a message.
569
+ * connection could be had or broke during the call; never from a message. A connection a proxy did not open names the
570
+ * proxy as the hop that failed (#5473).
554
571
  * @param {typeof import("pg").DatabaseError} DatabaseError
555
572
  * @returns {(failure: StorageFailureCause) => SqliteDriverTransientFailure | undefined}
556
573
  */
@@ -558,18 +575,26 @@ function transientFailureOf(DatabaseError) {
558
575
  return (failure) => {
559
576
  /** @type {PostgresConnectionFailure | undefined} */
560
577
  let connection;
578
+ /** @type {ProxyTunnelError | undefined} */
579
+ let tunnel;
561
580
  /** @type {unknown} */
562
581
  let current = failure;
563
582
  for (let depth = 0; depth < MAX_CAUSE_DEPTH && typeof current === "object" && current !== null; depth++) {
564
583
  if (current instanceof DatabaseError) return TRANSIENT_SQLSTATES.get(current.code ?? "");
565
584
  if (current instanceof PostgresConnectionFailure) connection ??= current;
585
+ else if (current instanceof ProxyTunnelError) tunnel ??= current;
566
586
  else if (current instanceof StorageError) return undefined;
567
587
  current = /** @type {{ readonly cause?: unknown }} */ (current).cause;
568
588
  }
569
589
  if (connection === undefined) return undefined;
570
- return connection.phase === "connect"
590
+ if (connection.phase === "lost") return { code: "connection-lost", outcome: "unknown" };
591
+ return tunnel === undefined
571
592
  ? { code: "connection-refused", outcome: "not-applied" }
572
- : { code: "connection-lost", outcome: "unknown" };
593
+ : {
594
+ code: "connection-refused",
595
+ outcome: "not-applied",
596
+ hop: { name: `the proxy ${tunnel.proxy}`, failure: tunnel.message },
597
+ };
573
598
  };
574
599
  }
575
600
 
@@ -581,6 +606,62 @@ function lockKey(scope) {
581
606
  return `hashtextextended(${literal(scope)}, 0)`;
582
607
  }
583
608
 
609
+ /**
610
+ * The endpoint pg connects to for `config`, resolved as pg resolves it: the URL's host and port, else `PGHOST` and
611
+ * `PGPORT`, else `localhost` and 5432.
612
+ * @param {{ host?: string | null, port?: string | number | null }} config
613
+ * @returns {{ host: string, port: number }}
614
+ */
615
+ function endpointOf(config) {
616
+ return {
617
+ host: config.host || process.env.PGHOST || "localhost",
618
+ port: Number.parseInt(String(config.port || process.env.PGPORT || 5432), 10),
619
+ };
620
+ }
621
+
622
+ /** The protocol's SSLRequest code, sent before a TLS handshake on a new connection. */
623
+ const SSL_REQUEST_CODE = 80877103;
624
+
625
+ /**
626
+ * `raw`, a new connection to the server, with TLS negotiated on it as pg negotiates it for a session: an SSLRequest,
627
+ * then a handshake with `ssl`'s options that checks the certificate against `host`. A server that declines TLS gets
628
+ * nothing more, so a cancel key meant for an encrypted connection is never sent in clear (#5473).
629
+ * @param {import("node:stream").Duplex} raw
630
+ * @param {string} host
631
+ * @param {boolean | import("node:tls").ConnectionOptions} ssl
632
+ * @returns {Promise<import("node:stream").Duplex>}
633
+ */
634
+ function secureCancelStream(raw, host, ssl) {
635
+ return new Promise((resolve, reject) => {
636
+ const request = Buffer.alloc(8);
637
+ request.writeInt32BE(8, 0);
638
+ request.writeInt32BE(SSL_REQUEST_CODE, 4);
639
+ raw.once("error", reject);
640
+ raw.once("data", (/** @type {Buffer} */ answer) => {
641
+ raw.pause();
642
+ if (answer.toString("latin1") !== "S") {
643
+ raw.destroy();
644
+ reject(new Error("The server declined TLS for the cancel request"));
645
+ return;
646
+ }
647
+ const secure = connectTls({
648
+ socket: /** @type {import("node:net").Socket} */ (raw),
649
+ host,
650
+ ...(ssl === true ? {} : ssl),
651
+ ...(isIP(host) === 0 ? { servername: host } : {}),
652
+ });
653
+ secure.once("error", reject);
654
+ secure.once("secureConnect", () => {
655
+ secure.off("error", reject);
656
+ resolve(secure);
657
+ });
658
+ });
659
+ // A tunnel is handed over paused, and a `data` listener alone does not resume a paused stream.
660
+ raw.resume();
661
+ raw.write(request);
662
+ });
663
+ }
664
+
584
665
  /**
585
666
  * Quotes `text` as a SQL string literal.
586
667
  * @param {string} text
@@ -609,6 +690,12 @@ export async function openPostgresDatabase(options) {
609
690
  );
610
691
  if (options.schema !== undefined && (typeof options.schema !== "string" || !SCHEMA_NAME.test(options.schema)))
611
692
  throw configError("schema", "invalid-schema", "Use a lowercase identifier of letters, digits and _, such as atomic");
693
+ if (options.proxy !== undefined && typeof options.proxy !== "string")
694
+ throw configError("proxy", "unsupported-proxy", 'Use an http:// or https:// proxy URL, or "none"');
695
+ if (options.socket !== undefined && typeof options.socket !== "function")
696
+ throw configError("socket", "invalid-socket-factory", "Pass a function that opens a connection to { host, port }");
697
+ if (options.proxy !== undefined && options.socket !== undefined)
698
+ throw configError("proxy", "conflicting-transport", "Pass either a proxy or a socket factory, not both");
612
699
  /**
613
700
  * The schema every statement runs in, set with `SET LOCAL search_path` in each transaction so a transaction-mode
614
701
  * pooler can serve it: the configured one, else `atomic`, or `public` for a database an earlier release set up there.
@@ -648,6 +735,38 @@ export async function openPostgresDatabase(options) {
648
735
  const listenConnection =
649
736
  options.listenUrl === undefined ? connection : parseConnection(connectionUrl(options.listenUrl, "listenUrl"));
650
737
 
738
+ /**
739
+ * How connections to `target` are opened (#5473): through the caller's socket factory, the `proxy` option, or the
740
+ * environment's HTTP proxy, as `postgresTransport` decides; undefined for a direct connection, which pg opens itself.
741
+ * A socket directory is always reached directly. The decision is made for the endpoint pg connects to, which falls
742
+ * back to `PGHOST` and `PGPORT` when the URL names no host or port.
743
+ * @param {typeof connection} target
744
+ * @returns {import("./proxy.js").PostgresSocketFactory | undefined}
745
+ */
746
+ const openerFor = (target) => {
747
+ const { host, port } = endpointOf(target);
748
+ if (host.startsWith("/")) return undefined;
749
+ if (options.socket !== undefined) return options.socket;
750
+ try {
751
+ return socketOpener(postgresTransport({ host, port }, process.env, options.proxy));
752
+ } catch (error) {
753
+ if (error instanceof ProxySettingError)
754
+ throw configError(
755
+ "proxy",
756
+ "unsupported-proxy",
757
+ `${error.message}. Use an http:// or https:// proxy URL, set NO_PROXY for the database host, or pass proxy "none"`,
758
+ );
759
+ throw error;
760
+ }
761
+ };
762
+ const opener = openerFor(connection);
763
+ const listenOpener = listenConnection === connection ? opener : openerFor(listenConnection);
764
+ /**
765
+ * pg's `stream` option for connections opened by `open`: a fresh stream for each connection.
766
+ * @param {import("./proxy.js").PostgresSocketFactory | undefined} open
767
+ */
768
+ const streamOption = (open) => (open === undefined ? {} : { stream: () => new OpenedSocket(open) });
769
+
651
770
  /** The cloud token providers of the pool's and the listening connection's hosts. */
652
771
  /** @type {Set<{ invalidate(): void }>} */
653
772
  const tokenProviders = new Set();
@@ -699,6 +818,7 @@ export async function openPostgresDatabase(options) {
699
818
  const pool = new pg.Pool({
700
819
  Client: /** @type {typeof pg.Client} */ (/** @type {unknown} */ (ClosingClient)),
701
820
  ...connection,
821
+ ...streamOption(opener),
702
822
  ...(password === undefined ? {} : { password }),
703
823
  max: maxConnections,
704
824
  connectionTimeoutMillis: CONNECT_TIMEOUT_MS,
@@ -716,11 +836,20 @@ export async function openPostgresDatabase(options) {
716
836
  pool.on("error", (_error, client) => lost.add(client));
717
837
  pool.on("connect", (client) => client.on("error", () => lost.add(client)));
718
838
 
839
+ /**
840
+ * The proxy's refusal or failure the latest attempt to connect ended in, kept here because the facade passes on a
841
+ * redacted copy of a failure, which is no longer a `ProxyTunnelError` (#5473). Cleared by a connection that opens.
842
+ * @type {ProxyTunnelError | undefined}
843
+ */
844
+ let tunnelFailure;
719
845
  /** @returns {Promise<PoolClient>} */
720
846
  const connect = async () => {
721
847
  try {
722
- return await pool.connect();
848
+ const client = await pool.connect();
849
+ tunnelFailure = undefined;
850
+ return client;
723
851
  } catch (cause) {
852
+ tunnelFailure = proxyTunnelFailure(cause);
724
853
  // A cloud token the server refused (28P01, or Azure's 28000 for a malformed one) is dropped, and a fresh one
725
854
  // tried once: a clock that runs behind can reuse a cached token past its expiry (#5218).
726
855
  if (tokenProviders.size > 0 && cause instanceof pg.DatabaseError && REFUSED_TOKEN_SQLSTATES.has(cause.code ?? "")) {
@@ -733,6 +862,9 @@ export async function openPostgresDatabase(options) {
733
862
  }
734
863
  const tls = tlsVerificationFailure(cause);
735
864
  if (tls !== undefined) throw tls;
865
+ // A proxy that refused the tunnel refuses it again: permanent, never retried as unreachable (#5473).
866
+ const tunnel = proxyTunnelFailure(cause);
867
+ if (tunnel?.permanent === true) throw new StorageError(tunnel.message, { cause: /** @type {Error} */ (cause) });
736
868
  throw new PostgresConnectionFailure("connect", /** @type {StorageFailureCause} */ (cause));
737
869
  }
738
870
  };
@@ -751,13 +883,52 @@ export async function openPostgresDatabase(options) {
751
883
  request.writeInt32BE(CANCEL_REQUEST_CODE, 4);
752
884
  request.writeInt32BE(processID, 8);
753
885
  request.writeInt32BE(secretKey, 12);
754
- const host = connection.host ?? "localhost";
755
- const port = connection.port ?? 5432;
756
- const socket = host.startsWith("/") ? connectSocket(`${host}/.s.PGSQL.${port}`) : connectSocket(port, host);
757
- socket.setTimeout(CLIENT_TIMEOUT_GRACE_MS, () => socket.destroy());
758
- socket.on("error", () => socket.destroy());
759
- socket.end(request);
760
- return new Promise((resolve) => socket.once("close", () => resolve()));
886
+ const { host, port } = endpointOf(connection);
887
+ return new Promise((resolve) => {
888
+ /** @type {import("node:stream").Duplex | undefined} */
889
+ let socket;
890
+ let done = false;
891
+ const finish = () => {
892
+ if (done) return;
893
+ done = true;
894
+ clearTimeout(timer);
895
+ socket?.destroy();
896
+ resolve(undefined);
897
+ };
898
+ // The whole request, a proxy tunnel and its TLS included, is bounded.
899
+ const timer = setTimeout(finish, CLIENT_TIMEOUT_GRACE_MS);
900
+ /** @type {Promise<import("node:stream").Duplex>} */
901
+ const opened =
902
+ opener === undefined
903
+ ? Promise.resolve(
904
+ host.startsWith("/") ? connectSocket(`${host}/.s.PGSQL.${port}`) : connectSocket(port, host),
905
+ )
906
+ : // Through a tunnel the request is sent over TLS when the connection is, so the proxy never sees the
907
+ // connection's cancel key (#5473).
908
+ Promise.resolve()
909
+ .then(() => opener({ host, port }))
910
+ .then((raw) => {
911
+ // Kept at once, so the bound closes the tunnel whatever stage the request reached: a hung
912
+ // server may never answer the SSLRequest or finish the handshake.
913
+ socket = raw;
914
+ if (done) {
915
+ raw.destroy();
916
+ return raw;
917
+ }
918
+ return connection.ssl ? secureCancelStream(raw, host, connection.ssl) : raw;
919
+ });
920
+ opened.then(
921
+ (opening) => {
922
+ socket = opening;
923
+ if (done) return void opening.destroy();
924
+ opening.on("error", finish);
925
+ opening.once("close", finish);
926
+ opening.end(request);
927
+ opening.resume();
928
+ },
929
+ finish,
930
+ );
931
+ });
761
932
  };
762
933
 
763
934
  /**
@@ -843,6 +1014,7 @@ export async function openPostgresDatabase(options) {
843
1014
  creatingSchema ??= (async () => {
844
1015
  const client = new ClosingClient({
845
1016
  ...connection,
1017
+ ...streamOption(opener),
846
1018
  ...(password === undefined ? {} : { password }),
847
1019
  connectionTimeoutMillis: CONNECT_TIMEOUT_MS,
848
1020
  application_name: "atomic",
@@ -853,6 +1025,8 @@ export async function openPostgresDatabase(options) {
853
1025
  client.connect((/** @type {Error | undefined} */ error) => (error ? reject(error) : resolve(undefined))),
854
1026
  );
855
1027
  } catch (cause) {
1028
+ const tunnel = proxyTunnelFailure(cause);
1029
+ if (tunnel?.permanent === true) throw new StorageError(tunnel.message, { cause: /** @type {Error} */ (cause) });
856
1030
  throw new PostgresConnectionFailure("connect", /** @type {StorageFailureCause} */ (cause));
857
1031
  }
858
1032
  try {
@@ -1008,6 +1182,7 @@ export async function openPostgresDatabase(options) {
1008
1182
  async connect() {
1009
1183
  const client = new ClosingClient({
1010
1184
  ...listenConnection,
1185
+ ...streamOption(listenOpener),
1011
1186
  ...(listenPassword === undefined ? {} : { password: listenPassword }),
1012
1187
  connectionTimeoutMillis: CONNECT_TIMEOUT_MS,
1013
1188
  // A short keepalive notices a peer that vanished without a reset sooner than the system's two hours; the
@@ -1057,7 +1232,7 @@ export async function openPostgresDatabase(options) {
1057
1232
  // The locks nest: one without a domain holds the whole database's lock, and one with a domain holds that lock
1058
1233
  // shared, so it waits for and excludes whole-database transactions, but not those of other domains. The locks,
1059
1234
  // and every row lock after them, wait at most `lockWaitMs`; the statement timeout starts after them.
1060
- const lock =
1235
+ const lock = begin.readOnly === true ? "" :
1061
1236
  concurrency.kind !== "serial"
1062
1237
  ? concurrency.excludesSerial === true
1063
1238
  ? `SELECT pg_advisory_xact_lock_shared(${lockKey(inSchema(DATABASE_LOCK_SCOPE))}); `
@@ -1072,7 +1247,7 @@ export async function openPostgresDatabase(options) {
1072
1247
  client,
1073
1248
  () =>
1074
1249
  client.query(
1075
- `BEGIN; SET LOCAL lock_timeout = ${lockWaitMs}; ${lock}SET LOCAL statement_timeout = ${statementTimeoutMs}; ${searchPathSql()}`,
1250
+ `${begin.readOnly === true ? "BEGIN READ ONLY ISOLATION LEVEL REPEATABLE READ" : "BEGIN"}; SET LOCAL lock_timeout = ${lockWaitMs}; ${lock}SET LOCAL statement_timeout = ${statementTimeoutMs}; ${searchPathSql()}`,
1076
1251
  ),
1077
1252
  lockWaitMs + clientTimeoutMs,
1078
1253
  );
@@ -1140,7 +1315,13 @@ export async function openPostgresDatabase(options) {
1140
1315
  }
1141
1316
  else schemaReady = Number(found?.present) > 0;
1142
1317
  return database;
1143
- } catch (error) {
1318
+ } catch (caught) {
1319
+ // A proxy that did not open the tunnel is named, with the server it was asked for, in the failure itself (#5473):
1320
+ // a worker that relays only the message keeps the reason. The message names the proxy without its credentials.
1321
+ const error =
1322
+ tunnelFailure === undefined
1323
+ ? caught
1324
+ : new StorageUnavailableError(database.descriptor, /** @type {Error} */ (caught), tunnelFailure.message);
1144
1325
  await database
1145
1326
  .close()
1146
1327
  .catch((cleanupCause) =>
@@ -1178,6 +1359,8 @@ const adapter = {
1178
1359
  ...(typeof options.statementTimeoutMs === "number" ? { statementTimeoutMs: options.statementTimeoutMs } : {}),
1179
1360
  ...(typeof options.listenUrl === "string" ? { listenUrl: options.listenUrl } : {}),
1180
1361
  ...(options.schema === undefined ? {} : { schema: /** @type {string} */ (options.schema) }),
1362
+ // A value that is not a string reaches the option's check, which names it.
1363
+ ...(options.proxy === undefined ? {} : { proxy: /** @type {string} */ (options.proxy) }),
1181
1364
  // A cloud SDK `atomic install` put in the user packages, for an adapter installed from a local path (#5218).
1182
1365
  ...(cloud ? { sdkSearchPaths: [join(context.agentDir, "npm")] } : {}),
1183
1366
  });
package/proxy.d.ts ADDED
@@ -0,0 +1,114 @@
1
+ import type { Duplex } from "node:stream";
2
+
3
+ /** A connection's target: the endpoint pg connects to, the URL's host and port, else `PGHOST` and `PGPORT`. */
4
+ export interface ProxyTarget {
5
+ readonly host: string;
6
+ readonly port: number;
7
+ }
8
+
9
+ /**
10
+ * Opens a connection that carries the PostgreSQL protocol to `target`, for a custom transport. The adapter negotiates
11
+ * TLS over it with the server, checking the certificate against `target.host`, as it does over a socket.
12
+ */
13
+ export type PostgresSocketFactory = (target: ProxyTarget) => Duplex | Promise<Duplex>;
14
+
15
+ /** How long a proxy may take to accept a connection and answer its tunnel request, in milliseconds. */
16
+ export const PROXY_ANSWER_TIMEOUT_MS: 8000;
17
+
18
+ /**
19
+ * Whether a `NO_PROXY` value exempts `host` on `port`, as Atomic's HTTPS clients decide it: entries separated by commas
20
+ * or white space; a host matches itself and its subdomains, `*.name` only subdomains, `*` every host; an entry with a
21
+ * port matches that port only.
22
+ */
23
+ export function noProxyMatches(host: string, port: number, value: string): boolean;
24
+
25
+ /**
26
+ * The environment's proxy for a connection to PostgreSQL and the variable it came from: `https_proxy` or `HTTPS_PROXY`,
27
+ * then `all_proxy` or `ALL_PROXY` when it names an HTTP proxy, then `http_proxy` or `HTTP_PROXY`.
28
+ */
29
+ export function proxySetting(env: {
30
+ readonly [name: string]: string | undefined;
31
+ }): { readonly variable: string; readonly value: string } | undefined;
32
+
33
+ /** An HTTP proxy a setting names; `label` names it without credentials. */
34
+ export interface HttpProxy {
35
+ readonly protocol: "http:" | "https:";
36
+ readonly host: string;
37
+ readonly port: number;
38
+ readonly label: string;
39
+ readonly authorization?: string;
40
+ }
41
+
42
+ export type PostgresTransport = { readonly kind: "direct" } | { readonly kind: "proxy"; readonly proxy: HttpProxy };
43
+
44
+ /** A proxy setting that cannot be used; the message names where it came from, never its value. */
45
+ export class ProxySettingError extends Error {
46
+ constructor(subject: string, problem: string);
47
+ }
48
+
49
+ /** The proxy a setting names: an `http:` or `https:` URL, or a bare `host:port`, read as `http:`. */
50
+ export function parseProxy(value: string, subject: string): HttpProxy;
51
+
52
+ /**
53
+ * Whether `host` is this machine: a socket directory, a loopback name or a loopback address, in any spelling a URL or
54
+ * the resolver reads as one, such as `127.1`, `localhost.` or `::ffff:127.0.0.1`.
55
+ */
56
+ export function isLocalTarget(host: string): boolean;
57
+
58
+ /**
59
+ * How a connection to `target` is opened: through the proxy `option` names (`"none"`: directly), else through the
60
+ * environment's proxy unless `NO_PROXY` exempts the target; a socket directory or loopback target is reached directly.
61
+ */
62
+ export function postgresTransport(
63
+ target: ProxyTarget,
64
+ env: { readonly [name: string]: string | undefined },
65
+ option?: string,
66
+ ): PostgresTransport;
67
+
68
+ /** `host:port` as a tunnel request names it, with an IPv6 address in brackets. */
69
+ export function authorityOf(target: ProxyTarget): string;
70
+
71
+ export type ProxyTunnelErrorCode =
72
+ | "proxy-refused"
73
+ | "proxy-auth-required"
74
+ | "proxy-upstream"
75
+ | "proxy-protocol"
76
+ | "proxy-closed"
77
+ | "proxy-unreachable"
78
+ | "proxy-timeout";
79
+
80
+ /** A tunnel a proxy did not open; `permanent` when asking again would not change the answer. */
81
+ export class ProxyTunnelError extends Error {
82
+ readonly code: ProxyTunnelErrorCode;
83
+ /** The proxy, without credentials. */
84
+ readonly proxy: string;
85
+ /** The `host:port` the tunnel was asked for. */
86
+ readonly target: string;
87
+ readonly permanent: boolean;
88
+ readonly status?: number;
89
+ constructor(
90
+ code: ProxyTunnelErrorCode,
91
+ message: string,
92
+ details: { proxy: string; target: string; permanent: boolean; status?: number; cause?: unknown },
93
+ );
94
+ }
95
+
96
+ /** Asks `proxy` for a `CONNECT` tunnel to `target`; resolves with the connection once the proxy answers 2xx. */
97
+ export function openProxyTunnel(
98
+ proxy: HttpProxy,
99
+ target: ProxyTarget,
100
+ options?: { timeoutMs?: number },
101
+ ): Promise<import("node:net").Socket>;
102
+
103
+ /** The stream pg is given for a connection `open` opens: it emits `connect` once `open` resolved. */
104
+ export class OpenedSocket extends Duplex {
105
+ constructor(open: PostgresSocketFactory);
106
+ connect(port: number | string, host?: string): this;
107
+ setNoDelay(noDelay?: boolean): this;
108
+ setKeepAlive(enable?: boolean, initialDelay?: number): this;
109
+ ref(): this;
110
+ unref(): this;
111
+ }
112
+
113
+ /** The function that opens connections through `transport`, or undefined for a direct connection pg opens itself. */
114
+ export function socketOpener(transport: PostgresTransport): PostgresSocketFactory | undefined;
package/proxy.js ADDED
@@ -0,0 +1,619 @@
1
+ // @ts-check
2
+ import { connect as connectNet, isIP } from "node:net";
3
+ import { Duplex } from "node:stream";
4
+ import { connect as connectTls } from "node:tls";
5
+
6
+ /**
7
+ * How the adapter reaches PostgreSQL through an HTTP proxy (#5473): which connections a proxy applies to, the `CONNECT`
8
+ * tunnel each of them is opened through, and the stream pg is given for it. PostgreSQL's own protocol, TLS included,
9
+ * then runs inside the tunnel with the real server, so the proxy passes only the bytes the server would see.
10
+ */
11
+
12
+ /**
13
+ * How long a proxy may take to accept the connection and answer its tunnel request: less than the adapter's 10 s bound
14
+ * for a whole connection, so a silent proxy is named as the reason rather than a connection timeout.
15
+ */
16
+ export const PROXY_ANSWER_TIMEOUT_MS = 8_000;
17
+ /** The most bytes all proxy responses may take through the blank line ending the final headers. */
18
+ const MAX_PROXY_ANSWER_BYTES = 16 * 1024;
19
+ /** The most characters of a proxy's status text a failure repeats. */
20
+ const MAX_REASON_LENGTH = 80;
21
+
22
+ /**
23
+ * Node's codes for a certificate TLS verification refused: an https proxy that shows one is refused the same way on
24
+ * every attempt.
25
+ * @type {ReadonlySet<string>}
26
+ */
27
+ const TLS_VERIFICATION_CODES = new Set([
28
+ "ERR_TLS_CERT_ALTNAME_INVALID",
29
+ "UNABLE_TO_VERIFY_LEAF_SIGNATURE",
30
+ "UNABLE_TO_GET_ISSUER_CERT",
31
+ "UNABLE_TO_GET_ISSUER_CERT_LOCALLY",
32
+ "SELF_SIGNED_CERT_IN_CHAIN",
33
+ "DEPTH_ZERO_SELF_SIGNED_CERT",
34
+ "CERT_HAS_EXPIRED",
35
+ "CERT_NOT_YET_VALID",
36
+ "CERT_UNTRUSTED",
37
+ "CERT_REJECTED",
38
+ "CERT_SIGNATURE_FAILURE",
39
+ "CERT_CHAIN_TOO_LONG",
40
+ "INVALID_CA",
41
+ "HOSTNAME_MISMATCH",
42
+ ]);
43
+
44
+ /**
45
+ * @typedef {{ readonly host: string, readonly port: number }} ProxyTarget
46
+ * @typedef {{ readonly [name: string]: string | undefined }} ProxyEnvironment
47
+ * @typedef {{
48
+ * readonly protocol: "http:" | "https:",
49
+ * readonly host: string,
50
+ * readonly port: number,
51
+ * readonly label: string,
52
+ * readonly authorization?: string,
53
+ * }} HttpProxy
54
+ * @typedef {(target: ProxyTarget) => import("node:stream").Duplex | Promise<import("node:stream").Duplex>} PostgresSocketFactory
55
+ * @typedef {{ readonly kind: "direct" } | { readonly kind: "proxy", readonly proxy: HttpProxy }} PostgresTransport
56
+ */
57
+
58
+ /**
59
+ * Why a proxy setting cannot be used: a value that is not a URL, or one whose scheme is not `http:` or `https:`.
60
+ * `subject` names where the setting came from, never its value, which can hold credentials.
61
+ */
62
+ export class ProxySettingError extends Error {
63
+ /**
64
+ * @param {string} subject
65
+ * @param {string} problem
66
+ */
67
+ constructor(subject, problem) {
68
+ super(`${subject} ${problem}`);
69
+ this.name = "ProxySettingError";
70
+ }
71
+ }
72
+
73
+ /** `host` as the proxy rules compare it: lowercase, without IPv6 brackets or a trailing dot. */
74
+ function normalizedHost(/** @type {string} */ host) {
75
+ let name = host.replace(/^\[(.+)\]$/, "$1").toLowerCase();
76
+ if (name.length > 1 && name.endsWith(".")) name = name.slice(0, -1);
77
+ return name;
78
+ }
79
+
80
+ /**
81
+ * The entries of a `NO_PROXY` value, read as Atomic's HTTPS clients (Undici's `EnvHttpProxyAgent`) read them: separated
82
+ * by commas or white space; each a host name, an IPv4 address, a bare or bracketed IPv6 address, or `*`, with an
83
+ * optional `:port`; a leading `.` or `*.` makes it match subdomains, and `*.` excludes the domain itself.
84
+ * @param {string} value
85
+ * @returns {{ hostname: string, port: number, wildcard: boolean }[]}
86
+ */
87
+ function noProxyEntries(value) {
88
+ /** @type {{ hostname: string, port: number, wildcard: boolean }[]} */
89
+ const entries = [];
90
+ for (const entry of value.split(/[,\s]/)) {
91
+ if (entry === "") continue;
92
+ let hostname;
93
+ let port;
94
+ const bracketed = /^\[(.+)\]:(\d+)$/.exec(entry);
95
+ if (bracketed !== null) {
96
+ hostname = /** @type {string} */ (bracketed[1]);
97
+ port = Number.parseInt(/** @type {string} */ (bracketed[2]), 10);
98
+ } else {
99
+ const unbracketed = entry.replace(/^\[(.+)\]$/, "$1");
100
+ const colons = (unbracketed.match(/:/g) ?? []).length;
101
+ const parsed = colons === 1 ? /^(.+):(\d+)$/.exec(unbracketed) : null;
102
+ hostname = parsed === null ? unbracketed : /** @type {string} */ (parsed[1]);
103
+ port = parsed === null ? 0 : Number.parseInt(/** @type {string} */ (parsed[2]), 10);
104
+ }
105
+ entries.push({
106
+ hostname: hostname
107
+ .replace(/^\*?\./, "")
108
+ .replace(/^(.+)\.$/, "$1")
109
+ .toLowerCase(),
110
+ port,
111
+ wildcard: entry.startsWith("*"),
112
+ });
113
+ }
114
+ return entries;
115
+ }
116
+
117
+ /**
118
+ * Whether a `NO_PROXY` value exempts `host` on `port`, as Atomic's HTTPS clients decide it: an entry with a port matches
119
+ * that port only; `*` matches every host; a host name matches itself and its subdomains, and `*.name` only subdomains.
120
+ * @param {string} host
121
+ * @param {number} port
122
+ * @param {string} value
123
+ */
124
+ export function noProxyMatches(host, port, value) {
125
+ const name = normalizedHost(host);
126
+ for (const entry of noProxyEntries(value)) {
127
+ if (entry.port !== 0 && entry.port !== port) continue;
128
+ if (entry.hostname === "*") return true;
129
+ if (!entry.wildcard && name === entry.hostname) return true;
130
+ if (name.endsWith(`.${entry.hostname}`)) return true;
131
+ }
132
+ return false;
133
+ }
134
+
135
+ /**
136
+ * The environment's proxy for a connection to PostgreSQL, and the variable it came from, or undefined when none is set:
137
+ * `https_proxy` (else `HTTPS_PROXY`) as for any HTTPS request, then `all_proxy` (else `ALL_PROXY`) when it names an
138
+ * HTTP proxy, then `http_proxy` (else `HTTP_PROXY`), which Atomic's HTTPS clients also fall back to. A lowercase variable
139
+ * wins over its uppercase form even when empty, as there; an empty value sets no proxy.
140
+ * @param {ProxyEnvironment} env
141
+ * @returns {{ readonly variable: string, readonly value: string } | undefined}
142
+ */
143
+ export function proxySetting(env) {
144
+ for (const [lower, upper] of [
145
+ ["https_proxy", "HTTPS_PROXY"],
146
+ ["all_proxy", "ALL_PROXY"],
147
+ ["http_proxy", "HTTP_PROXY"],
148
+ ]) {
149
+ const variable = env[/** @type {string} */ (lower)] !== undefined ? lower : upper;
150
+ const value = env[/** @type {string} */ (variable)]?.trim() ?? "";
151
+ if (value === "") continue;
152
+ // ALL_PROXY often names a SOCKS proxy for other tools; only an HTTP one can carry a tunnel here.
153
+ if (lower === "all_proxy" && !/^(?:https?:\/\/|[^:/]+(?::\d+)?\/?$)/i.test(value)) continue;
154
+ return { variable: /** @type {string} */ (variable), value };
155
+ }
156
+ return undefined;
157
+ }
158
+
159
+ /**
160
+ * The proxy a setting names: an `http:` or `https:` URL, or a bare `host:port`, read as `http:`. Credentials in it are
161
+ * sent as `Proxy-Authorization: Basic`, and left out of `label`, the form failures name the proxy by.
162
+ * @param {string} value
163
+ * @param {string} subject Where the value came from, as a failure names it.
164
+ * @returns {HttpProxy}
165
+ */
166
+ export function parseProxy(value, subject) {
167
+ /** @type {URL} */
168
+ let url;
169
+ try {
170
+ url = new URL(/^[a-z][a-z0-9+.-]*:\/\//i.test(value) ? value : `http://${value}`);
171
+ } catch {
172
+ throw new ProxySettingError(subject, "is not a proxy URL");
173
+ }
174
+ if (url.protocol !== "http:" && url.protocol !== "https:")
175
+ throw new ProxySettingError(
176
+ subject,
177
+ `names a ${url.protocol} proxy; PostgreSQL connections can only be tunnelled through an http:// or https:// proxy`,
178
+ );
179
+ if (url.hostname === "") throw new ProxySettingError(subject, "names no proxy host");
180
+ const protocol = /** @type {"http:" | "https:"} */ (url.protocol);
181
+ const port = url.port === "" ? (protocol === "https:" ? 443 : 80) : Number(url.port);
182
+ const host = url.hostname.replace(/^\[(.+)\]$/, "$1");
183
+ const label = `${protocol}//${url.host}`;
184
+ if (url.username === "" && url.password === "") return { protocol, host, port, label };
185
+ /** @type {string} */
186
+ let credentials;
187
+ try {
188
+ credentials = `${decodeURIComponent(url.username)}:${decodeURIComponent(url.password)}`;
189
+ } catch {
190
+ throw new ProxySettingError(subject, "has credentials that are not valid percent-encoding");
191
+ }
192
+ return {
193
+ protocol,
194
+ host,
195
+ port,
196
+ label,
197
+ authorization: `Basic ${Buffer.from(credentials, "utf8").toString("base64")}`,
198
+ };
199
+ }
200
+
201
+ /**
202
+ * `host` in the canonical form a URL gives an address, such as `127.0.0.1` for `127.1` and `::1` for
203
+ * `0:0:0:0:0:0:0:1`, which name the same address to the resolver; a name, or a host a URL cannot hold, as it is.
204
+ */
205
+ function canonicalHost(/** @type {string} */ host) {
206
+ try {
207
+ return normalizedHost(new URL(`http://${host.includes(":") ? `[${host}]` : host}/`).hostname);
208
+ } catch {
209
+ return host;
210
+ }
211
+ }
212
+
213
+ /**
214
+ * Whether `host` is this machine: a socket directory, a loopback name or a loopback address, in any spelling a URL or
215
+ * the resolver reads as one, such as `127.1`, `localhost.` or `::ffff:127.0.0.1`.
216
+ */
217
+ export function isLocalTarget(/** @type {string} */ host) {
218
+ const name = normalizedHost(host);
219
+ if (name === "" || name.startsWith("/")) return true;
220
+ const canonical = canonicalHost(name);
221
+ return (
222
+ canonical === "localhost" ||
223
+ canonical === "::1" ||
224
+ /^127(?:\.\d{1,3}){3}$/.test(canonical) ||
225
+ // An IPv4-mapped IPv6 address of 127.0.0.0/8, which a URL writes as `::ffff:7fxx:xxxx`.
226
+ /^::ffff:7f[0-9a-f]{2}:[0-9a-f]{1,4}$/.test(canonical)
227
+ );
228
+ }
229
+
230
+ /**
231
+ * How a connection to `target` is opened (#5473): through the proxy `option` names (`"none"` for a direct connection),
232
+ * else through the environment's proxy unless `NO_PROXY` exempts the target; a socket directory and a loopback target
233
+ * are reached directly whatever the environment says, as a proxy elsewhere could not reach them.
234
+ * @param {ProxyTarget} target
235
+ * @param {ProxyEnvironment} env
236
+ * @param {string} [option]
237
+ * @returns {PostgresTransport}
238
+ */
239
+ export function postgresTransport(target, env, option) {
240
+ if (option !== undefined) {
241
+ if (option.trim().toLowerCase() === "none") return { kind: "direct" };
242
+ return { kind: "proxy", proxy: parseProxy(option.trim(), "The proxy option") };
243
+ }
244
+ if (isLocalTarget(target.host)) return { kind: "direct" };
245
+ const setting = proxySetting(env);
246
+ if (setting === undefined) return { kind: "direct" };
247
+ const noProxy = env.no_proxy ?? env.NO_PROXY ?? "";
248
+ // Matched against the host's canonical form, as Atomic's HTTPS clients match a URL's host: `10.1` is `10.0.0.1`.
249
+ if (noProxyMatches(canonicalHost(target.host), target.port, noProxy)) return { kind: "direct" };
250
+ return { kind: "proxy", proxy: parseProxy(setting.value, setting.variable) };
251
+ }
252
+
253
+ /** `host:port` as a tunnel request names it, with an IPv6 address in brackets. */
254
+ export function authorityOf(/** @type {ProxyTarget} */ target) {
255
+ const host = target.host.replace(/^\[(.+)\]$/, "$1");
256
+ return `${isIP(host) === 6 ? `[${host}]` : host}:${target.port}`;
257
+ }
258
+
259
+ /**
260
+ * A tunnel a proxy did not open: `permanent` when the proxy refused it (a 4xx answer, an answer that is not HTTP, or an
261
+ * https proxy whose certificate was not accepted), which asking again would not change; otherwise the proxy or what it
262
+ * connects to could not be reached for now. The message names the proxy without its credentials, and the target.
263
+ */
264
+ export class ProxyTunnelError extends Error {
265
+ /**
266
+ * @param {"proxy-refused" | "proxy-auth-required" | "proxy-upstream" | "proxy-protocol" | "proxy-closed" | "proxy-unreachable" | "proxy-timeout"} code
267
+ * @param {string} message
268
+ * @param {{ proxy: string, target: string, permanent: boolean, status?: number, cause?: unknown }} details
269
+ */
270
+ constructor(code, message, details) {
271
+ super(message, details.cause === undefined ? undefined : { cause: details.cause });
272
+ this.name = "ProxyTunnelError";
273
+ this.code = code;
274
+ this.proxy = details.proxy;
275
+ this.target = details.target;
276
+ this.permanent = details.permanent;
277
+ if (details.status !== undefined) this.status = details.status;
278
+ }
279
+ }
280
+
281
+ /** A proxy's status text, as a failure may repeat it: printable ASCII, bounded. */
282
+ function reasonText(/** @type {string} */ text) {
283
+ return text.replace(/[^\x20-\x7e]/g, "").trim().slice(0, MAX_REASON_LENGTH);
284
+ }
285
+
286
+ /** The code of a TLS verification failure along `cause`, or undefined. */
287
+ function tlsVerificationCode(/** @type {unknown} */ cause) {
288
+ const code = /** @type {{ code?: unknown }} */ (cause ?? {}).code;
289
+ return typeof code === "string" && TLS_VERIFICATION_CODES.has(code) ? code : undefined;
290
+ }
291
+
292
+ /**
293
+ * Opens a connection to `proxy` and asks it, with `CONNECT`, for a tunnel to `target`. Resolves with the connection
294
+ * once the proxy answers 2xx, carrying only the target's bytes from then on; rejects with a `ProxyTunnelError` when the
295
+ * proxy cannot be reached, refuses, does not answer HTTP, or does not answer within `timeoutMs`.
296
+ * @param {HttpProxy} proxy
297
+ * @param {ProxyTarget} target
298
+ * @param {{ timeoutMs?: number }} [options]
299
+ * @returns {Promise<import("node:net").Socket>}
300
+ */
301
+ export function openProxyTunnel(proxy, target, options = {}) {
302
+ const timeoutMs = options.timeoutMs ?? PROXY_ANSWER_TIMEOUT_MS;
303
+ const authority = authorityOf(target);
304
+ return new Promise((resolve, reject) => {
305
+ const socket =
306
+ proxy.protocol === "https:"
307
+ ? connectTls({
308
+ host: proxy.host,
309
+ port: proxy.port,
310
+ ...(isIP(proxy.host) === 0 ? { servername: proxy.host } : {}),
311
+ ALPNProtocols: ["http/1.1"],
312
+ })
313
+ : connectNet({ host: proxy.host, port: proxy.port });
314
+ let connected = false;
315
+ let settled = false;
316
+ let answerBytes = 0;
317
+ let line = "";
318
+ let afterCR = false;
319
+ /** @type {RegExpExecArray | null} */
320
+ let status = null;
321
+ /**
322
+ * @param {ConstructorParameters<typeof ProxyTunnelError>[0]} code
323
+ * @param {string} message
324
+ * @param {boolean} permanent
325
+ * @param {{ status?: number, cause?: unknown }} [extra]
326
+ */
327
+ const fail = (code, message, permanent, extra = {}) => {
328
+ if (settled) return;
329
+ settled = true;
330
+ clearTimeout(timer);
331
+ socket.destroy();
332
+ reject(new ProxyTunnelError(code, message, { proxy: proxy.label, target: authority, permanent, ...extra }));
333
+ };
334
+ const timer = setTimeout(
335
+ () =>
336
+ connected
337
+ ? fail(
338
+ "proxy-timeout",
339
+ `the proxy ${proxy.label} did not answer the tunnel request to ${authority} within ${timeoutMs} ms`,
340
+ false,
341
+ )
342
+ : // No connection to the proxy at all, as at an address that drops packets: nothing was asked yet.
343
+ fail(
344
+ "proxy-unreachable",
345
+ `the proxy ${proxy.label} could not be reached for the tunnel to ${authority} (no connection within ${timeoutMs} ms)`,
346
+ false,
347
+ ),
348
+ timeoutMs,
349
+ );
350
+ socket.once(proxy.protocol === "https:" ? "secureConnect" : "connect", () => {
351
+ connected = true;
352
+ socket.write(
353
+ `CONNECT ${authority} HTTP/1.1\r\nHost: ${authority}\r\n${
354
+ proxy.authorization === undefined ? "" : `Proxy-Authorization: ${proxy.authorization}\r\n`
355
+ }\r\n`,
356
+ );
357
+ });
358
+ socket.on("error", (/** @type {Error} */ cause) => {
359
+ const tls = tlsVerificationCode(cause);
360
+ if (tls !== undefined)
361
+ return fail(
362
+ "proxy-unreachable",
363
+ `the proxy ${proxy.label} showed a TLS certificate that was not accepted (${tls}), so no tunnel to ${authority} was opened`,
364
+ true,
365
+ { cause },
366
+ );
367
+ const code = /** @type {{ code?: unknown }} */ (cause).code;
368
+ const detail = typeof code === "string" ? code : reasonText(cause.message);
369
+ if (connected)
370
+ return fail(
371
+ "proxy-closed",
372
+ `the connection to the proxy ${proxy.label} failed before it answered the tunnel request to ${authority} (${detail})`,
373
+ false,
374
+ { cause },
375
+ );
376
+ fail(
377
+ "proxy-unreachable",
378
+ `the proxy ${proxy.label} could not be reached for the tunnel to ${authority} (${detail})`,
379
+ false,
380
+ { cause },
381
+ );
382
+ });
383
+ const invalidAnswer = () =>
384
+ fail(
385
+ "proxy-protocol",
386
+ `the proxy ${proxy.label} answered the tunnel request to ${authority} with something other than HTTP`,
387
+ true,
388
+ );
389
+ // A connection that ends after a CR was cut, as one that ends anywhere else in the answer is (#5670).
390
+ socket.on("close", () => {
391
+ fail(
392
+ "proxy-closed",
393
+ `the proxy ${proxy.label} closed the connection before answering the tunnel request to ${authority}`,
394
+ false,
395
+ );
396
+ });
397
+ /**
398
+ * @param {number} code
399
+ * @param {string} text
400
+ * @param {Buffer} rest Bytes after the final response in the same read.
401
+ */
402
+ const finish = (code, text, rest) => {
403
+ const reason = reasonText(text);
404
+ const answered = reason === "" ? `${code}` : `${code} ${reason}`;
405
+ if (code >= 200 && code < 300) {
406
+ if (settled) return;
407
+ settled = true;
408
+ clearTimeout(timer);
409
+ socket.off("data", onData);
410
+ socket.removeAllListeners("error");
411
+ socket.removeAllListeners("close");
412
+ socket.pause();
413
+ if (rest.length > 0) socket.unshift(rest);
414
+ resolve(/** @type {import("node:net").Socket} */ (socket));
415
+ return;
416
+ }
417
+ if (code === 407)
418
+ return fail(
419
+ "proxy-auth-required",
420
+ `the proxy ${proxy.label} refused the tunnel to ${authority} without accepted credentials (${answered})`,
421
+ true,
422
+ { status: code },
423
+ );
424
+ if (code >= 500)
425
+ return fail(
426
+ "proxy-upstream",
427
+ `the proxy ${proxy.label} could not open the tunnel to ${authority} (${answered})`,
428
+ false,
429
+ { status: code },
430
+ );
431
+ fail("proxy-refused", `the proxy ${proxy.label} refused the tunnel to ${authority} (${answered})`, true, {
432
+ status: code,
433
+ });
434
+ };
435
+ /** @param {Buffer} chunk */
436
+ const onData = (chunk) => {
437
+ for (let i = 0; i < chunk.length && answerBytes < MAX_PROXY_ANSWER_BYTES; i++) {
438
+ answerBytes++;
439
+ const byte = /** @type {number} */ (chunk[i]);
440
+ if (afterCR && byte !== 0x0a) {
441
+ // A CR that no LF follows: a space inside a header field (RFC 9112 2.2), but no status line holds one (#5670).
442
+ if (status === null) return invalidAnswer();
443
+ line += " ";
444
+ }
445
+ afterCR = byte === 0x0d;
446
+ if (afterCR) {
447
+ // Nor does `HTTP/`.
448
+ if (status === null && line.length < 5) return invalidAnswer();
449
+ continue;
450
+ }
451
+ if (byte !== 0x0a) {
452
+ line += String.fromCharCode(byte);
453
+ if (status === null && line.length <= 5 && !"HTTP/".startsWith(line)) return invalidAnswer();
454
+ continue;
455
+ }
456
+ if (status === null) {
457
+ status = /^HTTP\/1\.[01] (\d{3})(?: (.*))?$/.exec(line);
458
+ if (status === null) return invalidAnswer();
459
+ } else if (line === "") {
460
+ const code = Number(status[1]);
461
+ // 101 switches protocols instead of continuing to a final CONNECT response.
462
+ if (code < 100 || code === 101 || code >= 200)
463
+ return finish(code, status[2] ?? "", chunk.subarray(i + 1));
464
+ status = null;
465
+ }
466
+ line = "";
467
+ }
468
+ if (answerBytes === MAX_PROXY_ANSWER_BYTES)
469
+ fail(
470
+ "proxy-protocol",
471
+ `the proxy ${proxy.label} exceeded ${MAX_PROXY_ANSWER_BYTES} bytes of response headers for the tunnel to ${authority}`,
472
+ true,
473
+ );
474
+ };
475
+ socket.on("data", onData);
476
+ });
477
+ }
478
+
479
+ /**
480
+ * The stream pg is given for a connection opened by `open`, such as a proxy tunnel: pg calls `connect(port, host)` on it
481
+ * as on a socket, and it emits `connect` once `open` resolved with a stream to the server, then carries pg's bytes,
482
+ * TLS included, to and from that stream. A failure of `open` is the stream's error.
483
+ */
484
+ export class OpenedSocket extends Duplex {
485
+ /** @param {PostgresSocketFactory} open */
486
+ constructor(open) {
487
+ super({ allowHalfOpen: false });
488
+ /** @type {PostgresSocketFactory} */
489
+ this.open = open;
490
+ /** @type {import("node:stream").Duplex | undefined} */
491
+ this.inner = undefined;
492
+ /** Whether a connection is being opened, as a socket says it. */
493
+ this.connecting = false;
494
+ /** @type {[Buffer | string, BufferEncoding, (error?: Error | null) => void][]} */
495
+ this.waiting = [];
496
+ /** @type {boolean | undefined} */
497
+ this.noDelay = undefined;
498
+ /** @type {[boolean, number | undefined] | undefined} */
499
+ this.keepAlive = undefined;
500
+ this.referenced = true;
501
+ }
502
+
503
+ /**
504
+ * @param {number | string} port
505
+ * @param {string} [host]
506
+ */
507
+ connect(port, host) {
508
+ this.connecting = true;
509
+ const target = { host: host ?? "localhost", port: Number(port) };
510
+ Promise.resolve()
511
+ .then(() => this.open(target))
512
+ .then(
513
+ (inner) => {
514
+ if (this.destroyed) {
515
+ inner.destroy();
516
+ return;
517
+ }
518
+ this.attach(inner);
519
+ },
520
+ (/** @type {Error} */ error) => this.destroy(error),
521
+ );
522
+ return this;
523
+ }
524
+
525
+ /** @param {import("node:stream").Duplex} inner */
526
+ attach(inner) {
527
+ this.inner = inner;
528
+ const socket = /** @type {Partial<import("node:net").Socket>} */ (inner);
529
+ if (this.noDelay !== undefined) socket.setNoDelay?.(this.noDelay);
530
+ if (this.keepAlive !== undefined) socket.setKeepAlive?.(...this.keepAlive);
531
+ if (!this.referenced) socket.unref?.();
532
+ inner.on("data", (/** @type {Buffer} */ chunk) => {
533
+ if (!this.push(chunk)) inner.pause();
534
+ });
535
+ inner.on("end", () => this.push(null));
536
+ inner.on("error", (/** @type {Error} */ error) => this.destroy(error));
537
+ inner.on("close", () => {
538
+ if (!this.destroyed) this.destroy();
539
+ });
540
+ inner.resume();
541
+ this.connecting = false;
542
+ for (const [chunk, encoding, callback] of this.waiting.splice(0)) inner.write(chunk, encoding, callback);
543
+ this.emit("connect");
544
+ this.emit("ready");
545
+ }
546
+
547
+ _read() {
548
+ this.inner?.resume();
549
+ }
550
+
551
+ /**
552
+ * @param {Buffer | string} chunk
553
+ * @param {BufferEncoding} encoding
554
+ * @param {(error?: Error | null) => void} callback
555
+ */
556
+ _write(chunk, encoding, callback) {
557
+ if (this.inner === undefined) this.waiting.push([chunk, encoding, callback]);
558
+ else this.inner.write(chunk, encoding, callback);
559
+ }
560
+
561
+ /** @param {(error?: Error | null) => void} callback */
562
+ _final(callback) {
563
+ if (this.inner === undefined) return callback();
564
+ this.inner.end(callback);
565
+ }
566
+
567
+ /**
568
+ * @param {Error | null} error
569
+ * @param {(error?: Error | null) => void} callback
570
+ */
571
+ _destroy(error, callback) {
572
+ this.inner?.destroy();
573
+ for (const [, , waiting] of this.waiting.splice(0)) waiting(error ?? new Error("The connection closed"));
574
+ // A TLS session on this stream that ends it, as when the server's certificate was refused, reports why on its
575
+ // next tick: this stream closes after that, so pg sees the reason before the end, as it does on a socket.
576
+ setImmediate(() => callback(error));
577
+ }
578
+
579
+ /** @param {boolean} [noDelay] */
580
+ setNoDelay(noDelay = true) {
581
+ this.noDelay = noDelay;
582
+ /** @type {Partial<import("node:net").Socket> | undefined} */ (this.inner)?.setNoDelay?.(noDelay);
583
+ return this;
584
+ }
585
+
586
+ /**
587
+ * @param {boolean} [enable]
588
+ * @param {number} [initialDelay]
589
+ */
590
+ setKeepAlive(enable = false, initialDelay) {
591
+ this.keepAlive = [enable, initialDelay];
592
+ /** @type {Partial<import("node:net").Socket> | undefined} */ (this.inner)?.setKeepAlive?.(enable, initialDelay);
593
+ return this;
594
+ }
595
+
596
+ ref() {
597
+ this.referenced = true;
598
+ /** @type {Partial<import("node:net").Socket> | undefined} */ (this.inner)?.ref?.();
599
+ return this;
600
+ }
601
+
602
+ unref() {
603
+ this.referenced = false;
604
+ /** @type {Partial<import("node:net").Socket> | undefined} */ (this.inner)?.unref?.();
605
+ return this;
606
+ }
607
+ }
608
+
609
+ /**
610
+ * The function that opens a connection to a target through `transport`, or undefined for a direct connection, which
611
+ * pg opens itself.
612
+ * @param {PostgresTransport} transport
613
+ * @returns {PostgresSocketFactory | undefined}
614
+ */
615
+ export function socketOpener(transport) {
616
+ if (transport.kind === "direct") return undefined;
617
+ const { proxy } = transport;
618
+ return (target) => openProxyTunnel(proxy, target);
619
+ }