@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 611 lines 24.1 KB
Raw
1 import { STATE_STORE_VERSION } from "alchemy/State/HttpStateApi";
2 import type { ReplacedResourceState } from "alchemy/State/ResourceState";
3 import {
4 State,
5 StateStoreError,
6 type PersistedState,
7 type StateService,
8 } from "alchemy/State/State";
9 import { encodeState, reviveStateRecursive } from "alchemy/State/StateEncoding";
10 import { recordStateStoreInit } from "alchemy/Telemetry/Metrics";
11 import * as Context from "effect/Context";
12 import * as Effect from "effect/Effect";
13 import * as Exit from "effect/Exit";
14 import * as Layer from "effect/Layer";
15 import type * as Redacted from "effect/Redacted";
16 import * as Scope from "effect/Scope";
17 import * as Semaphore from "effect/Semaphore";
18 import type * as SqlClient from "effect/sql/SqlClient";
19 import type * as SqlError from "effect/sql/SqlError";
20 import { resolveConnectionOptions } from "./PostgresTls.ts";
21
22 // `@effect/sql-pg` is loaded lazily rather than imported statically (as
23 // `SQL/Postgres.ts` does) so that `postgresState({ client })` — which takes
24 // any `@effect/sql` client — works without the optional peer installed at
25 // all. Only `postgresState({ url })`, which builds a pool, needs it.
26 const importPgClient = () =>
27 import("@effect/sql-pg/PgClient").catch((cause) => {
28 throw new Error(
29 "Failed to load '@effect/sql-pg'. Install the optional peer dependency '@effect/sql-pg' to use postgresState with a `url`.",
30 { cause },
31 );
32 });
33
34 export interface PostgresStateOptions<E = never, R = never> {
35 /**
36 * An existing `@effect/sql` client. The caller owns its lifecycle — the
37 * store only issues queries against it. Exactly one of `client` and `url`
38 * must be provided.
39 *
40 * The client must be **pool-backed** and able to hand out at least two
41 * concurrent connections: the store keeps one connection reserved for the
42 * advisory lock and verifies that lock from another one. A
43 * single-connection client (`PgClient.makeClient`) is refused at the first
44 * lease check, and a pool capped at `maxConnections: 1` blocks forever
45 * waiting for a free connection.
46 */
47 client?: SqlClient.SqlClient;
48 /**
49 * Postgres connection URL, as a `Redacted` value or an Effect yielding one
50 * — `Config.Redacted("STATE_DATABASE_URL")` is itself an Effect, so it can
51 * be passed directly. The store creates its own `@effect/sql-pg` pool from
52 * the URL and closes that pool when the state layer is released.
53 */
54 url?: Redacted.Redacted<string> | Effect.Effect<Redacted.Redacted<string>, E, R>;
55 /**
56 * Prefix for the advisory-lock key. The full key for a stack/stage is
57 * `{lockKeyPrefix}:{stack}/{stage}`.
58 *
59 * @default "alchemy"
60 */
61 lockKeyPrefix?: string;
62 /**
63 * State-store id reported in telemetry (`alchemy.state_store.id`).
64 *
65 * @default "postgres"
66 */
67 id?: string;
68 /**
69 * How long (in milliseconds) a passing lease check is trusted before the
70 * next state operation re-verifies the advisory lock. A lease lost inside
71 * the window is detected within this many milliseconds rather than
72 * instantly; in exchange, a burst of state operations does one lock
73 * round-trip instead of one per operation.
74 *
75 * @default 5000
76 */
77 leaseCheckTtlMs?: number;
78 }
79
80 const DEFAULT_LEASE_CHECK_TTL_MS = 5_000;
81
82 /**
83 * Amortizes a lease check over a short TTL: a passing check is trusted for
84 * `ttlMs`, so a burst of operations inside the window does one round-trip,
85 * not one per operation. A failing check is never cached — it propagates
86 * immediately and leaves the last-good timestamp untouched, so the very
87 * next operation re-checks.
88 */
89 const amortizeCheck = (
90 checkLive: Effect.Effect<void, StateStoreError>,
91 ttlMs: number,
92 ): Effect.Effect<void, StateStoreError> => {
93 let lastOkAt: number | undefined;
94 return Effect.suspend(() => {
95 if (lastOkAt !== undefined && Date.now() - lastOkAt < ttlMs) {
96 return Effect.void;
97 }
98 return checkLive.pipe(
99 Effect.tap(() =>
100 Effect.sync(() => {
101 lastOkAt = Date.now();
102 }),
103 ),
104 );
105 });
106 };
107
108 interface Lease {
109 readonly checkLive: Effect.Effect<void, StateStoreError>;
110 }
111
112 /**
113 * State store backed by any Postgres database.
114 *
115 * Stack state lives in two tables — `alchemy_resource_state` and
116 * `alchemy_stack_output` — created on first use with
117 * `create table if not exists`.
118 *
119 * Concurrent deploys are serialized with a session-scoped Postgres advisory
120 * lock per `(stack, stage)`: the lock is taken on a reserved connection
121 * (`SqlClient.reserve`) when the first operation for the pair runs, and
122 * contention fails immediately instead of queueing. Every subsequent
123 * operation first re-verifies — from a *different* connection, by inspecting
124 * `pg_locks` — that the backend which took the lock still holds it, so a
125 * dropped lock connection fails loudly instead of letting operations run
126 * unlocked. That check reports the backend it ran on as well, so a
127 * single-connection client, which would have the lock holder vouch for
128 * itself, is refused instead of silently trusted. If the process crashes,
129 * Postgres releases the session lock when the connection drops; no recovery
130 * bookkeeping is needed.
131 *
132 * ### Using the Postgres State Store
133 * **Example:** Connection URL from configuration
134 * ```typescript
135 * import * as Alchemy from "alchemy";
136 * import { postgresState } from "@alchemy.run/sql/PostgresState";
137 * import * as Config from "effect/Config";
138 *
139 * const Stack = Alchemy.Stack(
140 * "my-stack",
141 * {
142 * providers: myProviders(),
143 * state: postgresState({ url: Config.Redacted("STATE_DATABASE_URL") }),
144 * },
145 * Effect.gen(function* () {
146 * // ...
147 * }),
148 * );
149 * ```
150 *
151 * **Example:** Caller-owned pool
152 * ```typescript
153 * import * as PgClient from "@effect/sql-pg/PgClient";
154 * import * as Config from "effect/Config";
155 *
156 * // A pool, not `PgClient.makeClient`: the store needs a second connection
157 * // to verify the advisory lock held on the reserved one.
158 * const sql = yield* PgClient.make({
159 * url: yield* Config.Redacted("STATE_DATABASE_URL"),
160 * });
161 * const state = postgresState({
162 * client: sql,
163 * lockKeyPrefix: yield* Config.String("STATE_LOCK_PREFIX"),
164 * });
165 * ```
166 */
167 export const postgresState = <E = never, R = never>(options: PostgresStateOptions<E, R>) =>
168 Layer.effect(
169 State,
170 Effect.gen(function* () {
171 const scope = yield* Effect.scope;
172 // The layer carries the `url` Effect's requirements; the service it
173 // builds must not, so they are provided here, once.
174 const context = yield* Effect.context<R>();
175
176 const make = makePostgresState(options, scope).pipe(
177 recordStateStoreInit,
178 Effect.provideContext(context),
179 );
180
181 return yield* Effect.cached(make);
182 }),
183 );
184
185 /**
186 * Construct a Postgres-backed {@link StateService}.
187 *
188 * Construction itself never touches the database — pool creation (when a
189 * `url` was given), schema migration, and advisory-lock acquisition are all
190 * deferred to the first state operation. Finalizers for the advisory locks
191 * and any store-owned pool are registered on `scope`.
192 */
193 export const makePostgresState = <E = never, R = never>(
194 options: PostgresStateOptions<E, R>,
195 scope: Scope.Scope,
196 ) =>
197 Effect.gen(function* () {
198 const prefix = options.lockKeyPrefix ?? "alchemy";
199 const ttlMs = options.leaseCheckTtlMs ?? DEFAULT_LEASE_CHECK_TTL_MS;
200 // Captured once, so a `url` Effect that needs services (a custom
201 // ConfigProvider, say) can still be resolved later — from inside the
202 // service methods, whose own requirements are fixed at `never`.
203 const context = yield* Effect.context<R>();
204
205 const toError = (cause: unknown): StateStoreError =>
206 cause instanceof StateStoreError
207 ? cause
208 : new StateStoreError({
209 message:
210 cause instanceof Error
211 ? cause.message
212 : `Postgres state store error: ${String(cause)}`,
213 cause: cause instanceof Error ? cause : undefined,
214 });
215
216 const stateError = <A, E2, R2>(
217 effect: Effect.Effect<A, E2, R2>,
218 ): Effect.Effect<A, StateStoreError, R2> => Effect.mapError(effect, toError);
219
220 /**
221 * Idempotent schema migration. Concurrent `create table if not exists`
222 * statements can still collide inside Postgres on the shared catalog
223 * rows (duplicate pg_type/pg_class key errors), so the migration runs
224 * in a transaction — one connection, pinned by `withTransaction` — that
225 * first takes a transaction-scoped advisory lock on a fixed migration
226 * key. The lock releases automatically at commit or rollback.
227 */
228 const migrate = (sql: SqlClient.SqlClient) =>
229 sql
230 .withTransaction(
231 Effect.gen(function* () {
232 yield* sql`select pg_advisory_xact_lock(hashtextextended(${`${prefix}:schema`}, 0))`;
233 yield* sql`
234 create table if not exists alchemy_resource_state (
235 stack text not null,
236 stage text not null,
237 fqn text not null,
238 value jsonb not null,
239 updated_at timestamptz not null default now(),
240 primary key (stack, stage, fqn)
241 )
242 `;
243 yield* sql`
244 create table if not exists alchemy_stack_output (
245 stack text not null,
246 stage text not null,
247 value jsonb not null,
248 updated_at timestamptz not null default now(),
249 primary key (stack, stage)
250 )
251 `;
252 }),
253 )
254 .pipe(stateError);
255
256 /**
257 * Builds a store-owned `@effect/sql-pg` pool. Its `end` finalizer is
258 * registered on `scope`, so the pool closes with the state layer.
259 */
260 const openPool = (
261 url: NonNullable<PostgresStateOptions<E, R>["url"]>,
262 ): Effect.Effect<SqlClient.SqlClient, StateStoreError> =>
263 Effect.gen(function* () {
264 const PgClient = yield* Effect.tryPromise({
265 try: importPgClient,
266 catch: toError,
267 });
268 const resolved = Effect.isEffect(url)
269 ? yield* Effect.provideContext(url, context).pipe(stateError)
270 : url;
271 const built = yield* Layer.build(PgClient.layer(resolveConnectionOptions(resolved))).pipe(
272 Scope.provide(scope),
273 stateError,
274 );
275 return Context.get(built, PgClient.PgClient);
276 });
277
278 // Nothing touches the database at layer construction time. The client
279 // is resolved (or created from the URL) and the schema migrated inside
280 // this cached Effect, which runs once on the first state operation.
281 const ready = yield* Effect.cached(
282 Effect.gen(function* () {
283 const { client, url } = options;
284 const resolved: SqlClient.SqlClient =
285 client !== undefined && url === undefined
286 ? client
287 : url !== undefined && client === undefined
288 ? yield* openPool(url)
289 : yield* new StateStoreError({
290 message: "postgresState requires exactly one of `client` or `url`",
291 });
292 // The store reads columns by the exact names written below, so a
293 // client configured with name transforms must not rewrite them.
294 const sql = resolved.withoutTransforms();
295 yield* migrate(sql);
296 return sql;
297 }),
298 );
299
300 const run = <A>(
301 f: (sql: SqlClient.SqlClient) => Effect.Effect<A, SqlError.SqlError>,
302 ): Effect.Effect<A, StateStoreError> => ready.pipe(Effect.flatMap((sql) => stateError(f(sql))));
303
304 const lockKey = (stack: string, stage: string) => `${prefix}:${stack}/${stage}`;
305
306 /**
307 * Acquires the session-scoped advisory lock for `key` on a connection
308 * reserved for the store's lifetime. Session (not transaction) scope,
309 * because a deploy spans many commits. Contention fails immediately
310 * rather than queueing.
311 */
312 const acquireLease = (key: string): Effect.Effect<Lease, StateStoreError> =>
313 Effect.uninterruptibleMask((restore) =>
314 Effect.gen(function* () {
315 const sql = yield* restore(ready);
316 // Forked from the store's scope, so the reserved connection is
317 // reclaimed with the store even if nothing below closes it. From
318 // here to the unlock finalizer nothing is interruptible: handing
319 // a connection back to the pool while it still holds a session
320 // lock would strand that lock until the process exits, and every
321 // later deploy of this stack/stage would fail on it.
322 const lockScope = yield* Scope.fork(scope);
323 const releaseReserved = Scope.close(lockScope, Exit.void);
324 const reserved = yield* restore(
325 sql.reserve.pipe(Scope.provide(lockScope), stateError),
326 ).pipe(Effect.onError(() => releaseReserved));
327
328 // Pins a statement to the reserved connection exactly the way
329 // `withTransaction` does, so spans, span attributes and row
330 // handling stay identical to every other statement.
331 const onReserved = <A>(
332 effect: Effect.Effect<A, SqlError.SqlError>,
333 ): Effect.Effect<A, SqlError.SqlError> =>
334 Effect.provideService(effect, sql.transactionService, [reserved, 0]);
335
336 const acquired = yield* onReserved(
337 sql`select pg_try_advisory_lock(hashtextextended(${key}, 0)) as acquired, pg_backend_pid() as pid`,
338 ).pipe(
339 stateError,
340 Effect.map((rows) => rows[0]),
341 Effect.onError(() => releaseReserved),
342 );
343 if (acquired?.acquired !== true) {
344 yield* releaseReserved;
345 return yield* new StateStoreError({
346 message: `another deploy holds the Postgres state lock '${key}'`,
347 });
348 }
349 const lockPid = Number(acquired.pid);
350
351 yield* Scope.addFinalizer(
352 scope,
353 onReserved(sql`select pg_advisory_unlock(hashtextextended(${key}, 0))`).pipe(
354 // If the connection already dropped, Postgres auto-released
355 // the session-scoped lock; there is nothing left to unlock.
356 Effect.ignore,
357 Effect.andThen(releaseReserved),
358 ),
359 );
360
361 // Deliberately verifies from a DIFFERENT connection, never the
362 // reserved one: once the reserved connection's backend has been
363 // killed server-side, querying it cannot answer reliably. Asking
364 // another connection whether the backend pid captured at acquire
365 // time still holds this advisory lock in `pg_locks` gives the same
366 // answer (a dead or reused backend cannot hold the lock) without
367 // touching the connection that might be dead. The check reports
368 // its own backend pid too, because a single-connection client
369 // routes it straight back to the lock holder, which cannot vouch
370 // for itself.
371 const checkLive = run(
372 (poolSql) => poolSql`
373 select
374 exists (
375 select 1 from pg_locks
376 where locktype = 'advisory'
377 and pid = ${lockPid}
378 and objsubid = 1
379 and granted
380 -- pg_locks splits the 64-bit advisory key into two
381 -- int4 halves; reassembling them with << 32 relies on
382 -- bigint wraparound matching hashtextextended's signed
383 -- 64-bit result, which is exact for all inputs.
384 and ((classid::bigint << 32) | (objid::bigint & 4294967295))
385 = hashtextextended(${key}, 0)
386 ) as live,
387 pg_backend_pid() as checker_pid
388 `,
389 ).pipe(
390 Effect.flatMap((rows) => {
391 const row = rows[0];
392 if (Number(row?.checker_pid) === lockPid) {
393 return Effect.fail(
394 new StateStoreError({
395 message: `the Postgres state lock '${key}' cannot be verified: the check ran on the same backend (pid ${lockPid}) that holds the lock, so this client is not pool-backed; pass postgresState a connection pool`,
396 }),
397 );
398 }
399 return row?.live === true
400 ? Effect.void
401 : Effect.fail(
402 new StateStoreError({
403 message: `the Postgres state lock '${key}' was lost mid-run; refusing to continue unlocked`,
404 }),
405 );
406 }),
407 );
408
409 return { checkLive: amortizeCheck(checkLive, ttlMs) };
410 }),
411 );
412
413 // One lease per (stack, stage), acquired lazily on the first operation
414 // that touches the pair and cached for the store's lifetime. The mutex
415 // makes acquisition single-flight so two concurrent first operations
416 // cannot race each other into a self-inflicted contention failure.
417 const leaseMutex = Semaphore.makeUnsafe(1);
418 const leases = new Map<string, Effect.Effect<Lease, StateStoreError>>();
419
420 const leaseFor = (stack: string, stage: string): Effect.Effect<Lease, StateStoreError> =>
421 Semaphore.withPermits(
422 leaseMutex,
423 1,
424 )(
425 Effect.gen(function* () {
426 const key = lockKey(stack, stage);
427 const existing = leases.get(key);
428 if (existing !== undefined) return existing;
429 const cached = yield* Effect.cached(acquireLease(key));
430 leases.set(key, cached);
431 return cached;
432 }),
433 ).pipe(Effect.flatMap((lease) => lease));
434
435 /**
436 * Every storage operation on a `(stack, stage)` first ensures this
437 * store holds the pair's advisory lock and that the lease is still
438 * live. Reads are guarded too, not just writes: a lost lease means a
439 * concurrent deploy may already be mutating these rows, so a read could
440 * return stale or conflicting data.
441 */
442 const guarded = <A>(
443 request: { stack: string; stage: string },
444 op: Effect.Effect<A, StateStoreError>,
445 ): Effect.Effect<A, StateStoreError> =>
446 leaseFor(request.stack, request.stage).pipe(
447 Effect.flatMap((lease) => lease.checkLive),
448 Effect.andThen(op),
449 );
450
451 // Operations without a stage cannot name a single lease, so they
452 // re-verify every lease this store currently holds instead.
453 const verifyHeldLeases: Effect.Effect<void, StateStoreError> = Effect.suspend(() =>
454 Effect.forEach(
455 Array.from(leases.values()),
456 (lease) => lease.pipe(Effect.flatMap((held) => held.checkLive)),
457 { discard: true },
458 ),
459 );
460
461 const jsonParam = (value: unknown) => JSON.stringify(encodeState(value));
462
463 const deleteStage = (stack: string, stage: string) =>
464 run(
465 (sql) =>
466 sql`delete from alchemy_resource_state where stack = ${stack} and stage = ${stage}`,
467 ).pipe(
468 Effect.andThen(
469 run(
470 (sql) =>
471 sql`delete from alchemy_stack_output where stack = ${stack} and stage = ${stage}`,
472 ),
473 ),
474 Effect.asVoid,
475 );
476
477 const service: StateService = {
478 id: options.id ?? "postgres",
479 getVersion: () => Effect.succeed(STATE_STORE_VERSION),
480 listStacks: () =>
481 verifyHeldLeases.pipe(
482 Effect.andThen(
483 run(
484 (sql) =>
485 sql`select stack from alchemy_resource_state union select stack from alchemy_stack_output order by stack`,
486 ),
487 ),
488 Effect.map((rows) => rows.map((row) => String(row.stack))),
489 ),
490 listStages: (stack) =>
491 verifyHeldLeases.pipe(
492 Effect.andThen(
493 run(
494 (sql) =>
495 sql`select stage from alchemy_resource_state where stack = ${stack} union select stage from alchemy_stack_output where stack = ${stack} order by stage`,
496 ),
497 ),
498 Effect.map((rows) => rows.map((row) => String(row.stage))),
499 ),
500 get: (request) =>
501 guarded(
502 request,
503 run(
504 (sql) =>
505 sql`select value from alchemy_resource_state where stack = ${request.stack} and stage = ${request.stage} and fqn = ${request.fqn}`,
506 ).pipe(
507 Effect.map((rows) => {
508 const row = rows[0];
509 // Every row was written by `set` through `encodeState`, so
510 // reviving it recovers a PersistedState by construction.
511 return row === undefined
512 ? undefined
513 : (reviveStateRecursive(row.value) as PersistedState);
514 }),
515 ),
516 ),
517 // Filters by status directly in SQL rather than listing FQNs and
518 // re-fetching each one — same semantics as LocalState, without the
519 // N+1 round-trips.
520 getReplacedResources: (request) =>
521 guarded(
522 request,
523 run(
524 (sql) =>
525 sql`select value from alchemy_resource_state where stack = ${request.stack} and stage = ${request.stage} and value ->> 'status' = 'replaced'`,
526 ).pipe(
527 Effect.map((rows) =>
528 rows.map((row) => reviveStateRecursive(row.value) as ReplacedResourceState),
529 ),
530 ),
531 ),
532 set: (request) =>
533 guarded(
534 request,
535 run(
536 (sql) => sql`
537 insert into alchemy_resource_state (stack, stage, fqn, value, updated_at)
538 values (${request.stack}, ${request.stage}, ${request.fqn}, ${jsonParam(request.value)}::jsonb, now())
539 on conflict (stack, stage, fqn) do update
540 set value = excluded.value, updated_at = excluded.updated_at
541 `,
542 ).pipe(Effect.map(() => request.value)),
543 ),
544 delete: (request) =>
545 guarded(
546 request,
547 run(
548 (sql) =>
549 sql`delete from alchemy_resource_state where stack = ${request.stack} and stage = ${request.stage} and fqn = ${request.fqn}`,
550 ).pipe(Effect.asVoid),
551 ),
552 // Deleting a whole stack first acquires the advisory lock for every
553 // stage it is about to remove, so a concurrent deploy of any stage
554 // fails the lock instead of racing the delete. The stack-wide sweep
555 // that follows runs while all of those stage locks are still held.
556 deleteStack: ({ stack, stage }) =>
557 stage === undefined
558 ? verifyHeldLeases.pipe(
559 Effect.andThen(service.listStages(stack)),
560 Effect.flatMap((stages) =>
561 Effect.forEach(
562 stages,
563 (found) => guarded({ stack, stage: found }, deleteStage(stack, found)),
564 { discard: true },
565 ),
566 ),
567 Effect.andThen(
568 run((sql) => sql`delete from alchemy_resource_state where stack = ${stack}`),
569 ),
570 Effect.andThen(
571 run((sql) => sql`delete from alchemy_stack_output where stack = ${stack}`),
572 ),
573 Effect.asVoid,
574 )
575 : guarded({ stack, stage }, deleteStage(stack, stage)),
576 list: (request) =>
577 guarded(
578 request,
579 run(
580 (sql) =>
581 sql`select fqn from alchemy_resource_state where stack = ${request.stack} and stage = ${request.stage} order by fqn`,
582 ).pipe(Effect.map((rows) => rows.map((row) => String(row.fqn)))),
583 ),
584 getOutput: (request) =>
585 guarded(
586 request,
587 run(
588 (sql) =>
589 sql`select value from alchemy_stack_output where stack = ${request.stack} and stage = ${request.stage}`,
590 ).pipe(
591 Effect.map((rows) => {
592 const row = rows[0];
593 return row === undefined ? undefined : reviveStateRecursive(row.value);
594 }),
595 ),
596 ),
597 setOutput: (request) =>
598 guarded(
599 request,
600 run(
601 (sql) => sql`
602 insert into alchemy_stack_output (stack, stage, value, updated_at)
603 values (${request.stack}, ${request.stage}, ${jsonParam(request.value)}::jsonb, now())
604 on conflict (stack, stage) do update
605 set value = excluded.value, updated_at = excluded.updated_at
606 `,
607 ).pipe(Effect.map(() => request.value)),
608 ),
609 };
610 return service;
611 });