Skip to content

Commit b5c8ea4

Browse files
Refactor desktop backend startup into Effect process
- Spawn the backend through a shared Effect runner with fd3 bootstrap - Replace ad hoc readiness/listening plumbing with HTTP readiness hooks - Add contract support for desktop bootstrap payloads
1 parent d8f0d72 commit b5c8ea4

13 files changed

Lines changed: 511 additions & 663 deletions
Lines changed: 166 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,166 @@
1+
import { assert, describe, it } from "@effect/vitest";
2+
import { Duration, Effect, Layer, Schema, Sink, Stream } from "effect";
3+
import { HttpClient, HttpClientRequest, HttpClientResponse } from "effect/unstable/http";
4+
import { ChildProcess, ChildProcessSpawner } from "effect/unstable/process";
5+
6+
import {
7+
DesktopBackendBootstrap,
8+
type DesktopBackendBootstrap as DesktopBackendBootstrapValue,
9+
} from "@t3tools/contracts";
10+
import { runBackendProcess } from "./backendProcess.ts";
11+
12+
const bootstrap: DesktopBackendBootstrapValue = {
13+
mode: "desktop",
14+
noBrowser: true,
15+
port: 3773,
16+
t3Home: "/tmp/t3",
17+
host: "127.0.0.1",
18+
desktopBootstrapToken: "token",
19+
tailscaleServeEnabled: true,
20+
tailscaleServePort: 443,
21+
otlpTracesUrl: "http://127.0.0.1:4318/v1/traces",
22+
};
23+
24+
function makeProcess(options?: {
25+
readonly stdout?: Stream.Stream<Uint8Array>;
26+
readonly stderr?: Stream.Stream<Uint8Array>;
27+
readonly exitCode?: Effect.Effect<ChildProcessSpawner.ExitCode>;
28+
readonly kill?: ChildProcessSpawner.ChildProcessHandle["kill"];
29+
}): ChildProcessSpawner.ChildProcessHandle {
30+
return ChildProcessSpawner.makeHandle({
31+
pid: ChildProcessSpawner.ProcessId(123),
32+
stdout: options?.stdout ?? Stream.empty,
33+
stderr: options?.stderr ?? Stream.empty,
34+
all: Stream.merge(options?.stdout ?? Stream.empty, options?.stderr ?? Stream.empty),
35+
exitCode: options?.exitCode ?? Effect.succeed(ChildProcessSpawner.ExitCode(0)),
36+
isRunning: Effect.succeed(false),
37+
kill: options?.kill ?? (() => Effect.void),
38+
stdin: Sink.drain,
39+
getInputFd: () => Sink.drain,
40+
getOutputFd: () => Stream.empty,
41+
unref: Effect.succeed(Effect.void),
42+
});
43+
}
44+
45+
function httpClientLayer(status: number) {
46+
return Layer.succeed(
47+
HttpClient.HttpClient,
48+
HttpClient.make((request: HttpClientRequest.HttpClientRequest) =>
49+
Effect.succeed(HttpClientResponse.fromWeb(request, new Response(null, { status }))),
50+
),
51+
);
52+
}
53+
54+
function decodeBootstrap(raw: string) {
55+
return Schema.decodeEffect(Schema.fromJsonString(DesktopBackendBootstrap))(raw);
56+
}
57+
58+
describe("runBackendProcess", () => {
59+
it.effect("spawns the backend with fd3 bootstrap JSON and reports HTTP readiness", () =>
60+
Effect.gen(function* () {
61+
let spawnedCommand: ChildProcess.Command | undefined;
62+
let bootstrapJson = "";
63+
let finishExit: (() => void) | undefined;
64+
let readyCount = 0;
65+
66+
const spawnerLayer = Layer.succeed(
67+
ChildProcessSpawner.ChildProcessSpawner,
68+
ChildProcessSpawner.make((command) =>
69+
Effect.gen(function* () {
70+
spawnedCommand = command;
71+
if (command._tag === "StandardCommand") {
72+
const fd3 = command.options.additionalFds?.fd3;
73+
if (fd3?.type === "input" && fd3.stream) {
74+
bootstrapJson = yield* fd3.stream.pipe(Stream.decodeText(), Stream.mkString);
75+
}
76+
}
77+
78+
return makeProcess({
79+
exitCode: Effect.callback<ChildProcessSpawner.ExitCode>((resume) => {
80+
finishExit = () => resume(Effect.succeed(ChildProcessSpawner.ExitCode(0)));
81+
}),
82+
});
83+
}),
84+
),
85+
);
86+
87+
const exit = yield* runBackendProcess({
88+
executablePath: "/electron",
89+
entryPath: "/server/bin.mjs",
90+
cwd: "/server",
91+
env: { ELECTRON_RUN_AS_NODE: "1" },
92+
bootstrap,
93+
httpBaseUrl: new URL("http://127.0.0.1:3773"),
94+
captureOutput: true,
95+
onReady: () =>
96+
Effect.sync(() => {
97+
readyCount += 1;
98+
finishExit?.();
99+
}),
100+
}).pipe(Effect.scoped, Effect.provide(Layer.merge(spawnerLayer, httpClientLayer(200))));
101+
102+
assert.equal(exit.code, 0);
103+
assert.equal(readyCount, 1);
104+
assert.isDefined(spawnedCommand);
105+
if (spawnedCommand?._tag === "StandardCommand") {
106+
assert.equal(spawnedCommand.command, "/electron");
107+
assert.deepEqual(spawnedCommand.args, ["/server/bin.mjs", "--bootstrap-fd", "3"]);
108+
assert.equal(spawnedCommand.options.cwd, "/server");
109+
assert.equal(spawnedCommand.options.stdout, "pipe");
110+
assert.equal(spawnedCommand.options.stderr, "pipe");
111+
assert.equal(spawnedCommand.options.killSignal, "SIGTERM");
112+
assert.isDefined(spawnedCommand.options.forceKillAfter);
113+
assert.equal(
114+
Duration.toMillis(Duration.fromInputUnsafe(spawnedCommand.options.forceKillAfter)),
115+
2_000,
116+
);
117+
}
118+
assert.deepEqual(yield* decodeBootstrap(bootstrapJson), bootstrap);
119+
}),
120+
);
121+
122+
it.effect("inherits child output when captureOutput is false", () =>
123+
Effect.gen(function* () {
124+
let spawnedCommand: ChildProcess.Command | undefined;
125+
let finishExit: (() => void) | undefined;
126+
let readyCount = 0;
127+
128+
const spawnerLayer = Layer.succeed(
129+
ChildProcessSpawner.ChildProcessSpawner,
130+
ChildProcessSpawner.make((command) =>
131+
Effect.sync(() => {
132+
spawnedCommand = command;
133+
return makeProcess({
134+
exitCode: Effect.callback<ChildProcessSpawner.ExitCode>((resume) => {
135+
finishExit = () => resume(Effect.succeed(ChildProcessSpawner.ExitCode(0)));
136+
}),
137+
});
138+
}),
139+
),
140+
);
141+
142+
const exit = yield* runBackendProcess({
143+
executablePath: "/electron",
144+
entryPath: "/server/bin.mjs",
145+
cwd: "/server",
146+
env: { ELECTRON_RUN_AS_NODE: "1" },
147+
bootstrap,
148+
httpBaseUrl: new URL("http://127.0.0.1:3773"),
149+
captureOutput: false,
150+
onReady: () =>
151+
Effect.sync(() => {
152+
readyCount += 1;
153+
finishExit?.();
154+
}),
155+
}).pipe(Effect.scoped, Effect.provide(Layer.merge(spawnerLayer, httpClientLayer(200))));
156+
157+
assert.equal(exit.code, 0);
158+
assert.equal(readyCount, 1);
159+
assert.isDefined(spawnedCommand);
160+
if (spawnedCommand?._tag === "StandardCommand") {
161+
assert.equal(spawnedCommand.options.stdout, "inherit");
162+
assert.equal(spawnedCommand.options.stderr, "inherit");
163+
}
164+
}),
165+
);
166+
});

