@livedesk/hub 0.1.26 → 0.1.28

package/src/mode4-atlas.js

@@ -2,6 +2,61 @@ import { fork } from 'node:child_process';
 import { fileURLToPath } from 'node:url';
 
 const workerPath = fileURLToPath(new URL('./mode4-atlas-worker.js', import.meta.url));
+const WORKER_CLOSE_GRACE_MS = 2_500;
+const WORKER_FORCE_EXIT_MS = 750;
+const ENCODER_PARENT_TERM_MS = 250;
+const ENCODER_PARENT_KILL_MS = 750;
+
+function waitForChildExit(child, timeoutMs) {
+  if (!child || child.exitCode !== null || child.signalCode !== null) {
+    return Promise.resolve(true);
+  }
+  return new Promise(resolve => {
+    let settled = false;
+    let timer = null;
+    const finish = exited => {
+      if (settled) return;
+      settled = true;
+      if (timer) clearTimeout(timer);
+      child.off('exit', handleExit);
+      child.off('close', handleExit);
+      resolve(exited);
+    };
+    const handleExit = () => finish(true);
+    child.once('exit', handleExit);
+    child.once('close', handleExit);
+    timer = setTimeout(() => finish(
+      child.exitCode !== null || child.signalCode !== null
+    ), Math.max(1, Number(timeoutMs || 0)));
+    timer.unref?.();
+  });
+}
+
+function processIsAlive(pid) {
+  if (!Number.isSafeInteger(pid) || pid <= 0) return false;
+  try {
+    process.kill(pid, 0);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+async function terminateExactProcess(pid) {
+  if (!processIsAlive(pid)) return true;
+  try { process.kill(pid, 'SIGTERM'); } catch {}
+  const termDeadline = Date.now() + ENCODER_PARENT_TERM_MS;
+  while (processIsAlive(pid) && Date.now() < termDeadline) {
+    await new Promise(resolve => setTimeout(resolve, 25));
+  }
+  if (!processIsAlive(pid)) return true;
+  try { process.kill(pid, 'SIGKILL'); } catch {}
+  const killDeadline = Date.now() + ENCODER_PARENT_KILL_MS;
+  while (processIsAlive(pid) && Date.now() < killDeadline) {
+    await new Promise(resolve => setTimeout(resolve, 25));
+  }
+  return !processIsAlive(pid);
+}
 
 export class Mode4AtlasSession {
   constructor(options = {}) {
@@ -19,7 +74,26 @@ export class Mode4AtlasSession {
     this.pendingFrames = new Map();
     this.frameSendsInFlight = new Set();
     this.workerGeneration = 0;
-    this.startWorker();
+    this.encoderOwner = null;
+    this.workerExitCleanupPromises = new Map();
+    this.closePromise = null;
+    this.startBarrier = null;
+    if (options.startAfter && typeof options.startAfter.then === 'function') {
+      this.startBarrier = Promise.resolve(options.startAfter)
+        .catch(error => {
+          this.onStatus({
+            type: 'status',
+            state: 'prior-worker-close-error',
+            error: error instanceof Error ? error.message : String(error)
+          });
+        })
+        .then(() => {
+          this.startBarrier = null;
+          this.startWorker();
+        });
+    } else {
+      this.startWorker();
+    }
   }
 
   startWorker() {
@@ -33,7 +107,26 @@ export class Mode4AtlasSession {
     });
     this.worker = worker;
     worker.on('message', message => {
-      if (message?.type === 'frame' && message.metadata && message.payload) {
+      if (message?.type === 'encoder-owner') {
+        const pid = Number(message.pid || 0);
+        const encoderGeneration = Number(message.encoderGeneration || 0);
+        if (message.state === 'active' && Number.isSafeInteger(pid) && pid > 0) {
+          this.encoderOwner = {
+            pid,
+            encoderGeneration,
+            workerGeneration,
+            stopPromise: null
+          };
+        } else if (message.state === 'exited'
+          && this.encoderOwner?.workerGeneration === workerGeneration
+          && this.encoderOwner?.pid === pid
+          && this.encoderOwner?.encoderGeneration === encoderGeneration) {
+          this.encoderOwner = null;
+        }
+        this.onStatus(message);
+      } else if (this.closed) {
+        return;
+      } else if (message?.type === 'frame' && message.metadata && message.payload) {
         this.onFrame({
           metadata: { ...message.metadata, workerGeneration },
           payload: Buffer.from(message.payload)
@@ -45,15 +138,14 @@ export class Mode4AtlasSession {
       }
     });
     worker.on('exit', code => {
-      if (this.worker === worker) this.worker = null;
-      this.frameSendsInFlight.clear();
-      if (this.closed) return;
-      this.onStatus({ type: 'status', state: 'worker-restart', code });
-      clearTimeout(this.restartTimer);
-      this.restartTimer = setTimeout(() => {
-        this.startWorker();
-        if (this.config) this.worker?.send({ type: 'configure', ...this.config });
-      }, 750);
+      const cleanupPromise = this.handleWorkerExit(worker, workerGeneration, code);
+      this.workerExitCleanupPromises.set(workerGeneration, cleanupPromise);
+      const retireCleanupOwner = () => {
+        if (this.workerExitCleanupPromises.get(workerGeneration) === cleanupPromise) {
+          this.workerExitCleanupPromises.delete(workerGeneration);
+        }
+      };
+      void cleanupPromise.then(retireCleanupOwner, retireCleanupOwner);
     });
     worker.on('error', error => this.onStatus({ type: 'status', state: 'worker-error', error: error.message }));
     if (this.config) {
@@ -63,6 +155,49 @@ export class Mode4AtlasSession {
     }
   }
 
+  async stopEncoderOwnerForWorker(workerGeneration, reason) {
+    const owner = this.encoderOwner;
+    if (!owner || owner.workerGeneration !== workerGeneration) return true;
+    if (owner.stopPromise) return owner.stopPromise;
+    owner.stopPromise = terminateExactProcess(owner.pid).then(exited => {
+      if (!exited) {
+        this.onStatus({
+          type: 'status',
+          state: 'encoder-parent-stop-failed',
+          error: `Mode 4 encoder pid ${owner.pid} survived ${reason}.`,
+          pid: owner.pid,
+          encoderGeneration: owner.encoderGeneration,
+          workerGeneration
+        });
+      } else {
+        this.onStatus({
+          type: 'encoder-owner',
+          state: 'exited',
+          source: 'parent-reaper',
+          pid: owner.pid,
+          encoderGeneration: owner.encoderGeneration,
+          workerGeneration
+        });
+      }
+      if (exited && this.encoderOwner === owner) this.encoderOwner = null;
+      return exited;
+    });
+    return owner.stopPromise;
+  }
+
+  async handleWorkerExit(worker, workerGeneration, code) {
+    if (this.worker === worker) this.worker = null;
+    this.frameSendsInFlight.clear();
+    await this.stopEncoderOwnerForWorker(workerGeneration, 'worker-exit');
+    if (this.closed) return;
+    this.onStatus({ type: 'status', state: 'worker-restart', code });
+    clearTimeout(this.restartTimer);
+    this.restartTimer = setTimeout(() => {
+      this.startWorker();
+      if (this.config) this.worker?.send({ type: 'configure', ...this.config });
+    }, 750);
+  }
+
   configure(options = {}) {
     this.deviceIds = [...new Set((Array.isArray(options.deviceIds) ? options.deviceIds : [])
       .map(value => String(value || '').trim()).filter(Boolean))].slice(0, 100);
@@ -103,7 +238,7 @@ export class Mode4AtlasSession {
   }
 
   ingest(frameEvent) {
-    if (this.closed || !this.worker) return;
+    if (this.closed) return;
     const frame = frameEvent?.frame || {};
     const deviceId = String(frameEvent?.deviceId || frame.deviceId || '').trim();
     const mode = String(frame.frameMode || frame.mode || '').toLowerCase();
@@ -129,14 +264,43 @@ export class Mode4AtlasSession {
   }
 
   close() {
-    if (this.closed) return;
+    if (this.closePromise) return this.closePromise;
     this.closed = true;
     clearTimeout(this.restartTimer);
     this.pendingFrames.clear();
     this.frameSendsInFlight.clear();
     const worker = this.worker;
-    this.worker = null;
-    try { worker?.send({ type: 'close' }); } catch {}
-    setTimeout(() => { try { worker?.kill(); } catch {} }, 400).unref?.();
+    const workerGeneration = this.workerGeneration;
+    this.closePromise = (async () => {
+      if (!worker) {
+        await this.startBarrier?.catch?.(() => {});
+        await this.workerExitCleanupPromises.get(workerGeneration)?.catch?.(() => {});
+        const encoderExited = await this.stopEncoderOwnerForWorker(
+          workerGeneration,
+          'parent-close-without-worker'
+        );
+        return { workerExited: true, encoderExited };
+      }
+      try { worker.send({ type: 'close' }); } catch {}
+      let workerExited = await waitForChildExit(worker, WORKER_CLOSE_GRACE_MS);
+      if (!workerExited) {
+        await this.stopEncoderOwnerForWorker(workerGeneration, 'parent-close-timeout');
+        try { worker.kill('SIGKILL'); } catch {}
+        workerExited = await waitForChildExit(worker, WORKER_FORCE_EXIT_MS);
+      }
+      await Promise.resolve();
+      await this.workerExitCleanupPromises.get(workerGeneration)?.catch?.(() => {});
+      const encoderExited = await this.stopEncoderOwnerForWorker(workerGeneration, 'parent-close-final');
+      if (!workerExited) {
+        this.onStatus({
+          type: 'status',
+          state: 'worker-stop-failed',
+          error: `Mode 4 worker pid ${Number(worker.pid || 0)} did not exit during close.`,
+          workerGeneration
+        });
+      }
+      return { workerExited, encoderExited };
+    })();
+    return this.closePromise;
   }
 }

package/src/remote-audio-subscription-contract.mjs

@@ -0,0 +1,109 @@
+function normalizedText(value, maxLength = 160) {
+  return String(value || '').trim().slice(0, maxLength);
+}
+
+export function normalizeRemoteAudioStreamBindings(payload = {}, deviceIds = []) {
+  const bindings = new Map();
+  const byDevice = payload?.streamIdsByDeviceId;
+  if (byDevice && typeof byDevice === 'object' && !Array.isArray(byDevice)) {
+    for (const deviceId of deviceIds) {
+      const streamId = normalizedText(byDevice[deviceId], 128);
+      if (streamId) {
+        bindings.set(deviceId, streamId);
+      }
+    }
+  }
+  if (Array.isArray(payload?.streamBindings)) {
+    for (const binding of payload.streamBindings) {
+      const deviceId = normalizedText(binding?.deviceId);
+      const streamId = normalizedText(binding?.streamId, 128);
+      if (deviceIds.includes(deviceId) && streamId) {
+        bindings.set(deviceId, streamId);
+      }
+    }
+  }
+  if (deviceIds.length === 1 && !bindings.has(deviceIds[0])) {
+    const streamId = normalizedText(payload?.streamId, 128);
+    if (streamId) {
+      bindings.set(deviceIds[0], streamId);
+    }
+  }
+  return bindings;
+}
+
+export function remoteAudioSubscriberOwns(client, deviceId, streamId = '') {
+  const subscribedDeviceIds = client?.liveDeskAudioDeviceIds;
+  if (!(subscribedDeviceIds instanceof Set)
+    || subscribedDeviceIds.size === 0
+    || !subscribedDeviceIds.has(deviceId)) {
+    return !(subscribedDeviceIds instanceof Set) || subscribedDeviceIds.size === 0;
+  }
+  const expectedStreamId = normalizedText(streamId, 128);
+  const boundStreamId = client?.liveDeskAudioStreamIdsByDeviceId instanceof Map
+    ? normalizedText(client.liveDeskAudioStreamIdsByDeviceId.get(deviceId), 128)
+    : '';
+  // A legacy subscriber without an exact binding remains a wildcard owner.
+  return !expectedStreamId || !boundStreamId || boundStreamId === expectedStreamId;
+}
+
+export function collectReleasedRemoteAudioOwners({
+  previousDeviceIds,
+  previousStreamIdsByDeviceId,
+  nextDeviceIds,
+  nextStreamIdsByDeviceId,
+  fallbackOwners = []
+}) {
+  const previousIds = previousDeviceIds instanceof Set ? previousDeviceIds : new Set();
+  const nextIds = nextDeviceIds instanceof Set ? nextDeviceIds : new Set();
+  if (previousIds.size === 0) {
+    return fallbackOwners.map(owner => ({
+      deviceId: normalizedText(owner?.deviceId),
+      streamId: normalizedText(owner?.streamId, 128)
+    })).filter(owner => owner.deviceId);
+  }
+  const owners = [];
+  for (const deviceId of previousIds) {
+    const previousStreamId = previousStreamIdsByDeviceId instanceof Map
+      ? normalizedText(previousStreamIdsByDeviceId.get(deviceId), 128)
+      : '';
+    const nextStreamId = nextStreamIdsByDeviceId instanceof Map
+      ? normalizedText(nextStreamIdsByDeviceId.get(deviceId), 128)
+      : '';
+    if (!nextIds.has(deviceId) || previousStreamId !== nextStreamId) {
+      owners.push({ deviceId, streamId: previousStreamId });
+    }
+  }
+  return owners;
+}
+
+export function observeRemoteAudioStopConfirmation({
+  result,
+  deviceId,
+  streamId,
+  reason,
+  hasSubscriber,
+  disconnect,
+  warn = () => {}
+}) {
+  if (!result?.stopPromise) {
+    return false;
+  }
+  void Promise.resolve(result.stopPromise).then(confirmation => {
+    if (confirmation?.captureStopConfirmed === true) {
+      return;
+    }
+    if (!hasSubscriber(deviceId, streamId)) {
+      warn(
+        `audio capture stop was not confirmed device=${deviceId} reason=${reason}: `
+        + `${confirmation?.error || 'audio-stop-unconfirmed'}`
+      );
+      disconnect(deviceId, 'audio-capture-stop-unconfirmed');
+    }
+  }).catch(error => {
+    if (!hasSubscriber(deviceId, streamId)) {
+      warn(`audio capture stop confirmation failed device=${deviceId}: ${error instanceof Error ? error.message : String(error)}`);
+      disconnect(deviceId, 'audio-capture-stop-confirmation-failed');
+    }
+  });
+  return true;
+}

package/src/remote-audio-subscription-contract.test.mjs

@@ -0,0 +1,72 @@
+import assert from 'node:assert/strict';
+import test from 'node:test';
+
+import {
+  collectReleasedRemoteAudioOwners,
+  normalizeRemoteAudioStreamBindings,
+  observeRemoteAudioStopConfirmation,
+  remoteAudioSubscriberOwns
+} from './remote-audio-subscription-contract.mjs';
+
+function deferred() {
+  let resolve;
+  const promise = new Promise(resolvePromise => {
+    resolve = resolvePromise;
+  });
+  return { promise, resolve };
+}
+
+test('late old WebSocket cleanup keeps a differently bound replacement owner', () => {
+  const previousDeviceIds = new Set(['device-a']);
+  const previousBindings = new Map([['device-a', 'audio-old']]);
+  const replacement = {
+    liveDeskAudioDeviceIds: new Set(['device-a']),
+    liveDeskAudioStreamIdsByDeviceId: new Map([['device-a', 'audio-new']])
+  };
+  const released = collectReleasedRemoteAudioOwners({
+    previousDeviceIds,
+    previousStreamIdsByDeviceId: previousBindings,
+    nextDeviceIds: new Set(),
+    nextStreamIdsByDeviceId: new Map()
+  });
+
+  assert.deepEqual(released, [{ deviceId: 'device-a', streamId: 'audio-old' }]);
+  assert.equal(remoteAudioSubscriberOwns(replacement, 'device-a', 'audio-old'), false);
+  assert.equal(remoteAudioSubscriberOwns(replacement, 'device-a', 'audio-new'), true);
+});
+
+test('subscription binding change releases only the exact old stream', () => {
+  const nextBindings = normalizeRemoteAudioStreamBindings({
+    streamIdsByDeviceId: { 'device-a': 'audio-new' }
+  }, ['device-a']);
+  assert.deepEqual(
+    collectReleasedRemoteAudioOwners({
+      previousDeviceIds: new Set(['device-a']),
+      previousStreamIdsByDeviceId: new Map([['device-a', 'audio-old']]),
+      nextDeviceIds: new Set(['device-a']),
+      nextStreamIdsByDeviceId: nextBindings
+    }),
+    [{ deviceId: 'device-a', streamId: 'audio-old' }]
+  );
+});
+
+test('deduplicated API-first stop failure still forces final Agent drain', async () => {
+  const stop = deferred();
+  const disconnects = [];
+  const result = { stopPromise: stop.promise };
+  assert.equal(observeRemoteAudioStopConfirmation({
+    result,
+    deviceId: 'device-a',
+    streamId: 'audio-current',
+    reason: 'audio-subscriber-closed',
+    hasSubscriber: () => false,
+    disconnect: (...args) => disconnects.push(args)
+  }), true);
+
+  stop.resolve({ captureStopConfirmed: false, error: 'native-audio-stop-failed' });
+  await stop.promise;
+  await Promise.resolve();
+  assert.deepEqual(disconnects, [
+    ['device-a', 'audio-capture-stop-unconfirmed']
+  ]);
+});