Skip to content

Open-source Grok Bot alternative for named AI teammates. Local-first desktop, web, and mobile clients with per-bot tools, instructions, and memory. Independent fork of T3 Code.

[codex] structure desktop backend process errors (#3254)

Julius Marminge6ff6c13fc8bf
diff --git a/apps/desktop/src/backend/DesktopBackendManager.test.ts b/apps/desktop/src/backend/DesktopBackendManager.test.ts
index 4a88be883..0c083889f 100644
--- a/apps/desktop/src/backend/DesktopBackendManager.test.ts
+++ b/apps/desktop/src/backend/DesktopBackendManager.test.ts
@@ -3,12 +3,15 @@ import {
type DesktopBackendBootstrap as DesktopBackendBootstrapValue,
} from "@t3tools/contracts";
import { assert, describe, it } from "@effect/vitest";
+import * as Cause from "effect/Cause";
import * as Deferred from "effect/Deferred";
import * as Duration from "effect/Duration";
import * as Effect from "effect/Effect";
import * as FileSystem from "effect/FileSystem";
+import * as Fiber from "effect/Fiber";
import * as Layer from "effect/Layer";
import * as Option from "effect/Option";
+import * as PlatformError from "effect/PlatformError";
import * as Queue from "effect/Queue";
import * as Ref from "effect/Ref";
import * as Schema from "effect/Schema";
@@ -28,6 +31,7 @@ import * as DesktopWindow from "../window/DesktopWindow.ts";
const decodeDesktopBackendBootstrap = Schema.decodeEffect(
Schema.fromJsonString(DesktopBackendBootstrap),
);
+const isBackendProcessError = Schema.is(DesktopBackendManager.BackendProcessError);
const baseConfig: DesktopBackendManager.DesktopBackendStartConfig = {
executablePath: "/electron",
@@ -57,7 +61,7 @@ const configWithObservability: DesktopBackendBootstrapValue = {
function makeProcess(options?: {
readonly stdout?: Stream.Stream<Uint8Array>;
readonly stderr?: Stream.Stream<Uint8Array>;
- readonly exitCode?: Effect.Effect<ChildProcessSpawner.ExitCode>;
+ readonly exitCode?: Effect.Effect<ChildProcessSpawner.ExitCode, PlatformError.PlatformError>;
readonly kill?: ChildProcessSpawner.ChildProcessHandle["kill"];
}): ChildProcessSpawner.ChildProcessHandle {
return ChildProcessSpawner.makeHandle({
@@ -145,6 +149,23 @@ function makeManagerLayer(input: {
}
describe("DesktopBackendManager", () => {
+ it("preserves the complete restart cause and schedule context", () => {
+ const cause = Cause.combine(
+ Cause.fail(new Error("start failed")),
+ Cause.die(new Error("restart defect")),
+ );
+ const error = new DesktopBackendManager.DesktopBackendRestartError({
+ reason: "backend exited with code 1",
+ delayMs: 500,
+ cause,
+ });
+
+ assert.strictEqual(error.cause, cause);
+ assert.equal(error.reason, "backend exited with code 1");
+ assert.equal(error.delayMs, 500);
+ assert.equal(error.message, "Desktop backend restart failed after a scheduled 500ms delay.");
+ });
+
it.effect("spawns the backend with fd3 bootstrap JSON and reports HTTP readiness", () =>
Effect.gen(function* () {
let spawnedCommand: ChildProcess.Command | undefined;
@@ -218,6 +239,156 @@ describe("DesktopBackendManager", () => {
}),
);
+ it.effect("preserves the readiness timeout cause and process context", () =>
+ Effect.gen(function* () {
+ const requested = yield* Deferred.make<HttpClientRequest.HttpClientRequest>();
+ const layer = Layer.merge(
+ TestClock.layer(),
+ httpClientLayer((request) =>
+ Deferred.succeed(requested, request).pipe(Effect.andThen(Effect.never)),
+ ),
+ );
+
+ yield* Effect.gen(function* () {
+ const readiness = yield* DesktopBackendManager.waitForHttpReady({
+ executablePath: baseConfig.executablePath,
+ entryPath: baseConfig.entryPath,
+ cwd: baseConfig.cwd,
+ httpBaseUrl: baseConfig.httpBaseUrl,
+ timeout: Duration.millis(50),
+ }).pipe(Effect.flip, Effect.forkChild);
+
+ const request = yield* Deferred.await(requested);
+ assert.equal(request.url, "http://127.0.0.1:3773/.well-known/t3/environment");
+
+ yield* TestClock.adjust(Duration.millis(50));
+ const error = yield* Fiber.join(readiness);
+
+ assert.instanceOf(error, DesktopBackendManager.BackendReadinessTimeoutError);
+ assert.equal(error.executablePath, "/electron");
+ assert.equal(error.entryPath, "/server/bin.mjs");
+ assert.equal(error.cwd, "/server");
+ assert.equal(error.httpBaseUrl.href, "http://127.0.0.1:3773/");
+ assert.equal(error.readinessUrl.href, "http://127.0.0.1:3773/.well-known/t3/environment");
+ assert.equal(error.timeoutMs, 50);
+ assert.isTrue(Cause.isTimeoutError(error.cause));
+ assert.equal(
+ error.message,
+ "Timed out after 50ms waiting for desktop backend readiness at http://127.0.0.1:3773/.well-known/t3/environment.",
+ );
+ }).pipe(Effect.provide(layer));
+ }),
+ );
+
+ it.effect("reports bootstrap encoding failures with stable process context", () =>
+ Effect.gen(function* () {
+ const spawnerLayer = Layer.succeed(
+ ChildProcessSpawner.ChildProcessSpawner,
+ ChildProcessSpawner.make(() => Effect.die("unexpected backend spawn")),
+ );
+ const error = yield* DesktopBackendManager.runBackendProcess({
+ ...baseConfig,
+ bootstrap: {
+ ...baseConfig.bootstrap,
+ port: 0,
+ },
+ }).pipe(
+ Effect.flip,
+ Effect.scoped,
+ Effect.provide(Layer.merge(spawnerLayer, healthyHttpClientLayer)),
+ );
+
+ if (error._tag !== "BackendProcessBootstrapEncodeError") {
+ return assert.fail(`Expected bootstrap encode error, received ${error._tag}`);
+ }
+ assert.equal(error.executablePath, "/electron");
+ assert.equal(error.entryPath, "/server/bin.mjs");
+ assert.equal(error.cwd, "/server");
+ assert.equal(error.httpBaseUrl.href, "http://127.0.0.1:3773/");
+ assert.isDefined(error.cause);
+ assert.equal(
+ error.message,
+ "Failed to encode the desktop backend bootstrap payload for /server/bin.mjs.",
+ );
+ assert.isTrue(isBackendProcessError(error));
+ }),
+ );
+
+ it.effect("preserves spawn failures without deriving their message from the cause", () =>
+ Effect.gen(function* () {
+ const spawnCause = PlatformError.systemError({
+ _tag: "PermissionDenied",
+ module: "ChildProcessSpawner",
+ method: "spawn",
+ pathOrDescriptor: baseConfig.executablePath,
+ description: "low-level detail that must not become the public message",
+ });
+ const spawnerLayer = Layer.succeed(
+ ChildProcessSpawner.ChildProcessSpawner,
+ ChildProcessSpawner.make(() => Effect.fail(spawnCause)),
+ );
+ const error = yield* DesktopBackendManager.runBackendProcess(baseConfig).pipe(
+ Effect.flip,
+ Effect.scoped,
+ Effect.provide(Layer.merge(spawnerLayer, healthyHttpClientLayer)),
+ );
+
+ if (error._tag !== "BackendProcessSpawnError") {
+ return assert.fail(`Expected backend spawn error, received ${error._tag}`);
+ }
+ assert.equal(error.executablePath, "/electron");
+ assert.equal(error.entryPath, "/server/bin.mjs");
+ assert.equal(error.cwd, "/server");
+ assert.equal(error.httpBaseUrl.href, "http://127.0.0.1:3773/");
+ assert.strictEqual(error.cause, spawnCause);
+ assert.equal(
+ error.message,
+ "Failed to spawn desktop backend entry /server/bin.mjs with /electron.",
+ );
+ assert.notInclude(error.message, spawnCause.message);
+ assert.isTrue(isBackendProcessError(error));
+ }),
+ );
+
+ it.effect("preserves exit-status failures without copying their detail into the message", () =>
+ Effect.gen(function* () {
+ const exitCause = PlatformError.systemError({
+ _tag: "PermissionDenied",
+ module: "ChildProcess",
+ method: "exitCode",
+ description: "exit-status-secret-sentinel",
+ });
+ const spawnerLayer = Layer.succeed(
+ ChildProcessSpawner.ChildProcessSpawner,
+ ChildProcessSpawner.make(() =>
+ Effect.succeed(
+ makeProcess({
+ exitCode: Effect.fail(exitCause),
+ }),
+ ),
+ ),
+ );
+ const error = yield* DesktopBackendManager.runBackendProcess(baseConfig).pipe(
+ Effect.flip,
+ Effect.scoped,
+ Effect.provide(Layer.merge(spawnerLayer, healthyHttpClientLayer)),
+ );
+
+ if (error._tag !== "BackendProcessExitStatusError") {
+ return assert.fail(`Expected backend exit-status error, received ${error._tag}`);
+ }
+ assert.equal(error.pid, 123);
+ assert.equal(error.executablePath, "/electron");
+ assert.equal(error.entryPath, "/server/bin.mjs");
+ assert.equal(error.cwd, "/server");
+ assert.equal(error.httpBaseUrl.href, "http://127.0.0.1:3773/");
+ assert.strictEqual(error.cause, exitCause);
+ assert.equal(error.message, "Failed to read the exit status of desktop backend process 123.");
+ assert.notInclude(error.message, "exit-status-secret-sentinel");
+ assert.isTrue(isBackendProcessError(error));
+ }),
+ );
+
it.effect("retries HTTP readiness before reporting the backend ready", () =>
Effect.gen(function* () {
const requestUrls: Array<string> = [];
diff --git a/apps/desktop/src/backend/DesktopBackendManager.ts b/apps/desktop/src/backend/DesktopBackendManager.ts
index bc47cab37..8a40c9d21 100644
--- a/apps/desktop/src/backend/DesktopBackendManager.ts
+++ b/apps/desktop/src/backend/DesktopBackendManager.ts
@@ -9,7 +9,6 @@ import * as Layer from "effect/Layer";
import * as Option from "effect/Option";
import * as PlatformError from "effect/PlatformError";
import * as Ref from "effect/Ref";
-import * as Result from "effect/Result";
import * as Schedule from "effect/Schedule";
import * as Schema from "effect/Schema";
import * as Semaphore from "effect/Semaphore";
@@ -43,64 +42,107 @@ type BackendProcessRunRequirements = BackendProcessLayerServices | Scope.Scope;
export type BackendProcessOutputStream = "stdout" | "stderr";
-export interface DesktopBackendStartConfig {
+export interface BackendProcessContext {
readonly executablePath: string;
readonly entryPath: string;
readonly cwd: string;
+ readonly httpBaseUrl: URL;
+}
+
+export interface DesktopBackendStartConfig extends BackendProcessContext {
readonly env: Record<string, string | undefined>;
readonly bootstrap: DesktopBackendBootstrapValue;
- readonly httpBaseUrl: URL;
readonly captureOutput: boolean;
}
interface BackendProcessExit {
readonly code: Option.Option<number>;
readonly reason: string;
- readonly result: Result.Result<ChildProcessSpawner.ExitCode, PlatformError.PlatformError>;
}
-export class BackendTimeoutError extends Schema.TaggedErrorClass<BackendTimeoutError>()(
- "BackendTimeoutError",
+const backendProcessContextSchema = {
+ executablePath: Schema.String,
+ entryPath: Schema.String,
+ cwd: Schema.String,
+ httpBaseUrl: Schema.URL,
+};
+
+export class BackendReadinessTimeoutError extends Schema.TaggedErrorClass<BackendReadinessTimeoutError>()(
+ "BackendReadinessTimeoutError",
{
- url: Schema.URL,
+ ...backendProcessContextSchema,
+ readinessUrl: Schema.URL,
+ timeoutMs: Schema.Number,
+ cause: Schema.Defect(),
},
) {
override get message(): string {
- return `Timed out waiting for backend readiness at ${this.url.href}.`;
+ return `Timed out after ${this.timeoutMs}ms waiting for desktop backend readiness at ${this.readinessUrl.href}.`;
}
}
-class BackendProcessBootstrapEncodeError extends Schema.TaggedErrorClass<BackendProcessBootstrapEncodeError>()(
+export class BackendProcessBootstrapEncodeError extends Schema.TaggedErrorClass<BackendProcessBootstrapEncodeError>()(
"BackendProcessBootstrapEncodeError",
{
- detail: Schema.String,
+ ...backendProcessContextSchema,
cause: Schema.Defect(),
},
) {
override get message(): string {
- return `Failed to encode desktop backend bootstrap payload: ${this.detail}`;
+ return `Failed to encode the desktop backend bootstrap payload for ${this.entryPath}.`;
}
}
-class BackendProcessSpawnError extends Schema.TaggedErrorClass<BackendProcessSpawnError>()(
+export class BackendProcessSpawnError extends Schema.TaggedErrorClass<BackendProcessSpawnError>()(
"BackendProcessSpawnError",
{
- detail: Schema.String,
+ ...backendProcessContextSchema,
+ cause: Schema.Defect(),
+ },
+) {
+ override get message(): string {
+ return `Failed to spawn desktop backend entry ${this.entryPath} with ${this.executablePath}.`;
+ }
+}
+
+export class BackendProcessExitStatusError extends Schema.TaggedErrorClass<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 class DesktopBackendRestartError extends Schema.TaggedErrorClass<DesktopBackendRestartError>()(
+ "DesktopBackendRestartError",
+ {
+ reason: Schema.String,
+ delayMs: Schema.Number,
cause: Schema.Defect(),
},
) {
override get message(): string {
- return `Failed to spawn desktop backend process: ${this.detail}`;
+ return `Desktop backend restart failed after a scheduled ${this.delayMs}ms delay.`;
}
}
-type BackendProcessError = BackendProcessBootstrapEncodeError | BackendProcessSpawnError;
+export const BackendProcessError = Schema.Union([
+ BackendProcessBootstrapEncodeError,
+ BackendProcessSpawnError,
+ BackendProcessExitStatusError,
+]);
+export type BackendProcessError = typeof BackendProcessError.Type;
interface RunBackendProcessOptions extends DesktopBackendStartConfig {
readonly readinessTimeout?: Duration.Duration;
readonly onStarted?: (pid: number) => Effect.Effect<void>;
readonly onReady?: () => Effect.Effect<void>;
- readonly onReadinessFailure?: (error: BackendTimeoutError) => Effect.Effect<void>;
+ readonly onReadinessFailure?: (error: BackendReadinessTimeoutError) => Effect.Effect<void>;
readonly onOutput?: (
streamName: BackendProcessOutputStream,
chunk: Uint8Array,
@@ -183,11 +225,10 @@ const closeRun = (
).pipe(Effect.ignore);
};
-const waitForHttpReady = Effect.fn("desktop.backendManager.waitForHttpReady")(function* (
- baseUrl: URL,
- timeout: Duration.Duration,
-): Effect.fn.Return<void, BackendTimeoutError, HttpClient.HttpClient> {
- const readinessUrl = new URL(BACKEND_READINESS_PATH, baseUrl);
+export const waitForHttpReady = Effect.fn("desktop.backendManager.waitForHttpReady")(function* (
+ options: BackendProcessContext & { readonly timeout: Duration.Duration },
+): Effect.fn.Return<void, BackendReadinessTimeoutError, HttpClient.HttpClient> {
+ const readinessUrl = new URL(BACKEND_READINESS_PATH, options.httpBaseUrl);
const client = (yield* HttpClient.HttpClient).pipe(
HttpClient.filterStatusOk,
HttpClient.transformResponse(Effect.timeout(DEFAULT_BACKEND_READINESS_REQUEST_TIMEOUT)),
@@ -196,29 +237,22 @@ const waitForHttpReady = Effect.fn("desktop.backendManager.waitForHttpReady")(fu
yield* client.get(readinessUrl).pipe(
Effect.asVoid,
- Effect.timeout(timeout),
- Effect.mapError(() => new BackendTimeoutError({ url: readinessUrl })),
+ Effect.timeout(options.timeout),
+ Effect.mapError(
+ (cause) =>
+ new BackendReadinessTimeoutError({
+ executablePath: options.executablePath,
+ entryPath: options.entryPath,
+ cwd: options.cwd,
+ httpBaseUrl: options.httpBaseUrl,
+ readinessUrl,
+ timeoutMs: Duration.toMillis(options.timeout),
+ cause,
+ }),
+ ),
);
});
-function describeProcessExit(
- result: Result.Result<ChildProcessSpawner.ExitCode, PlatformError.PlatformError>,
-): BackendProcessExit {
- if (Result.isSuccess(result)) {
- return {
- code: Option.some(result.success),
- reason: `code=${result.success}`,
- result,
- };
- }
-
- return {
- code: Option.none(),
- reason: result.failure.message,
- result,
- };
-}
-
function drainBackendOutput(
streamName: BackendProcessOutputStream,
stream: Stream.Stream<Uint8Array, PlatformError.PlatformError>,
@@ -232,7 +266,7 @@ function drainBackendOutput(
const encodeBootstrapJson = Schema.encodeEffect(Schema.fromJsonString(DesktopBackendBootstrap));
-const runBackendProcess = Effect.fn("runBackendProcess")(function* (
+export const runBackendProcess = Effect.fn("runBackendProcess")(function* (
options: RunBackendProcessOptions,
): Effect.fn.Return<BackendProcessExit, BackendProcessError, BackendProcessRunRequirements> {
const spawner = yield* ChildProcessSpawner.ChildProcessSpawner;
@@ -240,7 +274,10 @@ const runBackendProcess = Effect.fn("runBackendProcess")(function* (
Effect.mapError(
(cause) =>
new BackendProcessBootstrapEncodeError({
- detail: cause.message,
+ executablePath: options.executablePath,
+ entryPath: options.entryPath,
+ cwd: options.cwd,
+ httpBaseUrl: options.httpBaseUrl,
cause,
}),
),
@@ -273,7 +310,10 @@ const runBackendProcess = Effect.fn("runBackendProcess")(function* (
Effect.mapError(
(cause) =>
new BackendProcessSpawnError({
- detail: cause.message,
+ executablePath: options.executablePath,
+ entryPath: options.entryPath,
+ cwd: options.cwd,
+ httpBaseUrl: options.httpBaseUrl,
cause,
}),
),
@@ -284,16 +324,37 @@ const runBackendProcess = Effect.fn("runBackendProcess")(function* (
yield* drainBackendOutput("stdout", handle.stdout, onOutput).pipe(Effect.forkScoped);
yield* drainBackendOutput("stderr", handle.stderr, onOutput).pipe(Effect.forkScoped);
}
- yield* waitForHttpReady(
- options.httpBaseUrl,
- options.readinessTimeout ?? DEFAULT_BACKEND_READINESS_TIMEOUT,
- ).pipe(
+ yield* waitForHttpReady({
+ executablePath: options.executablePath,
+ entryPath: options.entryPath,
+ cwd: options.cwd,
+ httpBaseUrl: options.httpBaseUrl,
+ timeout: options.readinessTimeout ?? DEFAULT_BACKEND_READINESS_TIMEOUT,
+ }).pipe(
Effect.tap(() => options.onReady?.() ?? Effect.void),
- Effect.catch((error) => options.onReadinessFailure?.(error) ?? Effect.void),
+ Effect.catchTags({
+ BackendReadinessTimeoutError: (error) => options.onReadinessFailure?.(error) ?? Effect.void,
+ }),
Effect.forkScoped,
);
- return describeProcessExit(yield* Effect.result(handle.exitCode));
+ const exitCode = yield* handle.exitCode.pipe(
+ Effect.mapError(
+ (cause) =>
+ new BackendProcessExitStatusError({
+ executablePath: options.executablePath,
+ entryPath: options.entryPath,
+ cwd: options.cwd,
+ httpBaseUrl: options.httpBaseUrl,
+ pid: Number(handle.pid),
+ cause,
+ }),
+ ),
+ );
+ return {
+ code: Option.some(exitCode),
+ reason: `code=${exitCode}`,
+ } satisfies BackendProcessExit;
});
export const make = Effect.gen(function* () {
@@ -351,7 +412,7 @@ export const make = Effect.gen(function* () {
const config = yield* configuration.resolve.pipe(
Effect.tapError((error) =>
logBackendManagerError("failed to generate desktop backend configuration", {
- cause: error.message,
+ cause: error,
}),
),
Effect.option,
@@ -489,14 +550,14 @@ export const make = Effect.gen(function* () {
yield* desktopWindow.handleBackendReady.pipe(
Effect.catch((error) =>
logBackendManagerError("failed to open main window after backend readiness", {
- message: error.message,
+ cause: error,
}),
),
);
}),
onReadinessFailure: (error) =>
logBackendManagerWarning("backend readiness check failed during bootstrap", {
- error: error.message,
+ error,
}),
onOutput: (streamName, chunk) => backendOutputLog.writeOutputChunk(streamName, chunk),
}).pipe(
@@ -504,7 +565,10 @@ export const make = Effect.gen(function* () {
Effect.provideService(HttpClient.HttpClient, httpClient),
Scope.provide(runScope),
Effect.matchEffect({
- onFailure: (error) => finalizeRun(error.message),
+ onFailure: (error) =>
+ logBackendManagerError(error.message, { error }).pipe(
+ Effect.andThen(finalizeRun(error.message)),
+ ),
onSuccess: (exit) => finalizeRun(exit.reason),
}),
Effect.ensuring(Scope.close(runScope, Exit.void).pipe(Effect.ignore)),
@@ -559,11 +623,17 @@ export const make = Effect.gen(function* () {
}),
),
Effect.flatMap((shouldRestart) => (shouldRestart ? start : Effect.void)),
- Effect.catchCause((cause) =>
- logBackendManagerError("desktop backend restart fiber failed", {
- cause: Cause.pretty(cause),
- }),
- ),
+ Effect.catchCause((cause) => {
+ if (Cause.hasInterruptsOnly(cause)) {
+ return Effect.void;
+ }
+ const error = new DesktopBackendRestartError({
+ reason,
+ delayMs: Duration.toMillis(delay),
+ cause,
+ });
+ return logBackendManagerError(error.message, { error });
+ }),
),
parentScope,
);