// Per-instance backend factory. Replaces the legacy singleton// `DesktopBackendManager` Context.Service: each call to// `makeBackendInstance(spec)` constructs an isolated backend lifecycle —// its own state Ref, mutex, restart loop, and active child process. The// returned `DesktopBackendInstance` exposes start/stop/snapshot/wait// methods that operate on that single backend.//// The pool layer (`DesktopBackendPool.ts`) calls this factory once per// backend it wants to run. Today that's the Windows primary; follow-up// commits add a second call for the WSL instance.//// Singleton couplings that the legacy service held inline are now// parameterized via the spec:// - configResolve replaces the legacy `DesktopBackendConfiguration.resolve`// so each instance can resolve its own start config — the primary wires// `configuration.resolvePrimary`, the WSL orchestrator wires a// `configuration.resolveWsl({ port, distro })` closure.// - onReady / onShutdown drive UI side effects (window auto-open,// readiness latch) only for instances that want them — the primary's// spec passes the window's handleBackendReady/handleBackendNotReady,// other pool instances pass nothing.// - log writes go through a per-instance writer that the factory// pulls from `DesktopBackendOutputLogFactory.forInstance(spec.id)`,// so each instance lands in its own rotating file. import * as Brand from "effect/Brand";import * as Cause from "effect/Cause";import * as Duration from "effect/Duration";import * as Effect from "effect/Effect";import * as Exit from "effect/Exit";import * as Fiber from "effect/Fiber";import * as FileSystem from "effect/FileSystem";import * as Option from "effect/Option";import * as PlatformError from "effect/PlatformError";import * as Ref from "effect/Ref";import * as Schedule from "effect/Schedule";import * as Schema from "effect/Schema";import * as Semaphore from "effect/Semaphore";import * as Scope from "effect/Scope";import * as Stream from "effect/Stream";import { HttpClient } from "effect/unstable/http";import { ChildProcess, ChildProcessSpawner } from "effect/unstable/process"; import { DesktopBackendBootstrap, type DesktopBackendBootstrap as DesktopBackendBootstrapValue, PRIMARY_LOCAL_ENVIRONMENT_ID, DesktopTelemetryControlMessage, type DesktopTelemetryControlMessage as DesktopTelemetryControlMessageValue,} from "@t3tools/contracts";import { waitForHttpReady as waitForHttpReadyShared } from "@t3tools/shared/httpReadiness"; import * as DesktopObservability from "../app/DesktopObservability.ts";import * as DesktopTelemetryPublisher from "../telemetry/DesktopTelemetryPublisher.ts";import * as DesktopWslEnvironment from "../wsl/DesktopWslEnvironment.ts"; const INITIAL_RESTART_DELAY = Duration.millis(500);const MAX_RESTART_DELAY = Duration.seconds(10);// After this many consecutive fatal preflight failures, stop the silent// restart loop and surface the reason via onPreflightFailed. Transient// failures may instead provide their own larger retryLimit when they should// self-heal for a while but must not leave the app connecting forever.const MAX_PREFLIGHT_FAILURE_ATTEMPTS = 5;const DEFAULT_BACKEND_READINESS_TIMEOUT = Duration.minutes(1);const DEFAULT_BACKEND_READINESS_INTERVAL = Duration.millis(100);const DEFAULT_BACKEND_READINESS_REQUEST_TIMEOUT = Duration.seconds(1);const DEFAULT_BACKEND_TERMINATE_GRACE = Duration.seconds(2);const DEFAULT_BACKEND_OUTPUT_DRAIN_TIMEOUT = Duration.seconds(5);const BACKEND_READINESS_PATH = "/.well-known/t3/environment";const { logWarning: logBackendProcessWarning } = DesktopObservability.makeComponentLogger("desktop-backend-process"); type BackendProcessLayerServices = ChildProcessSpawner.ChildProcessSpawner | HttpClient.HttpClient; type BackendProcessRunRequirements = BackendProcessLayerServices | Scope.Scope; export type BackendProcessOutputStream = "stdout" | "stderr"; export interface BackendProcessContext { readonly executablePath: string; readonly entryPath: string; readonly cwd: string; readonly httpBaseUrl: URL;} export type DesktopBackendBootstrapDelivery = "fd3" | "stdin"; export interface DesktopBackendStartConfig extends BackendProcessContext { readonly args: ReadonlyArray<string>; readonly env: Record<string, string | undefined>; // When true the spawner merges the desktop process.env on top of `env`; // when false `env` is passed verbatim. WSL mode opts out so a leaking // T3CODE_HOME can't pin the WSL backend to /mnt/c/...\.t3. readonly extendEnv: boolean; readonly bootstrap: DesktopBackendBootstrapValue; readonly bootstrapDelivery: DesktopBackendBootstrapDelivery; readonly httpBaseUrl: URL; readonly captureOutput: boolean; readonly preflightFailure: Option.Option<PreflightFailure>; // Present for a WSL run after the configured/default distro has been // resolved to the concrete distro passed to wsl.exe. readonly runningDistro?: string; // Present only when this run launched from a staged WSL-local runtime. // Once HTTP readiness succeeds, the manager uses it to retain this cache // plus the newest previous cache and prune older versions. readonly wslRuntimeId?: string;} // A preflight failure records whether it is fatal. Transient failures (WSL// cold-starting, wslpath while the VM boots) keep retrying so the backend can// self-heal; fatal ones (no node, wrong version, missing build tools) are// surfaced via onPreflightFailed and stop the restart loop after// MAX_PREFLIGHT_FAILURE_ATTEMPTS.export interface PreflightFailure { readonly reason: string; readonly fatal: boolean; readonly retryLimit?: number;} interface BackendProcessExit { readonly code: Option.Option<number>; readonly reason: string;} const backendProcessContextSchema = { executablePath: Schema.String, entryPath: Schema.String, cwd: Schema.String, httpBaseUrl: Schema.URL,}; export class BackendReadinessTimeoutError extends Schema.TaggedError<BackendReadinessTimeoutError>()( "BackendReadinessTimeoutError", { ...backendProcessContextSchema, readinessUrl: Schema.URL, timeoutMs: Schema.Number, cause: Schema.Defect(), },) { override get message(): string { return `Timed out after ${this.timeoutMs}ms waiting for desktop backend readiness at ${this.readinessUrl.href}.`; }} export class BackendProcessBootstrapEncodeError extends Schema.TaggedError<BackendProcessBootstrapEncodeError>()( "BackendProcessBootstrapEncodeError", { ...backendProcessContextSchema, cause: Schema.Defect(), },) { override get message(): string { return `Failed to encode the desktop backend bootstrap payload for ${this.entryPath}.`; }} export class BackendProcessSpawnError extends Schema.TaggedError<BackendProcessSpawnError>()( "BackendProcessSpawnError", { ...backendProcessContextSchema, cause: Schema.Defect(), },) { override get message(): string { return `Failed to spawn desktop backend entry ${this.entryPath} with ${this.executablePath}.`; }} export class BackendProcessOutputReadError extends Schema.TaggedError<BackendProcessOutputReadError>()( "BackendProcessOutputReadError", { ...backendProcessContextSchema, pid: Schema.Number, streamName: Schema.Literals(["stdout", "stderr"]), cause: Schema.Defect(), },) { override get message(): string { return `Failed to read ${this.streamName} from desktop backend process ${this.pid}.`; }} export class BackendProcessOutputHandlingError extends Schema.TaggedError<BackendProcessOutputHandlingError>()( "BackendProcessOutputHandlingError", { ...backendProcessContextSchema, pid: Schema.Number, streamName: Schema.Literals(["stdout", "stderr"]), chunkByteLength: Schema.Number, cause: Schema.Defect(), },) { override get message(): string { return `Failed to handle ${this.chunkByteLength} bytes from ${this.streamName} of desktop backend process ${this.pid}.`; }} export type BackendProcessOutputError = | BackendProcessOutputReadError | BackendProcessOutputHandlingError; export class BackendProcessExitStatusError extends Schema.TaggedError<BackendProcessExitStatusError>()( "BackendProcessExitStatusError", { ...backendProcessContextSchema, pid: Schema.Number, cause: Schema.Defect(), },) { override get message(): string { return `Failed to read the exit status of desktop backend process ${this.pid}.`; }} export const BackendProcessError = Schema.Union([ BackendProcessBootstrapEncodeError, BackendProcessSpawnError, BackendProcessExitStatusError,]);export type BackendProcessError = typeof BackendProcessError.Type; interface RunBackendProcessOptions extends DesktopBackendStartConfig { readonly desktopTelemetryStream: Stream.Stream<Uint8Array>; readonly onDesktopTelemetryControl?: ( message: DesktopTelemetryControlMessageValue, ) => Effect.Effect<void>; readonly readinessTimeout?: Duration.Duration; readonly outputDrainTimeout?: Duration.Duration; readonly onStarted?: (pid: number) => Effect.Effect<void>; readonly onExitObserved?: () => Effect.Effect<void>; readonly onReady?: () => Effect.Effect<void>; readonly onReadinessFailure?: (error: BackendReadinessTimeoutError) => Effect.Effect<void>; readonly onOutput?: ( streamName: BackendProcessOutputStream, chunk: Uint8Array, ) => Effect.Effect<void, Error>; readonly onOutputFailure?: (error: BackendProcessOutputError) => Effect.Effect<void>;} export interface DesktopBackendSnapshot { readonly desiredRunning: boolean; readonly ready: boolean; readonly activePid: Option.Option<number>; readonly restartAttempt: number; readonly restartScheduled: boolean;} // Opaque identifier for one backend process inside the pool. Today only// PRIMARY_INSTANCE_ID is registered. Follow-up commits add WSL distros// under ids derived from the distro name (e.g. "wsl:ubuntu"). Eventually// these map 1:1 with environment ids on the frontend; keeping them// desktop-local for now avoids leaking the contracts dependency.export type BackendInstanceId = string & Brand.Brand<"BackendInstanceId">;export const BackendInstanceId = Brand.nominal<BackendInstanceId>(); export const PRIMARY_INSTANCE_ID: BackendInstanceId = BackendInstanceId( PRIMARY_LOCAL_ENVIRONMENT_ID,); // One pooled backend instance. Same lifecycle surface as the legacy// `DesktopBackendManagerShape`; the id and label give the pool registry// + UI something to route on.export interface DesktopBackendInstance { readonly id: BackendInstanceId; readonly label: Effect.Effect<string>; readonly start: Effect.Effect<void>; readonly stop: (options?: { readonly timeout?: Duration.Duration }) => Effect.Effect<void>; readonly currentConfig: Effect.Effect<Option.Option<DesktopBackendStartConfig>>; readonly snapshot: Effect.Effect<DesktopBackendSnapshot>; // Polls desiredRunning + the instance's own ready flag until the // backend reports ready, or the timeout elapses. Returns true on // ready, false on timeout. Used by the WSL backend swap to drive its // rollback path. readonly waitForReady: (timeout: Duration.Duration) => Effect.Effect<boolean>;} // Spec describing one backend instance to spawn. The configResolve// effect is awaited each time the instance is (re)started so live// settings changes are picked up on the next start cycle. onReady and// onShutdown let the primary instance trigger UI side effects (window// open, global readiness flag) without coupling the factory to those// concerns; other instances pass them as undefined.export interface BackendInstanceSpec { readonly id: BackendInstanceId; readonly label: Effect.Effect<string>; // configResolve can now fail with PlatformError because the // bootstrap-token closure inside DesktopBackendConfiguration uses // crypto.randomBytes (Effect 4 beta.73 migration). readonly configResolve: Effect.Effect<DesktopBackendStartConfig, PlatformError.PlatformError>; // Receives the *resolved* httpBaseUrl of the run that just became // ready. The window service uses this to decide what URL to load // (the WSL backend reports its distro IP, the Windows backend reports // 127.0.0.1). Splitting this off from configResolve avoids races // between "fired onReady" and "currentConfig already advanced". readonly onReady?: (httpBaseUrl: URL) => Effect.Effect<void>; readonly onShutdown?: () => Effect.Effect<void>; // Fired once when a fatal or bounded preflight failure has exhausted its // retries. Returns true when the callback changed configuration and the // manager should resolve once more; false stops the failed instance. readonly onPreflightFailed?: (failure: PreflightFailure) => Effect.Effect<boolean>;} interface ActiveBackendRun { readonly id: number; readonly scope: Scope.Closeable; readonly fiber: Option.Option<Fiber.Fiber<void, never>>; readonly pid: Option.Option<number>; readonly exitObserved: boolean; readonly stopRequested: boolean;} interface BackendManagerState { readonly desiredRunning: boolean; readonly ready: boolean; readonly config: Option.Option<DesktopBackendStartConfig>; readonly active: Option.Option<ActiveBackendRun>; readonly restartAttempt: number; // Consecutive bounded/fatal preflight failures, reset on a clean or // unbounded-transient preflight. restartAttempt counts all restarts. readonly preflightFailureAttempt: number; readonly restartFiber: Option.Option<Fiber.Fiber<void, never>>; readonly nextRunId: number;} const initialState: BackendManagerState = { desiredRunning: false, ready: false, config: Option.none(), active: Option.none(), restartAttempt: 0, preflightFailureAttempt: 0, restartFiber: Option.none(), nextRunId: 1,}; const activePid = (active: Option.Option<ActiveBackendRun>): Option.Option<number> => Option.flatMap(active, (run) => run.pid); const withActiveRun = (runId: number, f: (run: ActiveBackendRun) => ActiveBackendRun) => (state: BackendManagerState): BackendManagerState => ({ ...state, active: Option.map(state.active, (run) => (run.id === runId ? f(run) : run)), }); const calculateRestartDelay = (attempt: number): Duration.Duration => Duration.min(Duration.times(INITIAL_RESTART_DELAY, 2 ** attempt), MAX_RESTART_DELAY); const closeRun = ( run: ActiveBackendRun, parentScope: Scope.Scope, options?: { readonly timeout?: Duration.Duration },): Effect.Effect<boolean> => { const waitForFiber = Option.match(run.fiber, { onNone: () => Effect.void, onSome: (fiber) => Fiber.await(fiber).pipe(Effect.asVoid), }); const close = Scope.close(run.scope, Exit.void).pipe(Effect.andThen(waitForFiber)); const timeout = options?.timeout; if (!timeout) { return close.pipe(Effect.as(true)); } return Effect.forkIn(close, parentScope).pipe( Effect.flatMap((closeFiber) => Fiber.await(closeFiber).pipe(Effect.timeoutOption(timeout), Effect.map(Option.isSome)), ), );}; export const waitForHttpReady = ( options: BackendProcessContext & { readonly timeout: Duration.Duration },): Effect.Effect<void, BackendReadinessTimeoutError, HttpClient.HttpClient> => { const readinessUrl = new URL(BACKEND_READINESS_PATH, options.httpBaseUrl); return waitForHttpReadyShared({ baseUrl: options.httpBaseUrl.href, path: BACKEND_READINESS_PATH, timeoutMs: Duration.toMillis(options.timeout), intervalMs: Duration.toMillis(DEFAULT_BACKEND_READINESS_INTERVAL), probeTimeoutMs: Duration.toMillis(DEFAULT_BACKEND_READINESS_REQUEST_TIMEOUT), makeError: ({ cause }) => new BackendReadinessTimeoutError({ executablePath: options.executablePath, entryPath: options.entryPath, cwd: options.cwd, httpBaseUrl: options.httpBaseUrl, readinessUrl, timeoutMs: Duration.toMillis(options.timeout), cause, }), });}; function drainBackendOutput( context: BackendProcessContext & { readonly pid: number }, streamName: BackendProcessOutputStream, stream: Stream.Stream<Uint8Array, PlatformError.PlatformError>, onOutput: ( streamName: BackendProcessOutputStream, chunk: Uint8Array, ) => Effect.Effect<void, Error>, onOutputFailure: (error: BackendProcessOutputError) => Effect.Effect<void>,): Effect.Effect<void> { return stream.pipe( Stream.mapError( (cause) => new BackendProcessOutputReadError({ ...context, streamName, cause, }), ), Stream.runForEach((chunk) => onOutput(streamName, chunk).pipe( Effect.mapError( (cause) => new BackendProcessOutputHandlingError({ ...context, streamName, chunkByteLength: chunk.byteLength, cause, }), ), Effect.catchTag("BackendProcessOutputHandlingError", onOutputFailure), ), ), Effect.catchTags({ BackendProcessOutputReadError: onOutputFailure, }), );} const encodeBootstrapJson = Schema.encodeEffect(Schema.fromJsonString(DesktopBackendBootstrap));const decodeDesktopTelemetryControlLine = Schema.decodeUnknownEffect( Schema.fromJsonString(DesktopTelemetryControlMessage),); export const runBackendProcess = Effect.fn("runBackendProcess")(function* ( options: RunBackendProcessOptions,): Effect.fn.Return<BackendProcessExit, BackendProcessError, BackendProcessRunRequirements> { const spawner = yield* ChildProcessSpawner.ChildProcessSpawner; const bootstrapJson = yield* encodeBootstrapJson(options.bootstrap).pipe( Effect.mapError( (cause) => new BackendProcessBootstrapEncodeError({ executablePath: options.executablePath, entryPath: options.entryPath, cwd: options.cwd, httpBaseUrl: options.httpBaseUrl, cause, }), ), ); const onOutput = options.onOutput ?? (() => Effect.void); const bootstrapStream = Stream.encodeText(Stream.make(`${bootstrapJson}\n`)); const additionalFds: Record<`fd${number}`, ChildProcess.AdditionalFdConfig> = {}; if (options.bootstrapDelivery === "fd3") { additionalFds.fd3 = { type: "input", stream: bootstrapStream, }; if (options.bootstrap.desktopTelemetryFd !== undefined) { additionalFds[`fd${options.bootstrap.desktopTelemetryFd}`] = { type: "input", stream: options.desktopTelemetryStream, }; } if (options.bootstrap.desktopTelemetryControlFd !== undefined) { additionalFds[`fd${options.bootstrap.desktopTelemetryControlFd}`] = { type: "output", }; } } const command = ChildProcess.make(options.executablePath, options.args, { cwd: options.cwd, env: options.env, extendEnv: options.extendEnv, // In Electron main, process.execPath points to the Electron binary. // Run the child in Node mode so this backend process does not become a GUI app instance. stdin: options.bootstrapDelivery === "stdin" ? bootstrapStream : "ignore", stdout: options.captureOutput ? "pipe" : "inherit", stderr: options.captureOutput ? "pipe" : "inherit", killSignal: "SIGTERM", forceKillAfter: DEFAULT_BACKEND_TERMINATE_GRACE, // wsl.exe drops additional file descriptors when forwarding to the Linux // side, so the WSL spawn path delivers the bootstrap envelope via stdin // (`--bootstrap-fd 0`) instead. ...(options.bootstrapDelivery === "fd3" ? { additionalFds } : {}), }); const handle = yield* spawner.spawn(command).pipe( Effect.mapError( (cause) => new BackendProcessSpawnError({ executablePath: options.executablePath, entryPath: options.entryPath, cwd: options.cwd, httpBaseUrl: options.httpBaseUrl,Lines 1–500 of 1168. Load more
// Per-instance backend factory. Replaces the legacy singleton // `DesktopBackendManager` Context.Service: each call to // `makeBackendInstance(spec)` constructs an isolated backend lifecycle — // its own state Ref, mutex, restart loop, and active child process. The // returned `DesktopBackendInstance` exposes start/stop/snapshot/wait // methods that operate on that single backend. // // The pool layer (`DesktopBackendPool.ts`) calls this factory once per // backend it wants to run. Today that's the Windows primary; follow-up // commits add a second call for the WSL instance. // // Singleton couplings that the legacy service held inline are now // parameterized via the spec: // - configResolve replaces the legacy `DesktopBackendConfiguration.resolve` // so each instance can resolve its own start config — the primary wires // `configuration.resolvePrimary`, the WSL orchestrator wires a // `configuration.resolveWsl({ port, distro })` closure. // - onReady / onShutdown drive UI side effects (window auto-open, // readiness latch) only for instances that want them — the primary's // spec passes the window's handleBackendReady/handleBackendNotReady, // other pool instances pass nothing. // - log writes go through a per-instance writer that the factory // pulls from `DesktopBackendOutputLogFactory.forInstance(spec.id)`, // so each instance lands in its own rotating file. import * as Brand from "effect/Brand"; import * as Cause from "effect/Cause"; import * as Duration from "effect/Duration"; import * as Effect from "effect/Effect"; import * as Exit from "effect/Exit"; import * as Fiber from "effect/Fiber"; import * as FileSystem from "effect/FileSystem"; import * as Option from "effect/Option"; import * as PlatformError from "effect/PlatformError"; import * as Ref from "effect/Ref"; import * as Schedule from "effect/Schedule"; import * as Schema from "effect/Schema"; import * as Semaphore from "effect/Semaphore"; import * as Scope from "effect/Scope"; import * as Stream from "effect/Stream"; import { HttpClient } from "effect/unstable/http"; import { ChildProcess, ChildProcessSpawner } from "effect/unstable/process"; import { DesktopBackendBootstrap, type DesktopBackendBootstrap as DesktopBackendBootstrapValue, PRIMARY_LOCAL_ENVIRONMENT_ID, DesktopTelemetryControlMessage, type DesktopTelemetryControlMessage as DesktopTelemetryControlMessageValue, } from "@t3tools/contracts"; import { waitForHttpReady as waitForHttpReadyShared } from "@t3tools/shared/httpReadiness"; import * as DesktopObservability from "../app/DesktopObservability.ts"; import * as DesktopTelemetryPublisher from "../telemetry/DesktopTelemetryPublisher.ts"; import * as DesktopWslEnvironment from "../wsl/DesktopWslEnvironment.ts"; const INITIAL_RESTART_DELAY = Duration.millis(500); const MAX_RESTART_DELAY = Duration.seconds(10); // After this many consecutive fatal preflight failures, stop the silent // restart loop and surface the reason via onPreflightFailed. Transient // failures may instead provide their own larger retryLimit when they should // self-heal for a while but must not leave the app connecting forever. const MAX_PREFLIGHT_FAILURE_ATTEMPTS = 5; const DEFAULT_BACKEND_READINESS_TIMEOUT = Duration.minutes(1); const DEFAULT_BACKEND_READINESS_INTERVAL = Duration.millis(100); const DEFAULT_BACKEND_READINESS_REQUEST_TIMEOUT = Duration.seconds(1); const DEFAULT_BACKEND_TERMINATE_GRACE = Duration.seconds(2); const DEFAULT_BACKEND_OUTPUT_DRAIN_TIMEOUT = Duration.seconds(5); const BACKEND_READINESS_PATH = "/.well-known/t3/environment"; const { logWarning: logBackendProcessWarning } = DesktopObservability.makeComponentLogger("desktop-backend-process"); type BackendProcessLayerServices = ChildProcessSpawner.ChildProcessSpawner | HttpClient.HttpClient; type BackendProcessRunRequirements = BackendProcessLayerServices | Scope.Scope; export type BackendProcessOutputStream = "stdout" | "stderr"; export interface BackendProcessContext { readonly executablePath: string; readonly entryPath: string; readonly cwd: string; readonly httpBaseUrl: URL; } export type DesktopBackendBootstrapDelivery = "fd3" | "stdin"; export interface DesktopBackendStartConfig extends BackendProcessContext { readonly args: ReadonlyArray<string>; readonly env: Record<string, string | undefined>; // When true the spawner merges the desktop process.env on top of `env`; // when false `env` is passed verbatim. WSL mode opts out so a leaking // T3CODE_HOME can't pin the WSL backend to /mnt/c/...\.t3. readonly extendEnv: boolean; readonly bootstrap: DesktopBackendBootstrapValue; readonly bootstrapDelivery: DesktopBackendBootstrapDelivery; readonly httpBaseUrl: URL; readonly captureOutput: boolean; readonly preflightFailure: Option.Option<PreflightFailure>; // Present for a WSL run after the configured/default distro has been // resolved to the concrete distro passed to wsl.exe. readonly runningDistro?: string; // Present only when this run launched from a staged WSL-local runtime. // Once HTTP readiness succeeds, the manager uses it to retain this cache // plus the newest previous cache and prune older versions. readonly wslRuntimeId?: string; } // A preflight failure records whether it is fatal. Transient failures (WSL // cold-starting, wslpath while the VM boots) keep retrying so the backend can // self-heal; fatal ones (no node, wrong version, missing build tools) are // surfaced via onPreflightFailed and stop the restart loop after // MAX_PREFLIGHT_FAILURE_ATTEMPTS. export interface PreflightFailure { readonly reason: string; readonly fatal: boolean; readonly retryLimit?: number; } interface BackendProcessExit { readonly code: Option.Option<number>; readonly reason: string; } const backendProcessContextSchema = { executablePath: Schema.String, entryPath: Schema.String, cwd: Schema.String, httpBaseUrl: Schema.URL, }; export class BackendReadinessTimeoutError extends Schema.TaggedError<BackendReadinessTimeoutError>()( "BackendReadinessTimeoutError", { ...backendProcessContextSchema, readinessUrl: Schema.URL, timeoutMs: Schema.Number, cause: Schema.Defect(), }, ) { override get message(): string { return `Timed out after ${this.timeoutMs}ms waiting for desktop backend readiness at ${this.readinessUrl.href}.`; } } export class BackendProcessBootstrapEncodeError extends Schema.TaggedError<BackendProcessBootstrapEncodeError>()( "BackendProcessBootstrapEncodeError", { ...backendProcessContextSchema, cause: Schema.Defect(), }, ) { override get message(): string { return `Failed to encode the desktop backend bootstrap payload for ${this.entryPath}.`; } } export class BackendProcessSpawnError extends Schema.TaggedError<BackendProcessSpawnError>()( "BackendProcessSpawnError", { ...backendProcessContextSchema, cause: Schema.Defect(), }, ) { override get message(): string { return `Failed to spawn desktop backend entry ${this.entryPath} with ${this.executablePath}.`; } } export class BackendProcessOutputReadError extends Schema.TaggedError<BackendProcessOutputReadError>()( "BackendProcessOutputReadError", { ...backendProcessContextSchema, pid: Schema.Number, streamName: Schema.Literals(["stdout", "stderr"]), cause: Schema.Defect(), }, ) { override get message(): string { return `Failed to read ${this.streamName} from desktop backend process ${this.pid}.`; } } export class BackendProcessOutputHandlingError extends Schema.TaggedError<BackendProcessOutputHandlingError>()( "BackendProcessOutputHandlingError", { ...backendProcessContextSchema, pid: Schema.Number, streamName: Schema.Literals(["stdout", "stderr"]), chunkByteLength: Schema.Number, cause: Schema.Defect(), }, ) { override get message(): string { return `Failed to handle ${this.chunkByteLength} bytes from ${this.streamName} of desktop backend process ${this.pid}.`; } } export type BackendProcessOutputError = | BackendProcessOutputReadError | BackendProcessOutputHandlingError; export class BackendProcessExitStatusError extends Schema.TaggedError<BackendProcessExitStatusError>()( "BackendProcessExitStatusError", { ...backendProcessContextSchema, pid: Schema.Number, cause: Schema.Defect(), }, ) { override get message(): string { return `Failed to read the exit status of desktop backend process ${this.pid}.`; } } export const BackendProcessError = Schema.Union([ BackendProcessBootstrapEncodeError, BackendProcessSpawnError, BackendProcessExitStatusError, ]); export type BackendProcessError = typeof BackendProcessError.Type; interface RunBackendProcessOptions extends DesktopBackendStartConfig { readonly desktopTelemetryStream: Stream.Stream<Uint8Array>; readonly onDesktopTelemetryControl?: ( message: DesktopTelemetryControlMessageValue, ) => Effect.Effect<void>; readonly readinessTimeout?: Duration.Duration; readonly outputDrainTimeout?: Duration.Duration; readonly onStarted?: (pid: number) => Effect.Effect<void>; readonly onExitObserved?: () => Effect.Effect<void>; readonly onReady?: () => Effect.Effect<void>; readonly onReadinessFailure?: (error: BackendReadinessTimeoutError) => Effect.Effect<void>; readonly onOutput?: ( streamName: BackendProcessOutputStream, chunk: Uint8Array, ) => Effect.Effect<void, Error>; readonly onOutputFailure?: (error: BackendProcessOutputError) => Effect.Effect<void>; } export interface DesktopBackendSnapshot { readonly desiredRunning: boolean; readonly ready: boolean; readonly activePid: Option.Option<number>; readonly restartAttempt: number; readonly restartScheduled: boolean; } // Opaque identifier for one backend process inside the pool. Today only // PRIMARY_INSTANCE_ID is registered. Follow-up commits add WSL distros // under ids derived from the distro name (e.g. "wsl:ubuntu"). Eventually // these map 1:1 with environment ids on the frontend; keeping them // desktop-local for now avoids leaking the contracts dependency. export type BackendInstanceId = string & Brand.Brand<"BackendInstanceId">; export const BackendInstanceId = Brand.nominal<BackendInstanceId>(); export const PRIMARY_INSTANCE_ID: BackendInstanceId = BackendInstanceId( PRIMARY_LOCAL_ENVIRONMENT_ID, ); // One pooled backend instance. Same lifecycle surface as the legacy // `DesktopBackendManagerShape`; the id and label give the pool registry // + UI something to route on. export interface DesktopBackendInstance { readonly id: BackendInstanceId; readonly label: Effect.Effect<string>; readonly start: Effect.Effect<void>; readonly stop: (options?: { readonly timeout?: Duration.Duration }) => Effect.Effect<void>; readonly currentConfig: Effect.Effect<Option.Option<DesktopBackendStartConfig>>; readonly snapshot: Effect.Effect<DesktopBackendSnapshot>; // Polls desiredRunning + the instance's own ready flag until the // backend reports ready, or the timeout elapses. Returns true on // ready, false on timeout. Used by the WSL backend swap to drive its // rollback path. readonly waitForReady: (timeout: Duration.Duration) => Effect.Effect<boolean>; } // Spec describing one backend instance to spawn. The configResolve // effect is awaited each time the instance is (re)started so live // settings changes are picked up on the next start cycle. onReady and // onShutdown let the primary instance trigger UI side effects (window // open, global readiness flag) without coupling the factory to those // concerns; other instances pass them as undefined. export interface BackendInstanceSpec { readonly id: BackendInstanceId; readonly label: Effect.Effect<string>; // configResolve can now fail with PlatformError because the // bootstrap-token closure inside DesktopBackendConfiguration uses // crypto.randomBytes (Effect 4 beta.73 migration). readonly configResolve: Effect.Effect<DesktopBackendStartConfig, PlatformError.PlatformError>; // Receives the *resolved* httpBaseUrl of the run that just became // ready. The window service uses this to decide what URL to load // (the WSL backend reports its distro IP, the Windows backend reports // 127.0.0.1). Splitting this off from configResolve avoids races // between "fired onReady" and "currentConfig already advanced". readonly onReady?: (httpBaseUrl: URL) => Effect.Effect<void>; readonly onShutdown?: () => Effect.Effect<void>; // Fired once when a fatal or bounded preflight failure has exhausted its // retries. Returns true when the callback changed configuration and the // manager should resolve once more; false stops the failed instance. readonly onPreflightFailed?: (failure: PreflightFailure) => Effect.Effect<boolean>; } interface ActiveBackendRun { readonly id: number; readonly scope: Scope.Closeable; readonly fiber: Option.Option<Fiber.Fiber<void, never>>; readonly pid: Option.Option<number>; readonly exitObserved: boolean; readonly stopRequested: boolean; } interface BackendManagerState { readonly desiredRunning: boolean; readonly ready: boolean; readonly config: Option.Option<DesktopBackendStartConfig>; readonly active: Option.Option<ActiveBackendRun>; readonly restartAttempt: number; // Consecutive bounded/fatal preflight failures, reset on a clean or // unbounded-transient preflight. restartAttempt counts all restarts. readonly preflightFailureAttempt: number; readonly restartFiber: Option.Option<Fiber.Fiber<void, never>>; readonly nextRunId: number; } const initialState: BackendManagerState = { desiredRunning: false, ready: false, config: Option.none(), active: Option.none(), restartAttempt: 0, preflightFailureAttempt: 0, restartFiber: Option.none(), nextRunId: 1, }; const activePid = (active: Option.Option<ActiveBackendRun>): Option.Option<number> => Option.flatMap(active, (run) => run.pid); const withActiveRun = (runId: number, f: (run: ActiveBackendRun) => ActiveBackendRun) => (state: BackendManagerState): BackendManagerState => ({ ...state, active: Option.map(state.active, (run) => (run.id === runId ? f(run) : run)), }); const calculateRestartDelay = (attempt: number): Duration.Duration => Duration.min(Duration.times(INITIAL_RESTART_DELAY, 2 ** attempt), MAX_RESTART_DELAY); const closeRun = ( run: ActiveBackendRun, parentScope: Scope.Scope, options?: { readonly timeout?: Duration.Duration }, ): Effect.Effect<boolean> => { const waitForFiber = Option.match(run.fiber, { onNone: () => Effect.void, onSome: (fiber) => Fiber.await(fiber).pipe(Effect.asVoid), }); const close = Scope.close(run.scope, Exit.void).pipe(Effect.andThen(waitForFiber)); const timeout = options?.timeout; if (!timeout) { return close.pipe(Effect.as(true)); } return Effect.forkIn(close, parentScope).pipe( Effect.flatMap((closeFiber) => Fiber.await(closeFiber).pipe(Effect.timeoutOption(timeout), Effect.map(Option.isSome)), ), ); }; export const waitForHttpReady = ( options: BackendProcessContext & { readonly timeout: Duration.Duration }, ): Effect.Effect<void, BackendReadinessTimeoutError, HttpClient.HttpClient> => { const readinessUrl = new URL(BACKEND_READINESS_PATH, options.httpBaseUrl); return waitForHttpReadyShared({ baseUrl: options.httpBaseUrl.href, path: BACKEND_READINESS_PATH, timeoutMs: Duration.toMillis(options.timeout), intervalMs: Duration.toMillis(DEFAULT_BACKEND_READINESS_INTERVAL), probeTimeoutMs: Duration.toMillis(DEFAULT_BACKEND_READINESS_REQUEST_TIMEOUT), makeError: ({ cause }) => new BackendReadinessTimeoutError({ executablePath: options.executablePath, entryPath: options.entryPath, cwd: options.cwd, httpBaseUrl: options.httpBaseUrl, readinessUrl, timeoutMs: Duration.toMillis(options.timeout), cause, }), }); }; function drainBackendOutput( context: BackendProcessContext & { readonly pid: number }, streamName: BackendProcessOutputStream, stream: Stream.Stream<Uint8Array, PlatformError.PlatformError>, onOutput: ( streamName: BackendProcessOutputStream, chunk: Uint8Array, ) => Effect.Effect<void, Error>, onOutputFailure: (error: BackendProcessOutputError) => Effect.Effect<void>, ): Effect.Effect<void> { return stream.pipe( Stream.mapError( (cause) => new BackendProcessOutputReadError({ ...context, streamName, cause, }), ), Stream.runForEach((chunk) => onOutput(streamName, chunk).pipe( Effect.mapError( (cause) => new BackendProcessOutputHandlingError({ ...context, streamName, chunkByteLength: chunk.byteLength, cause, }), ), Effect.catchTag("BackendProcessOutputHandlingError", onOutputFailure), ), ), Effect.catchTags({ BackendProcessOutputReadError: onOutputFailure, }), ); } const encodeBootstrapJson = Schema.encodeEffect(Schema.fromJsonString(DesktopBackendBootstrap)); const decodeDesktopTelemetryControlLine = Schema.decodeUnknownEffect( Schema.fromJsonString(DesktopTelemetryControlMessage), ); export const runBackendProcess = Effect.fn("runBackendProcess")(function* ( options: RunBackendProcessOptions, ): Effect.fn.Return<BackendProcessExit, BackendProcessError, BackendProcessRunRequirements> { const spawner = yield* ChildProcessSpawner.ChildProcessSpawner; const bootstrapJson = yield* encodeBootstrapJson(options.bootstrap).pipe( Effect.mapError( (cause) => new BackendProcessBootstrapEncodeError({ executablePath: options.executablePath, entryPath: options.entryPath, cwd: options.cwd, httpBaseUrl: options.httpBaseUrl, cause, }), ), ); const onOutput = options.onOutput ?? (() => Effect.void); const bootstrapStream = Stream.encodeText(Stream.make(`${bootstrapJson}\n`)); const additionalFds: Record<`fd${number}`, ChildProcess.AdditionalFdConfig> = {}; if (options.bootstrapDelivery === "fd3") { additionalFds.fd3 = { type: "input", stream: bootstrapStream, }; if (options.bootstrap.desktopTelemetryFd !== undefined) { additionalFds[`fd${options.bootstrap.desktopTelemetryFd}`] = { type: "input", stream: options.desktopTelemetryStream, }; } if (options.bootstrap.desktopTelemetryControlFd !== undefined) { additionalFds[`fd${options.bootstrap.desktopTelemetryControlFd}`] = { type: "output", }; } } const command = ChildProcess.make(options.executablePath, options.args, { cwd: options.cwd, env: options.env, extendEnv: options.extendEnv, // In Electron main, process.execPath points to the Electron binary. // Run the child in Node mode so this backend process does not become a GUI app instance. stdin: options.bootstrapDelivery === "stdin" ? bootstrapStream : "ignore", stdout: options.captureOutput ? "pipe" : "inherit", stderr: options.captureOutput ? "pipe" : "inherit", killSignal: "SIGTERM", forceKillAfter: DEFAULT_BACKEND_TERMINATE_GRACE, // wsl.exe drops additional file descriptors when forwarding to the Linux // side, so the WSL spawn path delivers the bootstrap envelope via stdin // (`--bootstrap-fd 0`) instead. ...(options.bootstrapDelivery === "fd3" ? { additionalFds } : {}), }); const handle = yield* spawner.spawn(command).pipe( Effect.mapError( (cause) => new BackendProcessSpawnError({ executablePath: options.executablePath, entryPath: options.entryPath, cwd: options.cwd, httpBaseUrl: options.httpBaseUrl,