@hienlh/ppm 0.23.11 → 0.23.12

package/src/services/remote-desktop/mediamtx-install.service.ts

@@ -0,0 +1,191 @@
+/**
+ * Installing the WebRTC relay: download the pinned MediaMTX archive, verify its SHA-256,
+ * unpack it into `<ppm dir>/mediamtx/bin`, and prove the binary actually runs before calling
+ * it installed.
+ *
+ * The last step is not ceremony. `Bun.spawn` **throws** on a missing or unrunnable binary
+ * rather than reporting it (CLAUDE.md), and a host that unpacked a build it cannot execute —
+ * wrong libc, quarantined by Gatekeeper, noexec mount — would otherwise be reported as
+ * installed and fail later at session start, where the user has no way to connect the two.
+ */
+import { chmodSync, existsSync, mkdirSync, rmSync } from "node:fs";
+import { resolve } from "node:path";
+import { downloadVerified, type FetchFn } from "../speech-to-text/whisper-download.ts";
+import { mediamtxAsset, MEDIAMTX_VERSION, type MediamtxAsset } from "./mediamtx-catalog.ts";
+import { activeRelayCount } from "./mediamtx-process.ts";
+import {
+  findMediamtxBinary, mediamtxBinDir, mediamtxBinaryName, mediamtxDir, mediamtxTmpDir,
+} from "./mediamtx-paths.ts";
+
+export interface MediamtxStatus {
+  installed: boolean;
+  /** Absolute path when installed. */
+  path?: string;
+  source?: "bundled" | "system";
+  /** The version PPM pins — not what a `system` copy happens to be. */
+  pinnedVersion: string;
+  /** Null when the release publishes no build for this host; it can still bring its own. */
+  available: boolean;
+}
+
+export function mediamtxStatus(
+  platform: NodeJS.Platform = process.platform,
+  arch: string = process.arch,
+): MediamtxStatus {
+  const found = findMediamtxBinary(platform);
+  return {
+    installed: !!found,
+    path: found?.path,
+    source: found?.source,
+    pinnedVersion: MEDIAMTX_VERSION,
+    available: mediamtxAsset(platform, arch) !== null,
+  };
+}
+
+async function extractArchive(
+  archive: string, asset: MediamtxAsset, destDir: string, platform: NodeJS.Platform,
+): Promise<void> {
+  const cmd =
+    asset.ext === "tar.gz"
+      ? ["tar", "-xzf", archive, "-C", destDir]
+      : platform === "win32"
+        // Windows 10+ ships bsdtar as tar.exe, which reads zip.
+        ? ["tar", "-xf", archive, "-C", destDir]
+        : ["unzip", "-o", "-q", archive, "-d", destDir];
+  const proc = Bun.spawn({ cmd, stdout: "ignore", stderr: "pipe" });
+  const [code, stderr] = await Promise.all([proc.exited, new Response(proc.stderr).text()]);
+  if (code !== 0) throw new Error(`extract failed (${cmd[0]} exit ${code}): ${stderr.slice(0, 200)}`);
+}
+
+/**
+ * `ReturnType<typeof Bun.spawn>` would widen `stdout`/`stderr` back to a union including a raw
+ * fd, which `new Response()` rejects — so the narrow type is preserved by naming the call
+ * (CLAUDE.md, the same trap `gpu-collector-nvidia.ts` hit).
+ */
+const spawnVersionProbe = (path: string) =>
+  Bun.spawn({ cmd: [path, "--version"], stdout: "pipe", stderr: "pipe", windowsHide: true });
+
+/** Run `--version` and require it to exit cleanly. Throws with the host's own words if not. */
+async function proveItRuns(path: string): Promise<string> {
+  let proc: ReturnType<typeof spawnVersionProbe>;
+  try {
+    proc = spawnVersionProbe(path);
+  } catch (e: any) {
+    // Bun.spawn raises synchronously here, so this cannot be folded into the await below.
+    throw new Error(`mediamtx could not be started: ${e?.message ?? e}`);
+  }
+  const [code, out, err] = await Promise.all([
+    proc.exited, new Response(proc.stdout).text(), new Response(proc.stderr).text(),
+  ]);
+  if (code !== 0) throw new Error(`mediamtx exited ${code}: ${(err || out).slice(0, 200)}`);
+  return out.trim() || err.trim();
+}
+
+export interface RelayInstallJob {
+  receivedBytes: number;
+  totalBytes: number;
+  done: boolean;
+  error: string | null;
+}
+
+let currentJob: RelayInstallJob | null = null;
+
+/**
+ * Start an install in the background and return immediately — the UI polls `relayStatus()`.
+ * One at a time: a second call while a job runs throws rather than racing two downloads onto
+ * the same `.part` file.
+ */
+export function startMediamtxInstall(opts: InstallOptions = {}): RelayInstallJob {
+  if (currentJob && !currentJob.done) throw new Error("An install is already running");
+  const job: RelayInstallJob = { receivedBytes: 0, totalBytes: 0, done: false, error: null };
+  currentJob = job;
+  installMediamtx({
+    ...opts,
+    onProgress: (received, total) => { job.receivedBytes = received; job.totalBytes = total; },
+  })
+    .then(() => { job.done = true; })
+    .catch((e: any) => {
+      job.error = e?.message ?? String(e);
+      job.done = true;
+      console.error("[remote-desktop] relay install failed:", job.error);
+    });
+  return job;
+}
+
+/** Status plus whatever install is in flight, which is what the Settings pane renders. */
+export function relayStatus(
+  platform: NodeJS.Platform = process.platform,
+  arch: string = process.arch,
+): MediamtxStatus & { job: RelayInstallJob | null } {
+  return { ...mediamtxStatus(platform, arch), job: currentJob };
+}
+
+/** Test seam: forget any finished job so a suite starts from a clean status. */
+export function _resetRelayInstallState(): void {
+  currentJob = null;
+}
+
+export interface InstallOptions {
+  platform?: NodeJS.Platform;
+  arch?: string;
+  onProgress?: (received: number, total: number) => void;
+  fetchFn?: FetchFn;
+  signal?: AbortSignal;
+}
+
+/** Download, verify, unpack and prove. Returns the version string the binary reports. */
+export async function installMediamtx(opts: InstallOptions = {}): Promise<string> {
+  const platform = opts.platform ?? process.platform;
+  const arch = opts.arch ?? process.arch;
+  const asset = mediamtxAsset(platform, arch);
+  if (!asset) {
+    throw new Error(
+      `MediaMTX publishes no build for ${platform}-${arch}. Install it yourself and put it on PATH.`,
+    );
+  }
+
+  const tmp = mediamtxTmpDir();
+  const binDir = mediamtxBinDir();
+  mkdirSync(tmp, { recursive: true });
+  mkdirSync(binDir, { recursive: true });
+
+  const archive = resolve(tmp, asset.file);
+  await downloadVerified({
+    url: asset.url, dest: archive, sha256: asset.sha256,
+    onProgress: opts.onProgress, fetchFn: opts.fetchFn, signal: opts.signal,
+  });
+
+  try {
+    await extractArchive(archive, asset, binDir, platform);
+  } finally {
+    rmSync(archive, { force: true });
+  }
+
+  const binary = resolve(binDir, mediamtxBinaryName(platform));
+  if (!existsSync(binary)) throw new Error(`archive did not contain ${mediamtxBinaryName(platform)}`);
+  if (platform !== "win32") chmodSync(binary, 0o755);
+
+  // The archive also carries its own mediamtx.yml, which listens on every interface and turns
+  // on RTMP/HLS/SRT/MoQ. PPM generates its own config and must never fall back to that one.
+  rmSync(resolve(binDir, "mediamtx.yml"), { force: true });
+
+  return await proveItRuns(binary);
+}
+
+/**
+ * Remove everything PPM installed. A `system` copy is the host's and is left alone.
+ *
+ * Takes the whole `mediamtx/` directory, not just `bin/`: the per-session configs and the tmp
+ * dir are PPM's too, and both are rebuilt on the next start.
+ */
+export function uninstallMediamtx(platform: NodeJS.Platform = process.platform): boolean {
+  if (currentJob && !currentJob.done) throw new Error("An install is running");
+  // Windows cannot delete a running executable, so removing the folder under a live relay would
+  // fail part-way through it.
+  if (activeRelayCount() > 0) throw new Error("A Remote Desktop session is using the relay; end it first");
+  const found = findMediamtxBinary(platform);
+  if (found?.source !== "bundled") return false;
+  rmSync(mediamtxDir(), { recursive: true, force: true });
+  currentJob = null;
+  return true;
+}

