@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 378 lines 12.9 KB
Raw
1 /**
2 * Connects Effect SQL to SQLite storage inside Cloudflare Durable Objects.
3 *
4 * Provides `SqliteClient` and the generic `SqlClient` service. Pass `db` for
5 * queries only, or `storage` for transactions and migrations. SQLite blobs are
6 * returned as `Uint8Array`; `updateValues` is unsupported.
7 *
8 * Transactions use `storage.transaction()` instead of transaction SQL, and
9 * hold the connection until storage completes. A failed or interrupted nested
10 * transaction rolls back only itself, unless the failure reaches the parent.
11 *
12 * Fibers that inherit the transaction context must finish their transaction
13 * work before the transaction exits; later use can bypass the connection
14 * semaphore.
15 *
16 * @stability unstable
17 * @since 4.0.0
18 */
19 import type { DurableObjectStorage, DurableObjectTransaction, SqlStorage } from "@cloudflare/workers-types"
20 import * as Cause from "effect/Cause"
21 import * as Config from "effect/Config"
22 import * as Context from "effect/Context"
23 import * as Effect from "effect/Effect"
24 import * as Exit from "effect/Exit"
25 import { identity } from "effect/Function"
26 import * as Layer from "effect/Layer"
27 import * as Reactivity from "effect/reactivity/Reactivity"
28 import * as Rec from "effect/Record"
29 import * as Scheduler from "effect/Scheduler"
30 import type * as Scope from "effect/Scope"
31 import * as Semaphore from "effect/Semaphore"
32 import * as Client from "effect/sql/SqlClient"
33 import type { Connection } from "effect/sql/SqlConnection"
34 import { classifySqliteError, SqlError, UnknownError } from "effect/sql/SqlError"
35 import * as Statement from "effect/sql/Statement"
36 import * as Stream from "effect/Stream"
37
38 const ATTR_DB_SYSTEM_NAME = "db.system.name"
39
40 const classifyError = (cause: unknown, message: string, operation: string) =>
41 classifySqliteError(cause, { message, operation })
42
43 /**
44 * Runtime type identifier used to mark Cloudflare Durable Object `SqliteClient` values.
45 *
46 * @stability unstable
47 * @category type IDs
48 * @since 4.0.0
49 */
50 export const TypeId: TypeId = "~@effect/sql-sqlite-do/SqliteClient"
51
52 /**
53 * Type-level identifier used to mark Cloudflare Durable Object `SqliteClient` values.
54 *
55 * @stability unstable
56 * @category type IDs
57 * @since 4.0.0
58 */
59 export type TypeId = "~@effect/sql-sqlite-do/SqliteClient"
60
61 /**
62 * Cloudflare Durable Object SQLite client service, extending `SqlClient` with its configuration. `updateValues` is not supported.
63 *
64 * @stability unstable
65 * @category services
66 * @since 4.0.0
67 */
68 export interface SqliteClient extends Client.SqlClient {
69 readonly [TypeId]: TypeId
70 readonly config: SqliteClientConfig
71
72 /** Not supported in sqlite */
73 readonly updateValues: never
74 }
75
76 /**
77 * Service tag for the Cloudflare Durable Object SQLite client service.
78 *
79 * **When to use**
80 *
81 * Use to access or provide a Durable Object SQLite client through the Effect
82 * context.
83 *
84 * @stability unstable
85 * @category services
86 * @since 4.0.0
87 */
88 export const SqliteClient = Context.Service<SqliteClient>("@effect/sql-sqlite-do/SqliteClient")
89
90 const SqliteTransaction = Context.Service<Client.TransactionConnection, Client.TransactionConnection.Service>(
91 "@effect/sql-sqlite-do/SqliteClient/SqliteTransaction"
92 )
93
94 /**
95 * Configuration for a Cloudflare Durable Object SQLite client, including either a `SqlStorage` handle or the full `DurableObjectStorage` for transaction support, span attributes, and query/result name transforms.
96 *
97 * @stability unstable
98 * @category models
99 * @since 4.0.0
100 */
101 export interface SqliteClientConfig {
102 readonly db?: SqlStorage | undefined
103 readonly storage?: DurableObjectStorage | undefined
104 readonly spanAttributes?: Record<string, unknown> | undefined
105
106 readonly transformResultNames?: ((str: string) => string) | undefined
107 readonly transformQueryNames?: ((str: string) => string) | undefined
108 }
109
110 const unsupportedTransaction = (message: string, operation: string) =>
111 new SqlError({
112 reason: new UnknownError({
113 cause: new Error(message),
114 message,
115 operation
116 })
117 })
118
119 const makeUnsupportedWithTransaction =
120 (message: string): Client.SqlClient["withTransaction"] =>
121 <R, E, A>(_effect: Effect.Effect<A, E, R>): Effect.Effect<A, E | SqlError, R> =>
122 Effect.fail(unsupportedTransaction(message, "transaction"))
123
124 interface StorageLevel {
125 readonly txn: DurableObjectTransaction
126 readonly resolve: () => void
127 readonly done: Promise<Exit.Exit<void, SqlError>>
128 }
129
130 const makeStorageBackedWithTransaction = (
131 storage: DurableObjectStorage,
132 connection: Connection,
133 acquirer: Effect.Effect<Connection, never, Scope.Scope>,
134 spanAttributes: ReadonlyArray<readonly [string, unknown]>
135 ): Client.SqlClient["withTransaction"] => {
136 // The open storage transaction at each depth. Transactions at the same depth
137 // never overlap.
138 const levels: Array<StorageLevel> = []
139
140 // Parks the storage callback so the body runs on the fiber.
141 const open = (id: number) =>
142 Effect.callback<void, SqlError>((resume) => {
143 const done: Promise<Exit.Exit<void, SqlError>> = storage.transaction((txn) =>
144 new Promise<void>((resolve) => {
145 resume(Effect.sync(() => {
146 levels[id] = { txn, resolve, done }
147 }))
148 })
149 ).then(
150 () => Exit.void,
151 (cause) => {
152 const exit = Exit.fail(new SqlError({ reason: classifyError(cause, "Failed transaction", "transaction") }))
153 // Only takes effect if storage rejects before the callback starts.
154 resume(exit)
155 return exit
156 }
157 )
158 })
159
160 const close = (id: number) =>
161 Effect.suspend(() => {
162 const level = levels[id]
163 levels.length = id
164 level.resolve()
165 return Effect.flatten(Effect.promise(() => level.done))
166 })
167
168 // Uses `txn.rollback()` because rejecting a nested callback can abort its parent.
169 const rollback = (id: number) => Effect.sync(() => levels[id].txn.rollback())
170
171 const withTransaction = Client.makeWithTransaction({
172 transactionService: SqliteTransaction,
173 spanAttributes,
174 acquireConnection: (restore) => restore(acquirer),
175 begin: () => open(0),
176 savepoint: (_, id) => open(id),
177 releaseSavepoint: (_, id) => close(id),
178 commit: () => close(0),
179 rollback: () => Effect.andThen(rollback(0), close(0)),
180 // `releaseSavepoint` runs next and closes the level.
181 rollbackSavepoint: (_, id) => rollback(id)
182 })
183
184 return <R, E, A>(effect: Effect.Effect<A, E, R>): Effect.Effect<A, E | SqlError, R> =>
185 Effect.withFiber((fiber) => {
186 const conn = Context.getOrUndefined(fiber.context, SqliteTransaction)
187 if (conn !== undefined && conn[0] !== connection) {
188 return Effect.fail(
189 unsupportedTransaction(
190 "Transactions cannot use a connection from a different SQLite client",
191 "transaction"
192 )
193 )
194 }
195 return withTransaction(effect)
196 }).pipe(
197 // The storage transaction closes the input gate, blocking dispatcher tasks until it completes.
198 Effect.provideService(Scheduler.PreventSchedulerYield, true)
199 )
200 }
201
202 /**
203 * Creates a scoped Cloudflare Durable Object SQLite client around Durable Object SQLite storage, serializing access and converting returned `ArrayBuffer` values to `Uint8Array`.
204 *
205 * @stability unstable
206 * @category constructors
207 * @since 4.0.0
208 */
209 export const make = (
210 options: SqliteClientConfig
211 ): Effect.Effect<SqliteClient, never, Scope.Scope | Reactivity.Reactivity> =>
212 Effect.gen(function*() {
213 const compiler = Statement.makeCompilerSqlite(options.transformQueryNames)
214 const transformRows = options.transformResultNames
215 ? Statement.defaultTransforms(options.transformResultNames).array
216 : undefined
217 const db = options.storage?.sql ?? options.db
218
219 if (db === undefined) {
220 return yield* Effect.die("SqliteClient.make requires either a Durable Object storage or sql storage")
221 }
222 const sqlStorage = db
223
224 const makeConnection = Effect.gen(function*() {
225 function* runIterator(
226 sql: string,
227 params: ReadonlyArray<unknown> = []
228 ) {
229 const cursor = sqlStorage.exec(sql, ...params)
230 const columns = cursor.columnNames
231 for (const result of cursor.raw()) {
232 const obj: any = {}
233 for (let i = 0; i < columns.length; i++) {
234 const value = result[i]
235 Rec.assignProperty(obj, columns[i], value instanceof ArrayBuffer ? new Uint8Array(value) : value)
236 }
237 yield obj
238 }
239 }
240
241 const runStatement = (
242 sql: string,
243 params: ReadonlyArray<unknown> = []
244 ): Effect.Effect<ReadonlyArray<any>, SqlError, never> =>
245 Effect.try({
246 try: () => Array.from(runIterator(sql, params)),
247 catch: (cause) => new SqlError({ reason: classifyError(cause, "Failed to execute statement", "execute") })
248 })
249
250 const runValues = (
251 sql: string,
252 params: ReadonlyArray<unknown> = []
253 ): Effect.Effect<ReadonlyArray<any>, SqlError, never> =>
254 Effect.try({
255 try: () =>
256 Array.from(sqlStorage.exec(sql, ...params).raw(), (row) => {
257 for (let i = 0; i < row.length; i++) {
258 const value = row[i]
259 if (value instanceof ArrayBuffer) {
260 row[i] = new Uint8Array(value) as any
261 }
262 }
263 return row
264 }),
265 catch: (cause) => new SqlError({ reason: classifyError(cause, "Failed to execute statement", "execute") })
266 })
267
268 return identity<Connection>({
269 execute(sql, params, transformRows) {
270 return transformRows
271 ? Effect.map(runStatement(sql, params), transformRows)
272 : runStatement(sql, params)
273 },
274 executeRaw(sql, params) {
275 return runStatement(sql, params)
276 },
277 executeValues(sql, params) {
278 return runValues(sql, params)
279 },
280 executeValuesUnprepared(sql, params) {
281 return runValues(sql, params)
282 },
283 executeUnprepared(sql, params, transformRows) {
284 return transformRows
285 ? Effect.map(runStatement(sql, params), transformRows)
286 : runStatement(sql, params)
287 },
288 executeStream(sql, params, transformRows) {
289 return Stream.suspend(() => {
290 const iterator = runIterator(sql, params)
291 return Stream.fromIteratorSucceed(iterator, 128)
292 }).pipe(
293 Stream.catchCauseFilter(Cause.findDefect, (defect) =>
294 Stream.fail(
295 new SqlError({
296 reason: classifyError(defect, "Failed to execute statement", "execute")
297 })
298 )),
299 transformRows
300 ? Stream.mapArray((chunk) => transformRows(chunk) as any)
301 : identity
302 )
303 }
304 })
305 })
306
307 const semaphore = yield* Semaphore.make(1)
308 const connection = yield* makeConnection
309
310 // Streams and reservations hold the permit until their scope closes.
311 const acquirer = Effect.as(
312 Effect.acquireRelease(semaphore.take(1), () => semaphore.release(1), { interruptible: true }),
313 connection
314 )
315
316 const spanAttributes: ReadonlyArray<readonly [string, unknown]> = [
317 ...(options.spanAttributes ? Object.entries(options.spanAttributes) : []),
318 [ATTR_DB_SYSTEM_NAME, "sqlite"]
319 ]
320
321 const client = (yield* Client.make({
322 driver: "sqlite-do",
323 acquirer,
324 borrower: (f) => semaphore.withPermit(f(connection)),
325 compiler,
326 transactionService: SqliteTransaction,
327 spanAttributes,
328 transformRows
329 })) as SqliteClient
330
331 return Object.assign(client, {
332 [TypeId]: TypeId as TypeId,
333 config: options,
334 withTransaction: options.storage
335 ? makeStorageBackedWithTransaction(options.storage, connection, acquirer, spanAttributes)
336 : makeUnsupportedWithTransaction(
337 "Transactions require Durable Object storage; pass ctx.storage as the storage option"
338 )
339 })
340 })
341
342 /**
343 * Creates a layer from a `Config`-wrapped Durable Object SQLite client configuration, providing both `SqliteClient` and `SqlClient`.
344 *
345 * @stability unstable
346 * @category layers
347 * @since 4.0.0
348 */
349 export const layerConfig = (
350 config: Config.Wrap<SqliteClientConfig>
351 ): Layer.Layer<SqliteClient | Client.SqlClient, Config.ConfigError> =>
352 Layer.effectContext(
353 Config.unwrap(config).pipe(
354 Effect.flatMap(make),
355 Effect.map((client) =>
356 Context.make(SqliteClient, client).pipe(
357 Context.add(Client.SqlClient, client)
358 )
359 )
360 )
361 ).pipe(Layer.provide(Reactivity.layer))
362
363 /**
364 * Creates a layer from a concrete Durable Object SQLite client configuration, providing both `SqliteClient` and `SqlClient`.
365 *
366 * @stability unstable
367 * @category layers
368 * @since 4.0.0
369 */
370 export const layer = (
371 config: SqliteClientConfig
372 ): Layer.Layer<SqliteClient | Client.SqlClient> =>
373 Layer.effectContext(
374 Effect.map(make(config), (client) =>
375 Context.make(SqliteClient, client).pipe(
376 Context.add(Client.SqlClient, client)
377 ))
378 ).pipe(Layer.provide(Reactivity.layer))