import { fileURLToPath } from "node:url";
import * as Cache from "effect/Cache";
import type * as Cause from "effect/Cause";
import * as Config from "effect/Config";
import * as Context from "effect/Context";
import * as Data from "effect/Data";
import * as Deferred from "effect/Deferred";
import * as Duration from "effect/Duration";
import * as Effect from "effect/Effect";
import * as Fiber from "effect/Fiber";
import * as HttpClient from "effect/http/HttpClient";
import * as HttpServer from "effect/http/HttpServer";
import { 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 type { PlatformError } from "effect/PlatformError";
import * as ChildProcess from "effect/process/ChildProcess";
import * as ChildProcessSpawner from "effect/process/ChildProcessSpawner";
import * as Queue from "effect/Queue";
import * as Schedule from "effect/Schedule";
import * as Schema from "effect/Schema";
import * as Scope from "effect/Scope";
import * as Stream from "effect/Stream";
import { LOG_FORMAT_ENV, logChildLine } from "../Util/LogRecord.ts";
import { nodeLoaderArgs } from "../Util/Node.ts";
import { httpServer } from "../Util/PlatformServices.ts";
import { timedShutdownStep } from "../Util/Shutdown.ts";
import { pipedColorEnv } from "../Util/Terminal.ts";
import { traceParentEnv } from "../Util/TraceParent.ts";
import { SPAWNER_URL_ENV_KEY } from "./RpcProviderProxy.ts";
import { RPC_SERVER_ENVIRONMENT_KEY, type RpcServerEnvironment } from "./RpcServerEnvironment.ts";
export class RpcSpawner extends Context.Service<
RpcSpawner,
{
readonly url: string;
}
>()("alchemy/Local/RpcSpawner") {}
class InvalidServerEntryUrl extends Data.TaggedError("InvalidServerEntryUrl")<{
cause: unknown;
}> {}
/**
* The spawner forks one child per distinct `serverEntryUrl`. Stack-specific
* context (stack name/stage, AlchemyContext) is NOT part of the spawn key —
* it travels per RPC session (see `SESSION_ENV_PARAM`), so many stacks
* (e.g. every test file in a run) share a single sidecar process.
*/
export const RpcSpawnPayload = Schema.Struct({ serverEntryUrl: Schema.String });
export type RpcSpawnPayload = typeof RpcSpawnPayload.Type;
/**
* One line of sidecar child output, tagged with the channel it arrived on.
* Streamed as NDJSON over the spawner's {@link LOGS_PATH} endpoint.
*/
export interface SidecarLogLine {
readonly channel: "stdout" | "stderr";
readonly line: string;
}
export const HeartbeatFrame = Schema.Struct({
channel: Schema.Literal("heartbeat"),
});
export type HeartbeatFrame = typeof HeartbeatFrame.Type;
const SidecarLogLineSchema = Schema.Struct({
channel: Schema.Literals(["stdout", "stderr"]),
line: Schema.String,
});
/**
* Path on the spawner's HTTP server that streams sidecar output as NDJSON
* ({@link SidecarLogLine} per line). Consumed by {@link forwardSidecarLogs}
* from the exec child, which owns the terminal renderer.
*/
export const LOGS_PATH = "/logs";
/** Options for the {@link RpcSpawner} that forks sidecar processes. */
export type RpcSpawnerOptions = Pick<RpcServerEnvironment, "profile" | "envFile"> & {
/**
* Prefixes of environment variables withheld from sidecar processes (and,
* through them, from their own children). Sidecars otherwise inherit this
* process's entire environment.
*/
readonly omitEnv?: ReadonlyArray<string>;
};
export const make = Effect.fn(function* ({ profile, envFile, omitEnv = [] }: RpcSpawnerOptions) {
const spawner = yield* ChildProcessSpawner.ChildProcessSpawner;
const scope = yield* Effect.scope;
const cache = yield* Cache.make({
lookup: (serverEntryUrl: string) => spawn(serverEntryUrl).pipe(Scope.provide(scope)),
capacity: Infinity,
});
// Sidecar output hub. During `alchemy dev` this process (the outer dev
// command) shares the tty with the exec child, and the exec child owns the
// repainting progress renderer. Printing sidecar lines RAW from here
// interleaves with the renderer's repaints and corrupts the region
// (stacked/duplicated frames). So: when an exec child is subscribed via
// the /logs endpoint, hand lines to it and let its logger route them into
// the renderer; only log from this process as a fallback when no
// subscriber is connected (e.g. during a --watch restart gap, when no
// renderer is alive either).
const subscribers = new Set<(line: SidecarLogLine) => void>();
const publish = (line: SidecarLogLine): Effect.Effect<void> =>
Effect.suspend(() => {
if (subscribers.size > 0) {
for (const notify of subscribers) notify(line);
return Effect.void;
}
// Fallback path (no exec child subscribed): render the sidecar's
// records through this process's loggers.
return logChildLine(line.line, { stream: line.channel, process: "sidecar" });
});
const spawn = Effect.fn(function* (serverEntryUrl: string) {
const bin = typeof globalThis.Bun !== "undefined" ? "bun" : "node";
const main = fileURLToPath(serverEntryUrl);
// The sidecar runs on THIS process's runtime binary, not whatever PATH
// resolves: a `.ts` entry (checkout) needs the dev-mode loader hooks,
// which are gated on this node's version, and a published `.js` entry
// must not silently switch Node versions between supervisor and sidecar.
const program = bin === "bun" ? "bun" : process.execPath;
// Stack-specific context is deliberately absent: sessions carry their
// own SessionEnvironment, so one child serves every stack.
const environment: RpcServerEnvironment = {
profile,
envFile,
};
// Sidecar stdio is piped, so toolchains down the chain (vite, workerd,
// pretty loggers) detect a non-TTY and drop ANSI colors — but their
// output ultimately renders on THIS process's terminal. Force color
// through the pipe when that terminal supports it, unless the user
// already decided (NO_COLOR / FORCE_COLOR). `extendEnv` propagates it
// from the sidecar to its own children (dev servers, workerd).
const command = ChildProcess.make(
program,
{
bun: ["run", main],
// Under Node the sidecar starts with alchemy's Oxc loader hooks, the
// same way `dev.ts` starts the exec child: a `.ts` entry (src/ in a
// checkout) also gets src-condition resolution, a `.js` entry (lib/
// in a published install) gets the loader alone.
node: [...nodeLoaderArgs(main), main],
}[bin],
{
stdout: "pipe",
// Piped (NOT inherited) so the child's output routes through the
// Effect Console service: raw writes to the parent's fd corrupt the
// test runner's reporter/TUI. The drain below is mandatory — an
// unread pipe eventually fills and blocks the child.
stderr: "pipe",
// `detached` deliberately unset: the spawner defaults to a new process
// group on POSIX (and none on Windows, where a detached console child
// has its own quirks). A terminal Ctrl+C must NOT reach the sidecar
// directly — its lifecycle belongs to this process's finalizer (the
// bounded kill below), and a sidecar tearing itself down concurrently
// yanks local providers out from under the exec child mid-shutdown.
// As a group leader the kill also reaps the sidecar's own children
// (workerd, emulators) instead of orphaning them.
env: {
...(omitEnv.length > 0 ? yield* inheritedEnv(omitEnv) : {}),
[RPC_SERVER_ENVIRONMENT_KEY]: JSON.stringify(environment),
// Its startup joins the trace of the call that spawned it; each
// provider call then carries its caller's span (RpcSerialization).
...(yield* traceParentEnv),
// Log records, not rendered text: see `forwardSidecarLogs`.
[LOG_FORMAT_ENV]: "json",
// Tools further down (vite, workerd) still style their own output;
// records keep that text as written.
...pipedColorEnv(),
},
// With variables to withhold, the full environment is built above.
extendEnv: omitEnv.length === 0,
},
);
const handle = yield* spawner.spawn(command);
const stderrReader = yield* handle.stderr.pipe(
Stream.decodeText,
Stream.splitLines,
Stream.runForEach((line) => publish({ channel: "stderr", line })),
Effect.ignore,
Effect.forkScoped,
);
const stdout = yield* readRpcOutput(handle.stdout, (line) =>
publish({ channel: "stdout", line }),
);
// This scope is the child handle's sole owner. Graceful shutdown runs this
// finalizer; abrupt parent loss closes the RPC parent connection and the
// child self-terminates (both paths are covered by RpcSpawnerCleanup).
// Command cleanup allows 1s for TERM and 1s for KILL; reserve 1s for sidecar teardown.
const kill = handle.kill({ forceKillAfter: "3 seconds" });
// Registered after the readers, so it runs before they are interrupted:
// the sidecar's own shutdown records drain until its pipes close.
yield* Effect.addFinalizer(() =>
kill.pipe(
Effect.ignore,
Effect.andThen(
Fiber.joinAll([stderrReader, stdout.reader]).pipe(
Effect.timeout("1 second"),
Effect.ignore,
),
),
timedShutdownStep(`stopped sidecar pid ${handle.pid}`),
),
);
const url = yield* Deferred.await(stdout.address);
const ws = yield* Effect.acquireRelease(
Effect.sync(() => {
const ws = new WebSocket(new URL("/parent", url));
// Keep the parent link active so no idle timer on either end can
// close it; the sidecar ignores messages on this link.
const heartbeat = setInterval(() => {
if (ws.readyState === WebSocket.OPEN) ws.send("heartbeat");
}, 30_000);
heartbeat.unref?.();
ws.addEventListener("close", () => clearInterval(heartbeat));
return ws;
}),
(ws) => Effect.sync(() => ws.close()),
);
return {
url,
isRunning: Effect.zipWith(
handle.isRunning,
Effect.sync(
() => ws.readyState === WebSocket.CONNECTING || ws.readyState === WebSocket.OPEN,
),
(a, b) => a && b,
{ concurrent: true },
),
kill,
};
});
const register = Effect.fn(function* (
serverEntryUrl: string,
attempt = 0,
): Effect.fn.Return<string, PlatformError> {
const child = yield* Cache.get(cache, serverEntryUrl);
if (yield* child.isRunning) {
return child.url;
}
if (attempt > 3) {
return yield* Effect.die(
new Error(`Failed to spawn RPC server for "${serverEntryUrl}" after ${attempt} attempts.`),
);
}
yield* Effect.logWarning(
`RPC sidecar for ${serverEntryUrl} is no longer running; respawning (attempt ${attempt + 1})`,
);
// The sidecar is usually already gone, and killing an exited process fails.
yield* child.kill.pipe(Effect.ignore);
yield* Cache.invalidate(cache, serverEntryUrl);
return yield* register(serverEntryUrl, attempt + 1);
});
const server = yield* HttpServer.HttpServer;
const encoder = new TextEncoder();
// The first heartbeat flushes the response headers immediately; the
// periodic ones defeat idle timeouts (Bun kills sockets that stay silent
// for ~10s). Entries without a `line` are skipped by the client.
const heartbeat: HeartbeatFrame = { channel: "heartbeat" };
const HEARTBEAT = encoder.encode(`${JSON.stringify(heartbeat)}\n`);
const heartbeats = Stream.make(HEARTBEAT).pipe(
Stream.concat(
Schedule.spaced(Duration.seconds(5)).pipe(
Stream.fromSchedule,
Stream.map(() => HEARTBEAT),
),
),
);
yield* server.serve(
Effect.gen(function* () {
const request = yield* HttpServerRequest;
// `request.url` is relative under Node and absolute under Bun —
// normalize to the pathname before matching.
const pathname = new URL(request.url, "http://localhost").pathname;
if (pathname === LOGS_PATH) {
// Long-lived NDJSON stream of sidecar output. The subscriber (exec
// child) routes these lines through its logger, which the renderer
// inserts above the progress region instead of tearing it. Client
// disconnect interrupts the stream and unregisters the subscriber.
const queue = yield* Queue.make<Uint8Array, Cause.Done>();
const notify = (line: SidecarLogLine) => {
Queue.offerUnsafe(queue, encoder.encode(`${JSON.stringify(line)}\n`));
};
subscribers.add(notify);
return HttpServerResponse.stream(
Stream.merge(
Stream.fromQueue(queue).pipe(
Stream.ensuring(Effect.sync(() => subscribers.delete(notify))),
),
heartbeats,
),
{ contentType: "application/x-ndjson" },
);
}
const decoded = yield* Effect.result(
request.json.pipe(Effect.flatMap(Schema.decodeUnknownEffect(RpcSpawnPayload))),
);
if (decoded._tag === "Failure") {
return HttpServerResponse.text("Invalid RPC spawn payload.", {
status: 400,
});
}
const entry = yield* Effect.result(
Effect.try({
try: () => new URL(decoded.success.serverEntryUrl),
catch: (cause) => new InvalidServerEntryUrl({ cause }),
}),
);
if (entry._tag === "Failure" || entry.success.protocol !== "file:") {
return HttpServerResponse.text("serverEntryUrl must be a valid file URL.", { status: 400 });
}
const url = yield* register(entry.success.href);
return HttpServerResponse.text(url);
}),
);
return RpcSpawner.of({
url: HttpServer.formatAddress(server.address),
});
});
/** This process's environment without the variables matching `omitEnv`. */
const inheritedEnv = (omitEnv: ReadonlyArray<string>) =>
Effect.sync(() =>
Object.fromEntries(
Object.entries(process.env).filter(
([key]) => !omitEnv.some((prefix) => key.startsWith(prefix)),
),
),
);
export const layerServer = (environment: RpcSpawnerOptions) =>
Layer.effect(RpcSpawner, make(environment)).pipe(
// `/logs` is deliberately long-lived. On shutdown the exec child still
// owns that response while this scope owns the exec child, so waiting for
// Node's default 20-second graceful HTTP drain creates a finalizer cycle.
// Stop accepting/serving immediately so the watcher finalizer can close
// the child; all actual sidecars still use their own bounded finalizers.
Layer.provide(httpServer(0, "127.0.0.1", { gracefulShutdownTimeout: 0 })),
);
const RPC_ADDRESS_REGEX = /(<ALCHEMY_RPC_ADDRESS>)(.+)(<\/ALCHEMY_RPC_ADDRESS>)/;
/**
* Read the sidecar's stdout: its log lines and the RPC address line. The
* reader runs until the pipe closes, so a caller can drain it on shutdown.
*/
const readRpcOutput = (
stdout: Stream.Stream<Uint8Array, PlatformError>,
publish: (line: string) => Effect.Effect<void>,
) =>
Effect.gen(function* () {
const address = yield* Deferred.make<string>();
// Every line but the address is published, including what the sidecar
// logs while starting: a layer that fails to build says why there.
const reader = yield* stdout.pipe(
Stream.decodeText,
Stream.splitLines,
Stream.runForEach((line) => {
const match = line.match(RPC_ADDRESS_REGEX);
return match ? Deferred.succeed(address, match[2]) : publish(line);
}),
Effect.ignore,
Effect.forkScoped,
);
return { address, reader };
});
export const parseSidecarLogLine = (raw: string): SidecarLogLine | undefined => {
try {
return Schema.decodeUnknownOption(SidecarLogLineSchema)(JSON.parse(raw)).pipe(
Option.getOrUndefined,
);
} catch {
return undefined;
}
};
/**
* Pull the sidecars' log records from the spawner (the outer `alchemy dev`
* process) into THIS process's loggers. The exec child owns the terminal
* renderer, so the records render above the repainting progress region
* instead of racing it on the shared tty; it forwards them on to the
* supervisor, which writes the run log. Forks in the ambient scope and never fails: when no spawner is
* configured (`ALCHEMY_RPC_SPAWNER_URL` absent — plain deploy/destroy) it is
* a no-op, and if the connection drops the spawner's own fallback printing
* takes over.
*/
export const forwardSidecarLogs: Effect.Effect<void, never, HttpClient.HttpClient | Scope.Scope> =
Config.String(SPAWNER_URL_ENV_KEY).pipe(
Effect.flatMap((spawnerUrl) => {
const streamOnce = Effect.gen(function* () {
const client = yield* HttpClient.HttpClient;
const response = yield* client.get(new URL(LOGS_PATH, spawnerUrl).toString());
yield* response.stream.pipe(
Stream.decodeText,
Stream.splitLines,
Stream.runForEach((raw) =>
Effect.suspend(() => {
const parsed = parseSidecarLogLine(raw);
if (parsed === undefined) return Effect.void;
// Sidecar lines are log records: replay them through this
// process's loggers, which render them (or pass them on as JSON).
return logChildLine(parsed.line, { stream: parsed.channel, process: "sidecar" });
}),
),
);
});
// Keep the subscription alive for the whole dev session: reconnect
// (paced) if the stream ends or errors. While disconnected the spawner's
// fallback printing covers the gap; the loop dies with the ambient scope.
return streamOnce.pipe(
Effect.ignore,
Effect.andThen(Effect.sleep("1 second")),
Effect.forever,
);
}),
Effect.ignore,
Effect.forkScoped,
Effect.asVoid,
);