authorgravatar for julius0216@outlook.comJulius Marminge <julius0216@outlook.com> 2026-06-20 11:56:52-07:00
committergravatar for noreply@github.comGitHub <noreply@github.com> 2026-06-20 11:56:52-07:00
logd2e38c53735718cee17c7aeb58f6c71be24bf435
tree7576d2f81be4b1a09885695a89d4de3e7d61274e
parent90bd5ee0c13782e56ccbeded52b0cc6c50deafad
signature Signed by PGP key B5690EEEBB952194

[codex] Structure Tailscale command failures (#3257)

Co-authored-by: codex <codex@users.noreply.github.com>

2 files changed, 256 insertions(+), 132 deletions(-)

packages/tailscale/src/tailscale.test.ts+97-5
......@@ -1,7 +1,9 @@
11import { assert, describe, it } from "@effect/vitest";
2import * as Cause from "effect/Cause";
23import * as Effect from "effect/Effect";
34import * as Fiber from "effect/Fiber";
45import * as Layer from "effect/Layer";
6import * as PlatformError from "effect/PlatformError";
57import * as Sink from "effect/Sink";
68import * as Stream from "effect/Stream";
79import * as TestClock from "effect/testing/TestClock";
......@@ -16,6 +18,10 @@ import {
1618 parseTailscaleStatus,
1719 readTailscaleStatus,
1820 TAILSCALE_STATUS_TIMEOUT,
21 TailscaleCommandExitError,
22 TailscaleCommandSpawnError,
23 TailscaleCommandTimeoutError,
24 TailscaleStatusParseError,
1925} from "./tailscale.ts";
2026
2127const encoder = new TextEncoder();
......@@ -100,6 +106,17 @@ describe("tailscale", () => {
100106 }),
101107 );
102108
109 it.effect("preserves status decoding failures without exposing cause text", () =>
110 Effect.gen(function* () {
111 const error = yield* parseTailscaleStatus("{not-json").pipe(Effect.flip);
112
113 assert.instanceOf(error, TailscaleStatusParseError);
114 assert.equal(error.message, "Failed to decode tailscale status JSON.");
115 assert.isDefined(error.cause);
116 assert.notInclude(error.message, String(error.cause));
117 }),
118 );
119
103120 it.effect("builds clean HTTPS base URLs", () =>
104121 Effect.sync(() => {
105122 assert.equal(
......@@ -131,6 +148,55 @@ describe("tailscale", () => {
131148 });
132149 });
133150
151 it.effect("preserves tailscale spawn failures as causes", () => {
152 const systemCause = new Error("private executable lookup detail");
153 const cause = PlatformError.systemError({
154 _tag: "NotFound",
155 module: "ChildProcess",
156 method: "spawn",
157 cause: systemCause,
158 });
159 const layer = Layer.succeed(
160 ChildProcessSpawner.ChildProcessSpawner,
161 ChildProcessSpawner.make(() => Effect.fail(cause)),
162 );
163
164 return Effect.gen(function* () {
165 const error = yield* readTailscaleStatus.pipe(Effect.flip, Effect.provide(layer));
166
167 assert.instanceOf(error, TailscaleCommandSpawnError);
168 assert.equal(error.executable, "tailscale");
169 assert.equal(error.subcommand, "status");
170 assert.equal(error.argumentCount, 2);
171 assert.strictEqual(error.cause, cause);
172 assert.equal(error.message, "Failed to spawn tailscale status.");
173 assert.notInclude(error.message, systemCause.message);
174 });
175 });
176
177 it.effect("keeps nonzero exit diagnostics structured", () => {
178 const layer = mockSpawnerLayer(() => ({
179 code: 7,
180 stderr: "not logged in tskey-auth-secret-token-value",
181 }));
182
183 return Effect.gen(function* () {
184 const error = yield* readTailscaleStatus.pipe(Effect.flip, Effect.provide(layer));
185
186 assert.instanceOf(error, TailscaleCommandExitError);
187 assert.equal(error.executable, "tailscale");
188 assert.equal(error.subcommand, "status");
189 assert.equal(error.argumentCount, 2);
190 assert.equal(error.exitCode, 7);
191 assert.equal(error.stdoutLength, 0);
192 assert.equal(error.stderrLength, 43);
193 assert.notProperty(error, "command");
194 assert.notProperty(error, "stderr");
195 assert.notInclude(error.message, "tskey-auth-secret-token-value");
196 assert.equal(error.message, "tailscale status exited with code 7.");
197 });
198 });
199
134200 it.effect("times out tailscale status through TestClock", () => {
135201 const layer = Layer.merge(
136202 TestClock.layer(),
......@@ -146,11 +212,13 @@ describe("tailscale", () => {
146212 yield* TestClock.adjust(TAILSCALE_STATUS_TIMEOUT);
147213 const error = yield* Fiber.join(fiber);
148214
149 if (error._tag !== "TailscaleCommandError") {
150 assert.fail(`Expected TailscaleCommandError, received ${error._tag}.`);
151 }
152 assert.equal(error.message, "Tailscale status timed out.");
153 assert.equal(error.exitCode, null);
215 assert.instanceOf(error, TailscaleCommandTimeoutError);
216 assert.equal(error.executable, "tailscale");
217 assert.equal(error.subcommand, "status");
218 assert.equal(error.argumentCount, 2);
219 assert.equal(error.timeoutMs, 1_500);
220 assert.isTrue(Cause.isTimeoutError(error.cause));
221 assert.equal(error.message, "tailscale status timed out after 1500ms.");
154222 }).pipe(Effect.provide(layer));
155223 });
156224
......@@ -164,6 +232,30 @@ describe("tailscale", () => {
164232 return ensureTailscaleServe({ localPort: 13773, servePort: 8443 }).pipe(Effect.provide(layer));
165233 });
166234
235 it.effect("retains tailscale serve exit diagnostics", () => {
236 const layer = mockSpawnerLayer(() => ({
237 code: 1,
238 stderr: "serve permission denied tskey-auth-secret-token-value",
239 }));
240
241 return Effect.gen(function* () {
242 const error = yield* ensureTailscaleServe({ localPort: 13773, servePort: 8443 }).pipe(
243 Effect.flip,
244 Effect.provide(layer),
245 );
246
247 assert.instanceOf(error, TailscaleCommandExitError);
248 assert.equal(error.executable, "tailscale");
249 assert.equal(error.subcommand, "serve");
250 assert.equal(error.argumentCount, 4);
251 assert.equal(error.exitCode, 1);
252 assert.equal(error.stderrLength, 53);
253 assert.notProperty(error, "command");
254 assert.notProperty(error, "stderr");
255 assert.notInclude(error.message, "tskey-auth-secret-token-value");
256 });
257 });
258
167259 it.effect("disables tailscale serve through the process spawner service", () => {
168260 const commands: {
169261 readonly command: string;
packages/tailscale/src/tailscale.ts+159-127
......@@ -1,5 +1,4 @@
11import { HostProcessPlatform } from "@t3tools/shared/hostProcess";
2import * as Data from "effect/Data";
32import * as Duration from "effect/Duration";
43import * as Effect from "effect/Effect";
54import * as Option from "effect/Option";
......@@ -15,23 +14,82 @@ export const TAILSCALE_PROBE_TIMEOUT = Duration.millis(2_500);
1514
1615// tailscale is a real executable everywhere (`tailscale.exe` on Windows), so
1716// it is always spawned directly rather than through cmd.exe shell mode.
18const tailscaleCommandForPlatform = (platform: NodeJS.Platform): string =>
17const tailscaleCommandForPlatform = (platform: NodeJS.Platform): "tailscale" | "tailscale.exe" =>
1918 platform === "win32" ? "tailscale.exe" : "tailscale";
2019
21export class TailscaleCommandError extends Data.TaggedError("TailscaleCommandError")<{
22 readonly command: readonly string[];
23 readonly message: string;
24 readonly exitCode: number | null;
25 readonly stderr: string;
26}> {}
20const TailscaleCommandContext = {
21 executable: Schema.Literals(["tailscale", "tailscale.exe"]),
22 subcommand: Schema.Literals(["status", "serve"]),
23 argumentCount: Schema.Number,
24};
25
26export class TailscaleCommandSpawnError extends Schema.TaggedErrorClass<TailscaleCommandSpawnError>()(
27 "TailscaleCommandSpawnError",
28 {
29 ...TailscaleCommandContext,
30 cause: Schema.Defect(),
31 },
32) {
33 override get message(): string {
34 return `Failed to spawn tailscale ${this.subcommand}.`;
35 }
36}
37
38export class TailscaleCommandOutputError extends Schema.TaggedErrorClass<TailscaleCommandOutputError>()(
39 "TailscaleCommandOutputError",
40 {
41 ...TailscaleCommandContext,
42 cause: Schema.Defect(),
43 },
44) {
45 override get message(): string {
46 return `Failed to read output from tailscale ${this.subcommand}.`;
47 }
48}
49
50export class TailscaleCommandExitError extends Schema.TaggedErrorClass<TailscaleCommandExitError>()(
51 "TailscaleCommandExitError",
52 {
53 ...TailscaleCommandContext,
54 exitCode: Schema.Number,
55 stdoutLength: Schema.optional(Schema.Number),
56 stderrLength: Schema.Number,
57 },
58) {
59 override get message(): string {
60 return `tailscale ${this.subcommand} exited with code ${this.exitCode}.`;
61 }
62}
2763
28export class TailscaleStatusParseError extends Data.TaggedError("TailscaleStatusParseError")<{
29 readonly cause: unknown;
30}> {}
64export class TailscaleCommandTimeoutError extends Schema.TaggedErrorClass<TailscaleCommandTimeoutError>()(
65 "TailscaleCommandTimeoutError",
66 {
67 ...TailscaleCommandContext,
68 timeoutMs: Schema.Number,
69 cause: Schema.Defect(),
70 },
71) {
72 override get message(): string {
73 return `tailscale ${this.subcommand} timed out after ${this.timeoutMs}ms.`;
74 }
75}
3176
32export class TailscaleUnavailableError extends Data.TaggedError("TailscaleUnavailableError")<{
33 readonly reason: string;
34}> {}
77export const TailscaleCommandError = Schema.Union([
78 TailscaleCommandSpawnError,
79 TailscaleCommandOutputError,
80 TailscaleCommandExitError,
81 TailscaleCommandTimeoutError,
82]);
83export type TailscaleCommandError = typeof TailscaleCommandError.Type;
84
85export class TailscaleStatusParseError extends Schema.TaggedErrorClass<TailscaleStatusParseError>()(
86 "TailscaleStatusParseError",
87 { cause: Schema.Defect() },
88) {
89 override get message(): string {
90 return "Failed to decode tailscale status JSON.";
91 }
92}
3593
3694const TailscaleStatusSelf = Schema.Struct({
3795 DNSName: Schema.optional(Schema.Unknown),
......@@ -61,19 +119,6 @@ const collectStdout = <E>(stream: Stream.Stream<Uint8Array, E>): Effect.Effect<s
61119
62120const collectStderr = collectStdout;
63121
64const tailscaleCommandError = (
65 args: readonly string[],
66 message: string,
67 exitCode: number | null,
68 stderr = "",
69): TailscaleCommandError =>
70 new TailscaleCommandError({
71 command: ["tailscale", ...args],
72 message,
73 exitCode,
74 stderr,
75 });
76
77122const decodeTailscaleStatusJson = Schema.decodeEffect(Schema.fromJsonString(TailscaleStatusJson));
78123
79124function normalizeMagicDnsName(status: TailscaleStatusJson): string | null {
......@@ -139,55 +184,52 @@ export const readTailscaleStatus = Effect.gen(function* () {
139184 const args = ["status", "--json"];
140185 const spawner = yield* ChildProcessSpawner.ChildProcessSpawner;
141186 const hostPlatform = yield* HostProcessPlatform;
142 const child = yield* spawner
143 .spawn(ChildProcess.make(tailscaleCommandForPlatform(hostPlatform), args))
144 .pipe(
145 Effect.mapError((cause) =>
146 tailscaleCommandError(
147 args,
148 cause instanceof Error ? cause.message : "Failed to spawn tailscale status.",
149 null,
150 ),
151 ),
152 );
153 const [stdout, stderr, exitCode] = yield* Effect.all(
154 [
155 collectStdout(child.stdout),
156 collectStderr(child.stderr),
157 child.exitCode.pipe(Effect.map(Number)),
158 ],
159 { concurrency: "unbounded" },
160 ).pipe(
161 Effect.mapError((cause) =>
162 tailscaleCommandError(
163 args,
164 cause instanceof Error ? cause.message : "Failed to run tailscale status.",
165 null,
166 ),
167 ),
168 );
169 if (exitCode !== 0) {
170 return yield* tailscaleCommandError(
171 args,
172 `Tailscale status exited with code ${exitCode}.`,
173 exitCode,
174 stderr,
187 const executable = tailscaleCommandForPlatform(hostPlatform);
188 const commandContext = {
189 executable,
190 subcommand: "status" as const,
191 argumentCount: args.length,
192 };
193 return yield* Effect.gen(function* () {
194 const child = yield* spawner
195 .spawn(ChildProcess.make(executable, args))
196 .pipe(
197 Effect.mapError((cause) => new TailscaleCommandSpawnError({ ...commandContext, cause })),
198 );
199 const [stdout, stderr, exitCode] = yield* Effect.all(
200 [
201 collectStdout(child.stdout),
202 collectStderr(child.stderr),
203 child.exitCode.pipe(Effect.map(Number)),
204 ],
205 { concurrency: "unbounded" },
206 ).pipe(
207 Effect.mapError((cause) => new TailscaleCommandOutputError({ ...commandContext, cause })),
175208 );
176 }
177 return yield* parseTailscaleStatus(stdout);
178}).pipe(
179 Effect.scoped,
180 Effect.timeoutOption(TAILSCALE_STATUS_TIMEOUT),
181 Effect.flatMap((result) =>
182 Option.match(result, {
183 onNone: () =>
209 if (exitCode !== 0) {
210 return yield* new TailscaleCommandExitError({
211 ...commandContext,
212 exitCode,
213 stdoutLength: stdout.length,
214 stderrLength: stderr.length,
215 });
216 }
217 return yield* parseTailscaleStatus(stdout);
218 }).pipe(
219 Effect.scoped,
220 Effect.timeout(TAILSCALE_STATUS_TIMEOUT),
221 Effect.catchTags({
222 TimeoutError: (cause) =>
184223 Effect.fail(
185 tailscaleCommandError(["status", "--json"], "Tailscale status timed out.", null),
224 new TailscaleCommandTimeoutError({
225 ...commandContext,
226 timeoutMs: Duration.toMillis(TAILSCALE_STATUS_TIMEOUT),
227 cause,
228 }),
186229 ),
187 onSome: Effect.succeed,
188230 }),
189 ),
190);
231 );
232});
191233
192234export function buildTailscaleHttpsBaseUrl(input: {
193235 readonly magicDnsName: string;
......@@ -204,53 +246,52 @@ export function buildTailscaleHttpsBaseUrl(input: {
204246
205247const runTailscaleCommand = (
206248 args: readonly string[],
207 input: {
208 readonly spawnMessage: string;
209 readonly runMessage: string;
210 readonly exitMessage: (exitCode: number) => string;
211 readonly timeoutMessage: string;
212 readonly timeout: Duration.Input;
213 },
249 timeoutInput: Duration.Input,
214250): Effect.Effect<void, TailscaleCommandError, ChildProcessSpawner.ChildProcessSpawner> =>
215251 Effect.gen(function* () {
216252 const spawner = yield* ChildProcessSpawner.ChildProcessSpawner;
217253 const hostPlatform = yield* HostProcessPlatform;
218 const child = yield* spawner
219 .spawn(ChildProcess.make(tailscaleCommandForPlatform(hostPlatform), args))
220 .pipe(
221 Effect.mapError((cause) =>
222 tailscaleCommandError(
223 args,
224 cause instanceof Error ? cause.message : input.spawnMessage,
225 null,
226 ),
227 ),
254 const executable = tailscaleCommandForPlatform(hostPlatform);
255 const commandContext = {
256 executable,
257 subcommand: "serve" as const,
258 argumentCount: args.length,
259 };
260 const timeout = Duration.fromInputUnsafe(timeoutInput);
261 return yield* Effect.gen(function* () {
262 const child = yield* spawner
263 .spawn(ChildProcess.make(executable, args))
264 .pipe(
265 Effect.mapError((cause) => new TailscaleCommandSpawnError({ ...commandContext, cause })),
266 );
267 const [stderr, exitCode] = yield* Effect.all(
268 [collectStderr(child.stderr), child.exitCode.pipe(Effect.map(Number))],
269 { concurrency: "unbounded" },
270 ).pipe(
271 Effect.mapError((cause) => new TailscaleCommandOutputError({ ...commandContext, cause })),
228272 );
229 const [stderr, exitCode] = yield* Effect.all(
230 [collectStderr(child.stderr), child.exitCode.pipe(Effect.map(Number))],
231 { concurrency: "unbounded" },
232 ).pipe(
233 Effect.mapError((cause) =>
234 tailscaleCommandError(
235 args,
236 cause instanceof Error ? cause.message : input.runMessage,
237 null,
238 ),
239 ),
240 );
241 if (exitCode !== 0) {
242 return yield* tailscaleCommandError(args, input.exitMessage(exitCode), exitCode, stderr);
243 }
244 }).pipe(
245 Effect.scoped,
246 Effect.timeoutOption(input.timeout),
247 Effect.flatMap((result) =>
248 Option.match(result, {
249 onNone: () => Effect.fail(tailscaleCommandError(args, input.timeoutMessage, null)),
250 onSome: Effect.succeed,
273 if (exitCode !== 0) {
274 return yield* new TailscaleCommandExitError({
275 ...commandContext,
276 exitCode,
277 stderrLength: stderr.length,
278 });
279 }
280 }).pipe(
281 Effect.scoped,
282 Effect.timeout(timeout),
283 Effect.catchTags({
284 TimeoutError: (cause) =>
285 Effect.fail(
286 new TailscaleCommandTimeoutError({
287 ...commandContext,
288 timeoutMs: Duration.toMillis(timeout),
289 cause,
290 }),
291 ),
251292 }),
252 ),
253 );
293 );
294 });
254295
255296export const ensureTailscaleServe = (input: {
256297 readonly localPort: number;
......@@ -260,13 +301,7 @@ export const ensureTailscaleServe = (input: {
260301 const servePort = input.servePort ?? DEFAULT_TAILSCALE_SERVE_PORT;
261302 const localHost = input.localHost ?? "127.0.0.1";
262303 const args = ["serve", "--bg", `--https=${servePort}`, `http://${localHost}:${input.localPort}`];
263 return runTailscaleCommand(args, {
264 spawnMessage: "Failed to spawn tailscale serve.",
265 runMessage: "Failed to run tailscale serve.",
266 exitMessage: (exitCode) => `Tailscale serve exited with code ${exitCode}.`,
267 timeoutMessage: "Tailscale serve timed out.",
268 timeout: TAILSCALE_SERVE_TIMEOUT,
269 });
304 return runTailscaleCommand(args, TAILSCALE_SERVE_TIMEOUT);
270305};
271306
272307export const disableTailscaleServe = (
......@@ -276,13 +311,10 @@ export const disableTailscaleServe = (
276311): Effect.Effect<void, TailscaleCommandError, ChildProcessSpawner.ChildProcessSpawner> =>
277312 Effect.gen(function* () {
278313 const servePort = input.servePort ?? DEFAULT_TAILSCALE_SERVE_PORT;
279 return yield* runTailscaleCommand(["serve", `--https=${servePort}`, "off"], {
280 spawnMessage: "Failed to spawn tailscale serve off.",
281 runMessage: "Failed to run tailscale serve off.",
282 exitMessage: (exitCode) => `Tailscale serve off exited with code ${exitCode}.`,
283 timeoutMessage: "Tailscale serve off timed out.",
284 timeout: TAILSCALE_SERVE_TIMEOUT,
285 });
314 return yield* runTailscaleCommand(
315 ["serve", `--https=${servePort}`, "off"],
316 TAILSCALE_SERVE_TIMEOUT,
317 );
286318 });
287319
288320export const probeTailscaleHttpsEndpoint = (input: {