@coasys/ad4m 0.13.1-staging.7 → 0.13.1-staging.9

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (93) hide show
  1. package/lib/index.cjs +652 -147
  2. package/lib/index.js +648 -148
  3. package/lib/src/agent/AgentClient.d.ts +6 -0
  4. package/lib/src/agent/AgentClient.js +17 -0
  5. package/lib/src/agent/AgentKind.d.ts +17 -0
  6. package/lib/src/agent/AgentKind.js +21 -0
  7. package/lib/src/apiClient.d.ts +4 -1
  8. package/lib/src/apiClient.js +13 -4
  9. package/lib/src/generated/api/CallSessionInfo.d.ts +1 -1
  10. package/lib/src/generated/api/Events.d.ts +2 -0
  11. package/lib/src/generated/api/PerspectiveModelSubscribeParams.d.ts +11 -0
  12. package/lib/src/generated/api/PerspectiveModelSubscribeParams.js +2 -0
  13. package/lib/src/generated/api/PerspectiveSubscribeQueryParams.d.ts +9 -0
  14. package/lib/src/generated/api/PerspectiveSubscribeQueryParams.js +2 -0
  15. package/lib/src/generated/api/RpcMethods.d.ts +10 -4
  16. package/lib/src/generated/api/RpcMethods.js +5 -0
  17. package/lib/src/generated/api/SfuAddIceCandidateParams.d.ts +4 -0
  18. package/lib/src/generated/api/SfuAnswerServerOfferParams.d.ts +4 -0
  19. package/lib/src/generated/api/SfuCallJoinParams.d.ts +13 -0
  20. package/lib/src/generated/api/SfuCallLeaveParams.d.ts +12 -0
  21. package/lib/src/generated/api/SfuCallLeaveParams.js +2 -0
  22. package/lib/src/generated/api/SfuCallRenegotiationOffer.d.ts +5 -0
  23. package/lib/src/generated/api/SfuDataMessage.d.ts +6 -0
  24. package/lib/src/generated/api/SfuQualityPreferenceParams.d.ts +4 -0
  25. package/lib/src/generated/api/SfuRestartIceParams.d.ts +12 -0
  26. package/lib/src/generated/api/SfuRestartIceParams.js +2 -0
  27. package/lib/src/generated/api/SfuRoomParticipantInfo.d.ts +4 -0
  28. package/lib/src/generated/api/SfuRoomRoster.d.ts +6 -2
  29. package/lib/src/generated/api/SfuRoomRoster.js +0 -1
  30. package/lib/src/generated/api/SfuRosterParticipant.d.ts +7 -0
  31. package/lib/src/generated/api/SfuRosterParticipant.js +2 -0
  32. package/lib/src/generated/api/SfuSendDataParams.d.ts +4 -0
  33. package/lib/src/generated/api/SfuSessionReplaced.d.ts +15 -0
  34. package/lib/src/generated/api/SfuSessionReplaced.js +2 -0
  35. package/lib/src/generated/api/SubscribeQueryRequest.d.ts +4 -0
  36. package/lib/src/generated/api/TrackMapEntry.d.ts +6 -1
  37. package/lib/src/generated/api/index.d.ts +1 -1
  38. package/lib/src/generated/api/index.js +1 -1
  39. package/lib/src/index.d.ts +1 -0
  40. package/lib/src/index.js +1 -0
  41. package/lib/src/neighbourhood/MeshManager.d.ts +19 -2
  42. package/lib/src/neighbourhood/MeshManager.js +55 -8
  43. package/lib/src/neighbourhood/NeighbourhoodClient.d.ts +34 -13
  44. package/lib/src/neighbourhood/NeighbourhoodClient.js +44 -14
  45. package/lib/src/neighbourhood/NeighbourhoodProxy.d.ts +15 -7
  46. package/lib/src/neighbourhood/NeighbourhoodProxy.js +26 -13
  47. package/lib/src/neighbourhood/Session.d.ts +24 -5
  48. package/lib/src/neighbourhood/Session.js +179 -35
  49. package/lib/src/neighbourhood/SfuManager.d.ts +98 -28
  50. package/lib/src/neighbourhood/SfuManager.js +258 -71
  51. package/lib/src/neighbourhood/SfuTypes.d.ts +4 -0
  52. package/lib/src/perspectives/PerspectiveClient.js +33 -4
  53. package/package.json +2 -2
  54. package/src/Ad4mClient.test.ts +5 -5
  55. package/src/agent/AgentClient.ts +20 -0
  56. package/src/agent/AgentKind.ts +28 -0
  57. package/src/agent/mutatePublicPerspective.test.ts +72 -0
  58. package/src/apiClient.test.ts +46 -0
  59. package/src/apiClient.ts +16 -5
  60. package/src/generated/api/CallSessionInfo.ts +1 -1
  61. package/src/generated/api/Events.ts +2 -0
  62. package/src/generated/api/PerspectiveModelSubscribeParams.ts +7 -0
  63. package/src/generated/api/PerspectiveSubscribeQueryParams.ts +7 -0
  64. package/src/generated/api/RpcMethods.ts +14 -4
  65. package/src/generated/api/SfuAddIceCandidateParams.ts +4 -0
  66. package/src/generated/api/SfuAnswerServerOfferParams.ts +4 -0
  67. package/src/generated/api/SfuCallJoinParams.ts +13 -0
  68. package/src/generated/api/SfuCallLeaveParams.ts +11 -0
  69. package/src/generated/api/SfuCallRenegotiationOffer.ts +6 -1
  70. package/src/generated/api/SfuDataMessage.ts +7 -1
  71. package/src/generated/api/SfuQualityPreferenceParams.ts +4 -0
  72. package/src/generated/api/SfuRestartIceParams.ts +11 -0
  73. package/src/generated/api/SfuRoomParticipantInfo.ts +5 -1
  74. package/src/generated/api/SfuRoomRoster.ts +6 -2
  75. package/src/generated/api/SfuRosterParticipant.ts +6 -0
  76. package/src/generated/api/SfuSendDataParams.ts +5 -1
  77. package/src/generated/api/SfuSessionReplaced.ts +13 -0
  78. package/src/generated/api/SubscribeQueryRequest.ts +5 -1
  79. package/src/generated/api/TrackMapEntry.ts +6 -1
  80. package/src/generated/api/index.ts +1 -1
  81. package/src/index.ts +1 -0
  82. package/src/neighbourhood/MeshManager.test.ts +101 -25
  83. package/src/neighbourhood/MeshManager.ts +56 -7
  84. package/src/neighbourhood/NeighbourhoodClient.test.ts +45 -15
  85. package/src/neighbourhood/NeighbourhoodClient.ts +49 -9
  86. package/src/neighbourhood/NeighbourhoodProxy.ts +29 -6
  87. package/src/neighbourhood/Session.test.ts +388 -36
  88. package/src/neighbourhood/Session.ts +185 -38
  89. package/src/neighbourhood/SfuManager.test.ts +626 -20
  90. package/src/neighbourhood/SfuManager.ts +275 -67
  91. package/src/neighbourhood/SfuTypes.ts +4 -0
  92. package/src/perspectives/PerspectiveClient.ts +36 -4
  93. package/src/perspectives/abandoned-subscribe.test.ts +219 -0
