switched rover <-> server streams to rtsptcp, and moved mediamtx to be a server owned and configured child process!

server/src/services/mediaMtxService/config.js

@@ -0,0 +1,100 @@
+// MediaMTX Config Builder
+// Purpose: Converts the rover server's media settings into the complete MediaMTX runtime configuration.
+// Scope: Keeps deployment-specific hosts in config.yaml while keeping protocol policy owned by the application.
+const path = require('path');
+
+function normalizeAdditionalHosts(rawHosts) {
+  if (rawHosts == null) return [];
+  if (!Array.isArray(rawHosts)) {
+    throw new Error('media.additionalHosts must be a list');
+  }
+
+  /*
+    MediaMTX accepts both IP addresses and DNS names here. Preserve that flexibility because
+    an installation can need a public candidate and a LAN candidate at the same time. Empty
+    entries and duplicates are removed so a harmless config typo does not create redundant
+    ICE candidates, while the values themselves remain entirely instance-owned.
+  */
+  return [...new Set(rawHosts.map((value) => String(value || '').trim()).filter(Boolean))];
+}
+
+function buildMediaMtxConfig({ config, serverPort, snapshotWriterPath }) {
+  const media = config?.media || {};
+  let additionalHosts = normalizeAdditionalHosts(media.additionalHosts);
+  if (!additionalHosts.length && media.whepBaseUrl) {
+    try {
+      /*
+        Existing installations predate media.additionalHosts. Using the already-configured
+        WHEP hostname as a one-host migration default keeps them reachable on first restart;
+        administrators can still list every public and LAN candidate explicitly afterward.
+      */
+      additionalHosts = [new URL(media.whepBaseUrl).hostname].filter(Boolean);
+    } catch {
+      throw new Error('media.whepBaseUrl must be a valid URL when media.additionalHosts is empty');
+    }
+  }
+  const authPort = Number(serverPort) || 8080;
+
+  return {
+    logLevel: 'info',
+    api: true,
+    apiAddress: '127.0.0.1:9997',
+    metrics: true,
+    metricsAddress: '127.0.0.1:9998',
+    pprof: false,
+    pprofAddress: '127.0.0.1:9999',
+
+    /*
+      Rover publishers and readers always request TCP explicitly. Declaring only TCP here
+      also prevents MediaMTX from opening the separate RTP/RTCP UDP listeners, which are not
+      useful for this local-network deployment and performed poorly in the measured tests.
+    */
+    rtsp: true,
+    rtspAddress: ':8554',
+    rtspTransports: ['tcp'],
+    rtmp: false,
+    hls: false,
+
+    webrtc: true,
+    webrtcLocalUDPAddress: ':8189',
+    webrtcLocalTCPAddress: ':8189',
+    webrtcAdditionalHosts: additionalHosts,
+    webrtcICEServers2: [
+      { url: 'stun:stun.l.google.com:19302' },
+      { url: 'stun:stun1.l.google.com:19302' },
+      { url: 'stun:stun2.l.google.com:19302' },
+      { url: 'stun:stun3.l.google.com:19302' },
+      { url: 'stun:stun4.l.google.com:19302' },
+      { url: 'stun:stun.cloudflare.com:3478' },
+    ],
+
+    /*
+      Several server-local paths still use SRT: PTZ publishing, replay capture, and the snapshot
+      writer. Rover media moves to RTSP, but removing this listener would break those independent
+      consumers, so both listeners remain deliberately enabled.
+    */
+    srt: true,
+    srtAddress: ':9000',
+
+    authMethod: 'http',
+    authHTTPAddress: `http://127.0.0.1:${authPort}/mediamtx/auth`,
+    authHTTPExclude: [
+      { action: 'api' },
+      { action: 'metrics' },
+      { action: 'pprof' },
+    ],
+    paths: {
+      all: {
+        source: 'publisher',
+        sourceOnDemand: false,
+        runOnReady: path.resolve(snapshotWriterPath),
+        runOnReadyRestart: true,
+      },
+    },
+  };
+}
+
+module.exports = {
+  buildMediaMtxConfig,
+  normalizeAdditionalHosts,
+};

