The best way to control Claude Code, Codex and more from any computer or phone

main
ts 2,311 lines 84.4 KB
Raw
1 /**
2 * Native PostgreSQL sessions built on the `PgProtocol` wire codec.
3 *
4 * **Details**
5 *
6 * Sessions support queries, streaming, `LISTEN`/`NOTIFY`, cancellation, and
7 * exclusive ownership for transactions.
8 *
9 * @stability unstable
10 * @since 4.0.0
11 */
12 import type * as Arr from "effect/Array"
13 import * as Cause from "effect/Cause"
14 import * as Channel from "effect/Channel"
15 import * as Context from "effect/Context"
16 import * as Deferred from "effect/Deferred"
17 import type * as Duration from "effect/Duration"
18 import * as Effect from "effect/Effect"
19 import * as Exit from "effect/Exit"
20 import * as Queue from "effect/Queue"
21 import type * as Redacted from "effect/Redacted"
22 import * as EffectResult from "effect/Result"
23 import * as Scheduler from "effect/Scheduler"
24 import * as Scope from "effect/Scope"
25 import * as Semaphore from "effect/Semaphore"
26 import { AuthenticationError, ConnectionError, SqlError, type SqlErrorReason, UnknownError } from "effect/sql/SqlError"
27 import * as Stream from "effect/Stream"
28 import { Buffer } from "node:buffer"
29 import { randomBytes } from "node:crypto"
30 import * as Net from "node:net"
31 import type { Duplex } from "node:stream"
32 import * as Tls from "node:tls"
33 import type { ConnectionOptions } from "node:tls"
34 import { resolveConfig, type ResolvedConfig } from "./internal/config.ts"
35 import { type ConnectionInternals, internalsKey } from "./internal/connection.ts"
36 import * as PasswordInternal from "./internal/password.ts"
37 import { classifySqlState, validateChannelName } from "./internal/sqlError.ts"
38 import * as PgAuth from "./PgAuth.ts"
39 import * as PgProtocol from "./PgProtocol.ts"
40 import * as PgTypes from "./PgTypes.ts"
41
42 /**
43 * The runtime type identifier for `PgConnection`.
44 *
45 * @stability unstable
46 * @category type IDs
47 * @since 4.0.0
48 */
49 export const TypeId: TypeId = "~@effect/sql-pg/PgConnection"
50
51 /**
52 * The type-level identifier for `PgConnection`.
53 *
54 * @stability unstable
55 * @category type IDs
56 * @since 4.0.0
57 */
58 export type TypeId = "~@effect/sql-pg/PgConnection"
59
60 /**
61 * Connection settings for a PostgreSQL session.
62 *
63 * **Details**
64 *
65 * A `url` is parsed as a libpq URI (`postgres://` or `postgresql://`);
66 * explicit fields win over anything the URL carries. A `stream` factory wins
67 * over `host`, `port`, and `path`. A `path` is used verbatim as the unix
68 * socket path, while a `host` beginning with `/` is treated as a socket
69 * directory and expands to `${host}/.s.PGSQL.${port}`.
70 *
71 * URL modes `sslmode=prefer` and `sslmode=allow` try TLS first, falling back
72 * to plaintext only when the server answers `SSLRequest` with `N`. Unlike
73 * libpq, `allow` also tries TLS first. Certificate verification stays enabled
74 * unless explicitly disabled through `ssl` options.
75 *
76 * Prepared statements are enabled by default and limited by
77 * `preparedStatementCacheSize`. Disable them for poolers that drop named
78 * statements, such as PgBouncer with `max_prepared_statements = 0`, or for
79 * workloads that generate unique SQL. Streams always use unnamed statements.
80 *
81 * With `multiplex` enabled, unpinned queries from multiple fibers are
82 * pipelined. Transactions, streams, and listeners remain exclusive. An
83 * unpinned multiplexed connection cannot be interrupted because cancellation
84 * could affect another fiber's query.
85 *
86 * @stability unstable
87 * @category models
88 * @since 4.0.0
89 */
90 export interface Config {
91 readonly url?: Redacted.Redacted | undefined
92 readonly host?: string | undefined
93 readonly port?: number | undefined
94 readonly path?: string | undefined
95 readonly ssl?: boolean | ConnectionOptions | undefined
96 readonly database?: string | undefined
97 readonly username?: string | undefined
98 /**
99 * A static password or an Effect evaluated for each connection attempt.
100 * Providers must handle typed errors and require no services.
101 * {@link Effect.orDie} converts typed errors to defects, not retryable SQL errors.
102 */
103 readonly password?: Redacted.Redacted | Effect.Effect<Redacted.Redacted> | undefined
104 readonly connectTimeout?: Duration.Input | undefined
105 /**
106 * Enables TCP keepalive on native TCP connections after this idle time.
107 *
108 * **Details**
109 *
110 * The duration is truncated to whole seconds (minimum 1 second). With Node's
111 * defaults, the connection errors after 10 unanswered probes sent 1 second
112 * apart. Disabled when omitted; Unix sockets and custom streams are unaffected.
113 *
114 * This is not a query timeout. Probes only run while no sent data is awaiting
115 * acknowledgement, so use `Effect.timeout` to bound a write to a dead peer.
116 */
117 readonly keepAlive?: Duration.Input | undefined
118 /**
119 * Overrides `startupParameters.application_name`, the URL's `application_name`,
120 * and the default `"@effect/sql-pg"`, in that order.
121 */
122 readonly applicationName?: string | undefined
123 /**
124 * Session defaults sent in every physical connection's startup packet.
125 * Names are lowercased; `user`, `database`, `replication`, and `options` are
126 * reserved. `client_encoding` only accepts UTF8 / UTF-8 (case-insensitive).
127 * Empty names and NUL bytes fail before connecting; PostgreSQL validates
128 * other settings. Do not set the same GUC here and in `startupOptions`.
129 */
130 readonly startupParameters?: Readonly<Record<string, string>> | undefined
131 /**
132 * Opaque PostgreSQL startup options, overriding the URL's `options` parameter.
133 * Forwarded without parsing `-c` flags or checking for duplicate GUCs.
134 */
135 readonly startupOptions?: string | undefined
136 readonly stream?: (() => Duplex) | undefined
137 readonly types?: PgTypes.Registry | undefined
138 readonly multiplex?: boolean | undefined
139 readonly prepare?: boolean | undefined
140 readonly preparedStatementCacheSize?: number | undefined
141 /** Maximum backend message size in bytes. Defaults to 16 MiB. */
142 readonly maxMessageSize?: number | undefined
143 }
144
145 /**
146 * Builds the prepared-statement cache a session should use, or `undefined`
147 * when `prepare` is off or the cache is sized to nothing.
148 */
149 const preparedCacheFor = (config: Config): PreparedCache | undefined => {
150 if (config.prepare === false) return undefined
151 const max = config.preparedStatementCacheSize ?? defaultPreparedStatements
152 return max > 0 ? new PreparedCache(max) : undefined
153 }
154
155 /**
156 * An object result row keyed by column name.
157 *
158 * @stability unstable
159 * @category models
160 * @since 4.0.0
161 */
162 export interface Row {
163 readonly [column: string]: unknown
164 }
165
166 /**
167 * Metadata for one result column.
168 *
169 * @stability unstable
170 * @category models
171 * @since 4.0.0
172 */
173 export interface Field {
174 readonly name: string
175 readonly dataTypeId: number
176 }
177
178 /**
179 * The result of a query.
180 *
181 * @stability unstable
182 * @category models
183 * @since 4.0.0
184 */
185 export interface Result {
186 readonly command: string
187 readonly rowCount: number
188 readonly oid: number | null
189 readonly rows: ReadonlyArray<Row>
190 readonly fields: ReadonlyArray<Field>
191 }
192
193 /**
194 * A `NOTIFY` message received while listening on a channel.
195 *
196 * @stability unstable
197 * @category models
198 * @since 4.0.0
199 */
200 export interface Notification {
201 readonly processId: number
202 readonly channel: string
203 readonly payload: string
204 }
205
206 /**
207 * A connected and authenticated PostgreSQL session.
208 *
209 * @stability unstable
210 * @category models
211 * @since 4.0.0
212 */
213 export interface PgConnection {
214 readonly [TypeId]: TypeId
215 readonly config: Config
216 readonly processId: number
217 /**
218 * Reserves the session for exclusive use until the scope closes. Pinning is
219 * reentrant. Calls through the returned connection skip the
220 * ownership queue, while calls through the original connection wait.
221 *
222 * **Details**
223 *
224 * After release, queries, streams and listeners through the returned
225 * connection fail, and its `interrupt` does nothing. Releasing a pin with
226 * an in-flight statement or an open listener closes the session and fails
227 * any listener queues, as does leaving a transaction the pin began aborted.
228 */
229 readonly pin: Effect.Effect<PgConnection, never, Scope.Scope>
230 /**
231 * Runs a query and returns rows keyed by column name. Pass `false` to skip
232 * the prepared statement cache.
233 *
234 * **Details**
235 *
236 * On interruption, the connection drains to `ReadyForQuery` and sends a
237 * `CancelRequest` if needed. Unless the backend confirms cancellation with
238 * `57014`, a pool retires the session before its next checkout. A retained
239 * checkout and an unpooled session remain exposed to a late cancel.
240 * `statement_timeout` also reports `57014` and can be mistaken for
241 * confirmation.
242 */
243 readonly query: (
244 sql: string,
245 params?: ReadonlyArray<unknown>,
246 prepare?: boolean
247 ) => Effect.Effect<Result, SqlError>
248 /**
249 * Runs a query and returns positional rows. Pass `false` to skip the
250 * prepared statement cache. Interruption behaves as for `query`.
251 */
252 readonly queryValues: (
253 sql: string,
254 params?: ReadonlyArray<unknown>,
255 prepare?: boolean
256 ) => Effect.Effect<ReadonlyArray<ReadonlyArray<unknown>>, SqlError>
257 /**
258 * Streams rows without collecting the full result. The session is pinned for
259 * the lifetime of the stream. An early abort behaves like an interrupted
260 * `query`.
261 */
262 readonly stream: (
263 sql: string,
264 params?: ReadonlyArray<unknown>
265 ) => Stream.Stream<Row, SqlError>
266 /**
267 * Registers a channel listener and returns its notification queue after
268 * PostgreSQL confirms `LISTEN`. The session stays pinned until the scope
269 * closes, when it runs `UNLISTEN` and shuts down the queue. A session that
270 * does not confirm `UNLISTEN` within 5 seconds is closed. PostgreSQL
271 * registration errors fail the acquiring effect.
272 * Connection failures after registration fail the queue with the original
273 * `SqlError`. Intentional scope closure interrupts consumers.
274 */
275 readonly listen: (
276 channel: string
277 ) => Effect.Effect<Queue.Dequeue<Notification, SqlError>, SqlError, Scope.Scope>
278 /**
279 * Attempts to cancel the active query through a side connection. This is a
280 * no-op for an unpinned multiplexed connection because the active
281 * query may belong to another fiber. The effect never fails.
282 */
283 readonly interrupt: Effect.Effect<void>
284 }
285
286 /**
287 * The service tag for `PgConnection`.
288 *
289 * @stability unstable
290 * @category services
291 * @since 4.0.0
292 */
293 export const PgConnection = Context.Service<PgConnection>("@effect/sql-pg/PgConnection")
294
295 /**
296 * Connects and authenticates a single PostgreSQL session.
297 *
298 * **Details**
299 *
300 * Password resolution, transport, optional `SSLRequest`, startup, and
301 * authentication run under `connectTimeout` (5 seconds by default). The effect
302 * resolves when the backend sends `ReadyForQuery`. Closing the scope sends
303 * `Terminate` and ends the socket.
304 *
305 * Use `sslmode=require` or explicit `ssl: true` to require encryption.
306 * Unix sockets and custom streams should set `ssl.servername` explicitly.
307 *
308 * @stability unstable
309 * @category constructors
310 * @since 4.0.0
311 */
312 export const make = (options: Config): Effect.Effect<PgConnection, SqlError, Scope.Scope> =>
313 Effect.flatMap(resolveConfig(options), (config) =>
314 Effect.acquireRelease(
315 Effect.gen(function*() {
316 const password = yield* PasswordInternal.resolve(config.password)
317 const session = yield* connect(config, password)
318 return new PgConnectionImpl(options, config, session, options.types)
319 }),
320 (connection) => Effect.sync(() => connection.closeUnsafe()),
321 { interruptible: true }
322 ).pipe(
323 Effect.timeoutOrElse({
324 duration: config.connectTimeout,
325 orElse: () =>
326 Effect.fail(
327 new SqlError({
328 reason: new ConnectionError({
329 cause: new Error("Connection timed out"),
330 message: "PgConnection: Connection timed out",
331 operation: "connect"
332 })
333 })
334 )
335 })
336 ))
337
338 interface Session {
339 readonly socket: Duplex
340 readonly encrypted: boolean
341 readonly parser: PgProtocol.Parser<unknown>
342 readonly processId: number
343 readonly secretKey: number
344 }
345
346 /**
347 * The active protocol consumer: the state machine of the statement currently
348 * on the wire. Messages the pump does not handle itself are forwarded here.
349 */
350 interface Consumer {
351 readonly onMessage: (message: PgProtocol.BackendMessage<unknown>) => void
352 readonly onBatchEnd?: (() => void) | undefined
353 readonly onFatal: (error: SqlError) => void
354 }
355
356 /** One statement waiting in, or travelling through, a multiplexed pipeline. */
357 interface PipelineEntry {
358 readonly plan: Plan
359 readonly deferred: Deferred.Deferred<QueryOutput, SqlError>
360 readonly machine: QueryMachine
361 abandoned: boolean
362 }
363
364 const abortDrainTimeoutMillis = 5000
365 const abortDrainGraceMillis = 10
366 /** PostgreSQL `query_canceled` SQLSTATE. */
367 const queryCanceledCode = "57014"
368 const cancelRequestTimeoutMillis = 5000
369 const unlistenTimeoutMillis = 5000
370 /** How many statements a multiplexed session keeps on the wire at once. */
371 const maxPipelineDepth = 128
372 const streamPauseThreshold = 512
373
374 class PgConnectionImpl implements PgConnection {
375 readonly [TypeId]: TypeId = TypeId
376 readonly config: Config
377 readonly processId: number
378 readonly session: Session
379 /** The custom codec registry, or `undefined` for the builtin catalogue. */
380 readonly registry: PgTypes.Registry | undefined
381 readonly bindEncoder: BindEncoder
382 /** The statements this session has named, or `undefined` when disabled. */
383 readonly prepared: PreparedCache | undefined
384 readonly resolved: ResolvedConfig
385 readonly multiplex: boolean
386 /** Serializes statements: one in-flight extended-query cycle. */
387 readonly wire = Semaphore.makeUnsafe(1)
388 /** Exclusive-ownership queue used by `pin` and unpinned statements. */
389 readonly owner = Semaphore.makeUnsafe(1)
390 pinned = false
391 consumer: Consumer | undefined
392 deadWith: SqlError | undefined
393 closed = false
394 cancelPending = false
395 /** Reported by the latest `ReadyForQuery`. */
396 transactionStatus: PgProtocol.TransactionStatus = "I"
397 readonly channels = new Map<string, Set<Queue.Queue<Notification, SqlError>>>()
398 readonly retireHooks = new Set<() => void>()
399 /** Queued but not yet written; drained into `pipelineInFlight` on flush. */
400 readonly pipelinePending: Array<PipelineEntry> = []
401 /** Written and awaiting their `ReadyForQuery`, oldest first. */
402 readonly pipelineInFlight: Array<PipelineEntry> = []
403 pipelineHead = 0
404 pipelineFlushScheduled = false
405 readonly pipelineIdleWaiters = new Set<() => void>()
406 readonly [internalsKey]: ConnectionInternals
407
408 constructor(config: Config, resolved: ResolvedConfig, session: Session, registry: PgTypes.Registry | undefined) {
409 this.config = config
410 this.resolved = resolved
411 this.session = session
412 this.processId = session.processId
413 this.registry = registry
414 this.bindEncoder = makeBindEncoder(registry)
415 this.prepared = preparedCacheFor(config)
416 this.multiplex = config.multiplex ?? false
417 this[internalsKey] = {
418 base: this,
419 deadError: () => this.deadWith,
420 retireHooks: this.retireHooks
421 }
422 session.socket.on("data", this.onData)
423 session.socket.on("error", this.onSocketError)
424 session.socket.on("close", this.onSocketClose)
425 }
426
427 private readonly onData = (chunk: Uint8Array): void => {
428 try {
429 this.session.parser.pushEach(chunk, this.dispatch)
430 } catch (cause) {
431 // A field reader that threw reports the row it could not decode; anything
432 // else came out of the framing itself.
433 return this.fatal(
434 cause instanceof PgProtocol.ParseError
435 ? connectionQueryError(cause, "PgConnection: Failed to parse server messages")
436 : queryError(cause, "PgConnection: Failed to decode row")
437 )
438 }
439 if (this.deadWith === undefined) this.consumer?.onBatchEnd?.()
440 }
441
442 private readonly onSocketError = (cause: Error): void =>
443 this.fatal(connectionQueryError(cause, "PgConnection: Socket error"))
444
445 private readonly onSocketClose = (): void =>
446 this.fatal(connectionQueryError(new Error("Connection closed"), "PgConnection: Connection closed"))
447
448 private readonly dispatch = (message: PgProtocol.BackendMessage<unknown>): void => {
449 if (this.deadWith !== undefined) return
450 switch (message._tag) {
451 case "ErrorResponse":
452 if (message.fields.code === queryCanceledCode) this.cancelPending = false
453 break
454 case "ReadyForQuery":
455 this.transactionStatus = message.status
456 if (this.cancelPending) {
457 this.cancelPending = false
458 this.retire()
459 }
460 break
461 case "NotificationResponse": {
462 const queues = this.channels.get(message.channel)
463 if (queues !== undefined) {
464 const notification: Notification = {
465 processId: message.pid,
466 channel: message.channel,
467 payload: message.payload
468 }
469 for (const queue of queues) Queue.offerUnsafe(queue, notification)
470 }
471 return
472 }
473 case "ParameterStatus":
474 case "NoticeResponse":
475 return
476 }
477 if (this.consumer !== undefined) return this.consumer.onMessage(message)
478 if (message._tag === "ErrorResponse") {
479 return this.fatal(
480 new SqlError({
481 reason: classifyFields(message.fields, "PgConnection: The server reported an error", "query")
482 })
483 )
484 }
485 this.fatal(
486 connectionQueryError(
487 new Error(`Unexpected ${message._tag} while idle`),
488 `PgConnection: Unexpected ${message._tag} while idle`
489 )
490 )
491 }
492
493 /** Marks the session dead: optionally destroys the socket, fails the active statement
494 * and every listen queue, and notifies pool hooks unless the session's own
495 * scope is being released. */
496 fatal(error: SqlError, destroySocket = true): void {
497 if (this.deadWith !== undefined) return
498 this.deadWith = error
499 if (destroySocket) this.session.socket.destroy()
500 const consumer = this.consumer
501 this.consumer = undefined
502 this.retire()
503 consumer?.onFatal(error)
504 const sets = Array.from(this.channels.values())
505 this.channels.clear()
506 const cause = this.closed ? Cause.interrupt() : Cause.fail(error)
507 for (const set of sets) {
508 for (const queue of set) Queue.failCauseUnsafe(queue, cause)
509 }
510 }
511
512 private retire(): void {
513 if (this.closed) return
514 for (const hook of this.retireHooks) hook()
515 }
516
517 closeUnsafe(): void {
518 this.closed = true
519 let destroySocket = true
520 if (this.deadWith === undefined && this.session.socket.writable) {
521 try {
522 this.session.socket.end(PgProtocol.encodeTerminate())
523 destroySocket = false
524 } catch {
525 // Fall back to the fatal path's immediate destroy below.
526 }
527 }
528 this.fatal(
529 new SqlError({
530 reason: new ConnectionError({
531 cause: new Error("Connection is closed"),
532 message: "PgConnection: Connection is closed",
533 operation: "query"
534 })
535 }),
536 destroySocket
537 )
538 const socket = this.session.socket
539 socket.off("data", this.onData)
540 socket.off("error", this.onSocketError)
541 socket.off("close", this.onSocketClose)
542 this.retireHooks.clear()
543 }
544
545 /** Plans one execution. `cache` is `undefined` to force the unnamed path. */
546 readonly encodeQuery = (
547 sql: string,
548 params: ReadonlyArray<unknown>,
549 cache: PreparedCache | undefined
550 ): Plan => encodeQuery(sql, params, this.registry, this.bindEncoder, cache)
551
552 /**
553 * Routes backend messages to the oldest statement still on the wire.
554 *
555 * Every cycle carries its own `Sync`, so the backend answers them in order
556 * and finishes each with a `ReadyForQuery`. That boundary is what advances
557 * the queue, and it is also why a statement the backend rejects only skips
558 * the rest of its own cycle: the ones queued behind it still run.
559 */
560 private readonly pipelineConsumer: Consumer = {
561 onMessage: (message) => {
562 const entry = this.pipelineInFlight[this.pipelineHead]
563 if (entry === undefined) {
564 return this.fatal(connectionQueryError(
565 new Error(`Unexpected ${message._tag} without an in-flight query`),
566 `PgConnection: Unexpected ${message._tag} without an in-flight query`
567 ))
568 }
569 entry.machine.onMessage(message)
570 },
571 onBatchEnd: () => this.flushPipeline(),
572 onFatal: (error) => {
573 const entries = [
574 ...this.pipelineInFlight.slice(this.pipelineHead),
575 ...this.pipelinePending
576 ]
577 this.pipelineInFlight.length = 0
578 this.pipelineHead = 0
579 this.pipelinePending.length = 0
580 this.pipelineFlushScheduled = false
581 for (const entry of entries) {
582 if (!entry.abandoned) Deferred.doneUnsafe(entry.deferred, Effect.fail(error))
583 }
584 this.notifyPipelineIdle()
585 }
586 }
587
588 private readonly pipelineDepth = (): number => this.pipelineInFlight.length - this.pipelineHead
589
590 private readonly pipelineIsIdle = (): boolean => this.pipelineDepth() === 0 && this.pipelinePending.length === 0
591
592 private readonly notifyPipelineIdle = (): void => {
593 if (!this.pipelineIsIdle()) return
594 this.consumer = undefined
595 this.session.parser.readField = undefined
596 const waiters = Array.from(this.pipelineIdleWaiters)
597 this.pipelineIdleWaiters.clear()
598 for (const waiter of waiters) waiter()
599 }
600
601 /** Resolves once nothing is on the wire, so `pin` can take the connection. */
602 readonly waitPipelineIdle: Effect.Effect<void> = Effect.callback((resume) => {
603 if (this.pipelineIsIdle()) return resume(Effect.void)
604 const waiter = () => resume(Effect.void)
605 this.pipelineIdleWaiters.add(waiter)
606 return Effect.sync(() => this.pipelineIdleWaiters.delete(waiter))
607 })
608
609 private readonly finishPipelineEntry = (
610 entry: PipelineEntry,
611 result: Effect.Effect<QueryOutput, SqlError>
612 ): void => {
613 if (this.pipelineInFlight[this.pipelineHead] !== entry) {
614 return this.fatal(connectionQueryError(
615 new Error("A pipelined query completed out of order"),
616 "PgConnection: A pipelined query completed out of order"
617 ))
618 }
619 this.pipelineHead++
620 // The next statement's rows can be in this same chunk, so its reader has to
621 // be in place before the parser reads on.
622 this.session.parser.readField = this.pipelineInFlight[this.pipelineHead]?.machine.readField
623 if (!entry.abandoned) Deferred.doneUnsafe(entry.deferred, result)
624 if (this.pipelineHead === this.pipelineInFlight.length) {
625 this.pipelineInFlight.length = 0
626 this.pipelineHead = 0
627 }
628 }
629
630 /** Writes everything queued since the last flush as one batch. */
631 private readonly flushPipeline = (): void => {
632 this.pipelineFlushScheduled = false
633 if (this.deadWith !== undefined) return
634 let capacity = maxPipelineDepth - this.pipelineDepth()
635 if (capacity <= 0) return
636 const wasEmpty = this.pipelineDepth() === 0
637 const batch: Array<PipelineEntry> = []
638 let index = 0
639 while (capacity > 0 && index < this.pipelinePending.length) {
640 const entry = this.pipelinePending[index++]
641 if (entry.abandoned) {
642 if (entry.plan.parses && entry.plan.prepared !== undefined) {
643 entry.plan.prepared.parsing = false
644 }
645 continue
646 }
647 batch.push(entry)
648 this.pipelineInFlight.push(entry)
649 capacity--
650 }
651 this.pipelinePending.splice(0, index)
652 if (batch.length === 0) {
653 this.notifyPipelineIdle()
654 return
655 }
656 if (wasEmpty) this.session.parser.readField = batch[0].machine.readField
657 const frame = batch.length === 1
658 ? batch[0].plan.frame
659 : concat(batch.map((entry) => entry.plan.frame))
660 try {
661 this.session.socket.write(frame)
662 } catch (cause) {
663 this.fatal(connectionQueryError(cause, "PgConnection: Failed to write query batch"))
664 }
665 }
666
667 private readonly schedulePipelineFlush = (): void => {
668 if (this.pipelineFlushScheduled || this.pipelineDepth() >= maxPipelineDepth) return
669 this.pipelineFlushScheduled = true
670 // A microtask is what lets fibers submitted in the same tick share a write.
671 queueMicrotask(this.flushPipeline)
672 }
673
674 /**
675 * One cycle on a multiplexed connection. The `owner` permit is only taken to
676 * queue the statement, so a pin still orders against submissions without
677 * serializing them.
678 */
679 private readonly pipelineCycle = (
680 sql: string,
681 params: ReadonlyArray<unknown>,
682 wantRows: boolean,
683 cache: PreparedCache | undefined
684 ): Effect.Effect<QueryOutput, SqlError> =>
685 Effect.flatMap(
686 this.owner.withPermit(Effect.suspend(() => {
687 if (this.deadWith !== undefined) return Effect.fail(this.deadWith)
688 let plan: Plan
689 try {
690 plan = this.encodeQuery(sql, params, cache)
691 } catch (cause) {
692 return Effect.fail(queryError(cause, "PgConnection: Failed to encode query"))
693 }
694 const deferred = Deferred.makeUnsafe<QueryOutput, SqlError>()
695 let entry: PipelineEntry
696 const machine = new QueryMachine(this, plan, wantRows, (result) => this.finishPipelineEntry(entry, result))
697 entry = { plan, deferred, machine, abandoned: false }
698 this.pipelinePending.push(entry)
699 this.consumer = this.pipelineConsumer
700 this.schedulePipelineFlush()
701 return Effect.succeed(entry)
702 })),
703 (entry) => {
704 const awaited = Deferred.await(entry.deferred).pipe(
705 Effect.onInterrupt(() =>
706 Effect.sync(() => {
707 entry.abandoned = true
708 })
709 )
710 )
711 if (cache === undefined || entry.plan.parses) return awaited
712 return retryStale(entry.plan, cache, awaited, () => this.pipelineCycle(sql, params, wantRows, undefined))
713 }
714 )
715
716 /**
717 * Runs one cycle for a caller that owns the session. No wire permit is needed
718 * because competing pinned work and streams must acquire `owner` first.
719 */
720 readonly cycleOwned = (
721 sql: string,
722 params: ReadonlyArray<unknown>,
723 wantRows: boolean,
724 cache: PreparedCache | undefined
725 ): Effect.Effect<QueryOutput, SqlError> => Effect.suspend(() => this.attempt(sql, params, wantRows, cache))
726
727 /**
728 * Runs one cycle. A reused statement the backend has since dropped, or whose
729 * plan no longer matches its columns, is parsed again on a second attempt;
730 * that attempt skips the cache, so it cannot loop.
731 */
732 private readonly attempt = (
733 sql: string,
734 params: ReadonlyArray<unknown>,
735 wantRows: boolean,
736 cache: PreparedCache | undefined
737 ): Effect.Effect<QueryOutput, SqlError> => {
738 if (this.deadWith !== undefined) return Effect.fail(this.deadWith)
739 let plan: Plan
740 try {
741 plan = this.encodeQuery(sql, params, cache)
742 } catch (cause) {
743 return Effect.fail(queryError(cause, "PgConnection: Failed to encode query"))
744 }
745 const run = runQuery(this, plan, wantRows)
746 if (cache === undefined || plan.parses) return run
747 return retryStale(plan, cache, run, () => this.attempt(sql, params, wantRows, undefined))
748 }
749
750 /** Sends a `CancelRequest` for this session on a side connection. */
751 readonly cancel: Effect.Effect<void> = Effect.suspend(() => {
752 if (this.deadWith !== undefined) return Effect.void
753 this.cancelPending = true
754 if (this.consumer === undefined) this.retire()
755 return sendCancelRequest(this.resolved, this.session)
756 })
757
758 readonly pin: Effect.Effect<PinnedPgConnection, never, Scope.Scope> = Effect.suspend(() => {
759 const reserve = this[internalsKey].reserve
760 return reserve === undefined ? this.pinExclusive : Effect.andThen(reserve, this.pinExclusive)
761 })
762
763 // Only the waits are interruptible, so a caller can bound how long it waits
764 // for the connection without leaking the `owner` permit.
765 private readonly pinExclusive: Effect.Effect<PinnedPgConnection, never, Scope.Scope> = Effect.acquireRelease(
766 Effect.uninterruptibleMask((restore) =>
767 Effect.flatMap(restore(this.owner.take(1)), () =>
768 // Holding `owner` stops new submissions; a pipeline already on the wire
769 // still has to drain before this fiber owns the connection.
770 Effect.map(
771 Effect.onInterrupt(restore(this.waitPipelineIdle), () => this.owner.release(1)),
772 () => {
773 this.pinned = true
774 return new PinnedPgConnection(this)
775 }
776 ))
777 ),
778 (view) =>
779 Effect.flatMap(
780 Effect.suspend(() => {
781 view.released = true
782 this.pinned = false
783 // An `UNLISTEN` that took the wire before the release is bounded by its
784 // own timeout, so wait for it rather than treating it as leaked work.
785 return view.unlistening > 0 ? Effect.as(this.wire.take(1), true) : this.wire.takeIfAvailable(1)
786 }),
787 (idle) => {
788 // Retire rather than wait indefinitely for leaked work to finish.
789 if (!idle || view.listeners > 0) {
790 this.fatal(connectionQueryError(
791 new Error("Pinned connection released with work outstanding"),
792 "PgConnection: Pinned connection released with work outstanding"
793 ))
794 } else if (view.startedIdle && this.transactionStatus === "E") {
795 // A failed cleanup, such as a cancelled `ROLLBACK`, leaves every later
796 // statement failing. A transaction open before the pin is its caller's.
797 this.fatal(connectionQueryError(
798 new Error("Pinned connection released in an aborted transaction"),
799 "PgConnection: Pinned connection released in an aborted transaction"
800 ))
801 }
802 return idle ? Effect.andThen(this.wire.release(1), this.owner.release(1)) : this.owner.release(1)
803 }
804 ),
805 { interruptible: true }
806 )
807
808 private readonly run = (
809 sql: string,
810 params: ReadonlyArray<unknown>,
811 wantRows: boolean,
812 prepare: boolean
813 ): Effect.Effect<QueryOutput, SqlError> => {
814 const cache = prepare ? this.prepared : undefined
815 return this.multiplex
816 ? this.pipelineCycle(sql, params, wantRows, cache)
817 : this.owner.withPermit(this.cycleOwned(sql, params, wantRows, cache))
818 }
819
820 readonly query = (sql: string, params?: ReadonlyArray<unknown>, prepare = true): Effect.Effect<Result, SqlError> =>
821 Effect.map(this.run(sql, params ?? emptyParams, true, prepare), takeResult)
822
823 readonly queryValues = (
824 sql: string,
825 params?: ReadonlyArray<unknown>,
826 prepare = true
827 ): Effect.Effect<ReadonlyArray<ReadonlyArray<unknown>>, SqlError> =>
828 Effect.map(this.run(sql, params ?? emptyParams, false, prepare), takeValues)
829
830 readonly stream = (sql: string, params?: ReadonlyArray<unknown>): Stream.Stream<Row, SqlError> =>
831 streamRows(this, this.pin, sql, params ?? emptyParams)
832
833 readonly listen = (
834 channel: string
835 ): Effect.Effect<Queue.Dequeue<Notification, SqlError>, SqlError, Scope.Scope> =>
836 listenChannel(this, this.pin, channel)
837
838 readonly interrupt: Effect.Effect<void> = Effect.suspend(() =>
839 this.multiplex && !this.pinned ? Effect.void : this.cancel
840 )
841 }
842
843 /**
844 * The view of a session returned by `pin`: statements skip the ownership
845 * queue and re-pinning is a no-op, making `pin` reentrant for `stream` and
846 * `listen` running inside a transaction.
847 */
848 class PinnedPgConnection implements PgConnection {
849 readonly [TypeId]: TypeId = TypeId
850 readonly base: PgConnectionImpl
851 readonly [internalsKey]: ConnectionInternals
852 readonly pin: Effect.Effect<PinnedPgConnection, never, Scope.Scope>
853 released = false
854 listeners = 0
855 unlistening = 0
856 /** No transaction was open when the pin took the session. */
857 readonly startedIdle: boolean
858
859 constructor(base: PgConnectionImpl) {
860 this.base = base
861 this[internalsKey] = base[internalsKey]
862 this.pin = Effect.succeed(this)
863 this.startedIdle = base.transactionStatus === "I"
864 }
865
866 // Check the lease under the wire permit so queued work cannot run after release.
867 private cycle(
868 sql: string,
869 params: ReadonlyArray<unknown>,
870 wantRows: boolean,
871 prepare: boolean
872 ): Effect.Effect<QueryOutput, SqlError> {
873 return this.base.wire.withPermit(Effect.suspend(() =>
874 this.released
875 ? Effect.fail(pinReleasedError())
876 : this.base.cycleOwned(sql, params, wantRows, prepare ? this.base.prepared : undefined)
877 ))
878 }
879
880 readonly interrupt: Effect.Effect<void> = Effect.suspend(() => this.released ? Effect.void : this.base.cancel)
881
882 get config(): Config {
883 return this.base.config
884 }
885
886 get processId(): number {
887 return this.base.processId
888 }
889
890 readonly query = (sql: string, params?: ReadonlyArray<unknown>, prepare = true): Effect.Effect<Result, SqlError> =>
891 Effect.map(this.cycle(sql, params ?? emptyParams, true, prepare), takeResult)
892
893 readonly queryValues = (
894 sql: string,
895 params?: ReadonlyArray<unknown>,
896 prepare = true
897 ): Effect.Effect<ReadonlyArray<ReadonlyArray<unknown>>, SqlError> =>
898 Effect.map(this.cycle(sql, params ?? emptyParams, false, prepare), takeValues)
899
900 readonly stream = (sql: string, params?: ReadonlyArray<unknown>): Stream.Stream<Row, SqlError> =>
901 streamRows(this.base, this.pin, sql, params ?? emptyParams)
902
903 readonly listen = (
904 channel: string
905 ): Effect.Effect<Queue.Dequeue<Notification, SqlError>, SqlError, Scope.Scope> =>
906 listenChannel(this.base, this.pin, channel)
907 }
908
909 interface QueryOutput {
910 readonly result: Result
911 readonly values: ReadonlyArray<ReadonlyArray<unknown>>
912 }
913
914 const INT32_MIN = -2147483648
915 const INT32_MAX = 2147483647
916
917 const inferredParameter = (oid: number, value: unknown): PgTypes.Parameter => ({
918 [PgTypes.ParameterTypeId]: PgTypes.ParameterTypeId,
919 oid,
920 value
921 })
922
923 const inferScalar = (value: unknown): PgTypes.Parameter => {
924 if (PgTypes.isParameter(value)) return value
925 if (value === null || value === undefined) return inferredParameter(0, null)
926 switch (typeof value) {
927 case "boolean":
928 return inferredParameter(PgTypes.OID.bool, value)
929 case "bigint":
930 return inferredParameter(PgTypes.OID.int8, value)
931 case "number":
932 if (Number.isInteger(value)) {
933 if (value >= INT32_MIN && value <= INT32_MAX) {
934 return inferredParameter(PgTypes.OID.int4, value)
935 }
936 if (Number.isSafeInteger(value)) {
937 return inferredParameter(PgTypes.OID.int8, BigInt(value))
938 }
939 }
940 return inferredParameter(PgTypes.OID.float8, value)
941 case "string":
942 // Bound with no concrete type, as a text-format literal, so the backend
943 // derives the type from the statement: a string works against a bigint
944 // or timestamp column the way it did with the text-protocol drivers.
945 return inferredParameter(0, value)
946 }
947 if (value instanceof Date) return inferredParameter(PgTypes.OID.timestamptz, value)
948 if (value instanceof Uint8Array) return inferredParameter(PgTypes.OID.bytea, value)
949 if (value instanceof Int8Array) {
950 return inferredParameter(
951 PgTypes.OID.bytea,
952 new Uint8Array(value.buffer, value.byteOffset, value.byteLength)
953 )
954 }
955 throw new PgTypes.CodecError({ message: `Cannot infer a PostgreSQL type for ${String(value)}` })
956 }
957
958 const inferParameter = (value: unknown, registry: PgTypes.Registry | undefined): PgTypes.Parameter => {
959 if (!Array.isArray(value)) return inferScalar(value)
960 if (value.length === 0) {
961 // Let the backend infer the array type from the statement, as for scalar strings.
962 return inferredParameter(0, "{}")
963 }
964 let elementOid: number | undefined
965 const values: Array<unknown> = new Array(value.length)
966 for (let index = 0; index < value.length; index++) {
967 const element = value[index]
968 if (Array.isArray(element)) {
969 throw new PgTypes.CodecError({ message: "Nested array parameters are not supported" })
970 }
971 const parameter = inferScalar(element)
972 // A scalar string binds untyped, but an array names its element type.
973 let oid = parameter.oid
974 if (oid === 0) {
975 if (parameter.value === null) {
976 values[index] = null
977 continue
978 }
979 oid = PgTypes.OID.text
980 }
981 if (Array.isArray(parameter.value)) {
982 throw new PgTypes.CodecError({ message: "Nested array parameters are not supported" })
983 }
984 if (elementOid === undefined) elementOid = oid
985 else if (elementOid !== oid) {
986 throw new PgTypes.CodecError({ message: "Array parameter elements must have the same inferred OID" })
987 }
988 values[index] = parameter.value
989 }
990 if (elementOid === undefined) {
991 throw new PgTypes.CodecError({ message: "Cannot infer the type of an array containing only null values" })
992 }
993 const arrayOid = PgTypes.arrayOidFor(elementOid, registry)
994 if (arrayOid === undefined) {
995 throw new PgTypes.CodecError({ message: `No array type known for element OID ${elementOid}` })
996 }
997 return inferredParameter(arrayOid, values)
998 }
999
1000 /**
1001 * Joins the parts of a frame into the buffer that goes on the wire.
1002 *
1003 * The buffer comes from Node's pool and can be passed directly to
1004 * `socket.write`. Every byte is initialized before the buffer is returned.
1005 */
1006 const concat = (chunks: ReadonlyArray<Uint8Array>): Uint8Array => {
1007 let length = 0
1008 for (let index = 0; index < chunks.length; index++) length += chunks[index].length
1009 const output = Buffer.allocUnsafe(length)
1010 let offset = 0
1011 for (let index = 0; index < chunks.length; index++) {
1012 output.set(chunks[index], offset)
1013 offset += chunks[index].length
1014 }
1015 return output
1016 }
1017
1018 const emptyParams: ReadonlyArray<unknown> = []
1019
1020 const takeResult = (output: QueryOutput): Result => output.result
1021 const takeValues = (output: QueryOutput): ReadonlyArray<ReadonlyArray<unknown>> => output.values
1022
1023 /**
1024 * The tail of every extended-query frame. `Describe` names the unnamed portal,
1025 * `Execute` runs it without a row limit, and `Sync` closes the cycle; none of
1026 * the three carries per-query state, so the bytes are encoded once.
1027 */
1028 const describeExecuteSync: Uint8Array = concat([
1029 PgProtocol.encodeDescribe({ target: "portal", name: "" }),
1030 PgProtocol.encodeExecute({ portal: "", maxRows: 0 }),
1031 PgProtocol.encodeSync()
1032 ])
1033
1034 /** The same tail for a statement whose columns are already known. */
1035 const executeSync: Uint8Array = concat([
1036 PgProtocol.encodeExecute({ portal: "", maxRows: 0 }),
1037 PgProtocol.encodeSync()
1038 ])
1039
1040 /** The default number of statements a connection keeps prepared. */
1041 const defaultPreparedStatements = 100
1042
1043 /**
1044 * A statement the backend has parsed and holds under a name.
1045 *
1046 * `ready` turns true once `ParseComplete` confirms the backend has it and the
1047 * first execution has reported its columns. Until then the entry is treated as
1048 * a miss, which is safe because one cycle runs at a time. A `ready` entry with
1049 * no `description` describes a statement that returns no rows.
1050 */
1051 interface Prepared {
1052 readonly name: string
1053 readonly key: string
1054 ready: boolean
1055 /** A cycle carrying this statement's `Parse` is on the wire. */
1056 parsing: boolean
1057 description: Description | undefined
1058 }
1059
1060 /** One planned execution: the bytes to write and what to expect back. */
1061 interface Plan {
1062 readonly frame: Uint8Array
1063 /** `CloseComplete` messages to consume before the cycle proper. */
1064 readonly closes: number
1065 /** Whether the frame carries a `Parse`. */
1066 readonly parses: boolean
1067 /** Whether the frame carries a `Describe`, so the columns arrive on the wire. */
1068 readonly describes: boolean
1069 /** The statement being filled in or reused, if this execution names one. */
1070 readonly prepared: Prepared | undefined
1071 /** Set when the columns were already known, so no `RowDescription` is coming. */
1072 readonly description: Description | undefined
1073 /** Set by the cycle when the backend rejected the name or the cached plan. */
1074 stale: boolean
1075 }
1076
1077 /** The unnamed path: `Parse` / `Bind` / `Describe` / `Execute` / `Sync`. */
1078 const encodeUnnamed = (
1079 sql: string,
1080 parameters: ReadonlyArray<PgTypes.Parameter>,
1081 parameterTypes: ReadonlyArray<number>,
1082 encodeBind: BindEncoder
1083 ): Plan => {
1084 const parse = PgProtocol.encodeParse({ name: "", query: sql, parameterTypes })
1085 if (EffectResult.isFailure(parse)) throw parse.failure
1086 const bind = encodeBind({ portal: "", statement: "", parameters })
1087 if (EffectResult.isFailure(bind)) throw bind.failure
1088 return {
1089 frame: concat([parse.success, bind.success, describeExecuteSync]),
1090 closes: 0,
1091 parses: true,
1092 describes: true,
1093 prepared: undefined,
1094 description: undefined,
1095 stale: false
1096 }
1097 }
1098
1099 /**
1100 * Builds one extended-query cycle as a single buffer, so a statement costs one
1101 * socket write.
1102 *
1103 * A statement the backend already holds under a name needs only
1104 * `Bind` / `Execute` / `Sync`: no `Parse` for the backend to plan and no
1105 * `Describe`, because the columns came back the first time and are cached with
1106 * the name. Statements evicted from the cache ride along as `Close` messages
1107 * rather than paying a round trip of their own.
1108 */
1109 const encodeQuery = (
1110 sql: string,
1111 params: ReadonlyArray<unknown>,
1112 registry: PgTypes.Registry | undefined,
1113 encodeBind: BindEncoder,
1114 cache: PreparedCache | undefined
1115 ): Plan => {
1116 const count = params.length
1117 const parameters: Array<PgTypes.Parameter> = new Array(count)
1118 const parameterTypes: Array<number> = new Array(count)
1119 for (let index = 0; index < count; index++) {
1120 const parameter = inferParameter(params[index], registry)
1121 parameters[index] = parameter
1122 parameterTypes[index] = parameter.oid
1123 }
1124
1125 if (cache === undefined) {
1126 return encodeUnnamed(sql, parameters, parameterTypes, encodeBind)
1127 }
1128
1129 const prepared = cache.get(sql, parameterTypes)
1130 if (!prepared.ready && prepared.parsing) {
1131 // Another cycle is already on the wire carrying this name's `Parse`.
1132 // Naming it again would collide, and reusing it would mean binding to
1133 // columns nobody has seen yet, so this execution goes unnamed.
1134 return encodeUnnamed(sql, parameters, parameterTypes, encodeBind)
1135 }
1136 const bind = encodeBind({ portal: "", statement: prepared.name, parameters })
1137 if (EffectResult.isFailure(bind)) throw bind.failure
1138 const parse = prepared.ready ? undefined : PgProtocol.encodeParse({ name: prepared.name, query: sql, parameterTypes })
1139 if (parse !== undefined && EffectResult.isFailure(parse)) throw parse.failure
1140 const closeFrames = cache.takeCloses()
1141
1142 if (parse === undefined) {
1143 return {
1144 frame: closeFrames === undefined
1145 ? concat([bind.success, executeSync])
1146 : concat([closeFrames.frames, bind.success, executeSync]),
1147 closes: closeFrames?.count ?? 0,
1148 parses: false,
1149 describes: false,
1150 prepared,
1151 description: prepared.description,
1152 stale: false
1153 }
1154 }
1155
1156 prepared.parsing = true
1157 return {
1158 frame: closeFrames === undefined
1159 ? concat([parse.success, bind.success, describeExecuteSync])
1160 : concat([closeFrames.frames, parse.success, bind.success, describeExecuteSync]),
1161 closes: closeFrames?.count ?? 0,
1162 parses: true,
1163 describes: true,
1164 prepared,
1165 description: undefined,
1166 stale: false
1167 }
1168 }
1169
1170 /**
1171 * The statements one connection has prepared, keyed by SQL text and the
1172 * parameter OIDs inferred for it: the same text with differently typed
1173 * parameters is a different statement to the backend.
1174 *
1175 * The cache is bounded and evicts least-recently-used. An evicted statement is
1176 * closed on the backend, but its `Close` waits for the next statement to go
1177 * out rather than taking a round trip of its own.
1178 */
1179 class PreparedCache {
1180 readonly max: number
1181 private readonly statements = new Map<string, Prepared>()
1182 private readonly namespace = randomBytes(8).toString("hex")
1183 private closes: Array<Uint8Array> | undefined
1184 private counter = 0
1185
1186 constructor(max: number) {
1187 this.max = max
1188 }
1189
1190 get(sql: string, parameterTypes: ReadonlyArray<number>): Prepared {
1191 const key = parameterTypes.length === 0 ? sql : `${sql}\u0000${parameterTypes.join(",")}`
1192 const found = this.statements.get(key)
1193 if (found !== undefined) {
1194 // Re-insert to move it to the end: `Map` iterates in insertion order, so
1195 // the first key is the least recently used one.
1196 this.statements.delete(key)
1197 this.statements.set(key, found)
1198 this.trim(found)
1199 return found
1200 }
1201 const prepared: Prepared = {
1202 name: `effect_${this.namespace}_${++this.counter}`,
1203 key,
1204 ready: false,
1205 parsing: false,
1206 description: undefined
1207 }
1208 this.statements.set(key, prepared)
1209 this.trim(prepared)
1210 return prepared
1211 }
1212
1213 /**
1214 * A statement still being parsed cannot be closed yet: its `Parse` may not
1215 * have reached the socket. Let the cache exceed its bound temporarily, then
1216 * discard abandoned entries and close excess ready statements on access.
1217 */
1218 private trim(protectedStatement?: Prepared): void {
1219 while (this.statements.size > this.max) {
1220 let evicted: Prepared | undefined
1221 for (const prepared of this.statements.values()) {
1222 if (prepared !== protectedStatement && (prepared.ready || !prepared.parsing)) {
1223 evicted = prepared
1224 break
1225 }
1226 }
1227 if (evicted === undefined) return
1228 this.statements.delete(evicted.key)
1229 if (evicted.ready) this.close(evicted.name)
1230 }
1231 }
1232
1233 /**
1234 * Drops a statement the backend no longer holds, or whose plan went stale.
1235 *
1236 * The name is closed either way. A plan that went stale is still held under
1237 * it, and re-parsing would collide; a name the backend has already lost
1238 * ignores the `Close`, which Postgres treats as a success.
1239 */
1240 evict(prepared: Prepared): void {
1241 if (prepared.parsing) return
1242 if (this.statements.delete(prepared.key) && prepared.ready) this.close(prepared.name)
1243 }
1244
1245 /**
1246 * Drops a statement whose parsing cycle failed before its columns arrived.
1247 *
1248 * A `Parse` that completed before the error outlives the failed cycle, so
1249 * the backend may hold the name while the entry can never become ready. The
1250 * name is closed either way: closing one the backend never registered is a
1251 * no-op.
1252 */
1253 evictFailed(prepared: Prepared): void {
1254 this.statements.delete(prepared.key)
1255 this.close(prepared.name)
1256 }
1257
1258 private close(name: string): void {
1259 ;(this.closes ??= []).push(PgProtocol.encodeClose({ target: "statement", name }))
1260 }
1261
1262 takeCloses(): { readonly frames: Uint8Array; readonly count: number } | undefined {
1263 const closes = this.closes
1264 if (closes === undefined) return undefined
1265 this.closes = undefined
1266 return { frames: closes.length === 1 ? closes[0] : concat(closes), count: closes.length }
1267 }
1268 }
1269
1270 /**
1271 * SQLSTATEs that mean "this name is no longer usable": the backend lost the
1272 * statement, or the plan behind it no longer matches the columns it was
1273 * prepared for. Both are recovered by parsing the statement again.
1274 */
1275 const isStalePreparedStatement = (code: string | undefined): boolean => code === "26000" || code === "0A000"
1276
1277 type BindEncoder = (options: {
1278 readonly portal: string
1279 readonly statement: string
1280 readonly parameters: ReadonlyArray<PgTypes.Parameter>
1281 }) => EffectResult.Result<Uint8Array, PgProtocol.EncodeError | PgTypes.CodecError>
1282
1283 /**
1284 * The default builtin-catalogue encoder, shared by every connection without a
1285 * custom registry. Passing `PgTypes.writeParameter` itself engages
1286 * `makeBindEncoder`'s unsafe fast path.
1287 */
1288 const defaultBindEncoder: BindEncoder = PgProtocol.makeBindEncoder(PgTypes.writeParameter, PgTypes.isTextFormat)
1289
1290 /** One bind encoder per registry, since building one allocates a closure. */
1291 const makeBindEncoder = (registry: PgTypes.Registry | undefined): BindEncoder =>
1292 registry === undefined
1293 ? defaultBindEncoder
1294 : PgProtocol.makeBindEncoder(
1295 (sink: PgProtocol.ValueSink, parameter: PgTypes.Parameter) => PgTypes.writeParameter(sink, parameter, registry),
1296 PgTypes.isTextFormat
1297 )
1298
1299 const queryError = (cause: unknown, message: string): SqlError =>
1300 new SqlError({ reason: new UnknownError({ cause, message, operation: "query" }) })
1301
1302 /**
1303 * Retries a cycle whose named statement the backend no longer honors: the
1304 * statement is dropped from the cache and the retry runs unnamed, so it cannot
1305 * loop.
1306 */
1307 const retryStale = (
1308 plan: Plan,
1309 cache: PreparedCache,
1310 run: Effect.Effect<QueryOutput, SqlError>,
1311 rerun: () => Effect.Effect<QueryOutput, SqlError>
1312 ): Effect.Effect<QueryOutput, SqlError> =>
1313 Effect.catchCause(run, (cause) => {
1314 if (!plan.stale) return Effect.failCause(cause)
1315 cache.evict(plan.prepared!)
1316 return rerun()
1317 })
1318
1319 const connectionQueryError = (cause: unknown, message: string): SqlError =>
1320 new SqlError({ reason: new ConnectionError({ cause, message, operation: "query" }) })
1321
1322 const pinReleasedError = (): SqlError =>
1323 connectionQueryError(new Error("Pinned connection was released"), "PgConnection: Pinned connection was released")
1324
1325 const escapeIdentifier = (identifier: string): string => `"${identifier.replaceAll("\"", "\"\"")}"`
1326
1327 type QueryPhase = "close" | "parse" | "bind" | "describe" | "rows" | "complete" | "error"
1328
1329 /**
1330 * Splits a command tag such as `SELECT 3` or `INSERT 0 1`. Reading the two
1331 * spaces directly keeps a completed statement from allocating the parts array
1332 * that splitting on every space would.
1333 */
1334 const parseCommandTag = (tag: string): { command: string; rowCount: number; oid: number | null } => {
1335 const firstSpace = tag.indexOf(" ")
1336 if (firstSpace < 0) return { command: tag, oid: null, rowCount: 0 }
1337 const command = tag.slice(0, firstSpace)
1338 const secondSpace = tag.indexOf(" ", firstSpace + 1)
1339 if (command === "INSERT" && secondSpace > 0) {
1340 return {
1341 command,
1342 oid: Number(tag.slice(firstSpace + 1, secondSpace)),
1343 rowCount: Number(tag.slice(secondSpace + 1))
1344 }
1345 }
1346 const last = tag.slice((secondSpace < 0 ? firstSpace : secondSpace) + 1)
1347 return { command, oid: null, rowCount: isDigits(last) ? Number(last) : 0 }
1348 }
1349
1350 const isDigits = (value: string): boolean => {
1351 if (value.length === 0) return false
1352 for (let index = 0; index < value.length; index++) {
1353 const code = value.charCodeAt(index)
1354 if (code < 48 || code > 57) return false
1355 }
1356 return true
1357 }
1358
1359 /**
1360 * Tracks one query cycle while the connection routes backend messages to it.
1361 * Each pipelined cycle keeps its own parser state and completes once.
1362 */
1363 class QueryMachine implements Consumer {
1364 private readonly conn: PgConnectionImpl
1365 private readonly plan: Plan
1366 private readonly finish: (effect: Effect.Effect<QueryOutput, SqlError>) => void
1367 /** Installed on the parser while this machine is at the head of the queue. */
1368 readonly readField: PgProtocol.FieldReader<unknown> | undefined
1369 /** Object rows, or `undefined` when the caller asked for positional ones. */
1370 private readonly rows: Array<Row> | undefined
1371 private readonly values: Array<ReadonlyArray<unknown>> | undefined
1372
1373 private closes: number
1374 private phase: QueryPhase
1375 private fieldCount: number
1376 private resultFields: ReadonlyArray<Field>
1377 private rowBuilder: RowBuilder | undefined
1378 private command = ""
1379 private rowCount = 0
1380 private oid: number | null = null
1381 private failure: SqlError | undefined
1382 private done = false
1383 private aborted = false
1384 private drainDone: (() => void) | undefined
1385
1386 constructor(
1387 conn: PgConnectionImpl,
1388 plan: Plan,
1389 wantRows: boolean,
1390 finish: (effect: Effect.Effect<QueryOutput, SqlError>) => void
1391 ) {
1392 this.conn = conn
1393 this.plan = plan
1394 this.finish = finish
1395 this.rows = wantRows ? [] : undefined
1396 this.values = wantRows ? undefined : []
1397 this.closes = plan.closes
1398 this.phase = plan.closes > 0 ? "close" : plan.parses ? "parse" : "bind"
1399 const description = plan.description
1400 this.readField = description?.readField
1401 this.fieldCount = description?.resultFields.length ?? 0
1402 this.resultFields = description?.resultFields ?? emptyFields
1403 this.rowBuilder = description?.rowBuilder
1404 }
1405
1406 isDone(): boolean {
1407 return this.done
1408 }
1409
1410 abort(onDrained: () => void): void {
1411 if (this.done) return onDrained()
1412 this.aborted = true
1413 this.drainDone = onDrained
1414 }
1415
1416 private complete(effect: Effect.Effect<QueryOutput, SqlError>): void {
1417 if (this.done) return
1418 this.done = true
1419 // Whether it parsed or not, this cycle no longer holds the name: success
1420 // has already marked it ready, failure leaves it to be parsed again.
1421 const prepared = this.plan.prepared
1422 if (prepared !== undefined) prepared.parsing = false
1423 this.finish(effect)
1424 }
1425
1426 private failDesync(message: string): void {
1427 this.conn.fatal(connectionQueryError(new Error(message), `PgConnection: ${message}`))
1428 }
1429
1430 onFatal(error: SqlError): void {
1431 if (this.done) return
1432 this.done = true
1433 const prepared = this.plan.prepared
1434 if (prepared !== undefined) prepared.parsing = false
1435 if (this.aborted) this.drainDone?.()
1436 else this.finish(Effect.fail(this.failure ?? error))
1437 }
1438
1439 onMessage(message: PgProtocol.BackendMessage<unknown>): void {
1440 if (this.aborted) {
1441 if (message._tag === "ReadyForQuery") {
1442 this.done = true
1443 this.drainDone?.()
1444 }
1445 return
1446 }
1447 if (this.phase === "error") {
1448 if (message._tag === "ReadyForQuery") {
1449 // Retrying in an aborted transaction would mask the original error with 25P02.
1450 if (this.plan.stale && !this.plan.parses && message.status === "E") {
1451 this.conn.prepared?.evict(this.plan.prepared!)
1452 this.plan.stale = false
1453 }
1454 return this.complete(Effect.fail(this.failure!))
1455 }
1456 return this.failDesync(`Unexpected ${message._tag} after ErrorResponse`)
1457 }
1458 switch (message._tag) {
1459 case "CloseComplete":
1460 if (this.phase !== "close") return this.failDesync(`Unexpected CloseComplete during ${this.phase}`)
1461 if (--this.closes === 0) this.phase = this.plan.parses ? "parse" : "bind"
1462 return
1463 case "ParseComplete":
1464 if (this.phase !== "parse") return this.failDesync(`Unexpected ParseComplete during ${this.phase}`)
1465 this.phase = "bind"
1466 return
1467 case "BindComplete":
1468 if (this.phase !== "bind") return this.failDesync(`Unexpected BindComplete during ${this.phase}`)
1469 this.phase = this.plan.describes ? "describe" : "rows"
1470 return
1471 case "RowDescription": {
1472 if (this.phase !== "describe") return this.failDesync(`Unexpected RowDescription during ${this.phase}`)
1473 const description = describe(message.fields, this.conn.registry)
1474 if (EffectResult.isFailure(description)) {
1475 return this.conn.fatal(queryError(description.failure, "PgConnection: Failed to decode row"))
1476 }
1477 this.fieldCount = message.fields.length
1478 this.resultFields = description.success.resultFields
1479 this.rowBuilder = description.success.rowBuilder
1480 // `pushEach` hands this description over before it reads the rows
1481 // behind it, including rows that arrived in the same chunk.
1482 this.conn.session.parser.readField = description.success.readField
1483 const prepared = this.plan.prepared
1484 if (prepared !== undefined) {
1485 prepared.description = description.success
1486 prepared.ready = true
1487 }
1488 this.phase = "rows"
1489 return
1490 }
1491 case "NoData": {
1492 if (this.phase !== "describe") return this.failDesync(`Unexpected NoData during ${this.phase}`)
1493 const prepared = this.plan.prepared
1494 if (prepared !== undefined) {
1495 prepared.description = undefined
1496 prepared.ready = true
1497 }
1498 this.phase = "rows"
1499 return
1500 }
1501 case "DataRow": {
1502 if (this.phase !== "rows" || this.rowBuilder === undefined) {
1503 return this.failDesync(`Unexpected DataRow during ${this.phase}`)
1504 }
1505 const rowValues = message.values
1506 if (rowValues.length !== this.fieldCount) {
1507 return this.failDesync(`DataRow has ${rowValues.length} values for ${this.fieldCount} fields`)
1508 }
1509 if (this.rows !== undefined) this.rows.push(this.rowBuilder(rowValues))
1510 else this.values!.push(rowValues)
1511 return
1512 }
1513 case "CommandComplete": {
1514 if (this.phase !== "rows") return this.failDesync(`Unexpected CommandComplete during ${this.phase}`)
1515 const parsed = parseCommandTag(message.commandTag)
1516 this.command = parsed.command
1517 this.rowCount = parsed.rowCount
1518 this.oid = parsed.oid
1519 this.phase = "complete"
1520 return
1521 }
1522 case "EmptyQueryResponse":
1523 if (this.phase !== "rows") return this.failDesync(`Unexpected EmptyQueryResponse during ${this.phase}`)
1524 this.phase = "complete"
1525 return
1526 case "ErrorResponse": {
1527 if (isStalePreparedStatement(message.fields.code)) this.plan.stale = true
1528 // A cycle that carried this statement's `Parse` but failed before its
1529 // columns arrived leaves an entry that can never become ready while
1530 // the backend may still hold the name: the `Parse` outlives the
1531 // failed cycle. Drop the entry and close the name, so the next
1532 // execution parses fresh under a new one.
1533 const prepared = this.plan.prepared
1534 if (this.plan.parses && prepared !== undefined && !prepared.ready) {
1535 this.conn.prepared?.evictFailed(prepared)
1536 }
1537 // Every phase drains the same way: the backend skips the rest of the
1538 // cycle and sends `ReadyForQuery` after the `Sync` that closes it, so
1539 // a statement it refused to parse leaves the session usable.
1540 this.failure = new SqlError({
1541 reason: classifyFields(message.fields, "PgConnection: Query failed", "query")
1542 })
1543 this.phase = "error"
1544 return
1545 }
1546 case "ReadyForQuery":
1547 if (this.phase !== "complete") return this.failDesync(`Unexpected ReadyForQuery during ${this.phase}`)
1548 return this.complete(Effect.succeed({
1549 result: {
1550 command: this.command,
1551 rowCount: this.rowCount,
1552 oid: this.oid,
1553 rows: this.rows ?? emptyRows,
1554 fields: this.resultFields
1555 },
1556 values: this.values ?? emptyValues
1557 }))
1558 case "CopyInResponse":
1559 case "CopyOutResponse":
1560 case "CopyBothResponse":
1561 case "CopyData":
1562 case "CopyDone":
1563 return this.failDesync(`Unexpected ${message._tag}; COPY is not supported`)
1564 default:
1565 return this.failDesync(`Unexpected ${message._tag} during ${this.phase}`)
1566 }
1567 }
1568 }
1569
1570 const emptyRows: ReadonlyArray<Row> = []
1571 const emptyValues: ReadonlyArray<ReadonlyArray<unknown>> = []
1572
1573 /** Drains an aborted statement, sending a cancel after a short grace period and failing if it stalls. */
1574 const drainAborted = (
1575 conn: PgConnectionImpl,
1576 timeoutMessage: string,
1577 abort: (onDrained: () => void) => void
1578 ): Effect.Effect<void> => {
1579 const drained = Deferred.makeUnsafe<void>()
1580 const timeout = setTimeout(
1581 () => conn.fatal(connectionQueryError(new Error(timeoutMessage), `PgConnection: ${timeoutMessage}`)),
1582 abortDrainTimeoutMillis
1583 )
1584 abort(() => {
1585 clearTimeout(timeout)
1586 Deferred.doneUnsafe(drained, Effect.void)
1587 })
1588 const grace = Effect.callback<void>((resume) => {
1589 const timer = setTimeout(() => resume(Effect.void), abortDrainGraceMillis)
1590 return Effect.sync(() => clearTimeout(timer))
1591 })
1592 const cancelAndDrain = Effect.andThen(conn.cancel, Deferred.await(drained))
1593 return Effect.andThen(
1594 Effect.raceFirst(Deferred.await(drained), grace),
1595 Effect.suspend(() => Deferred.isDoneUnsafe(drained) ? Effect.void : cancelAndDrain)
1596 )
1597 }
1598
1599 /** One cycle on a connection that carries a single statement at a time. */
1600 const runQuery = (
1601 conn: PgConnectionImpl,
1602 plan: Plan,
1603 wantRows: boolean
1604 ): Effect.Effect<QueryOutput, SqlError> =>
1605 Effect.callback<QueryOutput, SqlError>((resume) => {
1606 if (conn.deadWith !== undefined) {
1607 resume(Effect.fail(conn.deadWith))
1608 return
1609 }
1610 const machine = new QueryMachine(conn, plan, wantRows, (effect) => {
1611 conn.consumer = undefined
1612 resume(effect)
1613 })
1614 conn.consumer = machine
1615 // A reused statement has no `RowDescription` coming, so its reader has to
1616 // be in place before the rows are.
1617 conn.session.parser.readField = machine.readField
1618 try {
1619 conn.session.socket.write(plan.frame)
1620 } catch (cause) {
1621 conn.fatal(connectionQueryError(cause, "PgConnection: Failed to write query"))
1622 }
1623
1624 return Effect.suspend(() => {
1625 if (machine.isDone()) return Effect.void
1626 return drainAborted(conn, "Query cancellation timed out", (onDrained) =>
1627 machine.abort(() => {
1628 conn.consumer = undefined
1629 onDrained()
1630 }))
1631 })
1632 })
1633
1634 /** Turns one decoded row into an object keyed by column name. */
1635 type RowBuilder = (rowValues: ReadonlyArray<unknown>) => Row
1636
1637 /** Everything a query needs from one `RowDescription`. */
1638 interface Description {
1639 readonly readField: PgProtocol.FieldReader<unknown>
1640 readonly rowBuilder: RowBuilder
1641 readonly resultFields: ReadonlyArray<Field>
1642 }
1643
1644 const emptyFields: ReadonlyArray<Field> = []
1645
1646 /** Derives the per-column readers and the row constructor for a description. */
1647 const describe = (
1648 fields: ReadonlyArray<PgProtocol.FieldDescription>,
1649 registry: PgTypes.Registry | undefined
1650 ): EffectResult.Result<Description, PgTypes.CodecError> => {
1651 const reader = PgTypes.makeFieldReader(fields, registry)
1652 if (EffectResult.isFailure(reader)) return EffectResult.fail(reader.failure)
1653 const resultFields: Array<Field> = new Array(fields.length)
1654 for (let index = 0; index < fields.length; index++) {
1655 resultFields[index] = { name: fields[index].name, dataTypeId: fields[index].dataTypeOid }
1656 }
1657 return EffectResult.succeed({
1658 readField: reader.success,
1659 rowBuilder: makeRowBuilder(fields),
1660 resultFields
1661 })
1662 }
1663
1664 /**
1665 * Builds the row constructor for one `RowDescription`.
1666 *
1667 * Assignment is an order of magnitude faster than `Object.defineProperty` and
1668 * stores the same own, enumerable, writable, configurable property - except
1669 * for `__proto__`, which assignment routes to the prototype setter instead. A
1670 * description carrying that column name falls back to the slow spelling.
1671 */
1672 const makeRowBuilder = (fields: ReadonlyArray<PgProtocol.FieldDescription>): RowBuilder => {
1673 const names: Array<string> = new Array(fields.length)
1674 let hasProto = false
1675 for (let index = 0; index < fields.length; index++) {
1676 const name = fields[index].name
1677 names[index] = name
1678 if (name === "__proto__") hasProto = true
1679 }
1680 if (hasProto) {
1681 return (rowValues) => {
1682 const row: Record<string, unknown> = {}
1683 for (let index = 0; index < names.length; index++) {
1684 Object.defineProperty(row, names[index], {
1685 value: rowValues[index],
1686 enumerable: true,
1687 configurable: true,
1688 writable: true
1689 })
1690 }
1691 return row
1692 }
1693 }
1694 return (rowValues) => {
1695 const row: Record<string, unknown> = {}
1696 for (let index = 0; index < names.length; index++) {
1697 row[names[index]] = rowValues[index]
1698 }
1699 return row
1700 }
1701 }
1702
1703 const streamRows = (
1704 conn: PgConnectionImpl,
1705 pin: Effect.Effect<PinnedPgConnection, never, Scope.Scope>,
1706 sql: string,
1707 params: ReadonlyArray<unknown>
1708 ): Stream.Stream<Row, SqlError> =>
1709 Stream.fromChannel(Channel.fromTransform(Effect.fnUntraced(function*(_, scope) {
1710 const pinned = yield* Scope.provide(pin, scope)
1711 yield* Scope.provide(
1712 Effect.acquireRelease(conn.wire.take(1), () => conn.wire.release(1)),
1713 scope
1714 )
1715 if (pinned.released) return yield* pinReleasedError()
1716 // Streams stay on the unnamed path: a stream pays its setup once over the
1717 // whole result, so naming the statement buys little and would need the
1718 // stale-plan retry to unwind rows already delivered.
1719 const plan = yield* Effect.try({
1720 try: () => conn.encodeQuery(sql, params, undefined),
1721 catch: (cause) => queryError(cause, "PgConnection: Failed to encode query")
1722 })
1723 const frame = plan.frame
1724
1725 const socket = conn.session.socket
1726 const parser = conn.session.parser
1727 let phase: QueryPhase = "parse"
1728 let fieldCount = 0
1729 let rowBuilder: RowBuilder | undefined
1730 let buffer: Array<Row> = []
1731 let failure: SqlError | undefined
1732 let finished = false
1733 let done = false
1734 let aborted = false
1735 let paused = false
1736 let pending:
1737 | ((effect: Effect.Effect<Arr.NonEmptyReadonlyArray<Row>, SqlError | Cause.Done>) => void)
1738 | undefined
1739 let drainDone: (() => void) | undefined
1740
1741 const setPaused = (value: boolean): void => {
1742 if (paused === value) return
1743 paused = value
1744 if (value) socket.pause()
1745 else socket.resume()
1746 }
1747
1748 const deliver = (): void => {
1749 if (pending === undefined) return
1750 const resume = pending
1751 if (buffer.length > 0) {
1752 const chunk = buffer as Arr.NonEmptyArray<Row>
1753 buffer = []
1754 pending = undefined
1755 resume(Effect.succeed(chunk))
1756 } else if (finished) {
1757 pending = undefined
1758 resume(failure !== undefined ? Effect.fail(failure) : Cause.done())
1759 }
1760 }
1761
1762 const onFatal = (error: SqlError): void => {
1763 if (done) return
1764 done = true
1765 finished = true
1766 if (failure === undefined) failure = error
1767 drainDone?.()
1768 deliver()
1769 }
1770 // `conn.fatal` notifies the registered consumer; the direct `onFatal` call
1771 // covers the case where the connection was already dead.
1772 const failFatal = (error: SqlError): void => {
1773 conn.fatal(error)
1774 onFatal(error)
1775 }
1776 const failDesync = (message: string): void =>
1777 failFatal(connectionQueryError(new Error(message), `PgConnection: ${message}`))
1778
1779 const onMessage = (message: PgProtocol.BackendMessage<unknown>): void => {
1780 if (aborted) {
1781 if (message._tag === "ReadyForQuery") {
1782 done = true
1783 conn.consumer = undefined
1784 drainDone?.()
1785 }
1786 return
1787 }
1788 if (phase === "error") {
1789 switch (message._tag) {
1790 case "ReadyForQuery":
1791 finished = true
1792 done = true
1793 conn.consumer = undefined
1794 deliver()
1795 return
1796 default:
1797 return failDesync(`Unexpected ${message._tag} after ErrorResponse`)
1798 }
1799 }
1800 switch (message._tag) {
1801 case "ParseComplete":
1802 if (phase !== "parse") return failDesync(`Unexpected ParseComplete during ${phase}`)
1803 phase = "bind"
1804 return
1805 case "BindComplete":
1806 if (phase !== "bind") return failDesync(`Unexpected BindComplete during ${phase}`)
1807 phase = "describe"
1808 return
1809 case "RowDescription": {
1810 if (phase !== "describe") return failDesync(`Unexpected RowDescription during ${phase}`)
1811 const description = describe(message.fields, conn.registry)
1812 if (EffectResult.isFailure(description)) {
1813 return failFatal(queryError(description.failure, "PgConnection: Failed to decode row"))
1814 }
1815 fieldCount = message.fields.length
1816 rowBuilder = description.success.rowBuilder
1817 parser.readField = description.success.readField
1818 phase = "rows"
1819 return
1820 }
1821 case "NoData":
1822 if (phase !== "describe") return failDesync(`Unexpected NoData during ${phase}`)
1823 phase = "rows"
1824 return
1825 case "DataRow": {
1826 if (phase !== "rows" || rowBuilder === undefined) {
1827 return failDesync(`Unexpected DataRow during ${phase}`)
1828 }
1829 const rowValues = message.values
1830 if (rowValues.length !== fieldCount) {
1831 return failDesync(`DataRow has ${rowValues.length} values for ${fieldCount} fields`)
1832 }
1833 buffer.push(rowBuilder(rowValues))
1834 return
1835 }
1836 case "CommandComplete":
1837 if (phase !== "rows") return failDesync(`Unexpected CommandComplete during ${phase}`)
1838 phase = "complete"
1839 return
1840 case "EmptyQueryResponse":
1841 if (phase !== "rows") return failDesync(`Unexpected EmptyQueryResponse during ${phase}`)
1842 phase = "complete"
1843 return
1844 case "ErrorResponse": {
1845 failure = new SqlError({
1846 reason: classifyFields(message.fields, "PgConnection: Query failed", "query")
1847 })
1848 phase = "error"
1849 return
1850 }
1851 case "ReadyForQuery":
1852 if (phase !== "complete") return failDesync(`Unexpected ReadyForQuery during ${phase}`)
1853 finished = true
1854 done = true
1855 conn.consumer = undefined
1856 deliver()
1857 return
1858 case "CopyInResponse":
1859 case "CopyOutResponse":
1860 case "CopyBothResponse":
1861 case "CopyData":
1862 case "CopyDone":
1863 return failDesync(`Unexpected ${message._tag}; COPY is not supported`)
1864 default:
1865 return failDesync(`Unexpected ${message._tag} during ${phase}`)
1866 }
1867 }
1868
1869 const onBatchEnd = (): void => {
1870 if (done || aborted) return
1871 if (pending !== undefined) deliver()
1872 else if (buffer.length >= streamPauseThreshold) setPaused(true)
1873 }
1874
1875 yield* Scope.addFinalizer(
1876 scope,
1877 Effect.suspend(() => {
1878 // A dead session has nothing left to drain.
1879 if (done || conn.deadWith !== undefined) return Effect.void
1880 aborted = true
1881 const drain = drainAborted(conn, "Stream cancellation timed out", (onDrained) => {
1882 drainDone = onDrained
1883 })
1884 setPaused(false)
1885 return drain
1886 })
1887 )
1888
1889 // Checked as the consumer is registered: a session that dies any earlier
1890 // has no consumer to tell through `onFatal`.
1891 if (conn.deadWith !== undefined) return yield* conn.deadWith
1892 conn.consumer = { onMessage, onBatchEnd, onFatal }
1893 parser.readField = undefined
1894 // @effect-diagnostics-next-line tryCatchInEffectGen:off
1895 try {
1896 socket.write(frame)
1897 } catch (cause) {
1898 failFatal(connectionQueryError(cause, "PgConnection: Failed to write query"))
1899 }
1900
1901 // @effect-diagnostics-next-line returnEffectInGen:off
1902 return Effect.callback<Arr.NonEmptyReadonlyArray<Row>, SqlError | Cause.Done>((resume) => {
1903 pending = resume
1904 setPaused(false)
1905 deliver()
1906 if (pending === undefined) return
1907 return Effect.sync(() => {
1908 if (pending === resume) pending = undefined
1909 })
1910 })
1911 })))
1912
1913 const listenChannel = (
1914 conn: PgConnectionImpl,
1915 pin: Effect.Effect<PinnedPgConnection, never, Scope.Scope>,
1916 channel: string
1917 ): Effect.Effect<Queue.Dequeue<Notification, SqlError>, SqlError, Scope.Scope> =>
1918 Effect.uninterruptibleMask((restore) =>
1919 Effect.gen(function*() {
1920 const channelError = validateChannelName(channel, "listen")
1921 if (channelError !== undefined) return yield* Effect.fail(channelError)
1922 const parentScope = yield* Scope.Scope
1923 const scope = yield* Scope.fork(parentScope)
1924 return yield* restore(Effect.gen(function*() {
1925 const pinned = yield* Scope.provide(pin, scope)
1926 if (conn.deadWith !== undefined) return yield* conn.deadWith
1927 if (pinned.released) return yield* pinReleasedError()
1928 const queue = yield* Queue.unbounded<Notification, SqlError>()
1929 const identifier = escapeIdentifier(channel)
1930 let queues = conn.channels.get(channel)
1931 if (queues === undefined) {
1932 queues = new Set()
1933 conn.channels.set(channel, queues)
1934 }
1935 queues.add(queue)
1936 pinned.listeners++
1937 yield* Scope.addFinalizer(
1938 scope,
1939 Effect.suspend(() => {
1940 pinned.listeners--
1941 const current = conn.channels.get(channel)
1942 if (current === undefined) return Queue.shutdown(queue)
1943 current.delete(queue)
1944 if (current.size > 0) return Queue.shutdown(queue)
1945 conn.channels.delete(channel)
1946 return Effect.andThen(unlisten(conn, pinned, identifier), Queue.shutdown(queue))
1947 })
1948 )
1949 yield* pinned.query(`LISTEN ${identifier}`)
1950 return queue
1951 })).pipe(
1952 Effect.tapCause((cause) => Scope.close(scope, Exit.failCause(cause)))
1953 )
1954 })
1955 )
1956
1957 /**
1958 * Runs `UNLISTEN` and closes the session if PostgreSQL does not answer in time.
1959 * The timer starts once the wire is free, so a long statement on the same
1960 * pinned session does not count against it. Nothing is sent once the session
1961 * is dead or its pin released, as the session may already have a new owner.
1962 * A pin released while `UNLISTEN` holds the wire waits for it to finish, so
1963 * the count moves together with the permit: the fiber cannot yield between
1964 * taking the wire and counting, or between uncounting and returning it.
1965 */
1966 const unlisten = (conn: PgConnectionImpl, pinned: PinnedPgConnection, identifier: string): Effect.Effect<void> =>
1967 Effect.uninterruptible(Effect.flatMap(
1968 withoutYield(Effect.flatMap(conn.wire.take(1), () =>
1969 Effect.sync(() => {
1970 pinned.unlistening++
1971 }))),
1972 () => {
1973 if (conn.deadWith !== undefined || pinned.released) return releaseUnlisten(conn, pinned)
1974 const timeout = setTimeout(
1975 () => conn.fatal(connectionQueryError(new Error("UNLISTEN timed out"), "PgConnection: UNLISTEN timed out")),
1976 unlistenTimeoutMillis
1977 )
1978 return Effect.ensuring(
1979 Effect.ignore(conn.cycleOwned(`UNLISTEN ${identifier}`, emptyParams, true, conn.prepared)),
1980 Effect.andThen(Effect.sync(() => clearTimeout(timeout)), releaseUnlisten(conn, pinned))
1981 )
1982 }
1983 ))
1984
1985 const releaseUnlisten = (conn: PgConnectionImpl, pinned: PinnedPgConnection): Effect.Effect<void> =>
1986 withoutYield(Effect.suspend(() => {
1987 pinned.unlistening--
1988 return Effect.asVoid(conn.wire.release(1))
1989 }))
1990
1991 const withoutYield = <A, E, R>(effect: Effect.Effect<A, E, R>): Effect.Effect<A, E, R> =>
1992 Effect.provideService(effect, Scheduler.PreventSchedulerYield, true)
1993
1994 const sendCancelRequest = (config: ResolvedConfig, session: Session): Effect.Effect<void> =>
1995 Effect.callback<void>((resume) => {
1996 let done = false
1997 let socket: Duplex
1998 let timer: ReturnType<typeof setTimeout> | undefined
1999 const finish = (): void => {
2000 if (done) return
2001 done = true
2002 if (timer !== undefined) clearTimeout(timer)
2003 socket?.destroy()
2004 resume(Effect.void)
2005 }
2006 const frame = PgProtocol.encodeCancelRequest({ pid: session.processId, secret: session.secretKey })
2007 // After the frame is written the server processes the request and closes
2008 // the connection, which lands in the `close` handler.
2009 const send = (): void => {
2010 socket.write(frame)
2011 }
2012 const begin = (): void => {
2013 if (config.ssl === false) return send()
2014 socket.once("data", (chunk: Uint8Array) => {
2015 if (done) return
2016 // A TLS session's cancel secret must stay encrypted.
2017 if (chunk.length === 1 && chunk[0] === 0x4e && config.sslOptional && !session.encrypted) return send()
2018 if (chunk.length !== 1 || chunk[0] !== 0x53) return finish()
2019 const raw = socket
2020 raw.off("error", finish)
2021 raw.off("close", finish)
2022 socket = Tls.connect({
2023 host: config.host,
2024 servername: Net.isIP(config.host) === 0 ? config.host : undefined,
2025 ...(typeof config.ssl === "object" ? config.ssl : {}),
2026 socket: raw as Net.Socket
2027 })
2028 socket.on("error", finish)
2029 socket.on("close", finish)
2030 socket.once("secureConnect", send)
2031 })
2032 socket.write(PgProtocol.encodeSslRequest())
2033 }
2034 try {
2035 socket = config.stream !== undefined
2036 ? config.stream()
2037 : config.path !== undefined
2038 ? Net.connect({ path: config.path })
2039 : Net.connect({ host: config.host, port: config.port, noDelay: true })
2040 } catch {
2041 resume(Effect.void)
2042 return
2043 }
2044 timer = setTimeout(finish, cancelRequestTimeoutMillis)
2045 socket.on("error", finish)
2046 socket.on("close", finish)
2047 if (config.stream !== undefined) begin()
2048 else socket.once("connect", begin)
2049 return Effect.sync(finish)
2050 })
2051
2052 const connect = (config: ResolvedConfig, resolvedPassword: string | undefined): Effect.Effect<Session, SqlError> =>
2053 Effect.callback<Session, SqlError>((resume) => {
2054 let done = false
2055 let socket: Duplex
2056 let encrypted = false
2057 let parser: PgProtocol.Parser<unknown> | undefined
2058 let sslErrorParser: PgProtocol.Parser | undefined
2059 let scram: PgAuth.ScramState | undefined
2060 let processId = 0
2061 let secretKey = 0
2062
2063 const fail = (reason: SqlErrorReason): void => {
2064 if (done) return
2065 done = true
2066 socket?.destroy()
2067 resume(Effect.fail(new SqlError({ reason })))
2068 }
2069 const failConnect = (cause: unknown, message: string): void =>
2070 fail(new ConnectionError({ cause, message, operation: "connect" }))
2071 const failAuth = (cause: unknown, message: string): void =>
2072 fail(new AuthenticationError({ cause, message, operation: "connect" }))
2073
2074 const onError = (cause: Error) => failConnect(cause, "PgConnection: Failed to connect")
2075 const onClose = () =>
2076 failConnect(new Error("Connection closed unexpectedly"), "PgConnection: Connection closed during startup")
2077
2078 const password = (): string | undefined => {
2079 if (resolvedPassword === undefined) {
2080 failAuth(
2081 new Error("The server requested password authentication"),
2082 "PgConnection: No password configured"
2083 )
2084 return undefined
2085 }
2086 return resolvedPassword
2087 }
2088
2089 const handleMessage = (message: PgProtocol.BackendMessage<unknown>): void => {
2090 switch (message._tag) {
2091 case "AuthenticationOk":
2092 case "NoticeResponse":
2093 case "NegotiateProtocolVersion":
2094 case "ParameterStatus":
2095 return
2096 case "AuthenticationCleartextPassword": {
2097 const secret = password()
2098 if (secret === undefined) return
2099 socket.write(PgProtocol.encodePasswordMessage({ password: secret }))
2100 return
2101 }
2102 case "AuthenticationMD5Password": {
2103 const secret = password()
2104 if (secret === undefined) return
2105 const hashed = PgAuth.md5Password({ user: config.username, password: secret, salt: message.salt })
2106 if (EffectResult.isFailure(hashed)) {
2107 return failAuth(hashed.failure, "PgConnection: MD5 authentication failed")
2108 }
2109 socket.write(PgProtocol.encodePasswordMessage({ password: hashed.success }))
2110 return
2111 }
2112 case "AuthenticationSASL": {
2113 if (!message.mechanisms.includes(PgAuth.SCRAM_SHA_256)) {
2114 return failAuth(
2115 new Error(`Unsupported SASL mechanisms: ${message.mechanisms.join(", ")}`),
2116 `PgConnection: Only ${PgAuth.SCRAM_SHA_256} is supported`
2117 )
2118 }
2119 const secret = password()
2120 if (secret === undefined) return
2121 const init = PgAuth.scramInit({ password: secret, nonce: randomBytes(18).toString("base64") })
2122 if (EffectResult.isFailure(init)) {
2123 return failAuth(init.failure, "PgConnection: SCRAM authentication failed")
2124 }
2125 scram = init.success.state
2126 socket.write(PgProtocol.encodeSASLInitialResponse({
2127 mechanism: PgAuth.SCRAM_SHA_256,
2128 initialResponse: init.success.response
2129 }))
2130 return
2131 }
2132 case "AuthenticationSASLContinue": {
2133 if (scram === undefined || scram._tag !== "ScramFirst") {
2134 return failConnect(new Error("Unexpected AuthenticationSASLContinue"), "PgConnection: Protocol desync")
2135 }
2136 const next = PgAuth.scramContinue(scram, message.data)
2137 if (EffectResult.isFailure(next)) {
2138 return failAuth(next.failure, "PgConnection: SCRAM authentication failed")
2139 }
2140 scram = next.success.state
2141 socket.write(PgProtocol.encodeSASLResponse({ data: next.success.response }))
2142 return
2143 }
2144 case "AuthenticationSASLFinal": {
2145 if (scram === undefined || scram._tag !== "ScramFinal") {
2146 return failConnect(new Error("Unexpected AuthenticationSASLFinal"), "PgConnection: Protocol desync")
2147 }
2148 const verified = PgAuth.scramFinish(scram, message.data)
2149 if (EffectResult.isFailure(verified)) {
2150 return failAuth(verified.failure, "PgConnection: SCRAM server verification failed")
2151 }
2152 scram = undefined
2153 return
2154 }
2155 case "AuthenticationUnsupported":
2156 return failAuth(
2157 new Error(`Authentication method ${message.method} is not supported`),
2158 "PgConnection: Unsupported authentication method"
2159 )
2160 case "BackendKeyData":
2161 processId = message.pid
2162 secretKey = message.secret
2163 return
2164 case "ErrorResponse":
2165 return fail(classifyFields(message.fields, "PgConnection: Failed to connect", "connect"))
2166 case "ReadyForQuery":
2167 if (scram !== undefined) {
2168 return failAuth(
2169 new Error("The server completed authentication without proving its identity"),
2170 "PgConnection: SCRAM exchange did not complete"
2171 )
2172 }
2173 done = true
2174 socket.off("data", onData)
2175 socket.off("error", onError)
2176 socket.off("close", onClose)
2177 socket.on("error", ignoreError)
2178 resume(Effect.succeed({ socket, encrypted, parser: parser!, processId, secretKey }))
2179 return
2180 default:
2181 return failConnect(
2182 new Error(`Unexpected ${message._tag} message during startup`),
2183 "PgConnection: Protocol desync"
2184 )
2185 }
2186 }
2187
2188 const onData = (chunk: Uint8Array): void => {
2189 let messages: ReadonlyArray<PgProtocol.BackendMessage<unknown>>
2190 try {
2191 messages = parser!.push(chunk)
2192 } catch (cause) {
2193 return failConnect(cause, "PgConnection: Failed to parse server response")
2194 }
2195 for (const message of messages) {
2196 if (done) return
2197 handleMessage(message)
2198 }
2199 }
2200
2201 const startup = (): void => {
2202 parser = PgProtocol.makeParser<unknown>({ maxMessageSize: config.maxMessageSize })
2203 socket.on("data", onData)
2204 socket.write(PgProtocol.encodeStartupMessage(config.startupParameters))
2205 }
2206
2207 const onSslResponse = (chunk: Uint8Array): void => {
2208 if (done) return
2209 if (sslErrorParser !== undefined || chunk[0] === 0x45) {
2210 sslErrorParser ??= PgProtocol.makeParser({ maxMessageSize: config.maxMessageSize })
2211 let messages: ReadonlyArray<PgProtocol.BackendMessage>
2212 try {
2213 messages = sslErrorParser.push(chunk)
2214 } catch (cause) {
2215 return failConnect(cause, "PgConnection: Failed to parse SSLRequest error response")
2216 }
2217 if (messages.length === 0) return
2218 socket.off("data", onSslResponse)
2219 const message = messages[0]
2220 if (messages.length !== 1 || message._tag !== "ErrorResponse") {
2221 return failConnect(
2222 new Error("Expected one ErrorResponse after SSLRequest"),
2223 "PgConnection: Invalid SSLRequest response"
2224 )
2225 }
2226 return fail(classifyFields(message.fields, "PgConnection: Failed to negotiate TLS", "connect"))
2227 }
2228 socket.off("data", onSslResponse)
2229 if (chunk.length !== 1) {
2230 return failConnect(
2231 new Error(`Received ${chunk.length} bytes in response to SSLRequest`),
2232 "PgConnection: Invalid SSLRequest response"
2233 )
2234 }
2235 const response = PgProtocol.decodeSslResponse(chunk[0])
2236 if (EffectResult.isFailure(response)) {
2237 return failConnect(response.failure, "PgConnection: Invalid SSLRequest response")
2238 }
2239 if (response.success === "N") {
2240 if (config.sslOptional) return startup()
2241 return failConnect(new Error("The server does not support TLS"), "PgConnection: Server refused TLS")
2242 }
2243 const raw = socket
2244 raw.off("error", onError)
2245 raw.off("close", onClose)
2246 socket = Tls.connect({
2247 host: config.host,
2248 servername: Net.isIP(config.host) === 0 ? config.host : undefined,
2249 ...(typeof config.ssl === "object" ? config.ssl : {}),
2250 socket: raw as Net.Socket
2251 })
2252 socket.on("error", onError)
2253 socket.on("close", onClose)
2254 socket.once("secureConnect", () => {
2255 encrypted = true
2256 startup()
2257 })
2258 }
2259
2260 const begin = (): void => {
2261 if (config.ssl === false) return startup()
2262 socket.on("data", onSslResponse)
2263 socket.write(PgProtocol.encodeSslRequest())
2264 }
2265
2266 try {
2267 socket = config.stream !== undefined
2268 ? config.stream()
2269 : config.path !== undefined
2270 ? Net.connect({ path: config.path })
2271 // A statement is one write and then a wait for its answer, so Nagle has
2272 // nothing to coalesce and only holds the write back.
2273 : Net.connect({
2274 host: config.host,
2275 port: config.port,
2276 noDelay: true,
2277 ...(config.keepAlive !== undefined && { keepAlive: true, keepAliveInitialDelay: config.keepAlive })
2278 })
2279 } catch (cause) {
2280 resume(Effect.fail(
2281 new SqlError({
2282 reason: new ConnectionError({ cause, message: "PgConnection: Failed to connect", operation: "connect" })
2283 })
2284 ))
2285 return
2286 }
2287 socket.on("error", onError)
2288 socket.on("close", onClose)
2289 if (config.stream !== undefined) {
2290 begin()
2291 } else {
2292 socket.once("connect", begin)
2293 }
2294
2295 return Effect.sync(() => {
2296 if (done) return
2297 done = true
2298 socket.destroy()
2299 })
2300 })
2301
2302 const ignoreError = (_: Error) => {}
2303
2304 const classifyFields = (
2305 fields: PgProtocol.ErrorFields,
2306 message: string,
2307 operation: string
2308 ): SqlErrorReason => {
2309 const cause = Object.assign(new Error(fields.message ?? "Unknown PostgreSQL error"), fields)
2310 return classifySqlState(fields.code, fields.constraint, { cause, message, operation })
2311 }