import type { Dependencies } from "alchemy/Dependencies";
import type { HttpEffect } from "alchemy/Http";
import type { InputProps } from "alchemy/Input";
import type { Named } from "alchemy/Named";
import type { PlatformIdentity } from "alchemy/Platform";
import type { Rpc as RpcShape } from "alchemy/Rpc";
import { effectClass, taggedFunction } from "alchemy/Util/effect";
import type { ConfigError } from "effect/Config";
import * as Context from "effect/Context";
import * as Effect from "effect/Effect";
import * as HttpClient from "effect/http/HttpClient";
import * as HttpClientResponse from "effect/http/HttpClientResponse";
import * as Layer from "effect/Layer";
import { type Rpc, RpcClient, type RpcGroup, RpcSerialization } from "effect/rpc";
import type * as RpcClientError from "effect/rpc/RpcClientError";
import type { Worker, WorkerProps } from "./Worker.ts";
import { Worker as WorkerCtor, WorkerEnvironment } from "./Worker.ts";
/**
* Props for {@link RpcWorker}. Same shape as {@link WorkerProps} with
* an additional `schema` field carrying the rpc group definition.
*/
export type RpcWorkerProps<Rpcs extends Rpc.Any> = {
/**
* The {@link RpcGroup.RpcGroup} served on this worker's `fetch`
* handler. The same value should be importable by any consumer of
* the worker (other workers or scripts using `RpcClient.make`).
*/
readonly schema: RpcGroup.RpcGroup<Rpcs>;
};
// Context tag carrying the surrounding `RpcWorker` value, so
// `yield* RpcWorker` inside the impl resolves to the worker itself
// (mirrors `yield* Worker` semantics inside `Cloudflare.Worker`).
// Documented as part of the main `RpcWorker` JSDoc below.
export class RpcWorkerScope extends Context.Service<RpcWorkerScope, Worker>()(
"Cloudflare.RpcWorker",
) {}
// Symbol used internally to stash the rpc `RpcGroup` schema on the
// `effectClass` that `RpcWorker(...)` returns, so `RpcWorker.bind`
// can recover it when handed the class later.
const SchemaSymbol = Symbol.for("alchemy.RpcWorker.schema");
// Phantom carrier — `RpcWorker.bind` uses `Rpcs` to type the returned
// rpc client. We don't tie it to a specific `Effect.R` since the
// requirements come from the underlying `Cloudflare.Worker` factory
// and shouldn't leak into the Stack-side service signature.
//
// `Deps` mirrors `Cloudflare.Worker<Self, Bindings, Deps>` — declares
// the DOs / Workers this script publishes for cross-script binding so
// `Counter.from(WorkerA)` type-checks from another script.
//
// `Id` is the const logical id (`Named<Id>`), matching `Cloudflare.Worker`.
export interface RpcWorkerYieldable<
Self,
Rpcs extends Rpc.Any,
Deps = never,
Id extends string = string,
>
extends
Effect.Effect<Worker<{}> & RpcShape<Self> & Dependencies<Deps>, never, any>,
Named<Id>,
PlatformIdentity<Id> {
/** @internal */
readonly [SchemaSymbol]: RpcGroup.RpcGroup<Rpcs>;
}
/**
* Type of the {@link RpcWorker} constructor. Mirrors the class-form
* signature of {@link Worker} so `class X extends RpcWorker<X>()(...)`
* works identically and the resulting worker is `Rpc<Self>`-typed for
* binding consumers.
*/
export interface RpcWorkerClass extends Effect.Effect<Worker, never, RpcWorkerScope> {
/**
* Class-based form: `class X extends RpcWorker<X>()(name, props, impl)`.
*
* The optional second type argument `Deps` mirrors
* `Cloudflare.Worker<Self, Bindings, Deps>` — it declares the DOs
* this Worker publishes for cross-script binding so consumers can
* write `Counter.from(WorkerA)` and have it type-check. `Rpcs` is
* always inferred from `props.schema`.
*
* Yielding the class in a Stack returns the {@link Worker} resource
* (so `worker.url`, `worker.workerName`, etc. work as usual). To get
* a typed `RpcClient` for *this* worker's rpc group from inside
* another worker's init, call {@link RpcWorker.bind}.
*/
<Self, Deps = never>(): {
/**
* Modular form (no impl). Mirrors `Cloudflare.Worker<Self>()(id, props)`.
* Use `WorkerClass.make(impl)` to provide the runtime as a
* `Layer.Layer<Self>` so consumers that don't host the worker can
* import the class without pulling its runtime into their bundle.
*/
<const Id extends string, Rpcs extends Rpc.Any>(
id: Id,
props: RpcWorkerProps<Rpcs>,
): RpcWorkerYieldable<Self, Rpcs, Deps, Id> & {
new (_: never): Named<Id>;
make<InnerR = never, InitReq = never>(
props: InputProps<WorkerProps>,
impl: Effect.Effect<Effect.Effect<HttpEffect<InnerR>, never, InnerR>, ConfigError, InitReq>,
): Layer.Layer<Self, never, Exclude<InitReq | InnerR, never>>;
};
/** Inline-impl form. */
<const Id extends string, Rpcs extends Rpc.Any, InnerR = never, InitReq = never>(
id: Id,
props: RpcWorkerProps<Rpcs> & InputProps<WorkerProps>,
impl: Effect.Effect<Effect.Effect<HttpEffect<InnerR>, never, InnerR>, ConfigError, InitReq>,
): RpcWorkerYieldable<Self, Rpcs, Deps, Id> & {
// Phantom — `class X extends RpcWorker<X>()(...)` carries `X`
// through the result type via `Rpc<Self>` on the binding side;
// the instance shape itself is empty besides `Named<Id>` (no
// methods exposed on `new X(...)` — everything goes through
// `fetch`).
new (_: never): Named<Id>;
};
};
/**
* Bind a typed Effect rpc client to a worker resource, using the
* worker's declared rpc {@link RpcGroup.RpcGroup} schema. Mirrors
* `Cloudflare.R2.ReadWriteBucket(MyBucket)` and friends.
*
* Yield once at **init** — the result is a normal `RpcClient` you
* can call directly from any per-request handler. Internally each
* method invocation builds a fresh underlying `RpcClient` (through
* a Proxy) because Cloudflare rejects I/O objects created on a
* previous request; this is hidden from the consumer.
*
* Pair with {@link RpcWorker} on the server side; both ends share
* the same schema so values round-trip through one `Schema` codec.
*
* @example
* ```ts
* // INIT: register the binding once and get the typed client
* const tasks = yield* Cloudflare.RpcWorker.bind(TaskWorker);
*
* // PER-REQUEST: call methods directly
* proxyGetTask: ({ id }) => tasks.getTask({ id }),
* ```
*/
readonly bind: <Self, Rpcs extends Rpc.Any>(
workerEff: RpcWorkerYieldable<Self, Rpcs>,
) => Effect.Effect<
RpcClient.RpcClient<Rpcs, RpcClientError.RpcClientError> & RpcShape<Self>,
never,
Worker
>;
}
/** @internal helper — exposed as `RpcWorker.bind` below. */
const bind = <Self, Rpcs extends Rpc.Any>(
workerEff: RpcWorkerYieldable<Self, Rpcs>,
): Effect.Effect<
RpcClient.RpcClient<Rpcs, RpcClientError.RpcClientError> & RpcShape<Self>,
never,
Worker
> =>
Effect.gen(function* () {
const schema = (workerEff as unknown as Record<symbol, unknown>)[SchemaSymbol] as
| RpcGroup.RpcGroup<Rpcs>
| undefined;
if (!schema) {
return yield* Effect.die(
new Error("RpcWorker.bind: passed value isn't an RpcWorker class — no schema attached."),
);
}
const worker = (yield* workerEff) as Worker;
// Register the service binding on the surrounding worker at INIT.
// Mirrors `Cloudflare.Workers.bindWorker` — yielding the class is *not*
// enough; we need an explicit `self.bind\`${worker}\`(...)` so
// workerd surfaces the stub on `env` at request time.
const self = yield* WorkerCtor;
yield* self.bind`${worker}`({
bindings: [{ type: "service", name: worker.LogicalId, service: worker.workerName }],
});
// Build a per-call factory that wraps the Cloudflare service-
// binding stub (Promise-based fetch) into an Effect `HttpClient`,
// then `RpcClient.make` over that transport. Each call gets its
// own `RpcClient` because Cloudflare rejects I/O objects (the
// stub.fetch body) that were created on a previous request.
const makeFreshClient = Effect.gen(function* () {
const env = yield* WorkerEnvironment;
const stub = (env as Record<string, { fetch: typeof fetch }>)[worker.LogicalId];
const httpClient = HttpClient.make((req) =>
Effect.promise((signal) =>
stub.fetch(
new Request(req.url, {
method: req.method,
headers: new Headers(req.headers as any),
body: (req.body as any)?.body ?? undefined,
signal,
}),
),
).pipe(Effect.map((res) => HttpClientResponse.fromWeb(req, res))),
);
const protocol = RpcClient.layerProtocolHttp({ url: "http://alchemy-rpc-worker/" }).pipe(
Layer.provide(RpcSerialization.layerNdjson),
Layer.provide(Layer.succeed(HttpClient.HttpClient, httpClient)),
);
return yield* RpcClient.make(schema).pipe(Effect.provide(protocol));
});
// Return a Proxy that LOOKS like an `RpcClient<Rpcs>` but defers
// the actual `RpcClient` construction to call time. Mirrors
// `makeRpcStub` from `./Rpc.ts`: each method invocation builds a
// fresh client, runs the call inside `Effect.scoped`, and tears
// the client's scope down with the call. From the consumer's
// perspective this is a normal `RpcClient`:
//
// const tasks = yield* Cloudflare.RpcWorker.bind(TaskWorker);
// yield* tasks.getTask({ id: "abc" });
return new Proxy(
{},
{
get: (_target, method) => {
if (typeof method !== "string") return undefined;
return (...args: unknown[]) =>
Effect.gen(function* () {
const client = yield* makeFreshClient;
const fn = (
client as unknown as Record<
string,
(...a: unknown[]) => Effect.Effect<unknown, unknown, unknown>
>
)[method];
return yield* fn(...args);
}).pipe(Effect.scoped);
},
},
) as RpcClient.RpcClient<Rpcs, RpcClientError.RpcClientError> & RpcShape<Self>;
});
/**
* `RpcWorker` is a thin sugar over {@link Worker} for the common case
* where a worker's entire `fetch` surface is a typed Effect `RpcGroup`.
* It takes the rpc `schema` directly in props alongside `main`, and
* accepts an init Effect that returns the already-piped
* `RpcServer.toHttpEffect(...)`-producing Effect (no `{ fetch }`
* wrapper) — the wrapper plugs it into the worker's `fetch` for you.
*
* Functionally identical to writing `Cloudflare.Worker(...)` with
* `return { fetch: RpcServer.toHttpEffect(schema).pipe(...) }`; use
* whichever style you prefer.
*
* The class form (`class X extends Cloudflare.RpcWorker<X>()(...)`)
* carries `Self` through the result type as `Rpc<Self>`, so other
* workers binding to this one see the rpc shape pinned to `Self`.
*
*
* ### Defining the rpc group
* **Example:** Pure schema description
* The rpc group and its schemas live outside any worker so both the
* server (`RpcWorker`) and any consumers (`RpcClient.make` /
* `RpcDurableObject`) import the same value.
* ```typescript
* import * as Schema from "effect/Schema";
* import { Rpc, RpcGroup } from "effect/rpc";
*
* export class TaskNotFound extends Schema.TaggedClass<TaskNotFound>()(
* "TaskNotFound",
* { id: Schema.String },
* ) {}
*
* const getTask = Rpc.make("getTask", {
* payload: { id: Schema.String },
* success: Schema.String,
* error: TaskNotFound,
* });
*
* export class TaskRpcs extends RpcGroup.make(getTask) {}
* ```
*
* ### Implementing the worker
* **Example:** Class form (recommended)
* Mirrors `Cloudflare.Worker<Self>()(...)` — `class X extends ...`
* works the same. The init Effect builds a handlers `Layer` from the
* group and returns the `RpcServer.toHttpEffect(schema)`-piped Effect
* directly.
* ```typescript
* import * as Cloudflare from "@alchemy.run/cloudflare";
* import * as Effect from "effect/Effect";
* import * as Layer from "effect/Layer";
* import { RpcSerialization, RpcServer } from "effect/rpc";
* import { TaskRpcs } from "./rpcs.ts";
*
* export default class Worker extends Cloudflare.RpcWorker<Worker>()(
* "Worker",
* { main: import.meta.url, schema: TaskRpcs },
* Effect.gen(function* () {
* const handlers = TaskRpcs.toLayer({
* getTask: ({ id }) => Effect.succeed(`task-${id}`),
* });
* return RpcServer.toHttpEffect(TaskRpcs).pipe(
* Effect.provide(Layer.mergeAll(handlers, RpcSerialization.layerJson)),
* );
* }),
* ) {}
* ```
*
* **Example:** NDJSON for streaming rpcs
* If any rpc in the group is a streaming rpc, the wire serialization
* must be `RpcSerialization.layerNdjson` — streaming rpcs need
* newline framing on the wire.
* ```typescript
* return RpcServer.toHttpEffect(ChatRpcs).pipe(
* Effect.provide(handlers),
* Effect.provide(RpcSerialization.layerNdjson),
* );
* ```
*
* ### Modular form: separate the class from its runtime
* **Example:** Class declaration with no impl + `static make(impl)`
* The inline class form above bundles the runtime into the class
* declaration. The two-arg form `(id, props)` declares the class
* as a pure tagged identifier; provide the runtime separately via
* `WorkerClass.make(impl)` so consumers can import the class for
* binding without pulling the host's runtime into their bundle.
* ```typescript
* export class TaskWorker extends Cloudflare.RpcWorker<TaskWorker>()(
* "TaskWorker",
* { main: import.meta.url, schema: TaskRpcs },
* ) {}
*
* // Only the host script imports this default export; consumers
* // import the class above for `RpcWorker.bind(TaskWorker)`.
* export default TaskWorker.make(
* Effect.gen(function* () {
* const handlers = TaskRpcs.toLayer({
* getTask: ({ id }) => Effect.succeed(`task-${id}`),
* });
* return RpcServer.toHttpEffect(TaskRpcs).pipe(
* Effect.provide(Layer.mergeAll(handlers, RpcSerialization.layerJson)),
* );
* }),
* );
* ```
*
* ### Hosting a Durable Object for cross-script binding
* **Example:** `RpcWorker<Self, Deps>()` declares published DOs
* The optional second type argument `Deps` mirrors
* `Cloudflare.Worker<Self, Bindings, Deps>` — it declares the DOs
* this Worker publishes for cross-script binding. With `Counter`
* named in `Deps`, any other Worker can write
* `Counter.from(TaskWorker)` and have it type-check.
* ```typescript
* import { Counter } from "./counter.ts";
*
* export class TaskWorker extends Cloudflare.RpcWorker<TaskWorker, Counter>()(
* "TaskWorker",
* { main: import.meta.url, schema: TaskRpcs },
* ) {}
* ```
* See {@link RpcDurableObject} for the consumer side
* (`Counter.from(TaskWorker)`).
*
* ### Binding it from another worker
* **Example:** `Cloudflare.RpcWorker.bind(WorkerClass)`
* Inside another worker's init, `RpcWorker.bind(WorkerClass)`
* registers the service binding on the surrounding worker and returns
* a typed `RpcClient` you can call directly from any per-request
* handler. Internally each method invocation builds a fresh underlying
* client (because Cloudflare rejects cross-request reuse of the
* stub I/O), but that's hidden behind a Proxy so the consumer sees a
* normal `RpcClient`.
* ```typescript
* import TaskWorker from "./task-worker.ts";
*
* export default class Caller extends Cloudflare.RpcWorker<Caller>()(
* "Caller",
* { main: import.meta.url, schema: CallerRpcs },
* Effect.gen(function* () {
* // INIT: register binding, get the typed client
* const tasks = yield* Cloudflare.RpcWorker.bind(TaskWorker);
*
* const handlers = CallerRpcs.toLayer({
* // PER-REQUEST: just call methods directly
* proxyGetTask: ({ id }) => tasks.getTask({ id }),
* });
* return RpcServer.toHttpEffect(CallerRpcs).pipe(
* Effect.provide(Layer.mergeAll(handlers, RpcSerialization.layerJson)),
* );
* }),
* ) {}
* ```
*
* ### Driving it from a test
* **Example:** `Test.make` + `RpcClient.make`
* The same `RpcGroup` drives a typed client. `Test.make` deploys the
* stack once for the file; each test yields the deploy handle for its
* URL and calls procedures directly.
* ```typescript
* import { expect } from "@alchemy.run/test";
* import * as Cloudflare from "@alchemy.run/cloudflare";
* import * as Test from "@alchemy.run/test/Alchemy";
* import * as Effect from "effect/Effect";
* import * as Layer from "effect/Layer";
* import * as Schedule from "effect/Schedule";
* import * as FetchHttpClient from "effect/http/FetchHttpClient";
* import * as RpcClient from "effect/rpc/RpcClient";
* import * as RpcSerialization from "effect/rpc/RpcSerialization";
* import Stack from "../alchemy.run.ts";
* import { TaskRpcs } from "../src/rpcs.ts";
*
* const { test, beforeAll, afterAll, deploy, destroy } = Test.make({
* providers: Cloudflare.providers(),
* });
* const stack = beforeAll(deploy(Stack));
* afterAll.skipIf(!!process.env.NO_DESTROY)(destroy(Stack));
*
* const layer = (url: string) =>
* RpcClient.layerProtocolHttp({ url }).pipe(
* Layer.provide(FetchHttpClient.layer),
* Layer.provide(
* Layer.succeed(RpcSerialization.RpcSerialization, RpcSerialization.json),
* ),
* );
*
* test(
* "getTask",
* Effect.gen(function* () {
* const { url } = yield* stack;
* yield* Effect.gen(function* () {
* const client = yield* RpcClient.make(TaskRpcs);
* const result = yield* client
* .getTask({ id: "abc" })
* .pipe(Effect.retry({ schedule: Schedule.exponential("500 millis"), times: 5 }));
* expect(result).toBe("task-abc");
* }).pipe(Effect.scoped, Effect.provide(layer(url)));
* }),
* );
* ```
*
* ### Yielding the surrounding worker from inside the impl
* **Example:** `yield* RpcWorker` inside the init effect
* Mirrors `yield* DurableObject` — yield the tag to access
* the surrounding worker.
* ```typescript
* Effect.gen(function* () {
* const self = yield* Cloudflare.RpcWorker;
* });
* ```
*
* @resource
* @product Workers
* @category Workers & Compute
*/
export const RpcWorker: RpcWorkerClass = (() => {
const fn = (...args: any[]) => {
// Class-form: zero args returns the inner builder. Inner-arg arity
// distinguishes modular (`(id, props)`, no impl — `static make(impl)`
// provides the runtime) from inline-impl (`(id, props, impl)`).
if (args.length === 0) {
return (...inner: any[]) => {
if (inner.length === 2) {
const [id, props] = inner as [string, RpcWorkerProps<any>];
return buildModular(id, props);
}
const [id, props, impl] = inner as [
string,
RpcWorkerProps<any>,
Effect.Effect<Effect.Effect<HttpEffect<any>>>,
];
return build(id, props, impl);
};
}
// Bare form: `(name, props, impl)`.
const [id, props, impl] = args as [
string,
RpcWorkerProps<any>,
Effect.Effect<Effect.Effect<HttpEffect<any>>>,
];
return build(id, props, impl);
};
const tagged = taggedFunction(RpcWorkerScope, fn as any) as any;
tagged.bind = bind;
return tagged;
})() as any;
const wrapImpl = (impl: Effect.Effect<Effect.Effect<HttpEffect<any>>>) =>
// The user's inner Effect resolves to `HttpEffect`; the underlying
// `Cloudflare.Worker` expects `{ fetch: HttpEffect }`. Box it.
Effect.map(impl, (fetch) => ({ fetch }) as unknown as { fetch: HttpEffect<any> });
// `effectClass` does not copy statics from the underlying Worker.
const stampLogicalId = (
klass: Record<symbol | string, unknown>,
source: { LogicalId?: unknown },
id: string,
) => {
klass.LogicalId = typeof source.LogicalId === "string" ? source.LogicalId : id;
return klass;
};
const buildModular = (id: string, props: RpcWorkerProps<any>) => {
const { schema } = props;
// Delegate to `Cloudflare.Worker<Self>()(id, props)` (modular form)
// so we inherit its `static make(impl)` plumbing for free. We just
// wrap the user's HttpEffect-returning impl into the `{ fetch }`
// shape `Cloudflare.Worker` expects, and stash the rpc schema on
// the class so `RpcWorker.bind(WorkerClass)` can recover it.
const Underlying: any = (WorkerCtor as any)()(id);
// `Underlying` is itself an Effect (the no-impl Worker class), so hand it
// straight to `effectClass` rather than reaching for a removed `.asEffect()`.
const klass = class extends effectClass(Underlying as Effect.Effect<Worker>) {
static make = (
props: InputProps<WorkerProps>,
impl: Effect.Effect<Effect.Effect<HttpEffect<any>>>,
): Layer.Layer<any, never, any> => Underlying.make(props, wrapImpl(impl));
} as unknown as Record<symbol | string, unknown>;
klass[SchemaSymbol] = schema;
return stampLogicalId(klass, Underlying, id);
};
const build = (
id: string,
props: RpcWorkerProps<any>,
impl: Effect.Effect<Effect.Effect<HttpEffect<any>>>,
) => {
const { schema, ...workerProps } = props;
// Wrap the user's HttpEffect-returning Effect into the `{ fetch }`
// shape `Cloudflare.Worker` expects.
const wrappedImpl = Effect.map(
impl,
(fetch) => ({ fetch }) as unknown as { fetch: HttpEffect<any> },
);
// Delegate registration / binding metadata to the underlying
// `Cloudflare.Worker`. The returned `effectClass`, when yielded,
// produces the standard `Worker` resource (so `worker.url`,
// `worker.workerName`, etc. all work as usual).
const underlying = (WorkerCtor as any)()(id, workerProps, wrappedImpl);
// Re-wrap as our own `effectClass` so we can stash the rpc schema
// on the class for `RpcWorker.bind` to recover later. (Re-using
// `effectClass` here means `class X extends RpcWorker<X>()(...)`
// still works.) `underlying` is already an Effect, so pass it directly.
const klass = effectClass(underlying as Effect.Effect<Worker>) as unknown as Record<
symbol | string,
unknown
>;
klass[SchemaSymbol] = schema;
return stampLogicalId(klass, underlying, id);
};