‎apps/desktop/src/backendProcess.ts‎

Lines changed: 122 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,122 @@
1+
import {
2+
DesktopBackendBootstrap,
3+
type DesktopBackendBootstrap as DesktopBackendBootstrapValue,
4+
} from "@t3tools/contracts";
5+
import * as Duration from "effect/Duration";
6+
import * as Effect from "effect/Effect";
7+
import * as PlatformError from "effect/PlatformError";
8+
import * as Result from "effect/Result";
9+
import * as Schema from "effect/Schema";
10+
import * as Scope from "effect/Scope";
11+
import * as Stream from "effect/Stream";
12+
import { HttpClient } from "effect/unstable/http";
13+
import { ChildProcess, ChildProcessSpawner } from "effect/unstable/process";
14+
15+
import { BackendTimeoutError, waitForHttpReadyEffect } from "./backendReadiness.ts";
16+
17+
const DEFAULT_BACKEND_READINESS_TIMEOUT = Duration.minutes(1);
18+
const DEFAULT_BACKEND_TERMINATE_GRACE = Duration.seconds(2);
19+
20+
export interface BackendProcessExit {
21+
readonly code: number | null;
22+
readonly reason: string;
23+
readonly cause: unknown;
24+
}
25+
26+
export interface RunBackendProcessOptions {
27+
readonly executablePath: string;
28+
readonly entryPath: string;
29+
readonly cwd: string;
30+
readonly env: Record<string, string | undefined>;
31+
readonly bootstrap: DesktopBackendBootstrapValue;
32+
readonly httpBaseUrl: URL;
33+
readonly captureOutput: boolean;
34+
readonly readinessTimeout?: Duration.Duration;
35+
readonly onStarted?: (pid: number) => Effect.Effect<void>;
36+
readonly onReady?: () => Effect.Effect<void>;
37+
readonly onReadinessFailure?: (error: BackendTimeoutError) => Effect.Effect<void>;
38+
readonly onOutput?: (streamName: "stdout" | "stderr", chunk: Uint8Array) => Effect.Effect<void>;
39+
}
40+
41+
const encodeBootstrapJson = Schema.encodeEffect(Schema.fromJsonString(DesktopBackendBootstrap));
42+
43+
function describeProcessExit(
44+
result: Result.Result<ChildProcessSpawner.ExitCode, PlatformError.PlatformError>,
45+
): BackendProcessExit {
46+
if (Result.isSuccess(result)) {
47+
const code = Number(result.success);
48+
return {
49+
code,
50+
reason: `code=${code}`,
51+
cause: result.success,
52+
};
53+
}
54+
55+
return {
56+
code: null,
57+
reason: result.failure.message,
58+
cause: result.failure,
59+
};
60+
}
61+
62+
function drainBackendOutput(
63+
streamName: "stdout" | "stderr",
64+
stream: Stream.Stream<Uint8Array, unknown>,
65+
onOutput: (streamName: "stdout" | "stderr", chunk: Uint8Array) => Effect.Effect<void>,
66+
): Effect.Effect<void> {
67+
return stream.pipe(
68+
Stream.runForEach((chunk) => onOutput(streamName, chunk)),
69+
Effect.ignore,
70+
);
71+
}
72+
73+
export const runBackendProcess = Effect.fn("runBackendProcess")(function* (
74+
options: RunBackendProcessOptions,
75+
): Effect.fn.Return<
76+
BackendProcessExit,
77+
unknown,
78+
ChildProcessSpawner.ChildProcessSpawner | HttpClient.HttpClient | Scope.Scope
79+
> {
80+
const spawner = yield* ChildProcessSpawner.ChildProcessSpawner;
81+
const bootstrapJson = yield* encodeBootstrapJson(options.bootstrap);
82+
const onOutput = options.onOutput ?? (() => Effect.void);
83+
const command = ChildProcess.make(
84+
options.executablePath,
85+
[options.entryPath, "--bootstrap-fd", "3"],
86+
{
87+
cwd: options.cwd,
88+
env: options.env,
89+
extendEnv: false,
90+
// In Electron main, process.execPath points to the Electron binary.
91+
// Run the child in Node mode so this backend process does not become a GUI app instance.
92+
stdin: "ignore",
93+
stdout: options.captureOutput ? "pipe" : "inherit",
94+
stderr: options.captureOutput ? "pipe" : "inherit",
95+
killSignal: "SIGTERM",
96+
forceKillAfter: DEFAULT_BACKEND_TERMINATE_GRACE,
97+
additionalFds: {
98+
fd3: {
99+
type: "input",
100+
stream: Stream.encodeText(Stream.make(`${bootstrapJson}\n`)),
101+
},
102+
},
103+
},
104+
);
105+
106+
const handle = yield* spawner.spawn(command);
107+
108+
yield* options.onStarted?.(Number(handle.pid)) ?? Effect.void;
109+
if (options.captureOutput) {
110+
yield* drainBackendOutput("stdout", handle.stdout, onOutput).pipe(Effect.forkScoped);
111+
yield* drainBackendOutput("stderr", handle.stderr, onOutput).pipe(Effect.forkScoped);
112+
}
113+
yield* waitForHttpReadyEffect(options.httpBaseUrl, {
114+
timeout: options.readinessTimeout ?? DEFAULT_BACKEND_READINESS_TIMEOUT,
115+
}).pipe(
116+
Effect.tap(() => options.onReady?.() ?? Effect.void),
117+
Effect.catch((error) => options.onReadinessFailure?.(error) ?? Effect.void),
118+
Effect.forkScoped,
119+
);
120+
121+
return describeProcessExit(yield* Effect.result(handle.exitCode));
122+
});

