import type * as cf from "@cloudflare/workers-types"; import * as Context from "effect/Context"; import * as Data from "effect/Data"; import * as Effect from "effect/Effect"; import * as Exit from "effect/Exit"; import * as Fiber from "effect/Fiber"; import * as Pipeable from "effect/Pipeable"; import * as Scheduler from "effect/Scheduler"; import * as Stream from "effect/Stream"; import type { RuntimeContext } from "../../RuntimeContext.ts"; import { ActiveStorageTransactions, type ActiveStorageTransaction, } from "./DurableObjectTransactionContext.ts"; /** A native transaction failure or invalid use of a transaction's owner. */ export class DurableObjectStorageError extends Data.TaggedError("DurableObjectStorageError")<{ readonly operation: string; readonly message: string; readonly cause?: unknown; }> {} // Pre-existing sibling fibers do not inherit the transaction's context. const activeStorageTransactions = new WeakMap(); const checkTransactionOwner = (transaction: ActiveStorageTransaction, allowRolledBack = false) => Effect.withFiber((fiber) => transaction.active && transaction.owner === fiber && (allowRolledBack || !transaction.rolledBack) ? Effect.void : Effect.fail( new DurableObjectStorageError({ operation: "transaction", message: !transaction.active ? "The storage transaction callback has already finished" : transaction.owner !== fiber ? "A storage transaction cannot be used by another fiber" : "The storage transaction has been rolled back", }), ), ); /** * The transaction a fiber outside it must respect. A transaction whose * callback has finished stays registered until the native transaction * commits or rolls back; a fiber that never joined it waits for that, as * workerd's input gate makes events and timers wait. */ const settledTransaction = ( storage: cf.DurableObjectStorage, ): Effect.Effect => Effect.suspend(() => { const transaction = activeStorageTransactions.get(storage); return transaction === undefined || transaction.active ? Effect.succeed(transaction) : Effect.promise(() => transaction.settled).pipe(Effect.andThen(settledTransaction(storage))); }); /** * @internal Starts a native transaction. Inside another transaction, workerd * runs it as a savepoint: its failure or rollback leaves the outer one intact. */ function withStorageTransaction( storage: cf.DurableObjectStorage, effect: Effect.Effect, ): Effect.Effect; function withStorageTransaction( storage: cf.DurableObjectStorage, closure: (txn: DurableObjectTransaction) => Effect.Effect, ): Effect.Effect; function withStorageTransaction( storage: cf.DurableObjectStorage, body: Effect.Effect | ((txn: DurableObjectTransaction) => Effect.Effect), ): Effect.Effect { return Effect.gen(function* () { const transactions = yield* ActiveStorageTransactions; const parent = transactions.get(storage) ?? (yield* settledTransaction(storage)); if (parent !== undefined) { yield* checkTransactionOwner(parent); } const context = yield* Effect.context(); // Native input gates can block timers; fiber yields must use microtasks. const scheduler = new Scheduler.MixedScheduler("sync"); return yield* Effect.scoped( Effect.gen(function* () { let cancelled = false; let native: Promise | undefined; let failure: Exit.Failure | undefined; let currentTransaction: ActiveStorageTransaction | undefined; const settlement = Promise.withResolvers(); const release = () => { if (currentTransaction !== undefined) { currentTransaction.active = false; if (activeStorageTransactions.get(storage) === currentTransaction) { if (parent === undefined) activeStorageTransactions.delete(storage); else activeStorageTransactions.set(storage, parent); } } settlement.resolve(); }; const evaluate = (transaction: ActiveStorageTransaction) => Effect.suspend(() => typeof body === "function" ? body( makeDurableObjectTransaction( transaction.transaction, checkTransactionOwner(transaction).pipe(Effect.orDie), checkTransactionOwner(transaction, true).pipe( Effect.andThen(() => Effect.sync(() => { if (!transaction.rolledBack) { transaction.transaction.rollback(); transaction.rolledBack = true; } }), ), Effect.orDie, ), ), ) : body, ); yield* Effect.addFinalizer( Effect.fn(function* () { cancelled = true; // The synchronous scheduler can re-enter this finalizer before // runForkWith returns. The callback publishes its owner first. const owner = currentTransaction?.owner; if (owner !== undefined) { yield* Fiber.interrupt(owner); } const settlement = native; if (settlement !== undefined) { // The callback must finish before waiting for native rollback. yield* Effect.promise(() => settlement.then( () => undefined, () => undefined, ), ); } }), ); return yield* Effect.callback((resume) => { const reject = (cause: unknown) => { release(); resume( failure !== undefined && cause === failure ? Effect.failCause(failure.cause) : Effect.fail( new DurableObjectStorageError({ operation: "transaction", message: "The native storage transaction failed", cause, }), ), ); }; try { native = storage.transaction((txn) => { if (cancelled) { throw new DurableObjectStorageError({ operation: "transaction", message: "The storage transaction caller was interrupted", }); } const transaction: ActiveStorageTransaction = { transaction: txn, owner: undefined, active: true, rolledBack: false, settled: settlement.promise, }; currentTransaction = transaction; activeStorageTransactions.set(storage, transaction); const callbackContext = Context.add( context, ActiveStorageTransactions, new Map(transactions).set(storage, transaction), ); return new Promise((resolve, rejectCallback) => { const callbackFiber = Effect.runForkWith(callbackContext)( Effect.withFiber((fiber) => { transaction.owner = fiber; return Effect.scoped(evaluate(transaction)); }), { scheduler }, ); callbackFiber.addObserver((exit) => { transaction.active = false; if (Exit.isSuccess(exit)) { resolve(exit.value); } else { failure = exit; rejectCallback(exit); } }); }); }); native.then((value) => { release(); resume(Effect.succeed(value)); }, reject); } catch (cause) { reject(cause); } }); }), ); }); } // --------------------------------------------------------------------------- // SqlStorage — Effect-native wrapper around cf.SqlStorage // --------------------------------------------------------------------------- export type SqlStorageValue = cf.SqlStorageValue; export interface SqlCursor> extends Stream.Stream { next(): Effect.Effect< { done?: false; value: T } | { done: true; value?: never }, never, RuntimeContext >; toArray(): Effect.Effect; one(): Effect.Effect; raw(): Stream.Stream; readonly columnNames: string[]; readonly rowsRead: Effect.Effect; readonly rowsWritten: Effect.Effect; } export interface SqlStorage { /** * The raw underlying Cloudflare SqlStorage binding. * * Use this when you need direct access for libraries that already support * Cloudflare Durable Object SQLite storage. */ readonly raw: cf.SqlStorage; exec>( query: string, ...bindings: any[] ): Effect.Effect, never, RuntimeContext>; readonly databaseSize: number; } const defineCursorField = (self: object, key: string, value: A): A => { Object.defineProperty(self, key, { value, enumerable: true, configurable: true, writable: true }); return value; }; // Writes commonly discard the cursor. Keep its Stream, bound methods, and // statistic Effects lazy so those writes allocate only this wrapper. class SqlCursorImpl> extends Pipeable.Class implements SqlCursor { #cursor: cf.SqlStorageCursor; constructor(cursor: cf.SqlStorageCursor) { super(); this.#cursor = cursor; } get [Stream.TypeId](): Stream.VarianceStruct { return Stream.empty[Stream.TypeId]; } get channel(): Stream.Stream["channel"] { return defineCursorField(this, "channel", Stream.toChannel(Stream.fromIterable(this.#cursor))); } get next(): SqlCursor["next"] { const cursor = this.#cursor; return defineCursorField(this, "next", () => Effect.sync(() => cursor.next())); } get toArray(): SqlCursor["toArray"] { const cursor = this.#cursor; return defineCursorField(this, "toArray", () => Effect.sync(() => cursor.toArray())); } get one(): SqlCursor["one"] { const cursor = this.#cursor; return defineCursorField(this, "one", () => Effect.sync(() => cursor.one())); } get raw(): SqlCursor["raw"] { const cursor = this.#cursor; return defineCursorField(this, "raw", () => Stream.fromIterableEffect(Effect.sync(() => cursor.raw())), ); } get columnNames(): string[] { return defineCursorField(this, "columnNames", this.#cursor.columnNames); } get rowsRead(): SqlCursor["rowsRead"] { const cursor = this.#cursor; return defineCursorField( this, "rowsRead", Effect.sync(() => cursor.rowsRead), ); } get rowsWritten(): SqlCursor["rowsWritten"] { const cursor = this.#cursor; return defineCursorField( this, "rowsWritten", Effect.sync(() => cursor.rowsWritten), ); } } const fromSqlCursor = >( cursor: cf.SqlStorageCursor, ): SqlCursor => new SqlCursorImpl(cursor); const fromSqlStorage = (sql: cf.SqlStorage, checkOwner: Effect.Effect): SqlStorage => ({ raw: sql, exec: >( query: string, ...bindings: any[] ): Effect.Effect> => Effect.andThen( checkOwner, Effect.sync(() => fromSqlCursor(sql.exec(query, ...bindings))), ), get databaseSize() { return sql.databaseSize; }, }); // --------------------------------------------------------------------------- // DurableObjectTransaction // --------------------------------------------------------------------------- export interface DurableObjectTransaction { get( key: string, options?: cf.DurableObjectGetOptions, ): Effect.Effect; get( keys: string[], options?: cf.DurableObjectGetOptions, ): Effect.Effect, never, RuntimeContext>; list( options?: cf.DurableObjectListOptions, ): Effect.Effect, never, RuntimeContext>; put( key: string, value: T, options?: cf.DurableObjectPutOptions, ): Effect.Effect; put( entries: Record, options?: cf.DurableObjectPutOptions, ): Effect.Effect; delete( key: string, options?: cf.DurableObjectPutOptions, ): Effect.Effect; delete( keys: string[], options?: cf.DurableObjectPutOptions, ): Effect.Effect; rollback(): Effect.Effect; getAlarm( options?: cf.DurableObjectGetAlarmOptions, ): Effect.Effect; setAlarm( scheduledTime: number | Date, options?: cf.DurableObjectSetAlarmOptions, ): Effect.Effect; deleteAlarm( options?: cf.DurableObjectSetAlarmOptions, ): Effect.Effect; } // --------------------------------------------------------------------------- // DurableObjectStorage // --------------------------------------------------------------------------- export interface DurableObjectStorage { get( key: string, options?: cf.DurableObjectGetOptions, ): Effect.Effect; get( keys: string[], options?: cf.DurableObjectGetOptions, ): Effect.Effect, never, RuntimeContext>; list( options?: cf.DurableObjectListOptions, ): Effect.Effect, never, RuntimeContext>; put( key: string, value: T, options?: cf.DurableObjectPutOptions, ): Effect.Effect; put( entries: Record, options?: cf.DurableObjectPutOptions, ): Effect.Effect; delete( key: string, options?: cf.DurableObjectPutOptions, ): Effect.Effect; delete( keys: string[], options?: cf.DurableObjectPutOptions, ): Effect.Effect; deleteAll(options?: cf.DurableObjectPutOptions): Effect.Effect; /** * Run an Effect inside a native storage transaction with the caller's context. * On SQLite-backed storage, SQL, KV, and alarm writes to this storage commit * together. Typed failures, defects, and interruption roll back the transaction. * Interruption waits for the callback fiber and native rollback to finish. * A call inside another transaction starts a nested one: if it fails or rolls * back, only its own writes are undone, and the outer transaction continues. * Transaction handles cannot be used by another fiber or after the callback * finishes. */ transaction( effect: Effect.Effect, ): Effect.Effect; transaction( closure: (txn: DurableObjectTransaction) => Effect.Effect, ): Effect.Effect; getAlarm( options?: cf.DurableObjectGetAlarmOptions, ): Effect.Effect; setAlarm( scheduledTime: number | Date, options?: cf.DurableObjectSetAlarmOptions, ): Effect.Effect; deleteAlarm( options?: cf.DurableObjectSetAlarmOptions, ): Effect.Effect; sync(): Effect.Effect; sql: SqlStorage; kv: cf.SyncKvStorage; getCurrentBookmark(): Effect.Effect; getBookmarkForTime(timestamp: number | Date): Effect.Effect; onNextSessionRestoreBookmark(bookmark: string): Effect.Effect; } // --------------------------------------------------------------------------- // Constructors from raw Cloudflare types // --------------------------------------------------------------------------- export const fromDurableObjectTransaction = ( txn: cf.DurableObjectTransaction, ): DurableObjectTransaction => makeDurableObjectTransaction(txn, Effect.void); const makeDurableObjectTransaction = ( txn: cf.DurableObjectTransaction, checkOwner: Effect.Effect, rollback = Effect.andThen( checkOwner, Effect.sync(() => txn.rollback()), ), ): DurableObjectTransaction => { const use = (effect: Effect.Effect) => Effect.andThen(checkOwner, effect); return { get: ((keyOrKeys: string | string[], options?: cf.DurableObjectGetOptions) => use(Effect.promise(() => txn.get(keyOrKeys as any, options)))) as any, list: (options?: cf.DurableObjectListOptions) => use(Effect.promise(() => txn.list(options))), put: (( keyOrEntries: string | Record, valueOrOptions?: unknown, maybeOptions?: cf.DurableObjectPutOptions, ) => use( typeof keyOrEntries === "string" ? Effect.promise(() => txn.put(keyOrEntries, valueOrOptions, maybeOptions)) : Effect.promise(() => txn.put(keyOrEntries, valueOrOptions as cf.DurableObjectPutOptions | undefined), ), )) as any, delete: ((keyOrKeys: string | string[], options?: cf.DurableObjectPutOptions) => use(Effect.promise(() => txn.delete(keyOrKeys as any, options)))) as any, rollback: () => rollback, getAlarm: (options?: cf.DurableObjectGetAlarmOptions) => use(Effect.promise(() => txn.getAlarm(options))), setAlarm: (scheduledTime: number | Date, options?: cf.DurableObjectSetAlarmOptions) => use(Effect.promise(() => txn.setAlarm(scheduledTime, options))), deleteAlarm: (options?: cf.DurableObjectSetAlarmOptions) => use(Effect.promise(() => txn.deleteAlarm(options))), }; }; export const fromDurableObjectStorage = ( storage: cf.DurableObjectStorage, ): DurableObjectStorage => { const checkOwner = Effect.withFiber((fiber) => { const owned = fiber.getRef(ActiveStorageTransactions).get(storage); return (owned === undefined ? settledTransaction(storage) : Effect.succeed(owned)).pipe( Effect.flatMap((transaction) => transaction === undefined ? Effect.void : checkTransactionOwner(transaction).pipe(Effect.orDie), ), ); }); const use = (effect: Effect.Effect) => Effect.andThen(checkOwner, effect); return { get: ((keyOrKeys: string | string[], options?: cf.DurableObjectGetOptions) => use(Effect.promise(() => storage.get(keyOrKeys as any, options)))) as any, list: (options?: cf.DurableObjectListOptions) => use(Effect.promise(() => storage.list(options))), put: (( keyOrEntries: string | Record, valueOrOptions?: unknown, maybeOptions?: cf.DurableObjectPutOptions, ) => use( typeof keyOrEntries === "string" ? Effect.promise(() => storage.put(keyOrEntries, valueOrOptions, maybeOptions)) : Effect.promise(() => storage.put(keyOrEntries, valueOrOptions as cf.DurableObjectPutOptions | undefined), ), )) as any, delete: ((keyOrKeys: string | string[], options?: cf.DurableObjectPutOptions) => use(Effect.promise(() => storage.delete(keyOrKeys as any, options)))) as any, deleteAll: (options?: cf.DurableObjectPutOptions) => use(Effect.promise(() => storage.deleteAll(options))), transaction: ( body: Effect.Effect | ((txn: DurableObjectTransaction) => Effect.Effect), ) => withStorageTransaction(storage, (txn) => (typeof body === "function" ? body(txn) : body)), getAlarm: (options?: cf.DurableObjectGetAlarmOptions) => use(Effect.promise(() => storage.getAlarm(options))), setAlarm: (scheduledTime: number | Date, options?: cf.DurableObjectSetAlarmOptions) => use(Effect.promise(() => storage.setAlarm(scheduledTime, options))), deleteAlarm: (options?: cf.DurableObjectSetAlarmOptions) => use(Effect.promise(() => storage.deleteAlarm(options))), sync: () => use(Effect.promise(() => storage.sync())), sql: fromSqlStorage(storage.sql, checkOwner), kv: storage.kv, getCurrentBookmark: () => use(Effect.promise(() => storage.getCurrentBookmark())), getBookmarkForTime: (timestamp: number | Date) => use(Effect.promise(() => storage.getBookmarkForTime(timestamp))), onNextSessionRestoreBookmark: (bookmark: string) => use(Effect.promise(() => storage.onNextSessionRestoreBookmark(bookmark))), }; };