import type * as cf from "@cloudflare/workers-types";
import * as NodeChildProcessSpawner from "@effect/platform-node/NodeChildProcessSpawner";
import * as NodeCrypto from "@effect/platform-node/NodeCrypto";
import * as NodeFileSystem from "@effect/platform-node/NodeFileSystem";
import * as NodePath from "@effect/platform-node/NodePath";
import * as NodeStdio from "@effect/platform-node/NodeStdio";
import * as NodeTerminal from "@effect/platform-node/NodeTerminal";
import { makeEntrypointLayer, reifyBoundConfigProvider } from "alchemy/Runtime";
import { RuntimeContext } from "alchemy/RuntimeContext";
import { Self } from "alchemy/Self";
import { StackContext } from "alchemy/StackContext";
import { Stage } from "alchemy/Stage";
import { buildEventTelemetry } from "alchemy/TelemetryRuntime";
import type { DurableObject, WorkerEntrypoint } from "cloudflare:workers";
import * as Cause from "effect/Cause";
import * as ConfigProvider from "effect/ConfigProvider";
import * as Context from "effect/Context";
import * as Effect from "effect/Effect";
import * as Exit from "effect/Exit";
import * as FetchHttpClient from "effect/http/FetchHttpClient";
import * as EffectHttp from "effect/http/HttpEffect";
import * as Layer from "effect/Layer";
import * as Logger from "effect/Logger";
import { MinimumLogLevel } from "effect/References";
import * as Scope from "effect/Scope";
import * as Stream from "effect/Stream";
import { CloudflareEnvironment } from "../CloudflareEnvironmentService.ts";
import cloudflare_workers from "./cloudflare_workers.ts";
import { isScopeEjected } from "./HttpServer.ts";
import {
ErrorTag,
type RpcErrorEnvelope,
type RpcStreamEnvelope,
encodeRpcError,
toRpcStream,
} from "./Rpc.ts";
import type { Worker } from "./Worker.ts";
import {
ExportedHandlerMethods,
WorkerEnvironment,
WorkerExecutionContext,
fromExecutionContext,
} from "./WorkerRuntime.ts";
import type { WorkerRuntimeContext } from "./WorkerRuntimeContext.ts";
/**
* The isolate-lifetime artifacts produced by a single layer build: the built
* service Context, the resolved export for this entrypoint, the user's
* RPC shape (a thunk — the shape is only populated once `serve` has run),
* and the telemetry Layer override registered during init (a thunk for the
* same reason).
*/
export interface WorkerBuild<Export = any> {
readonly context: Context.Context<any>;
readonly runtimeContext: WorkerRuntimeContext;
readonly export: Export;
readonly shape: () => Record<string, any>;
readonly telemetry: () => Layer.Layer<never, any, any> | undefined;
}
/**
* Makes the WorkerEntrypoint class and bridges to Effect fetch and RPC calls.
*/
export const makeWorkerBridge = (
Base: typeof WorkerEntrypoint | typeof DurableObject,
{ stack, entrypoint }: { stack: { name: string; stage: string }; entrypoint: any },
) => {
const { build } = getWorkerExport({ entrypoint, stack, exportName: "default" });
const processEvent = <T>(
makeEffect: (
build: WorkerBuild,
) => readonly [Effect.Effect<any, any, any>, Context.Context<never>],
ctx: cf.ExecutionContext,
env: Record<string, unknown> | undefined,
onExit: (exit: Exit.Exit<any, any>, scope: Scope.Closeable) => T | Promise<T>,
): Promise<T> => {
const scope = Scope.makeUnsafe();
return build((promise) => ctx.waitUntil(promise as Promise<any>))
.then(
(built) => {
const [eff, services] = makeEffect(built);
return eff.pipe(
// Per-event services take precedence over the captured services
// and the built isolate context: the real per-event
// WorkerExecutionContext (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 `ctx.waitUntil` below).
Effect.provide(
Layer.mergeAll(
Layer.succeed(WorkerExecutionContext, fromExecutionContext(ctx, env)),
Layer.succeed(Scope.Scope, scope),
Layer.succeed(RuntimeContext, built.runtimeContext),
// 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
// `ctx.waitUntil` below — never on workerd's ephemeral
// isolate scope.
Layer.effectContext(buildEventTelemetry(built.context, scope, built.telemetry())),
).pipe(
Layer.provideMerge(Layer.succeedContext(services)),
Layer.provideMerge(Layer.succeedContext(built.context)),
),
),
Effect.runPromiseExit,
);
},
// A failed isolate 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) => onExit(exit, scope))
.finally(() =>
isScopeEjected(scope)
? undefined
: ctx.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)),
),
),
);
};
class WorkerBridge extends Base {
constructor(
public readonly ctx: any,
public readonly env: any,
) {
super(ctx, env);
for (const methodName of ExportedHandlerMethods) {
(this as any)[methodName] = async (input: any) =>
processEvent(
(built) =>
built.export[methodName](input, this.env, this.ctx) as [
Effect.Effect<any>,
Context.Context<never>,
],
this.ctx,
this.env,
(exit) =>
exit._tag === "Success"
? Promise.resolve(exit.value)
: Promise.reject(Cause.squash(exit.cause)),
);
}
return new Proxy(this, {
get: (target, prop) => {
if (typeof prop !== "string") return (target as any)[prop];
if (prop in target) return (target as any)[prop];
return (...args: unknown[]) =>
processEvent(
(built) => {
const dispatcher = built.shape()?.[prop];
if (typeof dispatcher !== "function") {
return [
Effect.die(
new Error(
`Method "${prop}" not found on worker. ` +
`Make sure it's returned from the worker's default export.`,
),
),
Context.empty(),
] as const;
}
const result = dispatcher(...args);
// Effects (including nested-RPC values built by
// `asEffectOrStream`, which are Effects *branded* as Streams)
// must be run as effects — their resolved value may itself be
// a `Stream`, which `handleRpcExit` then encodes. Only a
// *genuine* `Stream` (not an Effect) is lifted into the
// success channel so `handleRpcExit` encodes it directly.
return [
Effect.isEffect(result)
? // oxlint-disable-next-line effecttsgo/unsafe-effect-type-assertion -- untyped RPC dispatcher result; failures are encoded by handleRpcExit
(result as Effect.Effect<any>)
: Stream.isStream(result)
? Effect.succeed(result)
: (result as Effect.Effect<any>),
Context.empty(),
] as const;
},
this.ctx,
this.env,
handleRpcExit,
);
},
});
}
}
// Stub prototype methods so Cloudflare's script-validate detects the
// standard handler set; per-instance overrides above are what actually
// run.
for (const method of ExportedHandlerMethods) {
Object.defineProperty(WorkerBridge.prototype, method, {
value: function () {
throw new Error(`Bridge method '${method}' was called before instance setup`);
},
writable: true,
configurable: true,
});
}
return WorkerBridge;
};
/**
* One isolate-lifetime layer build per entrypoint module. The generated
* entry passes the same `meta.entrypoint` object to `makeWorkerBridge`,
* `makeDurableObjectBridge`, and `makeWorkflowBridge`, so keying on it
* shares a single build (one run of the user's init closure) across the
* default worker and every Durable Object / Workflow class in the isolate.
*/
const sharedBuilds = new WeakMap<
object,
(pin: (promise: Promise<unknown>) => unknown) => Promise<Context.Context<any>>
>();
const getSharedBuild = (entrypoint: any, stack: { name: string; stage: string }) => {
let shared = sharedBuilds.get(entrypoint);
if (shared !== undefined) {
return shared;
}
const tag = Self as any as Context.Service<
never,
Worker & { RuntimeContext: WorkerRuntimeContext }
>;
const layer = makeEntrypointLayer(tag, entrypoint);
// `NodeServices.layer`, except `NodeTerminal` is only built when
// `process.stdin` is usable: it calls `process.stdin.once` while it builds,
// and workerd's `process` has no `stdin` on compatibility dates before
// Node.js process v2.
const terminal = Layer.unwrap(
Effect.sync(() =>
typeof globalThis.process?.stdin?.once === "function" ? NodeTerminal.layer : Layer.empty,
),
);
const platformServices = Layer.provideMerge(
NodeChildProcessSpawner.layer,
Layer.mergeAll(
NodeFileSystem.layer,
NodeCrypto.layer,
NodePath.layer,
NodeStdio.layer,
terminal,
),
);
const platform = Layer.mergeAll(
platformServices,
FetchHttpClient.layer,
// TODO(sam): wire this up to telemetry more directly
Logger.layer([Logger.consolePretty()]),
);
// Private scope for the isolate-lifetime layer build. Never closed —
// workerd has no isolate-teardown hook, so finalizers attached here can
// never run. It exists only because `Layer.buildWithMemoMap` requires a
// scope argument (`Layer.scoped`-style layers attach their finalizers to
// it). It is deliberately NOT provided as the ambient `Scope.Scope` of the
// init context: request-coupled resources are acquired inside handlers
// against the per-event scope that `processEvent` provides.
const instanceScope = Scope.makeUnsafe();
const memoMap = Layer.makeMemoMapUnsafe();
const globalContext = Layer.unwrap(
cloudflare_workers.pipe(
Effect.map(({ env }) =>
layer.pipe(
Layer.provideMerge(
Layer.succeed(StackContext, {
name: stack.name,
stage: stack.stage,
bindings: {},
resources: {},
actions: {},
}),
),
Layer.provideMerge(Layer.succeed(Stage, stack.stage)),
Layer.provideMerge(platform),
Layer.provideMerge(
Layer.succeed(
ConfigProvider.ConfigProvider,
ConfigProvider.orElse(
ConfigProvider.fromUnknown({ ALCHEMY_PHASE: "runtime" }),
// Auto-bound `Config` values arrive in `env` as
// `{"_tag":"Redacted","value":...}` markers; reify them so a
// `Config` re-read inside a request handler decodes the raw
// source value instead of the marker JSON.
reifyBoundConfigProvider(
ConfigProvider.fromUnknown(env),
env as Record<string, unknown>,
),
),
),
),
Layer.provideMerge(Layer.succeed(WorkerEnvironment, env)),
Layer.provideMerge(
Layer.succeed(
CloudflareEnvironment,
// TODO(sam): fix this with maybe a CloudflareAccountId Effect service
// @ts-expect-error - this is hacky, but we only need and have this property
Effect.succeed({ account: (env as any).ALCHEMY_CLOUDFLARE_ACCOUNT_ID }),
),
),
Layer.provideMerge(Layer.succeed(MinimumLogLevel, (env as any).DEBUG ? "Debug" : "Info")),
),
),
),
);
let built: Promise<Context.Context<any>> | undefined;
/**
* Build the isolate-lifetime layer stack exactly once; every subsequent
* event (and every export sharing this entrypoint) reuses the memoized
* Context.
*
* `pin` registers the in-flight build promise with the calling event
* (`ctx.waitUntil` / `state.waitUntil`). Every awaiting event must pin:
* workerd schedules a promise's continuations back into its origin request
* context and *drops* them if that context has ended
* (`handle_cross_request_promise_resolution`), so the origin event must be
* kept alive until the build settles or concurrent cold-start requests
* would hang.
*
* Only success is memoized — a transient init failure (e.g. a flaky
* `Config` read in user init) resets the memo and heals on the next event.
*/
shared = (pin) => {
const promise = (built ??= Effect.runPromise(
Layer.buildWithMemoMap(globalContext, memoMap, instanceScope).pipe(
// Strip the build's memo map from the exposed context so a Layer the
// user `Effect.provide`s *inside a handler* builds per event instead
// of sharing one instance (pinned to the first request's IoContext)
// across concurrent events.
Effect.map(Context.omit(Layer.CurrentMemoMap)),
),
).catch((error) => {
built = undefined;
throw error;
}));
pin(promise.catch(() => {}));
return promise;
};
sharedBuilds.set(entrypoint, shared);
return shared;
};
export const getWorkerExport = <Export = any>({
entrypoint,
stack,
exportName,
}: {
entrypoint: any;
stack: { name: string; stage: string };
exportName: string;
}) => {
const tag = Self as any as Context.Service<
never,
Worker & { RuntimeContext: WorkerRuntimeContext }
>;
const runtimeContext = tag.pipe(Effect.map((func) => func.RuntimeContext));
// oxlint-disable-next-line effecttsgo/unsafe-effect-type-assertion -- export resolution requirements are provided by the bridge at runtime
const exported = runtimeContext.pipe(
Effect.flatMap((context) => context.exports),
Effect.flatMap((exports) =>
Effect.isEffect(exports[exportName])
? exports[exportName]
: Effect.succeed(exports[exportName]),
),
) as Effect.Effect<Export>;
const sharedBuild = getSharedBuild(entrypoint, stack);
let built: Promise<WorkerBuild<Export>> | undefined;
/**
* Resolve this export against the shared isolate build; memoized so
* listener assembly and the captured services context resolve once per
* export. Same success-only memoization contract as the shared build.
*/
const build = (pin: (promise: Promise<unknown>) => unknown): Promise<WorkerBuild<Export>> => {
const promise = (built ??= sharedBuild(pin)
.then((context) =>
Effect.runPromise(
Effect.all([exported, runtimeContext]).pipe(
Effect.map(([exp, rc]): WorkerBuild<Export> => ({
context,
runtimeContext: rc,
export: exp,
shape: rc.shape,
telemetry: () => rc.telemetry,
})),
Effect.provideContext(context),
),
),
)
.catch((error) => {
built = undefined;
throw error;
}));
pin(promise.catch(() => {}));
return promise;
};
return { build };
};
export const makeRpcProxy = (
self: any,
userShape: Effect.Effect<any>,
processEvent: (eff: Effect.Effect<[Effect.Effect<any>, Context.Context<never>]>) => Promise<any>,
) =>
new Proxy(self, {
get: (target, prop) => {
if (typeof prop !== "string") return (target as any)[prop];
if (prop in target) return (target as any)[prop];
return (...args: unknown[]) =>
userShape
.pipe(
Effect.map((shape) => shape[prop]),
Effect.flatMap((dispatcher) => {
if (typeof dispatcher !== "function") {
return Effect.die(
new Error(
`Method "${prop}" not found on worker. ` +
`Make sure it's returned from the worker's default export.`,
),
);
}
const result = dispatcher(...args);
// Effects (including nested-RPC values built by
// `asEffectOrStream`, which are Effects *branded* as Streams)
// must be run as effects — their resolved value may itself be a
// `Stream`, which `handleRpcExit` then encodes. Only a *genuine*
// `Stream` (not an Effect) is lifted into the success channel so
// `handleRpcExit` encodes it directly.
return Effect.isEffect(result)
? // oxlint-disable-next-line effecttsgo/unsafe-effect-type-assertion -- untyped RPC dispatcher result; failures are encoded by handleRpcExit
(result as Effect.Effect<any>)
: Stream.isStream(result)
? Effect.succeed(result)
: (result as Effect.Effect<any>);
}),
processEvent,
)
.then((exit) => handleRpcExit(exit));
},
});
export const handleRpcExit = async (exit: Exit.Exit<any, any>, scope?: Scope.Closeable) => {
if (exit._tag === "Success") {
if (Stream.isStream(exit.value)) {
let stream = exit.value as Stream.Stream<any, any, any>;
if (scope !== undefined && !isScopeEjected(scope)) {
// The RPC transport drains the encoded ReadableStream *after* this
// function returns, so the request scope must outlive the handler:
// eject it from the bridge's close-on-return path and close it when
// the stream settles instead — mirroring `scopeTransferToStream` on
// the fetch path.
EffectHttp.scopeDisableClose(scope);
stream = stream.pipe(Stream.onExit((streamExit) => Scope.close(scope, streamExit)));
}
return await Effect.runPromise(toRpcStream(stream) as Effect.Effect<RpcStreamEnvelope>);
}
return exit.value;
}
const failReason = exit.cause.reasons.find(Cause.isFailReason);
if (failReason) {
return { _tag: ErrorTag, error: encodeRpcError(failReason.error) } satisfies RpcErrorEnvelope;
}
const dieReason = exit.cause.reasons.find(Cause.isDieReason);
throw dieReason?.defect ?? new Error("RPC method failed with an unexpected cause");
};