server/src/services/mediaMtxService/config.test.js

@@ -0,0 +1,45 @@
+// MediaMTX Config Builder Tests
+// Purpose: Pins the generated protocol policy and instance-specific ICE host handling.
+// Scope: Tests pure configuration output without starting listeners or leaving a child process running.
+const test = require('node:test');
+const assert = require('node:assert/strict');
+const { buildMediaMtxConfig, normalizeAdditionalHosts } = require('./config');
+
+test('generates RTSP over TCP without deployment-specific hardcodes', () => {
+  const generated = buildMediaMtxConfig({
+    config: {
+      media: {
+        whepBaseUrl: 'http://media.internal:8889/video',
+        additionalHosts: ['public.example.com', '10.20.30.40'],
+      },
+    },
+    serverPort: 8123,
+    snapshotWriterPath: '/opt/multirover/rover-snapshot-writer.sh',
+  });
+
+  assert.equal(generated.rtsp, true);
+  assert.equal(generated.rtspAddress, ':8554');
+  assert.deepEqual(generated.rtspTransports, ['tcp']);
+  assert.equal(Object.hasOwn(generated, 'rtpAddress'), false);
+  assert.equal(Object.hasOwn(generated, 'rtcpAddress'), false);
+  assert.deepEqual(generated.webrtcAdditionalHosts, ['public.example.com', '10.20.30.40']);
+  assert.equal(generated.authHTTPAddress, 'http://127.0.0.1:8123/mediamtx/auth');
+});
+
+test('uses the configured WHEP hostname while an older config has no additionalHosts', () => {
+  const generated = buildMediaMtxConfig({
+    config: { media: { whepBaseUrl: 'https://second-server.example/video' } },
+    serverPort: 8080,
+    snapshotWriterPath: '/usr/local/bin/rover-snapshot-writer.sh',
+  });
+
+  assert.deepEqual(generated.webrtcAdditionalHosts, ['second-server.example']);
+});
+
+test('normalizes duplicate and empty additional hosts', () => {
+  assert.deepEqual(
+    normalizeAdditionalHosts([' media.local ', '', 'media.local', null, 'public.example']),
+    ['media.local', 'public.example'],
+  );
+  assert.throws(() => normalizeAdditionalHosts('media.local'), /must be a list/);
+});

server/src/services/mediaMtxService/index.js

@@ -0,0 +1,46 @@
+// MediaMTX Service
+// Purpose: Composes server configuration, runtime paths, and child-process supervision.
+// Scope: Starts MediaMTX only after the HTTP auth endpoint is listening and stops it with the server.
+const { loadConfig } = require('../../helpers/configLoader');
+const globalConfig = require('../../globals/config');
+const logger = require('../../globals/logger').child('mediamtx');
+const { createMediaMtxSupervisor } = require('./supervisor');
+
+const supervisor = createMediaMtxSupervisor({
+  config: loadConfig(),
+  serverPort: globalConfig.port,
+  logger,
+});
+
+function startMediaMtx() {
+  return supervisor.start();
+}
+
+/*
+  Other services already use process signal hooks for their own workers. This hook performs
+  only synchronous signal delivery; systemd's default control-group cleanup remains the final
+  guarantee if the parent is killed before the child finishes exiting.
+*/
+process.once('exit', () => supervisor.stop());
+
+function stopForSignal(signal) {
+  let completed = false;
+  const finish = () => {
+    if (completed) return;
+    completed = true;
+    process.exit(signal === 'SIGINT' ? 130 : 143);
+  };
+
+  supervisor.stop(finish);
+  /*
+    A wedged child must not make systemd wait indefinitely. This timer is deliberately unref'd
+    so it never keeps an otherwise-finished process alive; it is only a bound on graceful exit.
+  */
+  const forceExitTimer = setTimeout(finish, 5000);
+  forceExitTimer.unref?.();
+}
+
+process.once('SIGINT', () => stopForSignal('SIGINT'));
+process.once('SIGTERM', () => stopForSignal('SIGTERM'));
+
+module.exports = { startMediaMtx };