‎apps/desktop/src/backendReadiness.test.ts‎

Lines changed: 1 addition & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -3,7 +3,7 @@ import { Duration, Effect, Fiber, Layer, Result } from "effect";
33
import { TestClock } from "effect/testing";
44
import { HttpClient, HttpClientRequest, HttpClientResponse } from "effect/unstable/http";
55

6-
import { BackendReadinessAbortedError, waitForHttpReadyEffect } from "./backendReadiness.ts";
6+
import { waitForHttpReadyEffect } from "./backendReadiness.ts";
77

88
function responseForRequest(
99
request: HttpClientRequest.HttpClientRequest,
@@ -110,11 +110,4 @@ describe("waitForHttpReadyEffect", () => {
110110
}
111111
}).pipe(Effect.provide(layer));
112112
});
113-
114-
it.effect("recognizes aborted readiness errors", () =>
115-
Effect.sync(() => {
116-
assert.equal(BackendReadinessAbortedError.is(new BackendReadinessAbortedError()), true);
117-
assert.equal(BackendReadinessAbortedError.is(new Error("nope")), false);
118-
}),
119-
);
120113
});
Lines changed: 0 additions & 36 deletions
Original file line numberDiff line numberDiff line change
@@ -1,9 +1,6 @@
1-
import * as NodeHttpClient from "@effect/platform-node/NodeHttpClient";
2-
import * as Cause from "effect/Cause";
31
import * as Data from "effect/Data";
42
import * as Duration from "effect/Duration";
53
import * as Effect from "effect/Effect";
6-
import * as Predicate from "effect/Predicate";
74
import * as Schedule from "effect/Schedule";
85
import { HttpClient } from "effect/unstable/http";
96

