/** * The engine-invariant event-dispatch core shared by every * engine's bridge: run one event's handler against a shared build under a * fresh per-event `Scope`, and normalize an RPC dispatcher's return value * into the effect the bridge runs. * * The engine's entrypoint class (workerd's `WorkerEntrypoint`, a runner's * server loop) owns the event API; it hands this core the per-event * services and its `waitUntil` hook. * * @internal */ import type * as Context from "effect/Context"; import * as Effect from "effect/Effect"; import * as Exit from "effect/Exit"; import * as Layer from "effect/Layer"; import * as Scope from "effect/Scope"; import * as Stream from "effect/Stream"; import { buildEventTelemetry } from "../TelemetryRuntime.ts"; import { EventLifetime, makeEventLifetime } from "./EventLifetime.ts"; import type { Pin, WorkerBuild } from "./Worker.ts"; export interface ProcessEventOptions> { /** * Select the handler effect for this event from the build, together with * the services captured when the export was assembled. */ readonly makeEffect: ( built: Build, ) => readonly [Effect.Effect, Context.Context]; /** * Per-event services that shadow the captured services and the built * instance context — e.g. the real per-event execution context, which * must win over the *deferred* one the instance context carries. */ readonly services?: ((built: Build) => Layer.Layer) | undefined; /** * Keep the event alive until `promise` settles (`ctx.waitUntil`). Used * to pin the in-flight build and to close the request scope after the * response has been returned. */ readonly waitUntil: Pin; /** Turn the handler's exit into the value returned to the engine. */ readonly onExit: ( exit: Exit.Exit, lifetime: EventLifetime["Service"], ) => T | Promise; } /** * Run one event: resolve the shared build (pinned to this event), run the * selected handler with a fresh request `Scope` provided as `Scope.Scope` * (so `Effect.addFinalizer` in a handler attaches to the request scope) and * the event's telemetry exporters, then close the scope into `waitUntil` * after the response. Closing waits for the work the event was told about * through its {@link EventLifetime}: `waitUntil` work, and a streamed body * or RPC stream. */ export const processEvent = >( build: (pin: Pin) => Promise, { makeEffect, services, waitUntil, onExit }: ProcessEventOptions, ): Promise => { const scope = Scope.makeUnsafe(); // Work the event hands to `waitUntil` runs after it returns, in its // context: the request scope waits for it before closing. const event = makeEventLifetime(scope); return build(waitUntil) .then( (built) => { const [eff, captured] = makeEffect(built); return Effect.andThen(event.holdExporters, eff).pipe( // Per-event services take precedence over the captured services // and the built isolate context: the real per-event execution // context (init only ever sees the reference's deferred default), // and the fresh request `Scope` so `Effect.addFinalizer` in a // handler attaches to the request scope (closed into `waitUntil` // below). Effect.provide( Layer.mergeAll( services?.(built) ?? Layer.empty, Layer.succeed(Scope.Scope, scope), Layer.succeed(EventLifetime, event.lifetime), // The configured telemetry exporters. Constructed as part of // this per-event layer, but `buildEventTelemetry` attaches // their batching fibers and flush finalizers to the request // `scope` (not this build's transient scope), so buffered // telemetry flushes when the scope closes into `waitUntil` // below — never on the instance scope, which workerd never // finalizes. Layer.effectContext(buildEventTelemetry(built.context, scope, built.telemetry())), ).pipe( Layer.provideMerge(Layer.succeedContext(captured)), Layer.provideMerge(Layer.succeedContext(built.context)), ), ), Effect.runPromiseExit, ); }, // A failed instance build reaches callers as a defect exit so the RPC // path can envelope-encode it like any other handler defect. (error) => Exit.die(error), ) .then((exit) => { event.holdScope(); return onExit(exit, event.lifetime); }) .finally(() => waitUntil( // The HttpMiddleware tracer ends the request's root span in a // dispatcher task scheduled after the handler effect resolves. // Yield one macrotask before closing the scope so that span // reaches the telemetry exporter's buffer before the scope's // flush finalizer runs. new Promise((resolve) => setTimeout(resolve, 0)).then(() => Effect.runPromise(Scope.close(scope, Exit.void)), ), ), ); }; /** * Normalize an RPC dispatcher's return value into the effect the bridge * runs. Effects (including nested-RPC values built by `asEffectOrStream`, * which are Effects *branded* as Streams) run as effects — their resolved * value may itself be a `Stream`, which `handleRpcExit` then encodes. A * *genuine* `Stream` (not an Effect) or a plain value is lifted into the * success channel so `handleRpcExit` encodes it directly. */ export const toRpcEffect = (result: unknown): Effect.Effect => Effect.isEffect(result) ? (result as Effect.Effect) : Effect.succeed(result); /** * Dispatch an RPC method call against a shape: a missing method is a * defect (the caller named something the worker never exported). */ export const dispatchRpcMethod = ( shape: Record | undefined, method: string, args: readonly unknown[], ): Effect.Effect => { // Never `Object.prototype` members (`constructor`, `__proto__`, ...). const dispatcher = method in Object.prototype ? undefined : shape?.[method]; if (typeof dispatcher !== "function") { return Effect.die( new Error( `Method "${method}" not found on worker. ` + `Make sure it's returned from the worker's default export.`, ), ); } return withEventContext(toRpcEffect(dispatcher(...args))); }; /** * The RPC transport reads a Stream result after the call has returned, outside * the event's fiber. Run it with the call's context, so its spans reach the * event's exporters and the `waitUntil` work it hands off joins the event. */ export const withEventContext = ( effect: Effect.Effect, ): Effect.Effect => effect.pipe( Effect.flatMap((value) => Stream.isStream(value) ? Effect.map(Effect.context(), (context) => // oxlint-disable-next-line effecttsgo/unsafe-effect-type-assertion -- an RPC Stream result needs no more than the call's context Stream.provideContext(value as Stream.Stream, context), ) : Effect.succeed(value), ), );