import type {
BindingHook,
BindingServices,
HyperdriveOrigin,
Assets as RuntimeAssets,
DurableObjectNamespace as RuntimeDurableObject,
QueueConsumer as RuntimeQueueConsumer,
RuntimeServices,
RuntimeWorker,
} from "@alchemy.run/cloudflare-runtime/core";
import type { Artifacts } from "alchemy/Artifacts";
import type * as Bundle from "alchemy/Bundle/Bundle";
import type * as Context from "effect/Context";
import * as Data from "effect/Data";
import * as Effect from "effect/Effect";
import type * as FileSystem from "effect/FileSystem";
import type * as Path from "effect/Path";
import type { PlatformError } from "effect/PlatformError";
import type { ChildProcessSpawner } from "effect/process/ChildProcessSpawner";
import type * as Scope from "effect/Scope";
import type * as Stream from "effect/Stream";
import type { AssetReadResult, ValidationError } from "./Assets.ts";
import { getToolingCompatibility } from "./Compatibility.ts";
import { makeInlineScriptSource } from "./Sources/InlineScript.ts";
import { makePrebuiltSource } from "./Sources/Prebuilt.ts";
import { isPythonMain, makePythonSource } from "./Sources/Python.ts";
import { makeRolldownSource } from "./Sources/Rolldown.ts";
import type { WorkerAssetsConfig, WorkerProps, WorkerSourceDescriptor } from "./Worker.ts";
import type { WorkerExport } from "./WorkerRuntimeContext.ts";
/**
* The hash slots a Worker source contributes to
* `Worker["Attributes"]["hash"]`. Slots a source doesn't use are
* `undefined`. The `metadata` hash (#745) is deliberately NOT a source
* slot — it covers the deploy-time metadata surface and stays owned by
* the WorkerProvider.
*/
export interface SourceHash {
readonly bundle: string | undefined;
readonly assets: string | undefined;
readonly input: string | undefined;
/**
* Auxiliary metadata for the `input` hash (vite's auto-detected
* workspace directories, relative to the source root). Never compared
* as a change signal — only carried so the next `hash()` call can
* recompute `input` over the same workspace set.
*/
readonly additionalWorkspaces: string[] | undefined;
}
export interface SourceBuildOutput {
/**
* Server bundle. `undefined` for assets-only workers (e.g. a static
* vite site with no server environment).
*/
readonly bundle: Bundle.BundleOutput | undefined;
/**
* Static assets, already read and manifest-hashed. `undefined` when the
* source doesn't own assets — the WorkerProvider merges in the
* props-level `assets` for those sources (see
* {@link SourceProvider.ownsAssets}).
*/
readonly assets: AssetReadResult | undefined;
/** Source-owned hash slots. Slots the source doesn't use are omitted. */
readonly hash: Partial<SourceHash>;
}
/**
* Everything a source may need, derived once by the WorkerProvider from
* `(id, props, stack)`. Source-specific inputs (entry module path, vite
* options, inline script, ...) are closed over by the provider instance
* itself — providers are resolved per Worker from props, not injected
* once per stack.
*/
export interface SourceContext {
/** Resolved runtime storage directory, excluded from source inputs. */
readonly dotAlchemy?: string;
/** Logical id of the Worker resource. */
readonly id: string;
/** Namespace-qualified id (`ns/Worker`) — the display prefix for log lines. */
readonly fqn: string;
/** Physical script name. */
readonly workerName: string;
readonly compatibility: {
readonly date: string;
readonly flags: string[];
};
/** Effect-entry vs external-entry (async workers). Drives the virtual-entry plugin. */
readonly entry:
| { readonly kind: "external" }
| {
readonly kind: "effect";
readonly exports: Record<string, WorkerExport>;
};
readonly stack: { readonly name: string; readonly stage: string };
/**
* Raw `props.env`. Deliberately unresolved: env entries may be Effects
* whose evaluation requires plan-phase context that is not available
* inside lifecycle operations — a source that needs literal values
* (e.g. vite's `import.meta.env` defines) resolves them itself, exactly
* as the vite arm always has.
*/
readonly env: Record<string, unknown> | undefined;
/**
* This Worker's own URL, when it has one and an env entry refers to
* it (`Worker.URL`). Only the WorkerProvider knows it — a source that
* resolves `env` substitutes it for that entry.
*/
readonly selfUrl: string | undefined;
/** `props.build` passthrough for rolldown-based sources. */
readonly extraOptions: Bundle.BundleExtraOptions | undefined;
/**
* Raw `props.assets`. Sources that own their assets (vite) merge its
* routing config into the assets they read out of the build; sources
* that don't own assets never touch it (the WorkerProvider reads and
* diffs props-level assets centrally).
*/
readonly assets: WorkerAssetsConfig | undefined;
}
/**
* Runtime settings of a Worker beyond its bindings, Durable Objects,
* Hyperdrives, queue consumers and assets: cron triggers, Workflows, tail
* consumers, the Cache API, `request.cf`, the zone, Access and the workerd
* process overrides.
*/
export type DevWorkerOptions = Pick<
RuntimeWorker,
| "workflows"
| "crons"
| "tails"
| "streamingTails"
| "cache"
| "cf"
| "zone"
| "access"
| "workerd"
>;
/**
* Runtime wiring for local dev, derived by the LocalWorkerProvider.
* Server-mode sources that embed their own workerd (the vite plugin)
* consume `worker` + `runtimeContext`; bundle-mode sources ignore both.
*/
export interface DevContext extends SourceContext {
readonly worker: {
readonly bindings: BindingHook<BindingServices>[];
readonly durableObjectNamespaces: (RuntimeDurableObject & {
uniqueKey: string;
})[];
readonly hyperdrives: Record<string, Required<HyperdriveOrigin>>;
/** Re-read on each (re)start so late-registered consumers are observed. */
readonly queueConsumers: Effect.Effect<RuntimeQueueConsumer[]>;
readonly assets: RuntimeAssets | undefined;
/**
* The Worker's other runtime settings. A source that runs the Worker in
* workerd spreads them whole into its runtime Worker, so a setting added
* here reaches every source.
*/
readonly options: DevWorkerOptions;
};
/** RuntimeServices context for providers that embed cloudflare-runtime. */
readonly runtimeContext: Context.Context<RuntimeServices>;
}
/**
* How a source serves local dev. Two irreducible modes:
*
* - `bundle` — the host runs workerd; the source supplies rebuild events
* and the host restarts workerd with each successful bundle.
* - `server` — the source runs its own dev server (vite dev); the host
* points the WorkerProxy at `url`.
*/
export type SourceDevHandle =
| {
readonly mode: "bundle";
readonly bundles: Stream.Stream<Bundle.BundleWatchEvent, SourceError, SourceDevServices>;
}
| {
readonly mode: "server";
readonly url: URL;
/** Register an HTTP forwarding Worker when the server does not run in workerd. */
readonly serviceBinding?: "http";
};
/**
* The closed requirements channel of a source. Anything else a source
* needs (vite module loading, framework CLIs, workerd runtime services
* for dev) it constructs internally — external providers must NOT demand
* bespoke services from the WorkerProvider.
*/
export type SourceServices =
| FileSystem.FileSystem
| Path.Path
| ChildProcessSpawner
| Scope.Scope
| Artifacts;
/** Requirements available to `dev()` (no per-run Artifacts cache in the local host). */
export type SourceDevServices =
| FileSystem.FileSystem
| Path.Path
| ChildProcessSpawner
| Scope.Scope;
/**
* An error raised by an external source provider, wrapped at the load
* boundary so the WorkerProvider's lifecycle error union stays closed.
*/
export class SourceProviderError extends Data.TaggedError(
"Cloudflare.Workers.SourceProviderError",
)<{
/** Module specifier or built-in kind. */
readonly provider: string;
readonly message: string;
readonly cause?: unknown;
}> {}
export type SourceError =
| Bundle.BundleError
| ValidationError
| PlatformError
| SourceProviderError;
/**
* A Worker source provider: supplies the static assets, the server
* bundle, and hashes for memoization, plus a dev-serving story. The five
* built-in arms (inline script, rolldown, python, prebuilt, vite) live in
* `Workers/Sources/`; framework providers implement the same interface.
*/
export interface SourceProvider {
/**
* Whether this source produces its own static assets from its build
* (vite, framework builds). When `false`, the WorkerProvider reads and
* diffs the props-level `assets` directory centrally — including the
* AssetsWithHash fast path — and the source only supplies the bundle.
*/
readonly ownsAssets: boolean;
/**
* Whether a server-mode `dev()` hosts `ctx.worker.bindings` in a runtime
* whose assets service is configured: the Vite plugin (which serves
* `publicDir` and the app's HTML), or a platform proxy given the app's
* static directory. The host then adds the `ASSETS` binding to
* `ctx.worker.bindings`, as a deployed Worker with assets has it. Leave
* unset otherwise: the binding fails when the assets service is
* unconfigured.
*
* @default false
*/
readonly devAssetsBinding?: boolean;
/**
* Full build. Called from reconcile (`putWorker`). If the build is
* expensive it MUST be memoized per run via `Artifacts.cached` under
* the same key `hash()` uses, so a diff that had to build doesn't
* build twice.
*/
readonly build: (
ctx: SourceContext,
) => Effect.Effect<SourceBuildOutput, SourceError, SourceServices>;
/**
* Recompute the source-owned hash slots for diff, as cheaply as
* possible and WITHOUT a full build when the source supports it.
* `previous` is `output.hash` from state. Returns only the slots this
* source uses; the WorkerProvider compares slot-wise against
* `previous` — any defined slot that differs ⇒ update.
*
* Invariants:
* - MUST be deterministic for an unchanged source tree and
* machine-independent for identical bytes (never hash absolute paths).
* - If it cannot avoid building, it MUST route the build through the
* same `Artifacts.cached` key as `build()` so diff→reconcile builds
* once.
* - `previous` is a hint, never truth: a source must not skip
* recomputation because `previous` looks fresh — it may only use it
* for auxiliary inputs (`additionalWorkspaces`).
*/
readonly hash: (
ctx: SourceContext,
previous: SourceHash | undefined,
) => Effect.Effect<Partial<SourceHash>, SourceError, SourceServices>;
/**
* Local dev. Scoped: closing the Scope stops the watcher / dev server.
*/
readonly dev: (
ctx: DevContext,
) => Effect.Effect<SourceDevHandle, SourceError, SourceDevServices | Scope.Scope>;
}
/**
* The contract of a dynamically-imported source-provider module: its
* default export builds a {@link SourceProvider} from the descriptor's
* (JSON-serializable) options. `make` provides the package's own layers
* internally, so the closed {@link SourceServices} requirement holds.
*/
export interface WorkerSourceModule {
readonly make: (
options: unknown,
) => Effect.Effect<SourceProvider, SourceProviderError, SourceServices>;
}
/**
* Validated provider modules memoized per specifier for the process
* lifetime — a Worker resolves its source at least twice per deploy
* (diff, then reconcile). `make(options)` still runs per resolution: a
* stack can host several Workers of the same provider with different
* options.
*/
const sourceModules = new Map<string, WorkerSourceModule>();
const importSourceModule = (
specifier: string,
): Effect.Effect<WorkerSourceModule, SourceProviderError> =>
Effect.suspend(() => {
const cached = sourceModules.get(specifier);
if (cached) {
return Effect.succeed(cached);
}
return Effect.tryPromise({
try: () => import(/* @vite-ignore */ specifier),
catch: (cause) =>
new SourceProviderError({
provider: specifier,
message:
`Failed to import Worker source provider "${specifier}". ` +
`Is the package installed in your project? Install it and re-run.`,
cause,
}),
}).pipe(
Effect.flatMap((mod: { default?: Partial<WorkerSourceModule> }) => {
if (typeof mod.default?.make !== "function") {
return Effect.fail(
new SourceProviderError({
provider: specifier,
message:
`Module "${specifier}" is not a Worker source provider: ` +
`its default export must satisfy WorkerSourceModule ({ make(options) }).`,
}),
);
}
const module = mod.default as WorkerSourceModule;
sourceModules.set(specifier, module);
return Effect.succeed(module);
}),
);
});
/**
* Load an external source provider from its serializable descriptor:
* dynamically import the module, validate the shape, and call
* `make(options)`.
*/
export const loadSource = (
descriptor: WorkerSourceDescriptor,
): Effect.Effect<SourceProvider, SourceProviderError, SourceServices> =>
importSourceModule(descriptor.provider).pipe(
Effect.flatMap((mod) => mod.make(descriptor.options)),
);
/**
* Whether a Worker has no code at all — no `main`, `script`, `vite` or
* `source` — and only serves its `assets`. Every other Worker resolves a
* {@link SourceProvider} with {@link resolveSource}.
*/
export const isAssetsOnly = (props: WorkerProps) =>
props.main === undefined && props.script === undefined && !props.vite && !props.source;
/**
* Resolve the {@link SourceProvider} for a Worker from its props. The
* `source` descriptor (external providers) wins; legacy props map to the
* built-in providers, preserving the historical precedence exactly:
* `script` → `vite` → `.py` main → `bundle: false` → rolldown (default).
*
* `source` is mutually exclusive with `script`/`vite`/`main` — a source
* is self-contained, and a provider that needs a custom entry takes it
* in its own `options`.
*/
export const resolveSource = (
props: WorkerProps,
): Effect.Effect<SourceProvider, SourceProviderError, SourceServices> => {
if (props.source) {
const conflict =
props.script !== undefined
? "script"
: props.vite
? "vite"
: props.main !== undefined
? "main"
: undefined;
if (conflict) {
return Effect.fail(
new SourceProviderError({
provider: props.source.provider,
message:
`Worker prop "source" is mutually exclusive with "${conflict}": ` +
`a source provider is self-contained — pass a custom entry via the provider's own options instead.`,
}),
);
}
return loadSource(props.source);
}
if (props.script !== undefined) {
return Effect.succeed(makeInlineScriptSource(props.script));
}
if (props.vite) {
// Loaded lazily: `./Sources/Vite.ts` pulls in
// `@alchemy.run/cloudflare-runtime/vite` (~0.5s), which is only
// needed for vite-based workers — not for every Worker resolution.
const vite = props.vite;
return Effect.promise(() => import("./Sources/Vite.ts")).pipe(
Effect.map((Vite) => Vite.makeViteSource(vite)),
);
}
if (isPythonMain(props.main)) {
return Effect.succeed(makePythonSource(props.main));
}
if (props.bundle === false) {
return Effect.succeed(makePrebuiltSource({ main: props.main!, rules: props.rules }));
}
return Effect.succeed(makeRolldownSource({ main: props.main!, rules: props.rules }));
};
/**
* Derive the shared {@link SourceContext} from a Worker's props. Pure —
* the physical `workerName` is computed by the caller (it may come from
* persisted output state rather than the name generator).
*/
export const makeSourceContext = (params: {
dotAlchemy?: string;
id: string;
fqn: string;
workerName: string;
props: WorkerProps;
compatibility: { date: string; flags: string[] };
stack: { name: string; stage: string };
selfUrl?: string;
}): SourceContext => ({
dotAlchemy: params.dotAlchemy,
id: params.id,
fqn: params.fqn,
workerName: params.workerName,
compatibility: getToolingCompatibility(params.compatibility, params.props.main),
entry: params.props.isExternal
? { kind: "external" }
: { kind: "effect", exports: params.props.exports ?? {} },
stack: { name: params.stack.name, stage: params.stack.stage },
env: params.props.env,
selfUrl: params.selfUrl,
extraOptions: params.props.build,
assets: params.props.assets,
});