@@ -14,25 +11,10 @@ export interface WaitForHttpReadyEffectOptions {
1411
readonly path?: string;
1512
}
1613

17-
export interface WaitForHttpReadyOptions extends WaitForHttpReadyEffectOptions {
18-
readonly signal?: AbortSignal;
19-
}
20-
2114
const DEFAULT_TIMEOUT = Duration.seconds(30);
2215
const DEFAULT_INTERVAL = Duration.millis(100);
2316
const DEFAULT_REQUEST_TIMEOUT = Duration.seconds(1);
2417

25-
export class BackendReadinessAbortedError extends Data.TaggedError(
26-
"BackendReadinessAbortedError",
27-
)<{}> {
28-
static is = (u: unknown): u is BackendReadinessAbortedError =>
29-
Predicate.isTagged(u, "BackendReadinessAbortedError");
30-
31-
override get message() {
32-
return "Backend readiness wait was aborted.";
33-
}
34-
}
35-
3618
export class BackendTimeoutError extends Data.TaggedError("BackendTimeoutError")<{
3719
readonly url: URL;
3820
}> {
@@ -63,21 +45,3 @@ export const waitForHttpReadyEffect = Effect.fn("waitForHttpReadyEffect")(functi
6345
Effect.mapError(() => new BackendTimeoutError({ url: baseUrl })),
6446
);
6547
});
66-
67-
/**
68-
* @deprecated - Temporary promise shim until remaining desktop entrypoint is ported to Effect
69-
*/
70-
export async function waitForHttpReady(
71-
baseUrl: URL,
72-
options?: WaitForHttpReadyOptions,
73-
): Promise<void> {
74-
const signal = options?.signal;
75-
76-
const exit = await Effect.runPromiseExit(
77-
waitForHttpReadyEffect(baseUrl, options).pipe(Effect.provide(NodeHttpClient.layerUndici)),
78-
{ signal },
79-
);
80-
if (exit._tag === "Success") return;
81-
if (Cause.hasInterrupts(exit.cause)) throw new BackendReadinessAbortedError();
82-
throw Cause.squash(exit.cause);
83-
}

0 commit comments

Comments
 (0)