@serverkgg/bridge 0.1.12 → 0.1.13

package/src/protocol/bridgeManifest.ts

@@ -13,6 +13,7 @@ export interface BridgeTerminalRuleManifest {
 export interface BridgeTerminalManifest {
 	commands: BridgeTerminalCommand[];
 	rules: BridgeTerminalRuleManifest[];
+	shell: boolean;
 }
 
 export interface BridgeModuleManifest {

package/src/runtime/bridgeContext.test.ts

@@ -66,6 +66,9 @@ describe("the context's variable maps", () => {
 			supervisor,
 			{
 				onLog: log,
+				onPrint() {
+					return;
+				},
 				onEmit() {
 					return;
 				},
@@ -155,6 +158,9 @@ describe("the context's ports and address", () => {
 				supervisor,
 				{
 					onLog: log,
+					onPrint() {
+						return;
+					},
 					onEmit() {
 						return;
 					},

package/src/runtime/bridgeContext.ts

@@ -1,5 +1,5 @@
 import type { BridgeContext } from "../context";
-import type { BridgeActivity, BridgeValues } from "../core";
+import { type BridgeActivity, BridgeStream, type BridgeValues } from "../core";
 import type { BridgeConfig, BridgeSetupRuntime } from "../protocol";
 import { stripAnsi } from "../utils";
 import { createBridgeCodecs } from "./bridgeCodec";
@@ -8,7 +8,7 @@ import { createBridgeEgress } from "./bridgeEgress";
 import { createBridgeExec } from "./bridgeExec";
 import { createBridgeFiles } from "./bridgeFiles";
 import { type BridgeLiveConfig, createBridgeLiveConfig } from "./bridgeLiveConfig";
-import type { BridgeLeveledLogger } from "./bridgeLog";
+import type { BridgeLeveledLogger, BridgePrinter } from "./bridgeLog";
 import { createBridgeNet } from "./bridgeNet";
 import { createBridgeProbes } from "./bridgeProbe";
 import { createBridgeRcons } from "./bridgeRcon";
@@ -16,6 +16,7 @@ import type { BridgeSupervisor } from "./bridgeSupervisor";
 
 export interface ContextHooks {
 	onLog: BridgeLeveledLogger;
+	onPrint: BridgePrinter;
 	onEmit: (event: string, payload?: BridgeValues) => void;
 	onSetup: (runtime: BridgeSetupRuntime | null) => void;
 	onActivity: (entry: BridgeActivity) => void;
@@ -178,5 +179,9 @@ export const createContext = (
 				},
 			},
 		),
+
+		print(line, stream = BridgeStream.Stdout) {
+			hooks.onPrint(line, stream);
+		},
 	};
 };

package/src/runtime/bridgeExec.test.ts

@@ -0,0 +1,150 @@
+import { afterEach, beforeEach, describe, expect, it } from "bun:test";
+import { mkdtemp, rm } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import type { BridgeStream } from "../core";
+import { createBridgeExec } from "./bridgeExec";
+
+const SHELL = "/bin/sh";
+
+const GROUP_GONE_WAIT_MS = 2000;
+
+const GROUP_POLL_MS = 100;
+
+const TIMING_TEST_TIMEOUT_MS = 20_000;
+
+const groupAlive = (group: number) => {
+	try {
+		process.kill(-group, 0);
+
+		return true;
+	} catch {
+		return false;
+	}
+};
+
+const groupGone = async (group: number) => {
+	for (let waited = 0; waited < GROUP_GONE_WAIT_MS; waited += GROUP_POLL_MS) {
+		if (!groupAlive(group)) {
+			return true;
+		}
+
+		await Bun.sleep(GROUP_POLL_MS);
+	}
+
+	return !groupAlive(group);
+};
+
+describe("createBridgeExec", () => {
+	let directory = "";
+
+	const execOf = () => {
+		return createBridgeExec({
+			cwd: directory,
+			uid: process.getuid?.() ?? 0,
+			gid: process.getgid?.() ?? 0,
+		});
+	};
+
+	beforeEach(async () => {
+		directory = await mkdtemp(join(tmpdir(), "serverk-exec-"));
+	});
+
+	afterEach(async () => {
+		await rm(directory, {
+			force: true,
+			recursive: true,
+		});
+	});
+
+	it("returns the output of a child that writes and exits", async () => {
+		const lines: string[] = [];
+
+		const result = await execOf()(
+			[
+				SHELL,
+				"-c",
+				"echo hello; echo oops >&2",
+			],
+			{
+				onOutput(line: string, stream: BridgeStream) {
+					lines.push(`${stream} ${line}`);
+				},
+			},
+		);
+
+		expect(result).toEqual({
+			stdout: "hello\n",
+			stderr: "oops\n",
+			code: 0,
+		});
+		expect(lines.toSorted()).toEqual([
+			"stderr oops",
+			"stdout hello",
+		]);
+	});
+
+	it(
+		"kills every process of the command on the deadline and returns at once",
+		async () => {
+			const startedAt = performance.now();
+
+			const result = await execOf()(
+				[
+					SHELL,
+					"-c",
+					"sleep 30 & sleep 30",
+				],
+				{
+					timeoutMs: 300,
+				},
+			);
+
+			expect(result.code).not.toBe(0);
+			expect(performance.now() - startedAt).toBeLessThan(2500);
+		},
+		TIMING_TEST_TIMEOUT_MS,
+	);
+
+	it(
+		"kills what a command left running in its group once it returns",
+		async () => {
+			const startedAt = performance.now();
+
+			const result = await execOf()([
+				SHELL,
+				"-c",
+				"echo $$; sleep 30 &",
+			]);
+
+			const group = Number(result.stdout.trim());
+
+			expect(result.code).toBe(0);
+			expect(Number.isSafeInteger(group) && group > 0).toBe(true);
+			expect(performance.now() - startedAt).toBeLessThan(5000);
+			expect(await groupGone(group)).toBe(true);
+		},
+		TIMING_TEST_TIMEOUT_MS,
+	);
+
+	it.skipIf(!Bun.which("setsid"))(
+		"returns after a short grace when a process that left the group still holds the output open",
+		async () => {
+			const startedAt = performance.now();
+
+			const result = await execOf()([
+				SHELL,
+				"-c",
+				"echo started; setsid sleep 6 &",
+			]);
+
+			expect(result).toEqual({
+				stdout: "started\n",
+				stderr: "",
+				code: 0,
+			});
+			expect(performance.now() - startedAt).toBeLessThan(5000);
+		},
+		TIMING_TEST_TIMEOUT_MS,
+	);
+});

package/src/runtime/bridgeExec.ts

@@ -1,6 +1,7 @@
 import type { BridgeExecOptions, BridgeExecResult } from "../context";
 import { BridgeStream } from "../core";
 import { settleUid, unprivilegedArgv } from "./bridgePrivilege";
+import { readProcessGroup, signalGroup } from "./bridgeSignal";
 
 const DEFAULT_EXEC_TIMEOUT_MS = 900_000;
 
@@ -8,6 +9,8 @@ const OUTPUT_LIMIT = 256 * 1024;
 
 const EXIT_GRACE_MS = 3000;
 
+const DRAIN_GRACE_MS = 3000;
+
 const FALLBACK_PATH = "/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin";
 
 const inheritedPath = () => {
@@ -45,8 +48,10 @@ const capped = (text: string) => {
 const drain = async (
 	stream: ReadableStream<Uint8Array>,
 	report: ((line: string) => void) | undefined,
+	signal: AbortSignal,
 ): Promise<string> => {
 	const decoder = new TextDecoder();
+	const reader = stream.getReader();
 
 	let collected = "";
 	let pending = "";
@@ -59,28 +64,46 @@ const drain = async (
 		}
 	};
 
-	for await (const chunk of stream) {
-		const text = decoder.decode(chunk, {
-			stream: true,
-		});
+	const cancel = () => {
+		void reader.cancel().catch(() => undefined);
+	};
 
-		if (collected.length < OUTPUT_LIMIT) {
-			collected += text;
-		}
+	signal.addEventListener("abort", cancel, {
+		once: true,
+	});
 
-		if (!report) {
-			continue;
-		}
+	try {
+		for (;;) {
+			const chunk = await reader.read();
+
+			if (chunk.done) {
+				break;
+			}
+
+			const text = decoder.decode(chunk.value, {
+				stream: true,
+			});
+
+			if (collected.length < OUTPUT_LIMIT) {
+				collected += text;
+			}
+
+			if (!report) {
+				continue;
+			}
 
-		pending += text;
+			pending += text;
 
-		const lines = pending.split("\n");
+			const lines = pending.split("\n");
 
-		pending = lines.pop() ?? "";
+			pending = lines.pop() ?? "";
 
-		for (const line of lines) {
-			emit(line);
+			for (const line of lines) {
+				emit(line);
+			}
 		}
+	} finally {
+		signal.removeEventListener("abort", cancel);
 	}
 
 	emit(pending);
@@ -107,6 +130,7 @@ export const createBridgeExec = (target: BridgeExecTarget) => {
 				HOME: target.cwd,
 				...environment,
 			},
+			detached: true,
 			stderr: "pipe",
 			stdin: "ignore",
 			stdout: "pipe",
@@ -131,15 +155,33 @@ export const createBridgeExec = (target: BridgeExecTarget) => {
 			}
 		}
 
+		const group = await readProcessGroup(child.pid);
+
 		const timer = setTimeout(() => {
-			child.kill("SIGKILL");
+			if (!signalGroup(child.pid, group, "SIGKILL")) {
+				child.kill("SIGKILL");
+			}
 		}, timeoutMs ?? DEFAULT_EXEC_TIMEOUT_MS);
 
+		const drained = new AbortController();
+
+		let grace: ReturnType<typeof setTimeout> | null = null;
+
+		const exited = async () => {
+			const code = await child.exited;
+
+			grace = setTimeout(() => {
+				drained.abort();
+			}, DRAIN_GRACE_MS);
+
+			return code;
+		};
+
 		try {
 			const [stdout, stderr, code] = await Promise.all([
-				drain(child.stdout, onOutput && ((line) => onOutput(line, BridgeStream.Stdout))),
-				drain(child.stderr, onOutput && ((line) => onOutput(line, BridgeStream.Stderr))),
-				child.exited,
+				drain(child.stdout, onOutput && ((line) => onOutput(line, BridgeStream.Stdout)), drained.signal),
+				drain(child.stderr, onOutput && ((line) => onOutput(line, BridgeStream.Stderr)), drained.signal),
+				exited(),
 			]);
 
 			return {
@@ -149,6 +191,12 @@ export const createBridgeExec = (target: BridgeExecTarget) => {
 			};
 		} finally {
 			clearTimeout(timer);
+
+			if (grace !== null) {
+				clearTimeout(grace);
+			}
+
+			signalGroup(child.pid, group, "SIGKILL");
 		}
 	};
 };

package/src/runtime/bridgeLog.ts

@@ -1,8 +1,11 @@
+import { BridgeStream } from "../core";
 import { BRIDGE_LOG_SOURCE } from "../protocol/bridgeLine";
 import { BridgeTerminalLevel } from "../terminal";
 
 export type BridgeLogger = (message: string, fields?: Record<string, unknown>) => void;
 
+export type BridgePrinter = (line: string, stream: BridgeStream) => void;
+
 export interface BridgeLeveledLogger extends BridgeLogger {
 	warn: BridgeLogger;
 	error: BridgeLogger;
@@ -33,6 +36,12 @@ export const log: BridgeLeveledLogger = Object.assign(
 	},
 );
 
+export const print: BridgePrinter = (line, stream) => {
+	const target = stream === BridgeStream.Stderr ? process.stderr : process.stdout;
+
+	target.write(`${line}\n`);
+};
+
 export const errorText = (error: unknown) => {
 	return error instanceof Error ? error.message : String(error);
 };

package/src/runtime/bridgeRedaction.test.ts

@@ -2,13 +2,20 @@ import { afterEach, beforeEach, describe, expect, it } from "bun:test";
 import { mkdtemp, rm, writeFile } from "node:fs/promises";
 import { tmpdir } from "node:os";
 import { join } from "node:path";
-import { BridgeKind } from "../core";
+import { BridgeKind, BridgeStream } from "../core";
 import type { BridgeDriver } from "../modules";
 import { BridgeControl, BridgeFormTarget, BridgeLayout, type BridgeTab } from "../panel";
 import type { BridgeConfig } from "../protocol";
 import { createBridgeLiveConfig } from "./bridgeLiveConfig";
 import type { BridgeLeveledLogger } from "./bridgeLog";
-import { createBridgeRedaction, REDACTED, redactLocalized, redactLogger, secretFieldKeys } from "./bridgeRedaction";
+import {
+	createBridgeRedaction,
+	REDACTED,
+	redactLocalized,
+	redactLogger,
+	redactPrinter,
+	secretFieldKeys,
+} from "./bridgeRedaction";
 
 const text = (value: string) => ({
 	ar: value,
@@ -309,6 +316,25 @@ describe("redacting what the bridge reports", () => {
 			},
 		]);
 	});
+
+	it("covers a raw console line and keeps its stream", () => {
+		const lines: unknown[] = [];
+		const printer = redactPrinter((line, stream) => {
+			lines.push({
+				line,
+				stream,
+			});
+		}, redact);
+
+		printer(`token=${TOKEN}`, BridgeStream.Stderr);
+
+		expect(lines).toEqual([
+			{
+				line: `token=${REDACTED}`,
+				stream: BridgeStream.Stderr,
+			},
+		]);
+	});
 });
 
 describe("redaction over the live config", () => {

package/src/runtime/bridgeRedaction.ts

@@ -2,7 +2,7 @@ import { BridgeSetupPromptKind, type LocalizedText } from "../core";
 import type { BridgeDriver } from "../modules";
 import { BridgeControl, BridgeLayout } from "../panel";
 import type { BridgeSetupAction, BridgeSetupPrompt, BridgeSetupRuntime } from "../protocol";
-import type { BridgeLeveledLogger, BridgeLogger } from "./bridgeLog";
+import type { BridgeLeveledLogger, BridgeLogger, BridgePrinter } from "./bridgeLog";
 
 export const REDACTED = "••••";
 
@@ -212,3 +212,9 @@ export const redactLogger = (logger: BridgeLeveledLogger, redact: BridgeRedact):
 		error: redactingWriter(logger.error, redact),
 	});
 };
+
+export const redactPrinter = (printer: BridgePrinter, redact: BridgeRedact): BridgePrinter => {
+	return (line, stream) => {
+		printer(redact(line), stream);
+	};
+};

package/src/runtime/bridgeRegistry.test.ts

@@ -91,6 +91,9 @@ const harnessFor = (driver: BridgeDriver, variables: Record<string, string> = {}
 
 	const context = createContext(settings, supervisor, {
 		onLog: log,
+		onPrint() {
+			return;
+		},
 		onEmit(event, payload) {
 			ring.emit(event, payload);
 		},
@@ -773,6 +776,33 @@ describe("the setup singleton", () => {
 	});
 });
 
+describe("the terminal block", () => {
+	const terminalDriver = (shell?: boolean): BridgeDriver => ({
+		...baseDriver(),
+		terminal: {
+			kind: BridgeKind.Terminal,
+			commands: [],
+			...(shell === undefined
+				? {}
+				: {
+						shell,
+					}),
+		},
+	});
+
+	it("advertises a terminal that runs its input as a shell command", () => {
+		expect(registryFor(terminalDriver(true)).manifest().terminal).toEqual({
+			commands: [],
+			rules: [],
+			shell: true,
+		});
+	});
+
+	it("advertises a terminal that declares no shell flag as one that writes to the process", () => {
+		expect(registryFor(terminalDriver()).manifest().terminal?.shell).toBe(false);
+	});
+});
+
 describe("protected action dispatch", () => {
 	it("advertises protection and refuses old callers before touching files", async () => {
 		let calls = 0;

package/src/runtime/bridgeRegistry.ts

@@ -112,6 +112,7 @@ const terminalManifestOf = (module: BridgeTerminalModule | undefined): BridgeTer
 				stream: rule.stream,
 			};
 		}),
+		shell: module.shell ?? false,
 	};
 };
 

package/src/runtime/bridgeScopedContext.ts

@@ -51,5 +51,8 @@ export const scopedContext = (
 			return context.restart();
 		},
 		log: context.log,
+		print(line, stream) {
+			context.print(line, stream);
+		},
 	};
 };

package/src/runtime/bridgeSetupHandlers.test.ts

@@ -45,6 +45,9 @@ const contextOf = (): BridgeContext => {
 
 	return createContext(settings, supervisor, {
 		onLog: log,
+		onPrint() {
+			return;
+		},
 		onEmit() {
 			return;
 		},

package/src/runtime/bridgeSupervisor.ts

@@ -6,7 +6,7 @@ import { BRIDGE_CRASH_LINE_LIMIT, BridgeCrashPhase, type BridgeCrashRecord } fro
 import { stripAnsi } from "../utils";
 import { createLineSpacing } from "./bridgeLineSpacing";
 import type { BridgeLeveledLogger } from "./bridgeLog";
-import { errorText } from "./bridgeLog";
+import { errorText, print } from "./bridgeLog";
 import { settleUid, unprivilegedArgv } from "./bridgePrivilege";
 import { readProcessGroup, signalGroup } from "./bridgeSignal";
 
@@ -287,11 +287,7 @@ export const createSupervisor = (options: SupervisorOptions) => {
 				}
 			: raw;
 
-		if (entry.stream === BridgeStream.Stderr) {
-			process.stderr.write(`${entry.line}\n`);
-		} else {
-			process.stdout.write(`${entry.line}\n`);
-		}
+		print(entry.line, entry.stream);
 
 		tail.push(entry);
 

package/src/runtime/serve.ts

@@ -19,9 +19,15 @@ import { validateDriver } from "./bridgeDriver";
 import { createEventRing } from "./bridgeEvents";
 import { decideInstall, recountHold } from "./bridgeInstall";
 import { createBridgeLiveConfig } from "./bridgeLiveConfig";
-import { errorDetail, errorText, log as stdoutLog } from "./bridgeLog";
+import { errorDetail, errorText, print, log as stdoutLog } from "./bridgeLog";
 import { pendingResult, rejectedPending, unsupportedPending } from "./bridgePending";
-import { createBridgeRedaction, redactLocalized, redactLogger, secretFieldKeys } from "./bridgeRedaction";
+import {
+	createBridgeRedaction,
+	redactLocalized,
+	redactLogger,
+	redactPrinter,
+	secretFieldKeys,
+} from "./bridgeRedaction";
 import { createRegistry } from "./bridgeRegistry";
 import { createServer } from "./bridgeServer";
 import { setupSummaryOf } from "./bridgeSetup";
@@ -182,6 +188,7 @@ export const serve = async (driver: BridgeDriver) => {
 		supervisor,
 		{
 			onLog: log,
+			onPrint: redactPrinter(print, redact),
 			onEmit(event, payload) {
 				ring.emit(event, payload);
 			},

package/src/wire/panel.test.ts

@@ -13,6 +13,7 @@ import {
 	BridgePlace,
 	type BridgeSetupManifest,
 	BridgeSetupStepKind,
+	type BridgeTerminalManifest,
 	BridgeUploadMode,
 } from "@serverkgg/bridge/protocol";
 import { bridgeAvailabilitySchema, bridgeCellsSchema, bridgeManifestSchema } from "./panel";
@@ -783,3 +784,34 @@ describe("the availability schema", () => {
 		expect(parsed.modules[0]?.actions).toContain(BridgeAction.Availability);
 	});
 });
+
+const terminalManifest = (shell: boolean): BridgeManifest => ({
+	version: "1.0.0",
+	panel: null,
+	terminal: {
+		commands: [],
+		rules: [],
+		shell,
+	},
+	setup: null,
+	modules: [],
+	events: [],
+});
+
+describe("the terminal mirror", () => {
+	it("carries the shell flag through unchanged", () => {
+		expect(bridgeManifestSchema.parse(terminalManifest(true)).terminal?.shell).toBe(true);
+	});
+
+	it("defaults a terminal from an older bridge that carries no shell flag to false", () => {
+		const older = terminalManifest(true);
+
+		delete (older.terminal as Partial<BridgeTerminalManifest>).shell;
+
+		expect(bridgeManifestSchema.parse(older).terminal).toEqual({
+			commands: [],
+			rules: [],
+			shell: false,
+		});
+	});
+});

package/src/wire/panel.ts

@@ -318,6 +318,7 @@ export const bridgeTerminalRuleSchema: z.ZodType<BridgeTerminalRuleManifest> = z
 export const bridgeTerminalManifestSchema: z.ZodType<BridgeTerminalManifest> = z.object({
 	commands: z.array(bridgeTerminalCommandSchema).max(128),
 	rules: z.array(bridgeTerminalRuleSchema).max(64),
+	shell: z.boolean().default(false),
 });
 
 const setupStepBase = {