package/src/services/remote-desktop/mediamtx-paths.ts

@@ -0,0 +1,51 @@
+/**
+ * Where the MediaMTX install lives, and how the binary is found.
+ *
+ * Everything PPM downloads sits under `<ppm dir>/mediamtx/` so uninstall is one `rm -rf` and
+ * an isolated `PPM_HOME` (tests) never touches a real install.
+ */
+import { existsSync } from "node:fs";
+import { resolve } from "node:path";
+import { getPpmDir } from "../ppm-dir.ts";
+
+export const mediamtxDir = () => resolve(getPpmDir(), "mediamtx");
+export const mediamtxBinDir = () => resolve(mediamtxDir(), "bin");
+export const mediamtxTmpDir = () => resolve(mediamtxDir(), "tmp");
+
+/**
+ * The generated runtime config. PPM writes this on every start and never uses the
+ * `mediamtx.yml` that ships inside the archive: that one listens on every interface and
+ * enables RTMP, HLS, SRT and MoQ, where PPM needs one loopback RTSP ingest and nothing else.
+ *
+ * One file per relay, named by its stream path. MediaMTX watches its config file and reloads
+ * when it changes, so with one shared file a second session's start rewrote the first relay's
+ * config under it — measured, the first relay stopped answering the moment the second came up.
+ */
+export const mediamtxConfigPath = (pathName: string) => resolve(mediamtxDir(), "run", `${pathName}.yml`);
+
+export const mediamtxBinaryName = (platform: NodeJS.Platform = process.platform) =>
+  platform === "win32" ? "mediamtx.exe" : "mediamtx";
+
+/** The copy PPM installed, or null. The archive is flat, so this is one lookup. */
+export function findBundledMediamtx(platform: NodeJS.Platform = process.platform): string | null {
+  const candidate = resolve(mediamtxBinDir(), mediamtxBinaryName(platform));
+  return existsSync(candidate) ? candidate : null;
+}
+
+export interface MediamtxBinary {
+  path: string;
+  /** `bundled` = installed by PPM and removable from Settings; `system` = the host's own. */
+  source: "bundled" | "system";
+}
+
+/**
+ * A host's own copy is accepted as a fallback because the release publishes no Windows ARM
+ * build (`mediamtx-catalog.ts`), so on that host bringing your own is the only route. PPM
+ * still generates the config either way, so a system copy cannot drag in its own listeners.
+ */
+export function findMediamtxBinary(platform: NodeJS.Platform = process.platform): MediamtxBinary | null {
+  const bundled = findBundledMediamtx(platform);
+  if (bundled) return { path: bundled, source: "bundled" };
+  const onPath = Bun.which(mediamtxBinaryName(platform));
+  return onPath ? { path: onPath, source: "system" } : null;
+}

