/** * Cloudflare's input gate, for Durable Object engines whose storage is * asynchronous. * * On Cloudflare, a Durable Object's calls interleave whenever one waits on * something, but never around storage: while a storage operation is in * flight no other call proceeds, so a `get` followed by a `put`, with only * plain code between them, can't lose an update. An engine that runs calls * concurrently over async storage (Rivet) loses that guarantee. This gate * restores it. * * The gate is held by a call, not a fiber: every fiber a call forks shares * it. A call takes the gate at its first storage operation and keeps it * while it keeps doing storage. Once it waits on anything else (a `fetch`, * another Durable Object, a sleep), the gate passes to the next call * waiting for storage. Calls still overlap while they wait on the outside * world; they only line up around storage. * * The bridge runs each request, each alarm and the instance's construction * as a call. Work a call hands to `waitUntil` and fibers it forks stay part * of it after it returns, so a background loop started by the constructor * is gated as one long call. * * It's opt-in: provide the {@link InputGate} Layer (`Workers.InputGate`, * from `alchemy/Workers`) to a Durable Object * class's outer Effect, and the Durable Object bridge gives each of its * instances a gate. Storage goes through the gate where the engine wraps * its operations in {@link gateStorage}. Cloudflare has a gate of its own, * so it's for engines without one (Rivet). * * @module */ import * as Context from "effect/Context"; import * as Effect from "effect/Effect"; import * as Layer from "effect/Layer"; import * as Option from "effect/Option"; import * as Scheduler from "effect/Scheduler"; import { CurrentRuntimeContext } from "../RuntimeContext.ts"; export interface InputGateShape { /** * Run one call. The call's fibers share one place in the gate, and the * call never yields to the scheduler on its own, so a `get` and a `put` * separated by plain code stay together. */ readonly call: (effect: Effect.Effect) => Effect.Effect; /** * Run one storage operation. Waits while another call holds the gate, * then holds it until the call next waits on something that isn't * storage. */ readonly storage: (effect: Effect.Effect) => Effect.Effect; /** * Hold the gate for the whole of `effect`, whatever it waits on (a * transaction). A call made back into this instance from inside waits * until `effect` finishes, so don't call out from it. */ readonly exclusive: (effect: Effect.Effect) => Effect.Effect; } /** One Durable Object instance's input gate. */ export class InstanceInputGate extends Context.Service()( "alchemy/Workers/InstanceInputGate", ) {} /** The call a fiber belongs to; forked fibers inherit it. */ const CurrentCall = Context.Reference("alchemy/Workers/InputGate/CurrentCall", { defaultValue: () => undefined, }); interface Waiter { readonly call: number; readonly resume: (effect: Effect.Effect) => void; granted: boolean; } /** Build a gate for one instance. */ export const makeInputGate: Effect.Effect = Effect.sync(() => { let nextCall = 0; // The call that may touch storage now. let holder: number | undefined; // The holder's storage operations (and exclusive sections) in flight. let pending = 0; let exclusive = 0; let checking = false; const waiters: Waiter[] = []; // Hand the gate to the longest-waiting call, with every one of its fibers // that's waiting too. const release = () => { holder = undefined; const next = waiters[0]; if (next === undefined) return; holder = next.call; for (let i = 0; i < waiters.length;) { const waiter = waiters[i]!; if (waiter.call !== holder) { i++; continue; } waiters.splice(i, 1); // Counted now, so the release check can't pass the gate on before the // waiter's fiber resumes. waiter.granted = true; pending++; waiter.resume(Effect.void); } }; // After a storage operation finishes, its call either starts another one // in the same run of plain code, or suspends on something else. Check on // the next macrotask, after that run, which it was. const scheduleCheck = () => { if (checking) return; checking = true; setImmediate(() => { checking = false; if (holder !== undefined && pending === 0 && exclusive === 0) release(); }); }; const done = Effect.sync(() => { pending--; scheduleCheck(); }); // Take the gate for `call`, counting one operation in flight. const acquire = (call: number) => Effect.callback((resume) => { if (holder === undefined || holder === call) { holder = call; pending++; resume(Effect.void); return; } const waiter: Waiter = { call, resume, granted: false }; waiters.push(waiter); return Effect.sync(() => { // Interrupted while waiting: leave the queue, or give back the turn // it was granted. const index = waiters.indexOf(waiter); if (index >= 0) waiters.splice(index, 1); else if (waiter.granted) { pending--; scheduleCheck(); } }); }); // Storage outside any call (an engine that doesn't run construction // through `call`) counts as a call of its own per operation. const currentCall = Effect.gen(function* () { return (yield* CurrentCall) ?? nextCall++; }); return { call: (effect) => Effect.suspend(() => effect.pipe( Effect.provideService(CurrentCall, nextCall++), Effect.provideService(Scheduler.PreventSchedulerYield, true), ), ), // Both pass the call down, so storage nested inside (an exclusive // section's operations) belongs to the same call. storage: (effect) => Effect.flatMap(currentCall, (call) => Effect.flatMap(acquire(call), () => Effect.ensuring(Effect.provideService(effect, CurrentCall, call), done), ), ), exclusive: (effect) => Effect.flatMap(currentCall, (call) => Effect.flatMap(acquire(call), () => Effect.suspend(() => { exclusive++; return Effect.ensuring( Effect.provideService(effect, CurrentCall, call), Effect.sync(() => { exclusive--; }).pipe(Effect.andThen(done)), ); }), ), ), }; }); /** * Cloudflare's input gate, for a Durable Object on an engine without one. * * Without it, an instance's calls run fully in parallel, storage included: * make a change atomic with a transaction. Provide it to a class's outer * Effect and each instance gets its own gate, so storage behaves as on * Cloudflare: while one call does storage, no other call's storage runs, * and a `get` followed by a `put`, with only plain code between them, can't * lose an update. Calls still overlap while they wait on anything else. * * Each storage operation then waits its turn, so give it to code written * for Cloudflare's gate, and use transactions everywhere else. * * ### Running Cloudflare code unchanged * **Example:** A get-then-put counter on Rivet that loses no updates * ```typescript * import * as Workers from "alchemy/Workers"; * * export default class Counter extends Rivet.DurableObject()( * "Counter", * { main: import.meta.url }, * Effect.gen(function* () { * return Effect.gen(function* () { * const state = yield* Rivet.DurableObjectState; * return { * increment: () => * Effect.gen(function* () { * const count = ((yield* state.storage.get("count")) ?? 0) + 1; * yield* state.storage.put("count", count); * return count; * }), * }; * }); * }).pipe(Effect.provide(Layer.mergeAll(Default, Workers.InputGate))), * ) {} * ``` */ export const InputGate: Layer.Layer = Layer.effectDiscard( Effect.gen(function* () { const ctx = yield* CurrentRuntimeContext; if (ctx !== undefined) ctx.inputGate = true; }), ); /** Run one call through the instance's gate, when it has one. */ export const gateCall = (effect: Effect.Effect): Effect.Effect => Effect.flatMap(Effect.serviceOption(InstanceInputGate), (gate) => Option.isSome(gate) ? gate.value.call(effect) : effect, ); /** Run one storage operation through the instance's gate, when it has one. */ export const gateStorage = (effect: Effect.Effect): Effect.Effect => Effect.flatMap(Effect.serviceOption(InstanceInputGate), (gate) => Option.isSome(gate) ? gate.value.storage(effect) : effect, ); /** Hold the instance's gate for the whole of `effect`, when it has one. */ export const gateExclusive = (effect: Effect.Effect): Effect.Effect => Effect.flatMap(Effect.serviceOption(InstanceInputGate), (gate) => Option.isSome(gate) ? gate.value.exclusive(effect) : effect, );