@effect/sql-pg 4.0.0-rc.115 → 4.0.0-rc.117

package/dist/PgConnection.js

@@ -17,6 +17,7 @@ import { randomBytes } from "node:crypto";
 import * as Net from "node:net";
 import * as Tls from "node:tls";
 import { internalsKey } from "./internal/connection.js";
+import * as PasswordInternal from "./internal/password.js";
 import { classifySqlState, validateChannelName } from "./internal/sqlError.js";
 import * as PgAuth from "./PgAuth.js";
 import * as PgProtocol from "./PgProtocol.js";
@@ -49,19 +50,22 @@ export const PgConnection = /*#__PURE__*/Context.Service("@effect/sql-pg/PgConne
  *
  * **Details**
  *
- * The transport, optional `SSLRequest`, startup, and authentication steps run
- * under `connectTimeout` (5 seconds by default). The effect resolves once the
- * backend sends `ReadyForQuery`. When the scope closes, the
- * session sends `Terminate` and ends the socket.
+ * Password resolution, transport, optional `SSLRequest`, startup, and
+ * authentication run under `connectTimeout` (5 seconds by default). The effect
+ * resolves when the backend sends `ReadyForQuery`. Closing the scope sends
+ * `Terminate` and ends the socket.
  *
- * When `ssl` is enabled, a server that rejects `SSLRequest` fails the
- * connection. Unix sockets and custom streams should set `ssl.servername`
- * explicitly.
+ * Use `sslmode=require` or explicit `ssl: true` to require encryption.
+ * Unix sockets and custom streams should set `ssl.servername` explicitly.
  *
  * @category constructors
  * @since 4.0.0
  */
-export const make = options => Effect.flatMap(resolveConfig(options), config => Effect.acquireRelease(Effect.map(connect(config), session => new PgConnectionImpl(options, config, session, options.types)), connection => Effect.sync(() => connection.closeUnsafe()), {
+export const make = options => Effect.flatMap(resolveConfig(options), config => Effect.acquireRelease(Effect.gen(function* () {
+  const password = yield* PasswordInternal.resolve(config.password);
+  const session = yield* connect(config, password);
+  return new PgConnectionImpl(options, config, session, options.types);
+}), connection => Effect.sync(() => connection.closeUnsafe()), {
   interruptible: true
 }).pipe(Effect.timeoutOrElse({
   duration: config.connectTimeout,
@@ -74,6 +78,9 @@ export const make = options => Effect.flatMap(resolveConfig(options), config =>
   }))
 })));
 const abortDrainTimeoutMillis = 5000;
+const abortDrainGraceMillis = 10;
+/** PostgreSQL `query_canceled` SQLSTATE. */
+const queryCanceledCode = "57014";
 const cancelRequestTimeoutMillis = 5000;
 /** How many statements a multiplexed session keeps on the wire at once. */
 const maxPipelineDepth = 128;
@@ -98,8 +105,9 @@ class PgConnectionImpl {
   consumer;
   deadWith;
   closed = false;
+  cancelPending = false;
   channels = /*#__PURE__*/new Map();
-  fatalHooks = /*#__PURE__*/new Set();
+  retireHooks = /*#__PURE__*/new Set();
   /** Queued but not yet written; drained into `pipelineInFlight` on flush. */
   pipelinePending = [];
   /** Written and awaiting their `ReadyForQuery`, oldest first. */
@@ -122,7 +130,7 @@ class PgConnectionImpl {
     this[internalsKey] = {
       base: this,
       deadError: () => this.deadWith,
-      fatalHooks: this.fatalHooks
+      retireHooks: this.retireHooks
     };
     this.pinnedView = new PinnedPgConnection(this);
     session.socket.on("data", this.onData);
@@ -144,6 +152,15 @@ class PgConnectionImpl {
   dispatch = message => {
     if (this.deadWith !== undefined) return;
     switch (message._tag) {
+      case "ErrorResponse":
+        if (message.fields.code === queryCanceledCode) this.cancelPending = false;
+        break;
+      case "ReadyForQuery":
+        if (this.cancelPending) {
+          this.cancelPending = false;
+          this.retire();
+        }
+        break;
       case "NotificationResponse":
         {
           const queues = this.channels.get(message.channel);
@@ -181,12 +198,15 @@ class PgConnectionImpl {
     consumer?.onFatal(error);
     const sets = Array.from(this.channels.values());
     this.channels.clear();
+    const cause = this.closed ? Cause.interrupt() : Cause.fail(error);
     for (const set of sets) {
-      for (const queue of set) Queue.failCauseUnsafe(queue, Cause.interrupt());
-    }
-    if (!this.closed) {
-      for (const hook of this.fatalHooks) hook();
+      for (const queue of set) Queue.failCauseUnsafe(queue, cause);
     }
+    this.retire();
+  }
+  retire() {
+    if (this.closed) return;
+    for (const hook of this.retireHooks) hook();
   }
   closeUnsafe() {
     this.closed = true;
@@ -373,7 +393,9 @@ class PgConnectionImpl {
   /** Sends a `CancelRequest` for this session on a side connection. */
   cancel = /*#__PURE__*/Effect.suspend(() => {
     if (this.deadWith !== undefined) return Effect.void;
-    return sendCancelRequest(this.resolved, this.session.processId, this.session.secretKey);
+    this.cancelPending = true;
+    if (this.consumer === undefined) this.retire();
+    return sendCancelRequest(this.resolved, this.session);
   });
   pin = /*#__PURE__*/Effect.suspend(() => {
     const reserve = this[internalsKey].reserve;
@@ -457,13 +479,7 @@ const inferScalar = value => {
       // or timestamp column the way it did with the text-protocol drivers.
       return inferredParameter(0, value);
   }
-  if (value instanceof Date) {
-    const time = value.getTime();
-    if (Number.isNaN(time)) throw new PgTypes.CodecError({
-      message: "Invalid Date parameter"
-    });
-    return inferredParameter(PgTypes.OID.timestamptz, time);
-  }
+  if (value instanceof Date) return inferredParameter(PgTypes.OID.timestamptz, value);
   if (value instanceof Uint8Array) return inferredParameter(PgTypes.OID.bytea, value);
   if (value instanceof Int8Array) {
     return inferredParameter(PgTypes.OID.bytea, new Uint8Array(value.buffer, value.byteOffset, value.byteLength));
@@ -662,6 +678,7 @@ const encodeQuery = (sql, params, registry, encodeBind, cache) => {
 class PreparedCache {
   max;
   statements = /*#__PURE__*/new Map();
+  namespace = /*#__PURE__*/randomBytes(8).toString("hex");
   closes;
   counter = 0;
   constructor(max) {
@@ -679,7 +696,7 @@ class PreparedCache {
       return found;
     }
     const prepared = {
-      name: `effect${++this.counter}`,
+      name: `effect_${this.namespace}_${++this.counter}`,
       key,
       ready: false,
       parsing: false,
@@ -1018,6 +1035,21 @@ class QueryMachine {
 }
 const emptyRows = [];
 const emptyValues = [];
+/** Drains an aborted statement, sending a cancel after a short grace period and failing if it stalls. */
+const drainAborted = (conn, timeoutMessage, abort) => {
+  const drained = Deferred.makeUnsafe();
+  const timeout = setTimeout(() => conn.fatal(connectionQueryError(new Error(timeoutMessage), `PgConnection: ${timeoutMessage}`)), abortDrainTimeoutMillis);
+  abort(() => {
+    clearTimeout(timeout);
+    Deferred.doneUnsafe(drained, Effect.void);
+  });
+  const grace = Effect.callback(resume => {
+    const timer = setTimeout(() => resume(Effect.void), abortDrainGraceMillis);
+    return Effect.sync(() => clearTimeout(timer));
+  });
+  const cancelAndDrain = Effect.andThen(conn.cancel, Deferred.await(drained));
+  return Effect.andThen(Effect.raceFirst(Deferred.await(drained), grace), Effect.suspend(() => Deferred.isDoneUnsafe(drained) ? Effect.void : cancelAndDrain));
+};
 /** One cycle on a connection that carries a single statement at a time. */
 const runQuery = (conn, plan, wantRows) => Effect.callback(resume => {
   if (conn.deadWith !== undefined) {
@@ -1037,19 +1069,12 @@ const runQuery = (conn, plan, wantRows) => Effect.callback(resume => {
   } catch (cause) {
     conn.fatal(connectionQueryError(cause, "PgConnection: Failed to write query"));
   }
-  // On interruption: cancel the statement and drain the connection back to
-  // ReadyForQuery so it stays usable, destroying it when the drain stalls.
   return Effect.suspend(() => {
     if (machine.isDone()) return Effect.void;
-    const wait = Effect.callback(resumeWait => {
-      const timer = setTimeout(() => conn.fatal(connectionQueryError(new Error("Query cancellation timed out"), "PgConnection: Query cancellation timed out")), abortDrainTimeoutMillis);
-      machine.abort(() => {
-        clearTimeout(timer);
-        conn.consumer = undefined;
-        resumeWait(Effect.void);
-      });
-    });
-    return Effect.andThen(conn.cancel, wait);
+    return drainAborted(conn, "Query cancellation timed out", onDrained => machine.abort(() => {
+      conn.consumer = undefined;
+      onDrained();
+    }));
   });
 });
 const emptyFields = [];
@@ -1262,21 +1287,14 @@ const streamRows = (conn, pin, sql, params) => Stream.fromChannel(Channel.fromTr
     if (done || aborted) return;
     if (pending !== undefined) deliver();else if (buffer.length >= streamPauseThreshold) setPaused(true);
   };
-  // On early abort: cancel the statement and drain back to ReadyForQuery so
-  // the pinned connection stays usable, destroying it when the drain stalls.
   yield* Scope.addFinalizer(scope, Effect.suspend(() => {
     if (done) return Effect.void;
     aborted = true;
-    setPaused(false);
-    const wait = Effect.callback(resumeWait => {
-      if (done) return resumeWait(Effect.void);
-      const timer = setTimeout(() => conn.fatal(connectionQueryError(new Error("Stream cancellation timed out"), "PgConnection: Stream cancellation timed out")), abortDrainTimeoutMillis);
-      drainDone = () => {
-        clearTimeout(timer);
-        resumeWait(Effect.void);
-      };
+    const drain = drainAborted(conn, "Stream cancellation timed out", onDrained => {
+      drainDone = onDrained;
     });
-    return Effect.andThen(conn.cancel, wait);
+    setPaused(false);
+    return drain;
   }));
   conn.consumer = {
     onMessage,
@@ -1330,7 +1348,7 @@ const listenChannel = (conn, pin, channel) => Effect.uninterruptibleMask(restore
     return queue;
   })).pipe(Effect.tapCause(cause => Scope.close(scope, Exit.failCause(cause))));
 }));
-const sendCancelRequest = (config, pid, secret) => Effect.callback(resume => {
+const sendCancelRequest = (config, session) => Effect.callback(resume => {
   let done = false;
   let socket;
   let timer;
@@ -1342,8 +1360,8 @@ const sendCancelRequest = (config, pid, secret) => Effect.callback(resume => {
     resume(Effect.void);
   };
   const frame = PgProtocol.encodeCancelRequest({
-    pid,
-    secret
+    pid: session.processId,
+    secret: session.secretKey
   });
   // After the frame is written the server processes the request and closes
   // the connection, which lands in the `close` handler.
@@ -1354,8 +1372,8 @@ const sendCancelRequest = (config, pid, secret) => Effect.callback(resume => {
     if (config.ssl === false) return send();
     socket.once("data", chunk => {
       if (done) return;
-      // Never send the cancel secret over a connection the server refused
-      // to upgrade.
+      // A TLS session's cancel secret must stay encrypted.
+      if (chunk.length === 1 && chunk[0] === 0x4e && config.sslOptional && !session.encrypted) return send();
       if (chunk.length !== 1 || chunk[0] !== 0x53) return finish();
       const raw = socket;
       raw.off("error", finish);
@@ -1390,9 +1408,10 @@ const sendCancelRequest = (config, pid, secret) => Effect.callback(resume => {
   if (config.stream !== undefined) begin();else socket.once("connect", begin);
   return Effect.sync(finish);
 });
-const connect = config => Effect.callback(resume => {
+const connect = (config, resolvedPassword) => Effect.callback(resume => {
   let done = false;
   let socket;
+  let encrypted = false;
   let parser;
   let sslErrorParser;
   let scram;
@@ -1419,11 +1438,11 @@ const connect = config => Effect.callback(resume => {
   const onError = cause => failConnect(cause, "PgConnection: Failed to connect");
   const onClose = () => failConnect(new Error("Connection closed unexpectedly"), "PgConnection: Connection closed during startup");
   const password = () => {
-    if (config.password === undefined) {
+    if (resolvedPassword === undefined) {
       failAuth(new Error("The server requested password authentication"), "PgConnection: No password configured");
       return undefined;
     }
-    return config.password;
+    return resolvedPassword;
   };
   const handleMessage = message => {
     switch (message._tag) {
@@ -1525,6 +1544,7 @@ const connect = config => Effect.callback(resume => {
         socket.on("error", ignoreError);
         resume(Effect.succeed({
           socket,
+          encrypted,
           parser: parser,
           processId,
           secretKey
@@ -1551,11 +1571,7 @@ const connect = config => Effect.callback(resume => {
       maxMessageSize: config.maxMessageSize
     });
     socket.on("data", onData);
-    socket.write(PgProtocol.encodeStartupMessage({
-      user: config.username,
-      database: config.database,
-      application_name: config.applicationName
-    }));
+    socket.write(PgProtocol.encodeStartupMessage(config.startupParameters));
   };
   const onSslResponse = chunk => {
     if (done) return;
@@ -1586,6 +1602,7 @@ const connect = config => Effect.callback(resume => {
       return failConnect(response.failure, "PgConnection: Invalid SSLRequest response");
     }
     if (response.success === "N") {
+      if (config.sslOptional) return startup();
       return failConnect(new Error("The server does not support TLS"), "PgConnection: Server refused TLS");
     }
     const raw = socket;
@@ -1599,7 +1616,10 @@ const connect = config => Effect.callback(resume => {
     });
     socket.on("error", onError);
     socket.on("close", onClose);
-    socket.once("secureConnect", startup);
+    socket.once("secureConnect", () => {
+      encrypted = true;
+      startup();
+    });
   };
   const begin = () => {
     if (config.ssl === false) return startup();
@@ -1649,7 +1669,7 @@ const configError = (message, cause) => new SqlError({
   })
 });
 const resolveConfig = options => Effect.suspend(() => {
-  const parsed = options.url !== undefined ? parseUrl(Redacted.value(options.url), options.ssl !== undefined) : EffectResult.succeed({});
+  const parsed = options.url !== undefined ? parseUrl(Redacted.value(options.url)) : EffectResult.succeed({});
   if (EffectResult.isFailure(parsed)) return Effect.fail(parsed.failure);
   const url = parsed.success;
   const host = options.host ?? url.host ?? "localhost";
@@ -1658,16 +1678,47 @@ const resolveConfig = options => Effect.suspend(() => {
   if (username === undefined) {
     return Effect.fail(configError("No username configured"));
   }
+  const named = Object.create(null);
+  for (const [name, value] of Object.entries(options.startupParameters ?? {})) {
+    const key = name.toLowerCase();
+    if (key === "user" || key === "database" || key === "replication" || key === "options") {
+      return Effect.fail(configError(`Reserved startup parameter: "${name}"`));
+    }
+    if (key === "client_encoding") {
+      const encoding = value.toUpperCase();
+      if (encoding !== "UTF8" && encoding !== "UTF-8") {
+        return Effect.fail(configError("Startup parameter client_encoding must be UTF8 or UTF-8"));
+      }
+      named[key] = "UTF8";
+    } else {
+      named[key] = value;
+    }
+    if (name === "" || name.includes("\0") || value.includes("\0")) {
+      return Effect.fail(configError("Startup parameter names must be nonempty and names/values must not contain NUL"));
+    }
+  }
+  const startupParameters = {
+    ...named,
+    user: username,
+    database: options.database ?? url.database,
+    application_name: options.applicationName ?? named.application_name ?? url.applicationName ?? "@effect/sql-pg",
+    options: options.startupOptions ?? url.options
+  };
+  for (const [name, value] of Object.entries(startupParameters)) {
+    if (value?.includes("\0")) {
+      return Effect.fail(configError(`Startup parameter "${name}" must not contain NUL`));
+    }
+  }
   return Effect.succeed({
     host,
     port,
     path: options.path ?? (host.startsWith("/") ? `${host}/.s.PGSQL.${port}` : undefined),
-    ssl: options.ssl ?? url.ssl ?? false,
-    database: options.database ?? url.database,
+    ssl: options.ssl ?? (url.ssl === "prefer" ? true : url.ssl ?? false),
+    sslOptional: options.ssl === undefined && url.ssl === "prefer",
     username,
-    password: options.password !== undefined ? Redacted.value(options.password) : url.password,
+    password: options.password ?? (url.password !== undefined ? Redacted.make(url.password) : undefined),
     connectTimeout: Duration.fromInputUnsafe(options.connectTimeout ?? url.connectTimeout ?? Duration.seconds(5)),
-    applicationName: options.applicationName ?? url.applicationName ?? "@effect/sql-pg",
+    startupParameters,
     stream: options.stream,
     maxMessageSize: options.maxMessageSize
   });
@@ -1683,7 +1734,7 @@ const parsePort = (value, what) => {
   const port = Number(value);
   return !Number.isInteger(port) || port < 1 || port > 65535 ? EffectResult.fail(configError(`Invalid port in URL ${what}: "${value}"`)) : EffectResult.succeed(port);
 };
-const parseUrl = (raw, hasExplicitSsl) => {
+const parseUrl = raw => {
   let url;
   try {
     url = new URL(raw);
@@ -1745,6 +1796,9 @@ const parseUrl = (raw, hasExplicitSsl) => {
       case "application_name":
         config.applicationName = value;
         break;
+      case "options":
+        config.options = value;
+        break;
       case "connect_timeout":
         {
           const seconds = Number(value);
@@ -1766,8 +1820,8 @@ const parseUrl = (raw, hasExplicitSsl) => {
             break;
           case "prefer":
           case "allow":
-            if (hasExplicitSsl) break;
-            return EffectResult.fail(configError(`sslmode "${value}" is not supported: set ssl explicitly to true or false`));
+            config.ssl = "prefer";
+            break;
           default:
             return EffectResult.fail(configError(`Unrecognized sslmode in URL: "${value}"`));
         }