@@ -1,16 +1,48 @@
1
- import { SfuManager } from "./SfuManager";
2
- import { MeshManager } from "./MeshManager";
1
+ import { defaultDeviceId, SfuManager } from "./SfuManager";
2
+ import { agentOfMeshPeer, MeshManager, meshPeerId } from "./MeshManager";
3
3
  /**
4
4
  * Call-presence predicate. When the session joins, it publishes an
5
- * online-status link with this predicate and the room id as target.
6
- * Other agents polling `onlineAgents()` use this to discover the
7
- * roster without a join message.
5
+ * online-status link with this predicate, its mesh peer id as source and
6
+ * the room id as target. Other agents polling `onlineAgents()` use this
7
+ * to discover the roster without a join message; one agent's devices each
8
+ * add a link of their own to the agent's one status.
8
9
  */
9
10
  const CALL_PRESENCE_PREDICATE = "ad4m://session/in-call";
10
11
  /** How often (ms) the mesh session polls `onlineAgents` for roster changes. */
11
12
  const ROSTER_POLL_INTERVAL_MS = 3000;
13
+ /**
14
+ * The mesh peer a call-presence link of `did` announces, or `null`. A link
15
+ * counts only for a peer of the agent whose status carries it, so no agent
16
+ * can place another in a call.
17
+ */
18
+ function presencePeer(did, link, roomId) {
19
+ if (link?.predicate !== CALL_PRESENCE_PREDICATE || link.target !== roomId)
20
+ return null;
21
+ const source = link.source;
22
+ if (typeof source !== "string" || source === did || agentOfMeshPeer(source) !== did)
23
+ return null;
24
+ return source;
25
+ }
26
+ /**
27
+ * Where a mesh session hears that this device joined the same call again,
28
+ * from another tab. `BroadcastChannel` reaches every tab of one browser
29
+ * profile — the same reach as the `localStorage` the device id lives in.
30
+ */
31
+ function sameDeviceChannel(agentDid, device, roomId) {
32
+ const Channel = globalThis.BroadcastChannel;
33
+ if (typeof Channel !== "function")
34
+ return null;
35
+ try {
36
+ return new Channel(`ad4m-call:${agentDid}:${device}:${roomId}`);
37
+ }
38
+ catch {
39
+ return null;
40
+ }
41
+ }
12
42
  export function createSession(config) {
13
- const { api, roomId, agentDid, neighbourhoodUrl, topology, sfuConfig, iceServers, channel, setOnlineStatus, ownOnlineStatus, onlineAgents, localSfuStatus, sfuServesAllMembers, } = config;
43
+ const { api, roomId, agentDid, neighbourhoodUrl, topology, sfuConfig, iceServers, deviceId, channel, setOnlineStatus, ownOnlineStatus, onlineAgents, localSfuStatus, sfuServesAllMembers, } = config;
44
+ const device = deviceId || defaultDeviceId();
45
+ const selfPeer = meshPeerId(agentDid, device);
14
46
  let state = "idle";
15
47
  let sfuManager = null;
16
48
  let meshManager = null;
@@ -23,6 +55,8 @@ export function createSession(config) {
23
55
  const trackListeners = [];
24
56
  const dataListeners = [];
25
57
  let dataUnsubscribe = null;
58
+ /** The mesh call's line to this device's other tabs; see {@link sameDeviceChannel}. */
59
+ let sameDevice = null;
26
60
  function emit(event, ...args) {
27
61
  const cbs = callbacks.get(event);
28
62
  if (cbs)
@@ -33,6 +67,13 @@ export function createSession(config) {
33
67
  state = next;
34
68
  emit("state-changed", next);
35
69
  }
70
+ /** `destroy()` ran: a join still resolving must not go on to reach the executor. */
71
+ /** Set when `destroy()` starts, before its awaits: a join that resumes
72
+ * while the session closes must not go on. */
73
+ let destroying = false;
74
+ function destroyed() {
75
+ return destroying || state === "closed";
76
+ }
36
77
  /**
37
78
  * Resolve the effective topology.
38
79
  *
@@ -66,7 +107,7 @@ export function createSession(config) {
66
107
  * leaving restores if the status cannot be read then. */
67
108
  let statusBeforeCall = [];
68
109
  let announced = false;
69
- /** This agent's status links, without this call's presence link. */
110
+ /** This agent's status links, without this device's presence link for this call. */
70
111
  async function ownLinksWithoutCall() {
71
112
  const status = ownOnlineStatus ? await ownOnlineStatus() : null;
72
113
  const links = [];
@@ -74,7 +115,7 @@ export function createSession(config) {
74
115
  const l = link.data;
75
116
  if (!l?.source || l.target === undefined)
76
117
  continue;
77
- if (l.predicate === CALL_PRESENCE_PREDICATE && l.target === roomId)
118
+ if (presencePeer(agentDid, l, roomId) === selfPeer)
78
119
  continue;
79
120
  links.push({ source: l.source, target: l.target, ...(l.predicate ? { predicate: l.predicate } : {}) });
80
121
  }
@@ -92,7 +133,7 @@ export function createSession(config) {
92
133
  console.warn("session: reading own status failed:", err);
93
134
  return [];
94
135
  });
95
- const presence = { source: agentDid, predicate: CALL_PRESENCE_PREDICATE, target: roomId };
136
+ const presence = { source: selfPeer, predicate: CALL_PRESENCE_PREDICATE, target: roomId };
96
137
  await setOnlineStatus({ links: [...statusBeforeCall, presence] });
97
138
  announced = true;
98
139
  }
@@ -119,10 +160,11 @@ export function createSession(config) {
119
160
  /**
120
161
  * Poll online agents and reconcile the mesh roster.
121
162
  *
122
- * Agents in the same call carry a link with predicate
123
- * `CALL_PRESENCE_PREDICATE` and target matching the room id.
124
- * The poll reads the full online-agents list, filters to those
125
- * links, and passes the resulting DID set to `mesh.setRoster()`.
163
+ * Each device in the call carries a link with predicate
164
+ * `CALL_PRESENCE_PREDICATE`, its peer id as source and the room id as
165
+ * target, in its agent's status. The poll reads other agents' statuses
166
+ * from the online-agents list and this agent's own — its other devices —
167
+ * from `ownOnlineStatus`, and passes the peers to `mesh.setRoster()`.
126
168
  * That function opens connections to new arrivals and tears down
127
169
  * connections to departed peers.
128
170
  */
@@ -133,25 +175,28 @@ export function createSession(config) {
133
175
  polling = true;
134
176
  try {
135
177
  const agents = await onlineAgents();
178
+ const own = ownOnlineStatus ? await ownOnlineStatus() : null;
136
179
  // The session left while the poll was in flight.
137
180
  if (meshManager !== mesh)
138
181
  return;
139
- const inCall = [];
140
- for (const agent of agents) {
141
- if (agent.did === agentDid)
142
- continue;
143
- // Each agent's status is a signed perspective: its links
144
- // sit under `data`. Check for the call-presence link
145
- // matching this room.
146
- for (const link of agent.status?.data?.links ?? []) {
147
- const l = link.data;
148
- if (l?.predicate === CALL_PRESENCE_PREDICATE && l.target === roomId) {
149
- inCall.push(agent.did);
150
- break;
151
- }
182
+ const inCall = new Set();
183
+ const collect = (did, links) => {
184
+ for (const link of links ?? []) {
185
+ const peer = presencePeer(did, link.data, roomId);
186
+ if (peer && peer !== selfPeer)
187
+ inCall.add(peer);
152
188
  }
189
+ };
190
+ // Each agent's status is a signed perspective: its links sit
191
+ // under `data`. Whether an executor lists the caller among the
192
+ // online agents varies, so this agent's own status is read here
193
+ // from where it was set, never from the list.
194
+ for (const agent of agents) {
195
+ if (agent.did !== agentDid)
196
+ collect(agent.did, agent.status?.data?.links);
153
197
  }
154
- mesh.setRoster(inCall);
198
+ collect(agentDid, own?.data?.links);
199
+ mesh.setRoster([...inCall]);
155
200
  }
156
201
  catch (err) {
157
202
  console.warn("session: roster poll failed:", err);
@@ -173,9 +218,13 @@ export function createSession(config) {
173
218
  }
174
219
  // ── Mesh wiring helpers ─────────────────────────────────────────
175
220
  function wireMeshEvents(mesh) {
176
- for (const event of ["participant-joined", "participant-left", "participant-updated", "peer-state", "peer-recovery", "error"]) {
221
+ for (const event of ["peer-state", "peer-recovery", "error"]) {
177
222
  mesh.on(event, (...args) => emit(event, ...args));
178
223
  }
224
+ // As the SFU path reports them: the session (here, the device) and the agent it belongs to.
225
+ for (const event of ["participant-joined", "participant-left", "participant-updated"]) {
226
+ mesh.on(event, (p) => emit(event, { ...p, participantId: p.did, did: agentOfMeshPeer(p.did) }));
227
+ }
179
228
  mesh.on("stream-added", (stream, track) => {
180
229
  emit("stream-added", stream, track);
181
230
  for (const cb of trackListeners)
@@ -185,19 +234,83 @@ export function createSession(config) {
185
234
  emit("stream-removed", stream, track);
186
235
  });
187
236
  }
237
+ /**
238
+ * The mesh another tab of this device took over. A destroy also lets the mesh go, so only
239
+ * this tells a join that its call moved on, and that the presence link is no longer its own.
240
+ */
241
+ let replacedMesh = null;
242
+ /**
243
+ * Listen for this device joining the same mesh call from another tab,
244
+ * and tell any tab already in it. Both tabs are one peer, so only one
245
+ * can hold the call: the earlier lets go, without withdrawing the
246
+ * presence link the two share, and says `replaced`.
247
+ */
248
+ function claimDevice(mesh) {
249
+ sameDevice = sameDeviceChannel(agentDid, device, roomId);
250
+ if (!sameDevice)
251
+ return;
252
+ const channel = sameDevice;
253
+ channel.onmessage = (event) => {
254
+ if (meshManager !== mesh || event.data?.joined !== true)
255
+ return;
256
+ replacedMesh = mesh;
257
+ releaseDevice();
258
+ stopRosterPolling();
259
+ if (dataUnsubscribe) {
260
+ dataUnsubscribe();
261
+ dataUnsubscribe = null;
262
+ }
263
+ meshManager = null;
264
+ announced = false;
265
+ void mesh.leave();
266
+ // Idle before listeners hear it: one may join again at once.
267
+ setState("idle");
268
+ emit("replaced", { targetDid: agentDid, neighbourhoodUrl, roomName: roomId, participantId: selfPeer });
269
+ };
270
+ channel.postMessage({ joined: true });
271
+ }
272
+ function releaseDevice() {
273
+ if (!sameDevice)
274
+ return;
275
+ sameDevice.onmessage = null;
276
+ sameDevice.close();
277
+ sameDevice = null;
278
+ }
188
279
  // ── SFU wiring helpers ──────────────────────────────────────────
189
280
  function wireSfuEvents(sfu) {
281
+ // A manager the session let go of (replaced, or left) may still settle a call it
282
+ // made before: none of its events reach the session's listeners.
283
+ const current = () => sfuManager === sfu;
190
284
  for (const event of ["topology-changed", "participant-joined", "participant-left", "active-speaker", "error"]) {
191
- sfu.on(event, (...args) => emit(event, ...args));
285
+ sfu.on(event, (...args) => { if (current())
286
+ emit(event, ...args); });
192
287
  }
193
288
  sfu.on("stream-added", (stream, track) => {
289
+ if (!current())
290
+ return;
194
291
  emit("stream-added", stream, track);
195
292
  for (const cb of trackListeners)
196
293
  cb(stream, track);
197
294
  });
198
295
  sfu.on("stream-removed", (stream, track) => {
296
+ if (!current())
297
+ return;
199
298
  emit("stream-removed", stream, track);
200
299
  });
300
+ // Another tab on this device took the call over. The manager has stopped
301
+ // and will not rejoin; the session is idle and may join again.
302
+ sfu.on("replaced", (event) => {
303
+ if (sfuManager !== sfu)
304
+ return;
305
+ if (dataUnsubscribe) {
306
+ dataUnsubscribe();
307
+ dataUnsubscribe = null;
308
+ }
309
+ sfuManager = null;
310
+ // Idle before listeners hear it: one may join again at once.
311
+ setState("idle");
312
+ emit("replaced", event);
313
+ });
201
314
  }
202
315
  // ── Session object ──────────────────────────────────────────────
203
316
  const session = {
@@ -208,6 +321,8 @@ export function createSession(config) {
208
321
  throw new Error("Session already active");
209
322
  setState("joining");
210
323
  const topo = await resolveTopology();
324
+ if (destroyed())
325
+ throw new Error("Session destroyed");
211
326
  if (topo === "mesh") {
212
327
  if (!channel) {
213
328
  throw new Error("Mesh topology requires a signalling channel — " +
@@ -238,7 +353,7 @@ export function createSession(config) {
238
353
  const mesh = new MeshManager({
239
354
  channel,
240
355
  callId: roomId,
241
- selfId: agentDid,
356
+ selfId: selfPeer,
242
357
  ...(meshIce.length > 0 ? { iceServers: meshIce } : {}),
243
358
  onNetworkChange: (cb) => api.onNetworkChange(cb),
244
359
  checkConnection: () => api.checkConnection(),
@@ -249,11 +364,29 @@ export function createSession(config) {
249
364
  for (const cb of dataListeners)
250
365
  cb(msg);
251
366
  });
367
+ claimDevice(mesh);
252
368
  await mesh.join(localStream);
369
+ // Replaced while joining: the session is idle again.
370
+ if (replacedMesh === mesh)
371
+ return;
372
+ // Destroyed while the mesh joined: destroy() already let the
373
+ // mesh go and found nothing to leave.
374
+ if (destroyed())
375
+ throw new Error("Session destroyed");
253
376
  // Announce this agent's presence in the call, then
254
377
  // start polling so the mesh reconciles connections
255
378
  // against whoever else the roster contains.
256
379
  await announceCallPresence();
380
+ // Replaced while announcing, destroyed or not: the link stays,
381
+ // for the tab that took over.
382
+ if (replacedMesh === mesh) {
383
+ announced = false;
384
+ return;
385
+ }
386
+ if (destroyed()) {
387
+ await withdrawCallPresence();
388
+ throw new Error("Session destroyed");
389
+ }
257
390
  startRosterPolling();
258
391
  emit("topology-changed", "mesh");
259
392
  setState("active");
@@ -263,13 +396,19 @@ export function createSession(config) {
263
396
  const iceConfig = iceServers && iceServers.length > 0
264
397
  ? { servers: iceServers.map(s => ({ urls: s.urls, ...(s.username ? { username: s.username } : {}), ...(s.credential ? { credential: s.credential } : {}) })) }
265
398
  : undefined;
266
- sfuManager = new SfuManager(api, roomId, agentDid, neighbourhoodUrl, iceConfig, sfuConfig);
267
- wireSfuEvents(sfuManager);
268
- dataUnsubscribe = sfuManager.subscribeDataChannel((msg) => {
399
+ const manager = new SfuManager(api, roomId, agentDid, neighbourhoodUrl, iceConfig, sfuConfig, device);
400
+ sfuManager = manager;
401
+ wireSfuEvents(manager);
402
+ dataUnsubscribe = manager.subscribeDataChannel((msg) => {
269
403
  for (const cb of dataListeners)
270
404
  cb(msg);
271
405
  });
272
- await sfuManager.join(localStream);
406
+ await manager.join(localStream);
407
+ if (destroyed())
408
+ throw new Error("Session destroyed");
409
+ // Replaced while joining: the session is idle again.
410
+ if (sfuManager !== manager)
411
+ return;
273
412
  emit("topology-changed", "sfu");
274
413
  setState("active");
275
414
  },
@@ -278,6 +417,7 @@ export function createSession(config) {
278
417
  return;
279
418
  setState("leaving");
280
419
  stopRosterPolling();
420
+ releaseDevice();
281
421
  await withdrawCallPresence();
282
422
  if (dataUnsubscribe) {
283
423
  dataUnsubscribe();
@@ -296,7 +436,8 @@ export function createSession(config) {
296
436
  get participants() {
297
437
  if (meshManager) {
298
438
  return meshManager.getParticipants().map(p => ({
299
- agentDid: p.did,
439
+ participantId: p.did,
440
+ agentDid: agentOfMeshPeer(p.did),
300
441
  stream: p.stream,
301
442
  hasAudio: p.hasAudio,
302
443
  hasVideo: p.hasVideo,
@@ -305,6 +446,7 @@ export function createSession(config) {
305
446
  }
306
447
  if (sfuManager) {
307
448
  return sfuManager.getParticipants().map(p => ({
449
+ participantId: p.participantId,
308
450
  agentDid: p.did,
309
451
  stream: p.stream,
310
452
  hasAudio: p.hasAudio,
@@ -389,12 +531,14 @@ export function createSession(config) {
389
531
  }
390
532
  },
391
533
  async destroy() {
534
+ destroying = true;
392
535
  // Capture refs before leave() nulls them
393
536
  const mesh = meshManager;
394
537
  const sfu = sfuManager;
395
538
  if (state === "active" || state === "joining")
396
539
  await session.leave();
397
540
  stopRosterPolling();
541
+ releaseDevice();
398
542
  if (mesh) {
399
543
  await mesh.destroy();
400
544
  }
@@ -10,25 +10,34 @@
10
10
  * through cascade pipes between executors, so the client never follows
11
11
  * a redirect or a rebalance to another node — it has no way to reach one.
12
12
  *
13
+ * One session per device: a join names this device (`deviceId`), and the
14
+ * executor gives it a participant id that every later call about the
15
+ * session names. The same agent on another device is another participant;
16
+ * a later join from this device — another tab — replaces this session, and
17
+ * the manager stops (`replaced`) rather than taking the call back. Each
18
+ * user join sends a random session key that the rebuilds of that call send
19
+ * again; the executor refuses (409) a key another tab's join replaced, so a
20
+ * tab that missed its `sfu-session-replaced` notice stops all the same.
21
+ *
13
22
  * Applications (Flux, WE, or any other) wrap this class with their
14
23
  * own reactive store and UI layer. The manager itself only touches
15
24
  * Web APIs (RTCPeerConnection, MediaStream) and the AD4M
16
25
  * neighbourhood RPC surface.
17
26
  */
18
27
  import { NeighbourhoodProxy } from "./NeighbourhoodProxy";
19
- import type { CallSessionInfo, SfuCallRenegotiationOffer, SfuConfig, SfuDataMessage, SfuQualityPreference, SfuRoomRoster } from "./SfuTypes";
28
+ import type { CallSessionInfo, SfuCallRenegotiationOffer, SfuConfig, SfuDataMessage, SfuQualityPreference, SfuRoomRoster, SfuSessionReplaced } from "./SfuTypes";
20
29
  /** Minimal interface for the neighbourhood client methods the SFU
21
30
  * manager calls. NeighbourhoodClient satisfies this directly —
22
31
  * pass the client through without an adapter. */
23
32
  export interface SfuNeighbourhoodApi {
24
- sfuCallJoin(neighbourhoodUrl: string, roomName: string, sdpOffer: string): Promise<CallSessionInfo>;
25
- sfuCallLeave(neighbourhoodUrl: string, roomName: string): Promise<boolean>;
26
- sfuCallSetQualityPreference(neighbourhoodUrl: string, roomName: string, preference: SfuQualityPreference): Promise<boolean>;
27
- sfuCallAnswerServerOffer(neighbourhoodUrl: string, roomName: string, sdpAnswer: string): Promise<boolean>;
33
+ sfuCallJoin(neighbourhoodUrl: string, roomName: string, sdpOffer: string, deviceId: string, sessionKey: string): Promise<CallSessionInfo>;
34
+ sfuCallLeave(neighbourhoodUrl: string, roomName: string, participantId: string): Promise<boolean>;
35
+ sfuCallSetQualityPreference(neighbourhoodUrl: string, roomName: string, participantId: string, preference: SfuQualityPreference): Promise<boolean>;
36
+ sfuCallAnswerServerOffer(neighbourhoodUrl: string, roomName: string, participantId: string, sdpAnswer: string): Promise<boolean>;
28
37
  subscribeSfuCallRenegotiationOffer(targetDid: string, callback: (event: SfuCallRenegotiationOffer) => void): () => void;
29
- /** Ask the SFU to restart ICE on this agent's connection; the offer
38
+ /** Ask the SFU to restart ICE on the session `participantId`; the offer
30
39
  * arrives through `subscribeSfuCallRenegotiationOffer`. */
31
- sfuCallRestartIce(neighbourhoodUrl: string, roomName: string): Promise<boolean>;
40
+ sfuCallRestartIce(neighbourhoodUrl: string, roomName: string, participantId: string): Promise<boolean>;
32
41
  /** Called after a network change, once calls reach the executor again. */
33
42
  onNetworkChange(callback: () => void): () => void;
34
43
  /** Check the executor socket now; one found dead is redialled and
@@ -36,10 +45,11 @@ export interface SfuNeighbourhoodApi {
36
45
  * network switch the platform announced nothing for leaves that socket
37
46
  * OPEN and dead, and the restart would go out on it. */
38
47
  checkConnection(): void;
39
- sfuAddIceCandidate(neighbourhoodUrl: string, roomName: string, candidate: string): Promise<boolean>;
40
- sfuSendData(neighbourhoodUrl: string, roomName: string, channelLabel: string, data: string, binary?: boolean): Promise<boolean>;
48
+ sfuAddIceCandidate(neighbourhoodUrl: string, roomName: string, participantId: string, candidate: string): Promise<boolean>;
49
+ sfuSendData(neighbourhoodUrl: string, roomName: string, participantId: string, channelLabel: string, data: string, binary?: boolean): Promise<boolean>;
41
50
  subscribeSfuDataChannel(callback: (message: SfuDataMessage) => void): () => void;
42
51
  subscribeSfuRoomRoster(callback: (roster: SfuRoomRoster) => void): () => void;
52
+ subscribeSfuSessionReplaced(callback: (event: SfuSessionReplaced) => void): () => void;
43
53
  }
44
54
  export type SfuTopology = "sfu" | "mesh" | "cascaded";
45
55
  export interface SfuCallState {
@@ -51,20 +61,31 @@ export interface SfuCallState {
51
61
  localStream: MediaStream | null;
52
62
  peerConnection: RTCPeerConnection | null;
53
63
  }
64
+ /** One session in the call: an agent on two devices is two participants. */
54
65
  export interface SfuParticipantState {
66
+ participantId: string;
55
67
  did: string;
56
68
  stream: MediaStream;
57
69
  hasAudio: boolean;
58
70
  hasVideo: boolean;
59
71
  isActiveSpeaker: boolean;
60
72
  }
61
- export type SfuEvent = "topology-changed" | "participant-joined" | "participant-left" | "active-speaker" | "stream-added" | "stream-removed" | "error";
73
+ export type SfuEvent = "topology-changed" | "participant-joined" | "participant-left" | "active-speaker" | "stream-added" | "stream-removed"
74
+ /** `(SfuSessionReplaced)` — a later join from this device took the call over; this manager stopped. */
75
+ | "replaced" | "error";
62
76
  export type SfuEventCallback = (...args: any[]) => void;
63
77
  /** ICE server configuration for SFU peer connections. */
64
78
  export interface SfuIceConfig {
65
79
  /** Used as given, before `sfuConfig.iceServers`. */
66
80
  servers?: RTCIceServer[];
67
81
  }
82
+ /**
83
+ * This device's id for SFU calls, unless the app gives one. In a browser it
84
+ * is kept in `localStorage`, which every tab of one profile shares, so the
85
+ * tabs of one browser are one device; outside a browser (Node), the process
86
+ * is the device.
87
+ */
88
+ export declare function defaultDeviceId(): string;
68
89
  /**
69
90
  * Determine the optimal call topology from the SFU config and the
70
91
  * current participant count. Returns the topology, the DID of the
@@ -80,6 +101,12 @@ export declare class SfuManager {
80
101
  private neighbourhoodUrl;
81
102
  private roomId;
82
103
  private agentDid;
104
+ /** The device this manager calls from: a later join from it replaces this session. */
105
+ private deviceId;
106
+ /** This call session's key: a rebuild joins with it again, a user's join
107
+ * makes a new one. The executor refuses a key a later join from this
108
+ * device replaced, so a tab that missed its notice cannot take the call back. */
109
+ private sessionKey;
83
110
  private state;
84
111
  private callbacks;
85
112
  private iceServers;
@@ -95,9 +122,9 @@ export declare class SfuManager {
95
122
  private reconnecting;
96
123
  /** Bumped by `leave()`, so a reconnect in flight stops before rejoining. */
97
124
  private generation;
98
- /** Which participant each received media section carries, from the server's mappings. */
125
+ /** Which participant (session and agent) each received media section carries, from the server's mappings. */
99
126
  private midToParticipant;
100
- /** DIDs the roster removed and has not listed since. */
127
+ /** Participant ids the roster removed and has not listed since. */
101
128
  private departed;
102
129
  /** The sender of each kind of local media: declared at join, so a later camera or screen needs no renegotiation. */
103
130
  private senders;
@@ -113,20 +140,33 @@ export declare class SfuManager {
113
140
  private answeredOffer;
114
141
  private renegotiationUnsubscribe;
115
142
  private rosterUnsubscribe;
143
+ /** For the manager's call, not one join: a reconnect between its leave and its join still hears a notice. */
144
+ private replacedUnsubscribe;
145
+ /** Participant ids of this call a notice can still name: the current one, and any whose leave found it gone. */
146
+ private heldIds;
147
+ /** Settles when the latest join has its participant id, or failed. */
148
+ private joinSettled;
116
149
  private dataChannelUnsubscribe;
117
150
  /** An ICE restart is in flight until this fires: ICE going disconnected
118
151
  * again joins it, a network change replaces it. */
119
152
  private restartTimer;
120
153
  private networkUnsubscribe;
121
- /** Running while the room's roster leaves this agent out: see `noticeRoster`. */
154
+ /** Running while the room's roster leaves this session out: see `noticeRoster`. */
122
155
  private unlistedTimer;
123
- /** How long the roster may leave this agent out before the call is rebuilt. */
156
+ /** How long the roster may leave this session out before the call is rebuilt. */
124
157
  private static readonly UNLISTED_GRACE_MS;
125
- constructor(neighbourhood: SfuNeighbourhoodApi, roomId: string, agentDid: string, neighbourhoodUrl?: string, iceConfig?: SfuIceConfig, sfuConfig?: SfuConfig);
158
+ constructor(neighbourhood: SfuNeighbourhoodApi, roomId: string, agentDid: string, neighbourhoodUrl?: string, iceConfig?: SfuIceConfig, sfuConfig?: SfuConfig,
159
+ /** This device; unset, `defaultDeviceId()`. Apps outside a browser profile (Electron, tests) pass their own. */
160
+ deviceId?: string);
126
161
  /**
127
162
  * Rebuild the call after its connection failed: leave, then join again
128
- * on this executor. Leaving first matters: the executor still holds this
129
- * DID's old session until it notices the connection died.
163
+ * on this executor. Leaving first frees the old session's slot at once;
164
+ * the join would replace it anyway, as it comes from this device.
165
+ * Another tab's join can still replace the old session before the leave
166
+ * lands: that notice stops the rebuild wherever it is, and a session its
167
+ * join already got is left. A tab that missed the notice learns it from
168
+ * the rejoin: the executor refuses the replaced session key (409), and
169
+ * the manager stops as the notice would have stopped it, without retrying.
130
170
  *
131
171
  * Two budgets. A rebuild whose join works but whose connection fails
132
172
  * again counts once against `MAX_RECONNECTS`, reset when ICE connects.
@@ -142,6 +182,12 @@ export declare class SfuManager {
142
182
  * DTLS, tracks and the room slot stay. If the connection is not back
143
183
  * within `RESTART_TIMEOUT_MS`, the call is rebuilt. One restart at a
144
184
  * time: a call while one is in flight does nothing.
185
+ *
186
+ * The restart names this manager's session, the participant id its
187
+ * current join returned: the executor restarts that session only, never
188
+ * another device's of the same agent. A manager with no session — its
189
+ * join not back yet, between a rebuild's leave and join, left, or
190
+ * replaced by another tab — sends nothing.
145
191
  */
146
192
  private restartIce;
147
193
  private endRestart;
@@ -154,16 +200,28 @@ export declare class SfuManager {
154
200
  private releaseServerEvents;
155
201
  private clearUnlistedTimer;
156
202
  /**
157
- * The room's roster no longer lists this agent while `pc` is the call's:
158
- * the server has dropped this session, and ICE may not say so. In E6
159
- * (CI job 53158) one of six sessions never started a rebuild after a
160
- * 20 s outage the server had dropped it for. Rebuild once the roster has
161
- * left this agent out for `UNLISTED_GRACE_MS`; a roster that lists it
162
- * again in that time cancels, since one published just before this
163
- * join landed can arrive after it.
203
+ * The room's roster no longer lists this session (its participant id)
204
+ * while `pc` is the call's: the server has dropped this session, and ICE
205
+ * may not say so. In E6 (CI job 53158) one of six sessions never started
206
+ * a rebuild after a 20 s outage the server had dropped it for. The check
207
+ * is per session, not per agent: another device of this agent keeps the
208
+ * DID listed. Rebuild once the roster has left this session out for
209
+ * `UNLISTED_GRACE_MS`; a roster that lists it again in that time
210
+ * cancels, since one published just before this join landed can arrive
211
+ * after it. A manager with no session (between leave and join, or
212
+ * stopped because a later tab replaced it) starts no rebuild: `stop`
213
+ * clears the timer and drops `pc`, so a replaced session never rejoins
214
+ * and never takes the call back from the newer tab.
164
215
  */
165
216
  private noticeRoster;
166
- /** Undo a join that failed part way: its subscription and its connection. */
217
+ /**
218
+ * Leave this manager's session on the executor, if it has one, and forget
219
+ * it. Only the participant id a join returned is ever left: a manager
220
+ * that never joined, or whose join was refused, sends nothing, so it can
221
+ * never end a session another tab of this agent is in.
222
+ */
223
+ private leaveSession;
224
+ /** Undo a join that failed part way: its subscriptions and its connection. */
167
225
  private abandon;
168
226
  /**
169
227
  * Subscribe to the server's events for this join: renegotiation offers
@@ -178,14 +236,25 @@ export declare class SfuManager {
178
236
  /** Apply one server offer to `pc` and answer it, unless `pc` is no longer the call's. */
179
237
  private applyServerOffer;
180
238
  /**
181
- * Make the participants match `dids`, the room's roster: everyone new
239
+ * Make the participants match `sessions`, the room's roster: everyone new
182
240
  * joins, and — when `complete`, as the roster event is — everyone
183
241
  * missing leaves. The join's own roster can lag the room, so it only adds.
242
+ * This session is never a participant; this agent's other devices are.
184
243
  */
185
244
  private applyRoster;
186
- /** The participant for `did`, joining them to the call if they are new. */
245
+ /** The participant for session `participantId` of `did`, joining them to the call if they are new. */
187
246
  private ensureParticipant;
247
+ /**
248
+ * A later join from this device replaced a session of this call: the
249
+ * executor has already dropped it. Stop as `leave` does, but never
250
+ * rejoin — the other tab has the call now — and say so with `replaced`.
251
+ * A session this manager got since (a reconnect's) is left.
252
+ */
253
+ private stopReplaced;
254
+ /** End this manager's call locally: no reconnect in flight continues, nothing is sent. */
255
+ private stop;
188
256
  private refreshKinds;
257
+ /** End the call: locally, and on the executor if this manager joined. */
189
258
  leave(): Promise<void>;
190
259
  /** Forget the call's participants, telling listeners each one left. */
191
260
  private resetParticipants;
@@ -207,7 +276,8 @@ export declare class SfuManager {
207
276
  */
208
277
  sendData(channelLabel: string, data: string, binary?: boolean): Promise<void>;
209
278
  /**
210
- * Subscribe to data channel messages from other participants.
279
+ * Subscribe to data channel messages from other participants — this
280
+ * agent's other devices included, this session's own messages not.
211
281
  * Returns an unsubscribe function. Only one subscription per
212
282
  * manager instance — a second call replaces the first.
213
283
  */