/** @effect-diagnostics anyUnknownInErrorContext:off */
import type { NodeServices } from "@effect/platform-node/NodeServices";
import * as ConfigError from "effect/Config";
import * as ConfigProvider from "effect/ConfigProvider";
import * as Context from "effect/Context";
import * as Effect from "effect/Effect";
import * as Effectable from "effect/Effectable";
import type { HttpClient } from "effect/http/HttpClient";
import type { HttpServerRequest } from "effect/http/HttpServerRequest";
import * as HttpServerResponse from "effect/http/HttpServerResponse";
import * as Layer from "effect/Layer";
import * as Option from "effect/Option";
import * as Redacted from "effect/Redacted";
import { Scope } from "effect/Scope";
import type * as Stream from "effect/Stream";
import type { Dependencies } from "./Dependencies.ts";
import { toFqn } from "./FQN.ts";
import type { HttpEffect } from "./Http.ts";
import type { InputProps } from "./Input.ts";
import type { Named, Tag } from "./Named.ts";
import { CurrentNamespace } from "./Namespace.ts";
import * as Output from "./Output.ts";
import { ALCHEMY_PHASE } from "./Phase.ts";
import type { Provider, ProviderCollectionLike } from "./Provider.ts";
import { Resource, type ResourceLike } from "./Resource.ts";
import type { Rpc } from "./Rpc.ts";
import { ServerHost, type ProcessContext } from "./Runtime/Process.ts";
import {
CurrentRuntimeContext,
RuntimeContext,
sanitizeKey,
type BaseRuntimeContext,
} from "./RuntimeContext.ts";
import { Self } from "./Self.ts";
import type { Stack, StackServices } from "./Stack.ts";
import { StackContext } from "./StackContext.ts";
import type { Stage } from "./Stage.ts";
import { effectClass } from "./Util/effect.ts";
export interface PlatformProps {
/**
* @internal type used to signal when this is an effect-native implementation
* @default false
*/
isExternal?: boolean;
}
/**
* Provide the platform class's layer (`cls.make(props, impl)`) with a
* lifetime that matches the phase.
*
* **At runtime** (`__ALCHEMY_RUNTIME__`, folded to `true` in every bundled
* artifact) the layer builds against the AMBIENT scope. `Effect.provide` is
* implemented with `scopedWith`, so its transient region scope would tear
* the layer down — firing init-level finalizers and releasing
* `Layer.scoped` services — the moment init completes. The runtime bridges
* evaluate the entrypoint under the instance-lifetime build scope (closed
* at instance shutdown where the platform offers one — Lambda's SIGTERM
* window — and never on workerd), so building against it keeps instance
* services alive for the instance.
*
* **At plan/deploy** it stays `Effect.provide`: the transient region evicts
* the layer's memo entry when each `yield*` of the class completes, so
* every deploy in a session re-evaluates the resource and re-registers its
* Output sources. Building on the session scope would keep the memo alive
* across deploys and a second `stack.deploy` would skip source
* registration (`MissingSourceError`).
*/
const provideClassLayer =
<ROut, E2, RIn>(layer: Layer.Layer<ROut, E2, RIn>) =>
<A, E, R>(
self: Effect.Effect<A, E, R>,
): Effect.Effect<A, E | E2, RIn | Scope | Exclude<R, ROut>> =>
(globalThis.__ALCHEMY_RUNTIME__
? Effect.flatMap(Effect.scope, (scope) =>
Effect.flatMap(Layer.buildWithScope(layer, scope), (context) =>
Effect.provideContext(self, context),
),
)
: Effect.provide(self, layer)) as Effect.Effect<A, E | E2, RIn | Scope | Exclude<R, ROut>>;
export type Main<InitServices = never> = void | {
fetch?:
| HttpEffect<InitServices | PlatformServices | RuntimeContext | Scope>
| Effect.Effect<
HttpEffect<InitServices | PlatformServices | RuntimeContext | Scope>,
never,
InitServices | PlatformServices
>;
};
export interface MainRpc<Req = never> {
[key: string]:
| Effect.Effect<any, any, PlatformServices | RuntimeContext | HttpServerRequest | Scope | Req>
| Stream.Stream<any, any, PlatformServices | RuntimeContext | HttpServerRequest | Scope | Req>
| ((
...args: any[]
) =>
| Effect.Effect<any, any, PlatformServices | RuntimeContext | Scope | Req>
| Stream.Stream<any, any, PlatformServices | RuntimeContext | Scope | Req>);
}
// Strip `void`/`undefined`/`never` from `Shape` before intersecting it with
// `BaseShape`. This matters when `Shape` fails its `extends MainShape`
// constraint (e.g. a `fetch` handler that leaks an error): TS clamps `Shape`
// to the constraint union `void | { fetch: ... }`, and a *distributive*
// conditional would split that into `BaseShape | ({ fetch } & BaseShape)` — a
// union. Feeding a union into the `new (_: never): ...` construct signature
// makes the base class a union type, which surfaces as the cryptic
// ts(2509) "Base constructor return type ... is not an object type" instead of
// the real assignability error on the `impl` argument. Excluding `void` here
// keeps the construct-sig return a single object type, so only the actionable
// error remains.
export type MakeShape<Shape, BaseShape> = [Exclude<Shape, void | undefined>] extends [never]
? Exclude<BaseShape, void | undefined>
: Exclude<Shape, void | undefined> & Exclude<BaseShape, void | undefined>;
// Services provided to the Resource's init/props effects. Deliberately does
// NOT include `Scope`: init runs once per instance under a build scope that
// closes at instance shutdown at best (Lambda's SIGTERM window; never on
// workerd), so init code that needs a scope must not typecheck. Handlers get
// a fresh per-event `Scope` from the bridge — note the explicit `| Scope` on
// the handler positions in `Main` / `MainRpc` above.
export type PlatformServices =
| NodeServices
| HttpClient
| Provider<any>
| ProviderCollectionLike
| Stack
| StackServices
| Stage
// Every platform provides its instance as the generic `Self` (see `make`),
// which host-agnostic bindings (e.g. Cloudflare `*Http`) name tokens after.
| Self;
/** A platform declaration's logical identity, readable without yielding it. */
export interface PlatformIdentity<Id extends string = string> {
readonly LogicalId: Id;
}
export interface Platform<
Resource extends ResourceLike<string, PlatformProps>,
Services,
MainShape,
RuntimeContext extends BaseRuntimeContext,
BaseShape = {},
InlineProps extends Resource["Props"] = Resource["Props"],
> extends Effect.Effect<Resource & RuntimeContext, never, Resource> {
Type: Resource["Type"];
Provider: Provider<Resource>;
<Self, Shape, Deps = never>(): {
<const Id extends string>(
id: Id,
): Effect.Effect<Resource & Rpc<Self> & Dependencies<Deps>, never, Resource["Providers"]> &
Named<Id> &
PlatformIdentity<Id> & {
make<PropsReq = never, InitReq = never>(
props:
| InputProps<InlineProps>
| Effect.Effect<InputProps<InlineProps>, ConfigError.ConfigError, PropsReq>,
impl: Effect.Effect<Shape, ConfigError.ConfigError, InitReq>,
): Layer.Layer<
Self,
never,
| Resource["Providers"]
| Exclude<PropsReq | InitReq, Services | PlatformServices | Resource>
>;
new (_: never): MakeShape<Shape, BaseShape> & Named<Id> & Tag<Resource["Type"]>;
of(shape: Shape & MainShape): MakeShape<Shape, BaseShape>;
};
};
<Self>(): {
<
const Id extends string,
Shape extends MainShape,
PropsReq = never,
InitReq extends Services | PlatformServices | Resource = never,
>(
id: Id,
props:
| InputProps<InlineProps>
| Effect.Effect<InputProps<InlineProps>, ConfigError.ConfigError, PropsReq>,
impl: Effect.Effect<Shape, ConfigError.ConfigError, InitReq>,
): Effect.Effect<
Resource & Rpc<Self>,
never,
| Resource["Providers"]
| Exclude<PropsReq, Services | PlatformServices | Resource>
| Exclude<InitReq, Services | PlatformServices | Resource>
> &
Named<Id> &
PlatformIdentity<Id> & {
new (_: never): MakeShape<Shape, BaseShape> & Named<Id> & Tag<Resource["Type"]>;
};
<const Id extends string>(
id: Id,
): Effect.Effect<Resource & Rpc<Self>, never, Resource["Providers"]> &
Named<Id> &
PlatformIdentity<Id> & {
make<PropsReq = never, InitReq extends Services | PlatformServices | Resource = never>(
props:
| InputProps<InlineProps>
| Effect.Effect<InputProps<InlineProps>, ConfigError.ConfigError, PropsReq>,
impl: Effect.Effect<MainShape, ConfigError.ConfigError, InitReq>,
): Layer.Layer<
Self,
never,
| Resource["Providers"]
| Exclude<PropsReq | InitReq, Services | PlatformServices | Resource>
>;
new (_: never): BaseShape & Named<Id> & Tag<Resource["Type"]>;
};
};
<
PropsReq = never,
InitReq extends Services | PlatformServices = never,
const Id extends string = string,
>(
id: Id,
props:
| InputProps<Resource["Props"]>
| Effect.Effect<InputProps<Resource["Props"]>, never, PropsReq>,
): Effect.Effect<
Resource,
never,
Resource["Providers"] | PropsReq | Exclude<InitReq, Services | PlatformServices>
> &
PlatformIdentity<Id>;
<
const Id extends string,
Shape extends MainShape,
PropsReq = never,
InitReq extends Services | PlatformServices = never,
>(
id: Id,
props: InputProps<InlineProps> | Effect.Effect<InputProps<InlineProps>, never, PropsReq>,
impl: Effect.Effect<Shape, ConfigError.ConfigError, InitReq>,
): Effect.Effect<
Resource & Rpc<Shape> & Named<Id>,
never,
Resource["Providers"] | PropsReq | Exclude<InitReq, Services | PlatformServices>
> &
Named<Id> &
PlatformIdentity<Id>;
}
export const Platform = <
R extends ResourceLike<
string,
| {
env?: Record<string, any>;
exports?: string[] | Record<string, any>;
}
| undefined
>,
>(
type: R["Type"],
hooks: {
createRuntimeContext: (id: string) => BaseRuntimeContext;
/**
* Legacy type names this platform's resource was previously registered
* under (see `ResourceOptions.aliases`) — threaded to the underlying
* `Resource` so state persisted under a pre-rename type keeps
* resolving.
*/
aliases?: string[];
// `onCreate` runs inside the resource-construction context, which already
// carries the Stack's providers — so the hook may yield child resources
// (e.g. an async Worker registering a `WorkflowResource` for a bound
// Workflow). Allow an ambient requirement (`any`) rather than forcing
// `never`; it is discharged by the surrounding provider context.
onCreate?: (resource: R, props: any) => Effect.Effect<void, never, any>;
/**
* Transform the user-supplied props before the underlying resource is
* declared. Runs in the resource-construction context (Stack, Namespace,
* and providers are available), so the hook may compose REAL child
* resources (the `StaticSite` pattern) and return derived props that
* reference their Outputs. Implementations MUST be a no-op at runtime
* (guard on `globalThis.__ALCHEMY_RUNTIME__`) — the hook is evaluated
* wherever the props effect is, including inside deployed bundles.
*/
transformProps?: (id: string, props: any) => Effect.Effect<any, any, any>;
},
methods?: { [key: string]: any },
): any => {
type Props = any;
type Impl = Effect.Effect<any>;
// Platform registrations must have resolved props by plan time: every
// legitimate construction (a `.make(props, impl)` Layer build, a tag
// declared with props, a plain call) produces them, so props still
// `undefined` at plan can only be a bare-tag forward reference whose
// `.make` Layer was never provided — `Plan.make` fails fast naming the
// class and its Layer (#1054).
const resource = Resource(type, {
aliases: hooks.aliases,
requiresImplementation: true,
});
const PlatformContext = RuntimeContext;
// Apply the optional `transformProps` hook to a (possibly Effect-valued)
// props argument. Returns the props untouched when no hook is installed so
// the plain-object fast paths below keep working, and leaves `undefined`
// props (a bare-tag forward reference) for `Plan.make` to report.
const applyTransformProps = (id: string, props: any): any =>
hooks.transformProps === undefined || props === undefined
? props
: Effect.flatMap(
// oxlint-disable-next-line effecttsgo/unsafe-effect-type-assertion -- props Effects are declarations resolved by the engine
Effect.isEffect(props) ? (props as Effect.Effect<any>) : Effect.succeed(props ?? {}),
(resolved) => hooks.transformProps!(id, resolved),
);
const constructor = (id?: string, props?: any, impl?: Impl, isTag = false): any => {
if (!id) {
// impl was not provided inline, this is a tagged instance
// e.g.
// export class Sandbox extends Cloudflare.Container<Sandbox>()(..) {}
//
// export const SandboxLive = Sandbox.make(..)
return (id: string, props?: any, impl?: Impl) => constructor(id, props, impl, true);
} else if (!impl) {
const cls = makeClass(id);
// A resource declared without an inline impl is "external": there is
// no Effect-native entry to inject (an ordinary bundled worker, or an
// assets-only worker with no script at all).
const externalProps = () => {
const transformed = applyTransformProps(id, props);
return Effect.isEffect(transformed)
? Effect.map(transformed, (p: any) => ({
...p,
isExternal: true,
}))
: {
...transformed,
isExternal: true,
};
};
const register = () =>
!isTag
? // this is a non-tagged resource yielded without providing an implementation
// e.g.
// yield* Cloudflare.Worker("id", { main: "./src/worker.ts" })
//
// This is where we bridge to non-effect, e.g. bundling an ordinary worker
// export default {
// fetch: (request: Request) => {
// return new Response("Hello, world!");
// }
// }
resource(id, externalProps())
: Effect.flatMap(
// this is a tagged resource
Effect.serviceOption(cls.Self),
Option.match({
// we are likely running at runtime, so we create.
// A tagged class WITH props and no impl is the class form of
// the external resource above (e.g.
// `class Site extends Worker<Site>()("Site", { assets }) {}`)
// — same isExternal marking; without props, this is a bare
// tag whose props/impl arrive later via `.make`.
onNone: () =>
// Without props this is a bare-tag FORWARD REFERENCE: its
// `.make(props, impl)` Layer may build before or after
// this yield (e.g. a worker tag bound in another worker's
// `env` — the #874 circular-binding pattern — resolves
// during that worker's async-binding pass, outside the
// Layer's own context). Register with `undefined` props;
// the Layer's build repairs them, and `Plan.make` fails
// fast on any platform registration whose props are still
// `undefined` after the whole program evaluated (see
// `requiresImplementation` above).
resource(
id,
props === undefined ? applyTransformProps(id, props) : externalProps(),
),
onSome: Effect.succeed,
}),
);
// Whether this `yield*` registers the resource. The stack holds one
// resource per FQN and every later `yield*` returns it. Outside a
// stack (at runtime) nothing registers, so the hook runs as before.
const isFirstRegistration = Effect.flatMap(
Effect.serviceOption(StackContext),
Option.match({
onNone: () => Effect.succeed(true),
onSome: (stack) =>
Effect.map(CurrentNamespace, (namespace) => !(toFqn(namespace, id) in stack.resources)),
}),
);
const evaluate = () =>
Effect.flatMap(isFirstRegistration, (firstRegistration) =>
register().pipe(
Effect.tap((resource) =>
// Run the hook only for the `yield*` that registered the
// resource. The hook yields the resource's `env`, so re-running
// it on every `yield*` lets two Workers whose `env` entries
// yield each other recurse forever (#2672). The resource is
// registered before the hook runs, so a cycle back to it stops.
hooks.onCreate && firstRegistration
? Effect.flatMap(
// `props` may itself be an Effect (e.g. when wrapped by
// `Cloudflare.Website.Vite` via `Effect.map`); resolve it
// before handing it to the hook so `onCreate` always sees
// the plain props object — the second call site (in
// `cls.make`) already does this.
Effect.isEffect(props) ? props : Effect.succeed(props ?? {}),
(resolved) => hooks.onCreate!(resource as R, resolved),
)
: Effect.void,
),
),
);
return Object.assign(
function (props: Props, impl: Impl) {
return cls.Self.pipe(provideClassLayer(cls.make(props, impl)));
},
// we splice in the Effect so this can be yielded to indicate a non-Effect native instance
// e.g. here, we yield it - in this case we don't want to provide an implementation
// const worker = yield* Cloudflare.Worker("id", {
// main: "./src/worker.ts"
// });
cls,
// Spread the Effect prototype LAST so it overrides the evaluate copied
// from `cls`: yielding this no-impl form bridges to the (possibly
// non-Effect-native) resource rather than resolving the Self tag.
Effectable.Prototype({
label: `${type}<${id}>`,
evaluate,
}),
);
} else {
// impl was provided inline, this is a non-tagged eager instance
// e.g.
// export default Cloudflare.Worker("id", { main: "./src/worker.ts" }, Effect.gen(function* () { .. })
const cls = makeClass(id);
return Object.assign(
cls.Self.pipe(provideClassLayer(cls.make(props, impl)), effectClass),
// Expose the logical id statically (mirrors `makeClass`) so a class
// reference identifies its resource without being yielded.
{ LogicalId: id },
);
}
};
const makeClass = (id: string) => {
class Platform {
/**
* Logical id of the resource this class declares. Statically readable
* — e.g. `DurableObjectProps.transferredFrom` accepts a Worker class
* and takes its identity from here without yielding it (yielding
* would add a dependency edge on the referenced resource).
*/
static readonly LogicalId = id;
static readonly Self = Self(`${type}<${id}>`);
static readonly Platform = Context.Service<Platform, Platform>(`Platform<${type}<${id}>>`);
static of = (shape: any) => shape;
static make = (props: Props, impl: Impl) => {
// build the Layer once for the root Self
const SelfLayer = Layer.effect(
Self,
Effect.flatMap(
Effect.all([
(() => {
const transformed = applyTransformProps(id, props);
return Effect.isEffect(transformed)
? // oxlint-disable-next-line effecttsgo/unsafe-effect-type-assertion -- props Effects are declarations resolved by the engine
(transformed as Effect.Effect<any>)
: Effect.succeed(transformed ?? {});
})(),
Effect.sync(() => hooks.createRuntimeContext(id)),
Effect.context<never>(),
]),
Effect.fn(function* ([props, runtimeContext, outerServices]) {
// The init effect (`impl`) is evaluated inside an
// `Effect.provide(...)` region below, whose implementation
// (`scopedWith`) would otherwise shadow the ambient `Scope`
// with a transient one that closes the moment init returns.
// Pin init's ambient scope to this layer's build scope
// instead: under the runtime bridges that scope belongs to
// the instance-lifetime build, so init-level finalizers run
// at instance shutdown or not at all — never per event
// (workerd never closes it; the Lambda entry closes it in the
// SIGTERM window). Request-coupled cleanup belongs in
// handlers, where the bridge provides a per-event scope.
const buildScope = yield* Effect.scope;
const instance = Object.assign(
yield* resource(id, props as any).pipe(
Effect.flatMap(
(resource) =>
hooks.onCreate?.(resource, props).pipe(Effect.map(() => resource)) ??
Effect.succeed(resource),
),
),
runtimeContext,
);
yield* impl.pipe(
Effect.flatMap((impl) => {
if (!impl) return Effect.void;
const shape = impl as Record<string, unknown>;
// Serve when there's a `fetch` handler OR any RPC shape
// methods. A pure-RPC impl (methods, no `fetch`) still needs
// the server to boot — hand `serveRpc` a default 404 fallback
// so `/__rpc__/*` is dispatched to the shape methods and
// everything else 404s.
// May be an `HttpEffect` or an Effect resolving to one (the
// `Main.fetch` shape); `serve` accepts both.
const fetch = shape.fetch as any;
const hasRpcMethods = Object.keys(shape).some((key) => key !== "fetch");
if (!fetch && !hasRpcMethods) return Effect.void;
// Hand the full impl to `serve` so the runtime can expose any
// non-handler methods on the impl shape (RPC methods)
// alongside the standard `fetch` handler.
return (
runtimeContext.serve?.(
fetch ??
Effect.succeed(HttpServerResponse.text("Not Found", { status: 404 })),
{ shape },
) ?? Effect.die("No serve handler")
);
}),
Effect.provide(
Layer.effect(
ConfigProvider.ConfigProvider,
Effect.gen(function* () {
// a Config Provider that we use to intercept config lookups and bind them to the RuntimeContext
const configProvider = yield* ConfigProvider.ConfigProvider;
const phase = yield* ALCHEMY_PHASE;
return ConfigProvider.make(
Effect.fnUntraced(function* (path) {
const ctx = yield* CurrentRuntimeContext;
// `set`/`get` store keys verbatim, so canonicalize the
// logical config path here (the caller's job) before
// handing it to the RuntimeContext.
const key = sanitizeKey(path.map((p) => p.toString()).join("_"));
const node = yield* configProvider.load(path);
if (phase === "plan" && node) {
// bind it to the RuntimeContext if running in plan phase
const output = Output.literal(Redacted.make(node.value));
yield* ctx?.set(key, output) ?? Effect.void;
return node;
} else if (phase === "runtime" && ctx) {
// retrieve from the RuntimeContext if running in runtime phase
const value = yield* ctx.get<unknown>(key);
if (value) {
// `get` JSON-decodes unbound env values (`"true"` →
// `true`), but a `Value` node holds the raw string the
// `Config` schema parses.
return ConfigProvider.makeValue(
Redacted.isRedacted(value)
? String(Redacted.value(value))
: typeof value === "string"
? value
: JSON.stringify(value),
);
}
}
// fallback to the config provider otherwise
return node;
}),
);
}),
).pipe(
Layer.provideMerge(
// Services the host provides its init (e.g. a Worker's `WebhookHost`),
// built over the instance so they can `yield*` it.
(runtimeContext.hostServices ?? Layer.empty).pipe(
Layer.provideMerge(
Layer.mergeAll(
// Pin init's ambient `Scope` to this layer's build
// scope. `Effect.provide` (`scopedWith`) would
// otherwise shadow it with a transient scope that
// closes the moment init returns; the build scope
// lives for the instance under the runtime bridges,
// so init-level finalizers run at instance shutdown
// (Lambda's SIGTERM window) or never (workerd) —
// request-coupled cleanup belongs in handlers, where
// the bridge provides a per-event scope. It also
// wins over any `Scope` captured in `outerServices`
// below.
Layer.succeed(Scope, buildScope),
Layer.succeed(Platform.Platform, runtimeContext),
Layer.succeed(PlatformContext, runtimeContext),
Layer.succeed(RuntimeContext, runtimeContext),
// Host contexts (EC2 instances, ECS tasks, processes)
// carry a `run` for registering long-running loops.
// Expose it as `ServerHost` so an inline program can
// `yield* ServerHost` during plan/deploy without the
// caller providing the layer itself.
"run" in runtimeContext &&
typeof (runtimeContext as { run?: unknown }).run === "function"
? Layer.succeed(ServerHost, {
run: (runtimeContext as ProcessContext).run,
})
: Layer.empty,
Layer.succeed(resource.Self, instance),
Layer.succeed(Platform.Self, instance),
Layer.succeed(Self, instance),
runtimeContext.planServices
? Layer.unwrap(
ALCHEMY_PHASE.pipe(
Effect.map((phase) =>
phase === "plan" ? runtimeContext.planServices! : Layer.empty,
),
),
)
: Layer.empty,
),
),
),
),
Layer.provideMerge(Layer.succeedContext(outerServices)),
),
),
);
instance.Props = {
...props,
env: {
...props?.env,
...runtimeContext.env,
},
exports: runtimeContext.exports ? yield* runtimeContext.exports : undefined,
};
return Object.assign(instance, {
RuntimeContext: runtimeContext,
}) as R;
}),
),
);
const self = Self as any; // TODO(sam): why do we need to cast?
return Layer.provideMerge(
Layer.mergeAll(
// sets the Context for all self-hierarchies
// Self
// Self<Cloudflare.Worker>
// Self<Cloudflare.Worker<Api>>
Layer.effect(Self<R>(type), self),
Layer.effect(Self<R>(`${type}<${id}>`), self),
),
// provide here so we build once and just mirror
SelfLayer,
);
};
}
// Make the platform class itself a real Effect: `yield* MyWorker` resolves
// the Self tag. Replaces the hand-rolled asEffect/pipe/[Symbol.iterator].
return Object.assign(
Platform,
Effectable.Prototype({
label: `${type}<${id}>`,
evaluate: () => Platform.Self,
}),
);
};
const instance = Object.assign(
constructor,
resource,
// Spread the Effect prototype LAST so it overrides any evaluate inherited
// from `resource`; `yield* Cloudflare.Worker` resolves the resource Self.
Effectable.Prototype({
label: `${type}`,
evaluate: () => resource.Self,
}),
{
Platform: Platform,
...methods,
},
) as any;
return instance;
};