package/src/services/remote-desktop/mediamtx-process.ts

@@ -0,0 +1,152 @@
+/**
+ * One MediaMTX relay per Remote Desktop session: pick free ports, write the generated config,
+ * spawn the binary, and wait until it is genuinely listening before anything tries to use it.
+ *
+ * "Genuinely listening" is not decorative. MediaMTX exits with a plain `ERR listen tcp ...
+ * address already in use` when a port is taken, and at the `warn` log level PPM asks for, a
+ * successful start prints *nothing at all* — so there is no output to wait for, and a caller
+ * that assumed the spawn meant readiness would push RTSP at a socket that is not there yet.
+ * `waitUntilListening` connects to the loopback signalling port instead.
+ */
+import { mkdirSync, rmSync, writeFileSync } from "node:fs";
+import { dirname } from "node:path";
+import { buildMediamtxConfig, randomStreamPath, rtspPublishUrl, whepUrl } from "./mediamtx-config.ts";
+import { findMediamtxBinary, mediamtxConfigPath } from "./mediamtx-paths.ts";
+
+export interface RelayHandle {
+  /** Where ffmpeg pushes the H.264 it already encoded. */
+  publishUrl: string;
+  /** Loopback WHEP endpoint. Only PPM's authenticated proxy ever calls this. */
+  whepUrl: string;
+  /** This session's unguessable stream path. */
+  pathName: string;
+  stop(): void;
+  isStopped(): boolean;
+}
+
+const active = new Set<RelayHandle>();
+let sweepRegistered = false;
+
+/** Kill every relay on the way out, the way `registerRemoteDesktopExitSweep` does for sessions. */
+export function registerRelayExitSweep(): void {
+  if (sweepRegistered) return;
+  sweepRegistered = true;
+  const sweep = () => { for (const r of [...active]) r.stop(); };
+  process.on("exit", sweep);
+  process.on("SIGINT", sweep);
+  process.on("SIGTERM", sweep);
+}
+
+/**
+ * A free TCP port, found by binding one and letting the OS choose.
+ *
+ * Inherently racy — the port is free when asked and could be taken before MediaMTX binds it —
+ * which is why `startRelay` surfaces a bind failure as an error rather than retrying blind.
+ */
+async function freeTcpPort(): Promise<number> {
+  const server = Bun.listen({ hostname: "127.0.0.1", port: 0, socket: { data() {} } });
+  const port = server.port;
+  server.stop(true);
+  return port;
+}
+
+/** Same, for the ICE port. UDP has to be asked separately: a free TCP port says nothing. */
+async function freeUdpPort(): Promise<number> {
+  const sock = await Bun.udpSocket({ port: 0 });
+  const port = sock.port;
+  sock.close();
+  return port;
+}
+
+/** Poll a loopback TCP port until something accepts, or give up. */
+async function waitUntilListening(port: number, timeoutMs = 5_000): Promise<boolean> {
+  const deadline = Date.now() + timeoutMs;
+  while (Date.now() < deadline) {
+    try {
+      const sock = await Bun.connect({ hostname: "127.0.0.1", port, socket: { data() {} } });
+      sock.end();
+      return true;
+    } catch {
+      await Bun.sleep(50);
+    }
+  }
+  return false;
+}
+
+export interface StartRelayOptions {
+  platform?: NodeJS.Platform;
+  /** Overridden by tests; real callers let it find the install. */
+  binaryPath?: string;
+}
+
+/**
+ * Start a relay. Throws when MediaMTX is not installed, when it cannot bind, or when it does
+ * not come up in time — never returns a handle to something that is not serving.
+ */
+export async function startRelay(opts: StartRelayOptions = {}): Promise<RelayHandle> {
+  registerRelayExitSweep();
+
+  const binary = opts.binaryPath ?? findMediamtxBinary(opts.platform ?? process.platform)?.path;
+  if (!binary) throw new Error("the WebRTC relay is not installed");
+
+  const [rtspPort, whepPort, iceUdpPort] = await Promise.all([
+    freeTcpPort(), freeTcpPort(), freeUdpPort(),
+  ]);
+  const pathName = randomStreamPath();
+
+  const configPath = mediamtxConfigPath(pathName);
+  mkdirSync(dirname(configPath), { recursive: true });
+  writeFileSync(configPath, buildMediamtxConfig({ rtspPort, whepPort, iceUdpPort, pathName }), {
+    // The config names this session's stream path, which is a per-session secret.
+    mode: 0o600,
+  });
+
+  const proc = Bun.spawn({
+    cmd: [binary, configPath],
+    stdout: "pipe", stderr: "pipe", windowsHide: true,
+  });
+
+  let stopped = false;
+  // The file names this session's stream path, and nothing reads it once the relay is gone.
+  const removeConfig = () => { try { rmSync(configPath, { force: true }); } catch { /* still held */ } };
+  const handle: RelayHandle = {
+    publishUrl: rtspPublishUrl(rtspPort, pathName),
+    whepUrl: whepUrl(whepPort, pathName),
+    pathName,
+    stop() {
+      if (stopped) return;
+      stopped = true;
+      active.delete(handle);
+      try { proc.kill(); } catch { /* already gone */ }
+      removeConfig();
+    },
+    isStopped: () => stopped,
+  };
+  active.add(handle);
+
+  if (!(await waitUntilListening(whepPort))) {
+    // MediaMTX prints the reason (a taken port, a rejected config key) and exits; hand that
+    // text back rather than a bare timeout, because it names the actual fault every time.
+    handle.stop();
+    const why = (await new Response(proc.stderr).text()).trim()
+      || (await new Response(proc.stdout).text()).trim();
+    throw new Error(`the WebRTC relay did not start${why ? `: ${why.slice(0, 300)}` : ""}`);
+  }
+
+  // A relay that dies mid-session must not look alive to the rest of the code. The config is
+  // removed once more after the exit, in case `stop` found it still open: Windows cannot delete
+  // an open file.
+  void proc.exited.then(() => { handle.stop(); removeConfig(); });
+
+  return handle;
+}
+
+/** How many relays are serving right now. */
+export function activeRelayCount(): number {
+  return active.size;
+}
+
+/** Test seam and a safety net for teardown paths that lose their handle. */
+export function stopAllRelays(): void {
+  for (const r of [...active]) r.stop();
+}