@devries-cameron20 / t3code Mirror · read-only
Fork 0

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

Mirrored from https://github.com/Camo67/t3code.git

Synced Nov 21, 04:45 UTC

main
ts 349 lines 13.2 KB
Raw
1 /**
2 * Pools of native `PgConnection` sessions.
3 *
4 * @stability unstable
5 * @since 4.0.0
6 */
7 import * as Clock from "effect/Clock"
8 import * as Context from "effect/Context"
9 import * as Duration from "effect/Duration"
10 import * as Effect from "effect/Effect"
11 import * as Exit from "effect/Exit"
12 import * as Option from "effect/Option"
13 import * as Pool from "effect/Pool"
14 import { TracerTimingEnabled } from "effect/References"
15 import * as Scope from "effect/Scope"
16 import { ConnectionError, SqlError } from "effect/sql/SqlError"
17 import { SpanPropagationEnabled } from "effect/sql/Statement"
18 import * as Tracer from "effect/Tracer"
19 import { connectionInternals } from "./internal/connection.ts"
20 import * as PgConnection from "./PgConnection.ts"
21
22 const defaultMultiplexConcurrency = 32
23
24 /**
25 * The runtime type identifier for `PgPool`.
26 *
27 * @stability unstable
28 * @category type IDs
29 * @since 4.0.0
30 */
31 export const TypeId: TypeId = "~@effect/sql-pg/PgPool"
32
33 /**
34 * The type-level identifier for `PgPool`.
35 *
36 * @stability unstable
37 * @category type IDs
38 * @since 4.0.0
39 */
40 export type TypeId = "~@effect/sql-pg/PgPool"
41
42 /**
43 * Connection and sizing settings for a PostgreSQL session pool.
44 *
45 * **Details**
46 *
47 * The defaults are 0 to 10 connections and a 60-second idle timeout.
48 * `connectionTTL` replaces connections that exceed the configured lifetime.
49 * Every connection is used at least once, so a TTL of zero disables reuse.
50 * `acquireTimeout` bounds how long a checkout takes to acquire a connection,
51 * including opening a new one; by default it waits indefinitely.
52 *
53 * With `multiplex` enabled, fibers may share pooled connections for pipelined
54 * queries. Reserved connections remain exclusive. Without multiplexing, every
55 * checkout is exclusive.
56 *
57 * @stability unstable
58 * @category models
59 * @since 4.0.0
60 */
61 export interface Config extends PgConnection.Config {
62 readonly idleTimeout?: Duration.Input | undefined
63 readonly maxConnections?: number | undefined
64 readonly minConnections?: number | undefined
65 readonly connectionTTL?: Duration.Input | undefined
66 /**
67 * How long a checkout may take to acquire a connection before failing with
68 * a `ConnectionError`. Acquisition includes waiting for a free connection
69 * and opening a new one when the pool needs it. With `multiplex` on,
70 * `reserve` also waits for statements already sent on the shared connection
71 * to finish, and that wait counts too. Work done with the connection after
72 * it is acquired is not bounded. Unbounded by default.
73 */
74 readonly acquireTimeout?: Duration.Input | undefined
75 /**
76 * How many statements may share one connection when `multiplex` is on.
77 * Defaults to `32`. Statements are pipelined into one write, so a higher
78 * number means fewer round trips, but it also means a slow statement holds
79 * up more of the statements queued behind it.
80 */
81 readonly multiplexConcurrency?: number | undefined
82 }
83
84 /**
85 * A PostgreSQL session pool.
86 *
87 * @stability unstable
88 * @category models
89 * @since 4.0.0
90 */
91 export interface PgPool {
92 readonly [TypeId]: TypeId
93 readonly config: Config
94 /**
95 * Checks out a session until the scope closes. Without multiplexing the
96 * checkout is exclusive. With multiplexing the
97 * session may be shared with other fibers, so multi-statement work should
98 * use `reserve` instead.
99 */
100 readonly get: Effect.Effect<PgConnection.PgConnection, SqlError, Scope.Scope>
101 /**
102 * Checks out a session for exclusive use until the scope closes. Use this for
103 * transactions and listeners on a multiplexed pool.
104 */
105 readonly reserve: Effect.Effect<PgConnection.PgConnection, SqlError, Scope.Scope>
106 /**
107 * Removes a session so the pool can replace it. Fatal protocol and socket
108 * errors invalidate sessions automatically.
109 */
110 /**
111 * Lends a session for the duration of one effect and takes it back on any
112 * exit, without opening a scope for it.
113 *
114 * **Details**
115 *
116 * For work that finishes with the effect that runs it. A lease that has to
117 * outlive its effect - a stream, a transaction - takes `get` or `reserve`.
118 */
119 readonly use: <A, E, R>(
120 f: (connection: PgConnection.PgConnection) => Effect.Effect<A, E, R>
121 ) => Effect.Effect<A, E | SqlError, R>
122 readonly invalidate: (connection: PgConnection.PgConnection) => Effect.Effect<void>
123 /**
124 * Returns a snapshot of session occupancy. Counts sessions rather than
125 * statements, so a multiplexed session shared by many fibers counts once. A
126 * session that has just failed can show as idle until the pool removes it.
127 */
128 readonly stats: Effect.Effect<Pool.Stats>
129 }
130
131 /**
132 * The service tag for `PgPool`.
133 *
134 * @stability unstable
135 * @category services
136 * @since 4.0.0
137 */
138 export const PgPool = Context.Service<PgPool>("@effect/sql-pg/PgPool")
139
140 /**
141 * Creates a scoped PostgreSQL session pool.
142 *
143 * **Details**
144 *
145 * Connections are opened lazily up to `maxConnections` and released down to
146 * `minConnections` after `idleTimeout` without use. Closing the scope shuts
147 * the pool down and releases every session.
148 *
149 * With `SpanPropagationEnabled`, a statement that waited for a new session gets
150 * a `db.connect` child span covering the part of the connect it waited for.
151 *
152 * @stability unstable
153 * @category constructors
154 * @since 4.0.0
155 */
156 export const make = Effect.fnUntraced(function*(options: Config): Effect.fn.Return<PgPool, SqlError, Scope.Scope> {
157 const clock = yield* Clock.Clock
158 const runFork = Effect.runForkWith(yield* Effect.context())
159
160 const multiplex = options.multiplex ?? false
161 const connectionTTL = options.connectionTTL !== undefined
162 ? Duration.toMillis(Duration.fromInputUnsafe(options.connectionTTL))
163 : undefined
164 const acquireTimeout = options.acquireTimeout !== undefined
165 ? Duration.fromInputUnsafe(options.acquireTimeout)
166 : undefined
167 const deadConnections = new Set<PgConnection.PgConnection>()
168 const createdAt = new WeakMap<PgConnection.PgConnection, number>()
169 const checkedOut = new WeakSet<PgConnection.PgConnection>()
170
171 // The pool opens sessions on its own fiber, where a span would have no
172 // statement parent. Each connect is recorded here instead and reported on the
173 // session's first checkout, under the statement that waited for it.
174 const connects = new WeakMap<PgConnection.PgConnection, readonly [startTime: bigint, endTime: bigint]>()
175
176 const reportConnect = (connection: PgConnection.PgConnection): Effect.Effect<void> =>
177 Effect.withFiber((fiber) => {
178 const opened = connects.get(connection)
179 if (opened === undefined) return Effect.void
180 connects.delete(connection)
181 const statement = fiber.cache.span
182 // Without span timing the statement span has no start time to measure from.
183 if (
184 !fiber.cache.tracerEnabled || statement?._tag !== "Span" || !fiber.getRef(SpanPropagationEnabled) ||
185 !fiber.getRef(TracerTimingEnabled)
186 ) {
187 return Effect.void
188 }
189 const [startTime, endTime] = opened
190 const waitedFrom = statement.status.startTime
191 if (endTime < waitedFrom) return Effect.void
192 const span = fiber.getRef(Tracer.Tracer).span({
193 name: "db.connect",
194 parent: Option.some(statement),
195 annotations: Context.empty(),
196 links: [],
197 startTime: startTime > waitedFrom ? startTime : waitedFrom,
198 kind: "client",
199 root: false,
200 sampled: statement.sampled
201 })
202 span.attribute("db.system.name", "postgresql")
203 span.attribute("db.client.connection.connect_time_ms", Number(endTime - startTime) / 1e6)
204 span.end(endTime, Exit.void)
205 return Effect.void
206 })
207
208 const handOut = (connection: PgConnection.PgConnection) =>
209 connects.has(connection) ? Effect.as(reportConnect(connection), connection) : Effect.succeed(connection)
210
211 // Assigned below, once the pool exists. `acquire` only runs when the pool
212 // opens a connection, which is always after that.
213 let pool: Pool.Pool<PgConnection.PgConnection, SqlError>
214 const acquire = Effect.suspend(() => {
215 const startTime = clock.currentTimeNanosUnsafe()
216 return Effect.tap(PgConnection.make(options), (connection) =>
217 Effect.sync(() => {
218 connects.set(connection, [startTime, clock.currentTimeNanosUnsafe()])
219 createdAt.set(connection, clock.currentTimeMillisUnsafe())
220 const internals = connectionInternals(connection)
221 internals.retireHooks.add(() => {
222 deadConnections.add(connection)
223 // `deadConnections` is only read by the next checkout, and a checkout
224 // already waiting for this connection would never get that far. Tell
225 // the pool now so it can replace the connection and admit them.
226 runFork(Pool.invalidate(pool, connection))
227 })
228 // Pinning a shared session has to take it out of circulation, or a
229 // second checkout lands on the connection its own stream is holding.
230 if (multiplex) internals.reserve = Pool.reserve(pool, connection)
231 }))
232 })
233
234 const maxConnections = options.maxConnections ?? 10
235 pool = yield* Pool.makeWithTTL({
236 acquire,
237 min: options.minConnections ?? 0,
238 max: maxConnections,
239 concurrency: multiplex
240 ? Math.max(1, options.multiplexConcurrency ?? defaultMultiplexConcurrency)
241 : 1,
242 timeToLive: options.idleTimeout ?? Duration.seconds(60),
243 timeToLiveStrategy: "usage"
244 })
245
246 const expired = (connection: PgConnection.PgConnection): boolean => {
247 if (connectionInternals(connection).deadError() !== undefined) return true
248 if (connectionTTL === undefined) return false
249 if (!checkedOut.has(connection)) {
250 checkedOut.add(connection)
251 return false
252 }
253 const openedAt = createdAt.get(connection)
254 return openedAt !== undefined && clock.currentTimeMillisUnsafe() - openedAt >= connectionTTL
255 }
256
257 // A checkout runs per statement, so the case where nothing has died and the
258 // first connection is usable stays a plain flatMap; retrying is the
259 // exception and pays for the loop.
260 const retry: Effect.Effect<PgConnection.PgConnection, SqlError, Scope.Scope> = Effect.gen(function*() {
261 while (true) {
262 if (deadConnections.size > 0) {
263 const dead = Array.from(deadConnections)
264 deadConnections.clear()
265 yield* Effect.forEach(dead, (connection) => Pool.invalidate(pool, connection), { discard: true })
266 }
267 const connection = yield* Pool.get(pool)
268 if (expired(connection)) {
269 yield* Pool.invalidate(pool, connection)
270 continue
271 }
272 return connection
273 }
274 })
275
276 const checkout: Effect.Effect<PgConnection.PgConnection, SqlError, Scope.Scope> = Effect.suspend(() =>
277 deadConnections.size > 0 ? retry : Effect.flatMap(Pool.get(pool), (connection) =>
278 expired(connection)
279 ? Effect.andThen(Pool.invalidate(pool, connection), retry)
280 : Effect.succeed(connection))
281 )
282
283 const acquireTimedOut = () =>
284 Effect.fail(
285 new SqlError({
286 reason: new ConnectionError({
287 cause: new Error("Timed out waiting for a pooled connection"),
288 message: "PgPool: Timed out waiting for a pooled connection",
289 operation: "acquireConnection"
290 })
291 })
292 )
293
294 // The acquisition runs in a child scope, so a timeout or failure gives back
295 // any lease or reservation it already took instead of leaving them to the
296 // caller's scope. On success the child scope closes with the caller's.
297 const withAcquireTimeout = <A>(
298 effect: Effect.Effect<A, SqlError, Scope.Scope>
299 ): Effect.Effect<A, SqlError, Scope.Scope> =>
300 acquireTimeout === undefined ?
301 effect :
302 Effect.uninterruptibleMask((restore) =>
303 Effect.flatMap(Effect.scope, (parent) =>
304 Effect.flatMap(Scope.fork(parent), (scope) =>
305 Effect.onError(
306 restore(Effect.timeoutOrElse(Scope.provide(effect, scope), {
307 duration: acquireTimeout,
308 orElse: acquireTimedOut
309 })),
310 (cause) => Scope.close(scope, Exit.failCause(cause))
311 )))
312 )
313
314 const handedOut = Effect.flatMap(checkout, handOut)
315 const get = withAcquireTimeout(handedOut)
316
317 // `pin` reserves the pool item itself. On a multiplexed pool it also waits
318 // for shared statements to drain, so the acquire timeout covers it too.
319 const reserve = withAcquireTimeout(Effect.flatMap(handedOut, (connection) => connection.pin))
320
321 // `Pool.use` cannot pre-check a session or bound its wait. Use it only when
322 // no TTL or acquire timeout applies and no connection awaits retirement.
323 // Checking inside its callback can deadlock a size-one pool while acquiring
324 // a replacement.
325 const use = <A, E, R>(
326 f: (connection: PgConnection.PgConnection) => Effect.Effect<A, E, R>
327 ): Effect.Effect<A, E | SqlError, R> =>
328 Effect.suspend(() =>
329 connectionTTL === undefined && acquireTimeout === undefined && deadConnections.size === 0
330 ? Pool.use(
331 pool,
332 (connection) =>
333 connects.has(connection) ? Effect.andThen(reportConnect(connection), f(connection)) : f(connection)
334 )
335 : Effect.scoped(Effect.flatMap(get, f))
336 )
337
338 const pgPool: PgPool = {
339 [TypeId]: TypeId,
340 config: options,
341 get,
342 reserve,
343 use,
344 invalidate: (connection) =>
345 Pool.invalidate(pool, connectionInternals(connection).base as PgConnection.PgConnection),
346 stats: Pool.stats(pool)
347 }
348 return pgPool
349 })