/** * The engine-invariant Durable Object instance core shared by every * engine's bridge: build one instance of a class export * against the shared build, run each call under a fresh per-call `Scope` * with the instance's state and telemetry provided, and dispatch RPC * methods against the built shape. * * The engine's class (workerd's `DurableObject` subclass) owns the * lifecycle API — it hands this core the state service and its * `waitUntil` hook and picks the RPC dispatch mode. * * @internal */ import * as Cause from "effect/Cause"; import * as Context from "effect/Context"; import * as Effect from "effect/Effect"; import * as Exit from "effect/Exit"; import * as HttpServerResponse from "effect/http/HttpServerResponse"; import * as Layer from "effect/Layer"; import * as Scope from "effect/Scope"; import * as Stream from "effect/Stream"; import type * as Tracer from "effect/Tracer"; import type { HttpEffect } from "../Http.ts"; import { rpcMethodOf, serveRpc } from "../Rpc.ts"; import { RuntimeContext } from "../RuntimeContext.ts"; import { buildEventTelemetry } from "../TelemetryRuntime.ts"; import type { DurableObjectExport, DurableObjectShape } from "./DurableObject.ts"; import { EventLifetime, makeEventLifetime } from "./EventLifetime.ts"; import { gateCall, InstanceInputGate, makeInputGate } from "./InputGate.ts"; import { handleRpcExit, type Pin, type WorkerBuild } from "./Worker.ts"; import { withEventContext } from "./WorkerBridge.ts"; /** * Lifecycle handlers dispatched by the bridge itself — never RPC methods. */ export const RESERVED_DURABLE_OBJECT_HANDLERS: ReadonlySet = new Set([ "fetch", "alarm", "webSocketOpen", "webSocketMessage", "webSocketClose", "webSocketError", ]); /** The built instance shape: the lifecycle handlers plus the RPC surface. */ export type DurableObjectInstanceShape = DurableObjectShape & Record; /** A built Durable Object instance plus the context its calls run under. */ export interface BuiltDurableObject { readonly instance: DurableObjectInstanceShape; readonly services: Context.Context; readonly context: Context.Context; /** The instance's decorated runtime context. */ readonly runtime: RuntimeContext["Service"]; readonly telemetry: () => Layer.Layer | undefined; } export interface DurableObjectInstanceOptions { /** The class export resolved against the shared build. */ readonly build: (pin: Pin) => Promise>; /** * Engine services available during construction and every call (the * engine's Durable Object state service). */ readonly services: Context.Context; /** * Decorate the instance's runtime context (e.g. its durable callback * factory), given the shared build's context. */ readonly runtimeContext?: ( runtime: RuntimeContext["Service"], context: Context.Context, ) => RuntimeContext["Service"]; /** Open callback registration for inner initialization; return its seal hook. */ readonly initialize?: () => () => void; /** Keep the instance alive until `promise` settles (`state.waitUntil`). */ readonly waitUntil: Pin; /** * How RPC methods reach the instance: * * - `"proxy"` — the engine resolves method names dynamically (workerd's * JSRPC dispatches through the bridge class's `Proxy`); `dispatch` * builds each method on demand. * - `"static"` — the RPC surface is materialized as real methods on * `target` once the instance builds (for engines whose RPC stalls on * Proxy-returning constructors), and {@link DurableObjectInstance.fetch} * serves the fetch-RPC protocol over the instance's own `fetch` so * streaming results ride HTTP chunked bodies end-to-end (for engines * whose native RPC cannot transfer `ReadableStream`s). */ readonly dispatch: "proxy" | "static"; /** `"static"` only: the object the RPC surface is materialized onto. */ readonly target?: object | undefined; /** * Runs the instance build. Engines whose object constructor has no I/O * context outside a concurrency gate (workerd: `state.blockConcurrencyWhile`) * pass that gate here so an init that performs I/O — a D1 `CREATE TABLE`, * a migration — runs INSIDE it. Default: run immediately. */ readonly gate?: (run: () => Promise) => Promise; } export interface DurableObjectInstance { /** * The instance, built once per in-memory activation: the export's * two-phase constructor runs with the state service and the captured * services provided. Rejects if the build fails (not memoized — see * `getWorkerExport`). */ readonly instance: Promise; /** * Run one call against the instance under a fresh `Scope` (provided as * `Scope.Scope`), the instance's state service, and the event * telemetry. `onExit` turns the exit into the returned value (default: * the success value, or the squashed cause thrown); the scope closes into * `waitUntil` after the result, once the work the call was told about * through its {@link EventLifetime} has settled. */ readonly execute: ( fn: (instance: DurableObjectInstanceShape) => Effect.Effect, onExit?: (exit: Exit.Exit, lifetime: EventLifetime["Service"]) => Promise, ) => Promise; /** * An RPC method: run the named member of the shape and encode its exit for * the wire, as a child of `parent` (the caller's span) when given. */ readonly dispatch: ( method: string, parent?: Tracer.AnySpan, ) => (...args: readonly unknown[]) => Promise; /** * The HTTP handler served for one request: in `"static"` mode a request * on the RPC path is served by `serveRpc` over the instance's RPC * surface; everything else is the instance's own `fetch` (404 when it has * none). */ readonly fetch: ( instance: DurableObjectInstanceShape, request: { readonly url: string }, ) => HttpEffect; } export const makeDurableObjectInstance = ({ build, services: engineServices, waitUntil, dispatch: mode, target, gate, runtimeContext, initialize, }: DurableObjectInstanceOptions): DurableObjectInstance => { const instance: Promise = (gate ?? ((run) => run()))(() => build(waitUntil).then(({ context, runtimeContext: runtime, export: exported, telemetry }) => { const { constructor } = exported; // A class given the `InputGate` Layer gets a gate per instance. const services = runtime?.inputGate ? Context.add(exported.services, InstanceInputGate, Effect.runSync(makeInputGate)) : exported.services; const instanceRuntimeContext = runtimeContext ? runtimeContext(runtime, context) : runtime; const doContext = Layer.succeedContext(engineServices).pipe( Layer.provideMerge(Layer.succeedContext(services)), Layer.provideMerge(Layer.succeedContext(context)), ); // Construction runs through the gate as a call of its own, so fibers it // forks (a background loop) belong to that call and their storage is // gated like any call's. return gateCall( constructor.pipe( Effect.flatMap((inner) => Effect.suspend(() => { const seal = initialize?.(); const instanceContext = Layer.succeed(RuntimeContext, instanceRuntimeContext).pipe( Layer.provideMerge(doContext), ); return inner.pipe( Effect.provide(instanceContext), Effect.ensuring(Effect.sync(() => seal?.())), ); }), ), ), ).pipe( Effect.provide(doContext), Effect.map((built): BuiltDurableObject => ({ instance: built as DurableObjectInstanceShape, services: Context.add(services, RuntimeContext, instanceRuntimeContext), context, runtime: instanceRuntimeContext, telemetry, })), Effect.runPromise, ); }), ); const execute = async ( fn: (instance: DurableObjectInstanceShape) => Effect.Effect, onExit?: (exit: Exit.Exit, lifetime: EventLifetime["Service"]) => Promise, ): Promise => { const scope = Scope.makeUnsafe(); // Work this call hands to `waitUntil` runs after it returns, in its // context: the call's scope waits for it before closing. const event = makeEventLifetime(scope); const { instance: shape, services, context, runtime, telemetry } = await instance; // A class given the `InputGate` Layer has a gate; the call runs // through it so storage can't interleave between calls. return Effect.andThen(event.holdExporters, gateCall(Effect.suspend(() => fn(shape)))) .pipe( Effect.provide( Layer.mergeAll( Layer.succeedContext(engineServices), Layer.succeed(EventLifetime, event.lifetime), Layer.succeed(Scope.Scope, scope), // The instance's decorated runtime context (its durable callback // factory) wins over any the engine services carry. Layer.succeed(RuntimeContext, runtime), // The configured telemetry exporters, attached to the *call* // scope by `buildEventTelemetry` so buffered telemetry flushes // when the scope closes into `waitUntil` below (the instance // scope never finalizes on workerd). Layer.effectContext(buildEventTelemetry(context, scope, telemetry())), ).pipe( Layer.provideMerge(Layer.succeedContext(services)), Layer.provideMerge(Layer.succeedContext(context)), ), ), Effect.runPromiseExit, ) .then((exit) => { event.holdScope(); return onExit ? onExit(exit, event.lifetime) : exit._tag === "Success" ? Promise.resolve(exit.value as T) : Promise.reject(Cause.squash(exit.cause)); }) .finally(() => waitUntil( // Match `processEvent`: yield one macrotask so the // HttpMiddleware tracer's late span-end reaches the telemetry // exporter before the scope's flush finalizer. new Promise((resolve) => setTimeout(resolve, 0)).then(() => Effect.runPromise(Scope.close(scope, Exit.void)), ), ), ); }; const dispatch = (method: string, parent?: Tracer.AnySpan) => (...args: readonly unknown[]) => execute( (shape) => Effect.suspend(() => { if (!Object.hasOwn(shape, method)) { return Effect.die(new Error(`Method "${method}" not found on Durable Object`)); } const member = shape[method]; const result = typeof member === "function" ? (member as (...args: readonly unknown[]) => unknown)(...args) : member; // Effects (including nested-RPC values built by // `asEffectOrStream`, which are Effects branded as Streams) run // as effects; a genuine Stream is lifted into the success // channel for `handleRpcExit` to encode. The RPC Shape // constraint rejects any other member at declaration, so // anything else got past it with a cast. if (Effect.isEffect(result)) return result; if (Stream.isStream(result)) return Effect.succeed(result); return Effect.die( new Error(`Durable Object RPC member "${method}" must return an Effect or a Stream`), ); }).pipe(withEventContext, (effect) => parent === undefined ? effect : Effect.withParentSpan(effect, parent), ), handleRpcExit, ); if (mode === "static" && target !== undefined) { // Materialize the built shape's RPC surface as real methods. The engine // gates event delivery on `instance` (`blockConcurrencyWhile`), so every // RPC call observes the assigned methods. A failed build is reported // through `instance` itself; this branch only observes success. void instance.then( (built) => { for (const name of Object.keys(built.instance)) { if (!RESERVED_DURABLE_OBJECT_HANDLERS.has(name) && !(name in target)) { Reflect.set(target, name, dispatch(name)); } } }, () => {}, ); } const notImplemented = Effect.succeed( HttpServerResponse.text("Not implemented", { status: 404 }), ); const fetch = ( shape: DurableObjectInstanceShape, request: { readonly url: string }, ): HttpEffect => { const own = shape.fetch ?? notImplemented; if (mode === "static" && rpcMethodOf(request) !== undefined) { const rpcShape: Record = {}; for (const name of Object.keys(shape)) { if (RESERVED_DURABLE_OBJECT_HANDLERS.has(name)) continue; const member = shape[name]; rpcShape[name] = typeof member === "function" ? member : () => member; } return serveRpc(rpcShape, own) as HttpEffect; } return own as HttpEffect; }; return { instance, execute, dispatch, fetch }; };