server/src/services/mediaMtxService/supervisor.js

@@ -0,0 +1,103 @@
+// MediaMTX Child Supervisor
+// Purpose: Writes the generated runtime configuration and owns the MediaMTX child process lifecycle.
+// Scope: Starts exactly one child, forwards its logs, and lets systemd restart the coherent server/media pair.
+const fs = require('fs');
+const path = require('path');
+const { spawn } = require('child_process');
+const yaml = require('js-yaml');
+const { buildMediaMtxConfig } = require('./config');
+
+function createMediaMtxSupervisor(deps) {
+  const {
+    config,
+    serverPort,
+    logger,
+    mediaMtxBin = process.env.MEDIAMTX_BIN || '/usr/local/bin/mediamtx',
+    runtimeDir = process.env.MULTIROVER_RUNTIME_DIR || '/run/multirover',
+    snapshotWriterPath = process.env.ROVER_SNAPSHOT_WRITER_BIN || '/usr/local/bin/rover-snapshot-writer.sh',
+    spawnProcess = spawn,
+  } = deps;
+
+  let child = null;
+  let stopping = false;
+  let stoppedCallback = null;
+
+  function forwardLines(stream, level) {
+    let pending = '';
+    stream.setEncoding('utf8');
+    stream.on('data', (chunk) => {
+      pending += chunk;
+      const lines = pending.split(/\r?\n/);
+      pending = lines.pop() || '';
+      lines.filter(Boolean).forEach((line) => logger[level](line));
+    });
+    stream.on('end', () => {
+      if (pending) logger[level](pending);
+    });
+  }
+
+  function start() {
+    if (child) return child;
+
+    const runtimeConfig = buildMediaMtxConfig({ config, serverPort, snapshotWriterPath });
+    const configPath = path.join(runtimeDir, 'mediamtx.yml');
+    fs.mkdirSync(runtimeDir, { recursive: true, mode: 0o750 });
+    fs.writeFileSync(configPath, yaml.dump(runtimeConfig, { noRefs: true, lineWidth: 120 }), { mode: 0o640 });
+
+    logger.info(`Starting MediaMTX with generated config ${configPath}`);
+    child = spawnProcess(mediaMtxBin, [configPath], {
+      stdio: ['ignore', 'pipe', 'pipe'],
+    });
+
+    forwardLines(child.stdout, 'info');
+    forwardLines(child.stderr, 'warn');
+
+    child.once('error', (err) => {
+      logger.error('Unable to start MediaMTX', err);
+      if (!stopping) {
+        /*
+          A spawn failure does not reliably emit the normal exit event on every platform.
+          Fail the parent here as well so the server can never stay nominally online without
+          its required media child and systemd gets the opportunity to repair the launch.
+        */
+        process.exit(1);
+      }
+    });
+    child.once('exit', (code, signal) => {
+      child = null;
+      if (stopping) {
+        stoppedCallback?.();
+        stoppedCallback = null;
+        return;
+      }
+
+      /*
+        MediaMTX is required for every live media path. Exiting the parent is intentionally
+        simpler and safer than maintaining a second retry policy inside Node: systemd already
+        restarts multirover.service, producing one clean server/MediaMTX lifecycle.
+      */
+      logger.error(`MediaMTX exited unexpectedly (code=${code ?? 'none'} signal=${signal || 'none'})`);
+      process.exit(1);
+    });
+    return child;
+  }
+
+  function stop(onStopped) {
+    stopping = true;
+    stoppedCallback = typeof onStopped === 'function' ? onStopped : null;
+    if (!child) {
+      stoppedCallback?.();
+      stoppedCallback = null;
+      return;
+    }
+    try {
+      child.kill('SIGTERM');
+    } catch (err) {
+      logger.warn('Unable to stop MediaMTX cleanly', err);
+    }
+  }
+
+  return { start, stop };
+}
+
+module.exports = { createMediaMtxSupervisor };