import type { WorkerLoader as _WorkerLoader } from "@cloudflare/workers-types";
import { ALCHEMY_PHASE } from "alchemy/Phase";
import type { RuntimeContext } from "alchemy/RuntimeContext";
import { asEffect } from "alchemy/Util";
import { taggedFunction } from "alchemy/Util/effect";
import * as Context from "effect/Context";
import * as Effect from "effect/Effect";
import * as Layer from "effect/Layer";
import { fromCloudflareFetcher, type Fetcher } from "../Fetcher.ts";
import { makeRpcStub } from "./Rpc.ts";
import { Worker, WorkerEnvironment } from "./Worker.ts";
type WorkerLoaderTypeId = "Cloudflare.DynamicWorker";
const WorkerLoaderTypeId: WorkerLoaderTypeId = "Cloudflare.DynamicWorker";
export interface WorkerLoaderWorkerCode {
compatibilityDate: string;
compatibilityFlags?: string[];
allowExperimental?: boolean;
limits?: workerdResourceLimits;
mainModule: string;
modules: Record<string, WorkerLoaderModule | string>;
env?: any;
globalOutbound?: Fetcher | null;
tails?: Fetcher[];
streamingTails?: Fetcher[];
}
export type DynamicWorkerEntrypoint<Shape = unknown> = Fetcher & {
[K in keyof Shape]: Shape[K];
};
export interface WorkerStub extends Fetcher {
getEntrypoint<Shape = unknown>(name?: string): DynamicWorkerEntrypoint<Shape>;
}
export type WorkerLoader = {
Type: WorkerLoaderTypeId;
name: string;
get<Err = never, Req = never>(
name: string | null,
getCode: () => WorkerLoaderWorkerCode | Effect.Effect<WorkerLoaderWorkerCode, Err, Req>,
): Effect.Effect<WorkerStub, Err, Req>;
load(code: WorkerLoaderWorkerCode): Effect.Effect<WorkerStub, never, RuntimeContext>;
};
/**
* Effect returned by `WorkerLoader(name)`.
*
* It is a real `Effect` — `yield* WorkerLoader(name)` inside a Worker init
* attaches the binding and resolves the runtime handle — but it also carries
* the `~alchemy/Kind` marker statically, so when it is declared on a Worker's
* `env` the binding machinery recognises it as a `worker_loader` binding
* (`isWorkerLoader`) instead of running it. Every env-resolution site that
* branches on "is this a runnable Effect?" therefore checks `~alchemy/Kind`
* (via `isWorkerLoader` or `isYieldableEffectLike`) before `Effect.isEffect`.
*/
export interface WorkerLoaderEffect extends Effect.Effect<
WorkerLoader,
never,
WorkerEnvironment | Worker
> {
"~alchemy/Kind": WorkerLoaderTypeId;
"~alchemy/Name": string;
name: string;
}
export const isWorkerLoader = (value: unknown): value is WorkerLoader =>
typeof value === "object" &&
value !== null &&
"~alchemy/Kind" in value &&
(value as WorkerLoaderEffect)["~alchemy/Kind"] === WorkerLoaderTypeId;
export interface WorkerLoaderClass extends Context.Service<WorkerLoader, WorkerLoader> {
(name?: string): WorkerLoaderEffect;
layer(loader: WorkerLoader): Layer.Layer<WorkerLoader>;
layer(id: string): Layer.Layer<WorkerLoader>;
}
/**
* Load and run ephemeral Workers at runtime from inline JavaScript
* modules.
*
* `WorkerLoader` registers a `worker_loader` binding on the
* parent Worker at deploy time. At runtime you call `.load()` with
* inline module source code and get back a fully typed Worker
* instance you can `fetch` or call RPC methods on. Each loaded
* Worker runs in its own isolate with full sandboxing.
*
* This is useful for evaluating user-provided code, running
* untrusted plugins, or dynamically generating Workers from
* templates.
*
*
* ### Creating a Loader
* Yield `Cloudflare.WorkerLoader(name)` in your Worker's init
* phase to register the binding and get back a runtime handle. The
* string argument becomes the binding name on the deployed Worker.
*
* **Example:** Registering a loader (effect-native Worker)
* ```typescript
* import * as Cloudflare from "@alchemy.run/cloudflare";
* import * as Effect from "effect/Effect";
* import { HttpServerRequest } from "effect/http/HttpServerRequest";
* import * as HttpServerResponse from "effect/http/HttpServerResponse";
* import * as HttpClientRequest from "effect/http/HttpClientRequest";
*
* export default class EvalWorker extends Cloudflare.Worker<EvalWorker>()(
* "EvalWorker",
* { main: import.meta.url },
* Effect.gen(function* () {
* // Registers the `worker_loader` binding on this Worker
* const loader = yield* Cloudflare.WorkerLoader("LOADER");
*
* return {
* fetch: Effect.gen(function* () {
* const request = yield* HttpServerRequest;
* const code = yield* request.text;
*
* // Spin up an isolated, sandboxed Worker from inline source.
* const worker = yield* loader.load({
* compatibilityDate: "2026-08-31",
* mainModule: "worker.js",
* modules: {
* "worker.js": `export default {
* async fetch(req) {
* const result = (0, eval)(await req.text());
* return new Response(String(result));
* }
* }`,
* },
* globalOutbound: null, // block outbound network access
* });
*
* // Call the loaded Worker over Effect-native HTTP.
* const response = yield* worker.fetch(
* HttpClientRequest.post("https://worker/").pipe(
* HttpClientRequest.bodyText(code),
* ),
* );
* return HttpServerResponse.fromClientResponse(response);
* }),
* };
* }),
* ) {}
* ```
*
* **Example:** Declaring on env (async Worker)
* ```typescript
* export const Worker = Cloudflare.Worker("Worker", {
* main: "./src/worker.ts",
* env: { LOADER: Cloudflare.WorkerLoader() },
* });
*
* export type WorkerEnv = Cloudflare.InferEnv<typeof Worker>;
*
* // worker.ts
* export default {
* async fetch(req: Request, env: WorkerEnv) {
* const worker = env.LOADER.load({
* compatibilityDate: "2026-08-31",
* mainModule: "worker.js",
* modules: { "worker.js": "export default { fetch: () => new Response('ok') }" },
* });
* return worker.getEntrypoint().fetch(req);
* },
* };
* ```
*
* ### Loading a Worker
* Call `loader.load()` with a compatibility date, a main module
* name, and a map of module names to source code strings. The
* returned instance exposes `.fetch()` for HTTP and RPC methods
* for named entrypoints.
*
* **Example:** Loading and calling a dynamic Worker
* ```typescript
* const worker = loader.load({
* compatibilityDate: "2026-08-31",
* mainModule: "worker.js",
* modules: {
* "worker.js": `export default {
* async fetch(request) {
* return new Response("Hello from dynamic worker!");
* }
* }`,
* },
* });
*
* const response = yield* worker.fetch(
* HttpClientRequest.get("https://worker/"),
* );
* ```
*
* ### Caching a Worker
* Call `loader.get(id, getCode)` to address a dynamic Worker by
* name. If an isolate with that id is already warm it is reused;
* `getCode` runs only on a cold start. The returned stub is a
* `WorkerStub`: call `.fetch()` on it directly, or
* `.getEntrypoint()` for a named export.
*
* **Example:** Loading a cached dynamic Worker
* ```typescript
* const worker = yield* loader.get("eval", () => ({
* compatibilityDate: "2026-08-31",
* mainModule: "worker.js",
* modules: {
* "worker.js": `export default {
* async fetch() {
* return new Response("cached");
* }
* }`,
* },
* }));
*
* const response = yield* worker.fetch(
* HttpClientRequest.get("https://worker/"),
* );
* ```
*
* ### Sandboxing
* Set `globalOutbound` to `null` to block all outbound network
* access from the dynamic Worker, or pass an RPC stub to intercept
* and proxy outbound requests.
*
* **Example:** Blocking outbound access
* ```typescript
* const worker = loader.load({
* compatibilityDate: "2026-08-31",
* mainModule: "worker.js",
* modules: {
* "worker.js": `export default {
* async fetch(req) {
* // fetch() calls from here will fail
* return new Response("sandboxed");
* }
* }`,
* },
* globalOutbound: null,
* });
* ```
*
* ### Named Entrypoints
* If the dynamic Worker exports named entrypoints, use
* `.getEntrypoint(name)` to get a typed stub for calling its
* methods.
*
* **Example:** Calling a named entrypoint
* ```typescript
* const worker = loader.load({ ... });
* const api = worker.getEntrypoint<{ greet: (name: string) => Effect.Effect<string> }>("api");
* const greeting = yield* api.greet("world");
* ```
*
* @resource
* @product Workers
* @category Workers & Compute
*/
export const WorkerLoader: WorkerLoaderClass = Object.assign(
taggedFunction(Context.Service()("Cloudflare.WorkerLoader"), (name = "LOADER") =>
Object.assign(
Effect.gen(function* () {
yield* (yield* Worker).bind`${name}`({
bindings: [{ type: "worker_loader", name }],
});
const loader: _WorkerLoader = yield* Effect.all([WorkerEnvironment, ALCHEMY_PHASE]).pipe(
Effect.flatMap(([env, phase]) => {
if (env === undefined || phase === "plan") {
return Effect.succeed(undefined as any);
}
const loader = env[name];
if (!loader) {
return Effect.die(new Error(`WorkerLoader '${name}' not found in env`));
}
return Effect.succeed(loader);
}),
);
return {
Type: WorkerLoaderTypeId,
name,
load: (options) =>
Effect.sync(() => wrapWorkerStub(loader.load(unwrapWorkerLoader(options)))),
get: <Err = never, Req = never>(
name: string | null,
getCode: () => WorkerLoaderWorkerCode | Effect.Effect<WorkerLoaderWorkerCode, Err, Req>,
) =>
Effect.flatMap(Effect.context<Req>(), (context) =>
Effect.sync(() =>
// Native get() returns a WorkerStub, not a Fetcher. The
// stub's fetcher is getEntrypoint(); wrapping the stub
// itself as a Fetcher makes worker.fetch throw
// "fetcher.fetch is not a function" (#1382).
wrapWorkerStub(
loader.get(name, () =>
asEffect(getCode()).pipe(
Effect.provide(context),
Effect.map(unwrapWorkerLoader),
Effect.runPromise,
),
),
),
),
),
} satisfies WorkerLoader;
}),
{
"~alchemy/Name": name,
"~alchemy/Kind": WorkerLoaderTypeId,
name,
},
),
),
{
layer: (loader: WorkerLoader) =>
Layer.succeed(Context.Service()("Cloudflare.WorkerLoader"), loader),
},
) as any;
/**
* Convert the Effect-level worker code into the shape the native
* `env.LOADER.get()` API expects, unwrapping wrapped `Fetcher`s to their raw
* Cloudflare fetchers. `globalOutbound: null` (disable network access for the
* dynamic worker) must survive as `null` — `?.raw` alone would coerce it to
* `undefined`, which the runtime treats as "default outbound", silently
* re-enabling network access for workers meant to be sandboxed (#746).
*/
const unwrapWorkerLoader = (loader: WorkerLoaderWorkerCode) => ({
...loader,
globalOutbound: loader.globalOutbound === null ? null : loader.globalOutbound?.raw,
tails: loader.tails?.map((t) => t.raw),
streamingTails: loader.streamingTails?.map((t) => t.raw),
});
const wrapDynamicWorkerEntrypoint = <Shape>(raw: any): DynamicWorkerEntrypoint<Shape> =>
Object.assign(makeRpcStub<any>(raw), fromCloudflareFetcher(raw));
const wrapWorkerStub = (raw: any): WorkerStub => {
const defaultEntrypoint = fromCloudflareFetcher(raw.getEntrypoint());
return {
...defaultEntrypoint,
getEntrypoint: <Shape>(name?: string) =>
wrapDynamicWorkerEntrypoint<Shape>(name ? raw.getEntrypoint(name) : raw.getEntrypoint()),
};
};