@coasys/ad4m 0.13.1-staging.1 → 0.13.1-staging.2
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.
- package/lib/index.cjs +3789 -1192
- package/lib/index.js +3783 -1193
- package/lib/src/generated/api/AgentsByDidsRequest.d.ts +3 -0
- package/lib/src/generated/api/CallSessionInfo.d.ts +23 -0
- package/lib/src/generated/api/DiscardBatchRequest.d.ts +3 -0
- package/lib/src/generated/api/Events.d.ts +13 -3
- package/lib/src/generated/api/Events.js +1 -0
- package/lib/src/generated/api/FlowStateChangedEvent.d.ts +38 -0
- package/lib/src/generated/api/FlowStateEntry.d.ts +18 -0
- package/lib/src/generated/api/FlowStateEntry.js +2 -0
- package/lib/src/generated/api/IceServer.d.ts +18 -0
- package/lib/src/generated/api/IceServer.js +2 -0
- package/lib/src/generated/api/OnlineAgent.d.ts +4 -0
- package/lib/src/generated/api/PerspectiveDiscardBatchParams.d.ts +4 -0
- package/lib/src/generated/api/PerspectiveDiscardBatchParams.js +2 -0
- package/lib/src/generated/api/PerspectiveFlowFiredParams.d.ts +8 -0
- package/lib/src/generated/api/PerspectiveFlowFiredParams.js +2 -0
- package/lib/src/generated/api/PerspectiveFlowStatesParams.d.ts +11 -0
- package/lib/src/generated/api/PerspectiveFlowStatesParams.js +2 -0
- package/lib/src/generated/api/PerspectiveGetAllShaclParams.d.ts +7 -0
- package/lib/src/generated/api/PerspectiveGetAllShaclParams.js +2 -0
- package/lib/src/generated/api/PerspectiveModelQueryParams.d.ts +6 -1
- package/lib/src/generated/api/PerspectiveRemoveSubjectParams.d.ts +6 -0
- package/lib/src/generated/api/PerspectiveRemoveSubjectParams.js +2 -0
- package/lib/src/generated/api/PerspectiveResynced.d.ts +8 -0
- package/lib/src/generated/api/PerspectiveResynced.js +2 -0
- package/lib/src/generated/api/PerspectiveSubscribed.d.ts +10 -0
- package/lib/src/generated/api/PerspectiveSubscribed.js +2 -0
- package/lib/src/generated/api/PerspectiveUpdateSubjectParams.d.ts +10 -0
- package/lib/src/generated/api/PerspectiveUpdateSubjectParams.js +2 -0
- package/lib/src/generated/api/QuerySubscriptionUpdate.d.ts +19 -0
- package/lib/src/generated/api/QuerySubscriptionUpdate.js +2 -0
- package/lib/src/generated/api/QuerySubscriptionUpdateEvent.d.ts +7 -0
- package/lib/src/generated/api/QuerySubscriptionUpdateEvent.js +1 -0
- package/lib/src/generated/api/QueryUpdatesLagged.d.ts +7 -0
- package/lib/src/generated/api/QueryUpdatesLagged.js +2 -0
- package/lib/src/generated/api/RemoveSubjectRequest.d.ts +9 -0
- package/lib/src/generated/api/RemoveSubjectRequest.js +2 -0
- package/lib/src/generated/api/ResyncSubscriptionRequest.d.ts +3 -0
- package/lib/src/generated/api/ResyncSubscriptionRequest.js +2 -0
- package/lib/src/generated/api/RpcMethods.d.ts +134 -14
- package/lib/src/generated/api/RpcMethods.js +12 -0
- package/lib/src/generated/api/SfuAddIceCandidateParams.d.ts +8 -0
- package/lib/src/generated/api/SfuAddIceCandidateParams.js +2 -0
- package/lib/src/generated/api/SfuAnswerServerOfferParams.d.ts +8 -0
- package/lib/src/generated/api/SfuAnswerServerOfferParams.js +2 -0
- package/lib/src/generated/api/SfuCallJoinParams.d.ts +14 -0
- package/lib/src/generated/api/SfuCallJoinParams.js +2 -0
- package/lib/src/generated/api/SfuCallRenegotiationOffer.d.ts +30 -0
- package/lib/src/generated/api/SfuCallRenegotiationOffer.js +1 -0
- package/lib/src/generated/api/SfuCascadePipe.d.ts +4 -0
- package/lib/src/generated/api/SfuCascadePipe.js +2 -0
- package/lib/src/generated/api/SfuCascadeStatus.d.ts +8 -0
- package/lib/src/generated/api/SfuCascadeStatus.js +1 -0
- package/lib/src/generated/api/SfuConfig.d.ts +52 -0
- package/lib/src/generated/api/SfuConfig.js +1 -0
- package/lib/src/generated/api/SfuDataMessage.d.ts +24 -0
- package/lib/src/generated/api/SfuDataMessage.js +2 -0
- package/lib/src/generated/api/SfuEnsureMembershipParams.d.ts +4 -0
- package/lib/src/generated/api/SfuEnsureMembershipParams.js +2 -0
- package/lib/src/generated/api/SfuMigrateEvent.d.ts +21 -0
- package/lib/src/generated/api/SfuMigrateEvent.js +2 -0
- package/lib/src/generated/api/SfuNeighbourhoodParams.d.ts +3 -0
- package/lib/src/generated/api/SfuNeighbourhoodParams.js +2 -0
- package/lib/src/generated/api/SfuParticipantQualityPreference.d.ts +7 -0
- package/lib/src/generated/api/SfuParticipantQualityPreference.js +2 -0
- package/lib/src/generated/api/SfuPerspectiveParams.d.ts +6 -0
- package/lib/src/generated/api/SfuPerspectiveParams.js +2 -0
- package/lib/src/generated/api/SfuQualityPreferenceParams.d.ts +8 -0
- package/lib/src/generated/api/SfuQualityPreferenceParams.js +2 -0
- package/lib/src/generated/api/SfuRoomInfo.d.ts +11 -0
- package/lib/src/generated/api/SfuRoomInfo.js +1 -0
- package/lib/src/generated/api/SfuRoomParams.d.ts +4 -0
- package/lib/src/generated/api/SfuRoomParams.js +2 -0
- package/lib/src/generated/api/SfuRoomParticipantInfo.d.ts +11 -0
- package/lib/src/generated/api/SfuRoomParticipantInfo.js +2 -0
- package/lib/src/generated/api/SfuRoomRoster.d.ts +13 -0
- package/lib/src/generated/api/SfuRoomRoster.js +2 -0
- package/lib/src/generated/api/SfuSendDataParams.d.ts +10 -0
- package/lib/src/generated/api/SfuSendDataParams.js +2 -0
- package/lib/src/generated/api/SfuSetConfigParams.d.ts +5 -0
- package/lib/src/generated/api/SfuSetConfigParams.js +1 -0
- package/lib/src/generated/api/SfuStatus.d.ts +24 -0
- package/lib/src/generated/api/SfuStatus.js +2 -0
- package/lib/src/generated/api/TrackMapEntry.d.ts +17 -0
- package/lib/src/generated/api/TrackMapEntry.js +2 -0
- package/lib/src/generated/api/UpdateSubjectRequest.d.ts +12 -0
- package/lib/src/generated/api/UpdateSubjectRequest.js +2 -0
- package/lib/src/generated/api/index.d.ts +3 -0
- package/lib/src/index.d.ts +7 -0
- package/lib/src/index.js +4 -0
- package/lib/src/model/Ad4mModel.d.ts +84 -0
- package/lib/src/model/Ad4mModel.js +234 -4
- package/lib/src/model/ModelQueryBuilder.d.ts +16 -35
- package/lib/src/model/ModelQueryBuilder.js +88 -270
- package/lib/src/model/decorators.d.ts +32 -0
- package/lib/src/model/decorators.js +40 -1
- package/lib/src/model/shacl-gen.d.ts +3 -1
- package/lib/src/model/shacl-gen.js +13 -1
- package/lib/src/model/types.d.ts +7 -0
- package/lib/src/neighbourhood/MeshManager.d.ts +384 -0
- package/lib/src/neighbourhood/MeshManager.js +1144 -0
- package/lib/src/neighbourhood/NeighbourhoodClient.d.ts +91 -0
- package/lib/src/neighbourhood/NeighbourhoodClient.js +196 -0
- package/lib/src/neighbourhood/NeighbourhoodProxy.d.ts +55 -1
- package/lib/src/neighbourhood/NeighbourhoodProxy.js +170 -3
- package/lib/src/neighbourhood/Session.d.ts +105 -0
- package/lib/src/neighbourhood/Session.js +412 -0
- package/lib/src/neighbourhood/SfuManager.d.ts +174 -0
- package/lib/src/neighbourhood/SfuManager.js +619 -0
- package/lib/src/neighbourhood/SfuTypes.d.ts +35 -0
- package/lib/src/neighbourhood/SfuTypes.js +8 -0
- package/lib/src/perspectives/FlowInstance.d.ts +63 -24
- package/lib/src/perspectives/FlowInstance.js +74 -31
- package/lib/src/perspectives/FlowModels.d.ts +0 -16
- package/lib/src/perspectives/FlowModels.js +8 -16
- package/lib/src/perspectives/LiveQuery.d.ts +49 -0
- package/lib/src/perspectives/LiveQuery.js +169 -0
- package/lib/src/perspectives/PerspectiveClient.d.ts +24 -15
- package/lib/src/perspectives/PerspectiveClient.js +33 -36
- package/lib/src/perspectives/PerspectiveProxy.d.ts +67 -167
- package/lib/src/perspectives/PerspectiveProxy.js +121 -475
- package/lib/src/perspectives/TextContent.d.ts +31 -0
- package/lib/src/perspectives/TextContent.js +52 -0
- package/lib/src/perspectives/WakerSubscriptionManager.d.ts +23 -0
- package/lib/src/perspectives/WakerSubscriptionManager.js +58 -17
- package/lib/src/shacl/SHACLFlow.d.ts +7 -4
- package/lib/src/shacl/SHACLFlow.js +7 -4
- package/lib/src/shacl/SHACLShape.d.ts +9 -0
- package/lib/src/shacl/SHACLShape.js +37 -0
- package/package.json +2 -2
- package/pnpm-workspace.yaml +4 -1
- package/src/Ad4mClient.test.ts +89 -17
- package/src/generated/api/AgentsByDidsRequest.ts +3 -0
- package/src/generated/api/CallSessionInfo.ts +20 -0
- package/src/generated/api/DiscardBatchRequest.ts +3 -0
- package/src/generated/api/Events.ts +14 -3
- package/src/generated/api/FlowStateChangedEvent.ts +36 -0
- package/src/generated/api/FlowStateEntry.ts +18 -0
- package/src/generated/api/IceServer.ts +19 -0
- package/src/generated/api/OnlineAgent.ts +6 -1
- package/src/generated/api/PerspectiveDiscardBatchParams.ts +3 -0
- package/src/generated/api/PerspectiveFlowFiredParams.ts +7 -0
- package/src/generated/api/PerspectiveFlowStatesParams.ts +11 -0
- package/src/generated/api/PerspectiveGetAllShaclParams.ts +6 -0
- package/src/generated/api/PerspectiveModelQueryParams.ts +5 -1
- package/src/generated/api/PerspectiveRemoveSubjectParams.ts +3 -0
- package/src/generated/api/PerspectiveResynced.ts +7 -0
- package/src/generated/api/PerspectiveSubscribed.ts +8 -0
- package/src/generated/api/PerspectiveUpdateSubjectParams.ts +7 -0
- package/src/generated/api/QuerySubscriptionUpdate.ts +10 -0
- package/src/generated/api/QuerySubscriptionUpdateEvent.ts +9 -0
- package/src/generated/api/QueryUpdatesLagged.ts +7 -0
- package/src/generated/api/RemoveSubjectRequest.ts +7 -0
- package/src/generated/api/ResyncSubscriptionRequest.ts +3 -0
- package/src/generated/api/RpcMethods.ts +68 -8
- package/src/generated/api/SfuAddIceCandidateParams.ts +7 -0
- package/src/generated/api/SfuAnswerServerOfferParams.ts +7 -0
- package/src/generated/api/SfuCallJoinParams.ts +13 -0
- package/src/generated/api/SfuCallRenegotiationOffer.ts +29 -0
- package/src/generated/api/SfuCascadePipe.ts +3 -0
- package/src/generated/api/SfuCascadeStatus.ts +7 -0
- package/src/generated/api/SfuConfig.ts +53 -0
- package/src/generated/api/SfuDataMessage.ts +23 -0
- package/src/generated/api/SfuEnsureMembershipParams.ts +3 -0
- package/src/generated/api/SfuMigrateEvent.ts +20 -0
- package/src/generated/api/{KeepAliveQueryRequest.ts → SfuNeighbourhoodParams.ts} +1 -1
- package/src/generated/api/SfuParticipantQualityPreference.ts +6 -0
- package/src/generated/api/{PerspectiveSubscribeQueryResult.ts → SfuPerspectiveParams.ts} +4 -1
- package/src/generated/api/SfuQualityPreferenceParams.ts +7 -0
- package/src/generated/api/SfuRoomInfo.ts +7 -0
- package/src/generated/api/SfuRoomParams.ts +3 -0
- package/src/generated/api/SfuRoomParticipantInfo.ts +8 -0
- package/src/generated/api/SfuRoomRoster.ts +12 -0
- package/src/generated/api/SfuSendDataParams.ts +7 -0
- package/src/generated/api/SfuSetConfigParams.ts +4 -0
- package/src/generated/api/SfuStatus.ts +24 -0
- package/src/generated/api/TrackMapEntry.ts +18 -0
- package/src/generated/api/UpdateSubjectRequest.ts +10 -0
- package/src/generated/api/index.ts +3 -0
- package/src/index.ts +7 -0
- package/src/model/Ad4mModel.test.ts +255 -231
- package/src/model/Ad4mModel.ts +271 -4
- package/src/model/ModelQueryBuilder.ts +103 -310
- package/src/model/abstract-classes.test.ts +225 -0
- package/src/model/decorators.ts +81 -0
- package/src/model/shacl-gen.ts +13 -0
- package/src/model/types.ts +7 -0
- package/src/neighbourhood/MeshManager.test.ts +2640 -0
- package/src/neighbourhood/MeshManager.ts +1350 -0
- package/src/neighbourhood/NeighbourhoodClient.ts +271 -0
- package/src/neighbourhood/NeighbourhoodProxy.test.ts +23 -0
- package/src/neighbourhood/NeighbourhoodProxy.ts +247 -1
- package/src/neighbourhood/Session.test.ts +800 -0
- package/src/neighbourhood/Session.ts +525 -0
- package/src/neighbourhood/SfuManager.test.ts +677 -0
- package/src/neighbourhood/SfuManager.ts +803 -0
- package/src/neighbourhood/SfuTypes.ts +40 -0
- package/src/perspectives/FlowInstance.ts +108 -31
- package/src/perspectives/FlowModels.ts +8 -18
- package/src/perspectives/LiveQuery.test.ts +197 -0
- package/src/perspectives/LiveQuery.ts +189 -0
- package/src/perspectives/PerspectiveClient.ts +51 -51
- package/src/perspectives/PerspectiveProxy.test.ts +85 -401
- package/src/perspectives/PerspectiveProxy.ts +126 -536
- package/src/perspectives/TextContent.test.ts +123 -0
- package/src/perspectives/TextContent.ts +36 -0
- package/src/perspectives/WakerSubscriptionManager.test.ts +88 -6
- package/src/perspectives/WakerSubscriptionManager.ts +69 -18
- package/src/shacl/SHACLFlow.ts +7 -4
- package/src/shacl/SHACLShape.test.ts +2 -1
- package/src/shacl/SHACLShape.ts +49 -0
- package/lib/src/generated/api/KeepAliveQueryRequest.d.ts +0 -3
- package/lib/src/generated/api/PerspectiveModelSubscribeResult.d.ts +0 -7
- package/lib/src/generated/api/PerspectiveQuerySubscriptionFilter.d.ts +0 -6
- package/lib/src/generated/api/PerspectiveSubscribeQueryResult.d.ts +0 -4
- package/src/generated/api/PerspectiveModelSubscribeResult.ts +0 -6
- package/src/generated/api/PerspectiveQuerySubscriptionFilter.ts +0 -3
- /package/lib/src/generated/api/{KeepAliveQueryRequest.js → AgentsByDidsRequest.js} +0 -0
- /package/lib/src/generated/api/{PerspectiveModelSubscribeResult.js → CallSessionInfo.js} +0 -0
- /package/lib/src/generated/api/{PerspectiveQuerySubscriptionFilter.js → DiscardBatchRequest.js} +0 -0
- /package/lib/src/generated/api/{PerspectiveSubscribeQueryResult.js → FlowStateChangedEvent.js} +0 -0
|
@@ -37,7 +37,9 @@ seedCache,
|
|
|
37
37
|
* this class. Attached to the SHACL shape node and re-emitted as
|
|
38
38
|
* an `ad4m://interpretation_hint` link by `SHACLShape.toLinks()`.
|
|
39
39
|
*/
|
|
40
|
-
interpretationHint
|
|
40
|
+
interpretationHint,
|
|
41
|
+
/** `@Model({ abstract: true })`: emitted as one `ad4m://abstract` link. */
|
|
42
|
+
isAbstract) {
|
|
41
43
|
const obj = target.prototype;
|
|
42
44
|
// ── Determine namespace from first property or relation ─────────────
|
|
43
45
|
let namespace = "ad4m://";
|
|
@@ -68,6 +70,9 @@ interpretationHint) {
|
|
|
68
70
|
if (interpretationHint) {
|
|
69
71
|
shape.interpretationHint = interpretationHint;
|
|
70
72
|
}
|
|
73
|
+
if (isAbstract) {
|
|
74
|
+
shape.isAbstract = true;
|
|
75
|
+
}
|
|
71
76
|
// ── Seed the memoisation cache while we keep building ──────────────
|
|
72
77
|
// Any subsequent `target.generateSHACL()` call from inside this
|
|
73
78
|
// function (typically when walking a self-referential or
|
|
@@ -210,6 +215,10 @@ interpretationHint) {
|
|
|
210
215
|
if (propMeta.identity) {
|
|
211
216
|
propShape.identity = true;
|
|
212
217
|
}
|
|
218
|
+
// Names for abstract classes (emitted as `ad4m://alias`).
|
|
219
|
+
if (propMeta.alias) {
|
|
220
|
+
propShape.alias = propMeta.alias;
|
|
221
|
+
}
|
|
213
222
|
// ── Setter actions ──────────────────────────────────────────────
|
|
214
223
|
if (propMeta.prologSetter) {
|
|
215
224
|
console.warn(`[SHACL Generation] Custom Prolog setter for property '${propName}' in class '${subjectName}' is not yet supported. ` +
|
|
@@ -310,6 +319,9 @@ interpretationHint) {
|
|
|
310
319
|
if (relMeta.interpretationHint) {
|
|
311
320
|
relShape.interpretationHint = relMeta.interpretationHint;
|
|
312
321
|
}
|
|
322
|
+
if (relMeta.alias) {
|
|
323
|
+
relShape.alias = relMeta.alias;
|
|
324
|
+
}
|
|
313
325
|
// Adder / Remover actions — only meaningful for relations backed
|
|
314
326
|
// by a real link predicate. Getter-only relations are read-only,
|
|
315
327
|
// and so is one declared `readOnly`, which keeps its predicate as
|
package/lib/src/model/types.d.ts
CHANGED
|
@@ -313,6 +313,13 @@ export type Query = {
|
|
|
313
313
|
* Individual relations can still be overridden via `include` (explicit entries take precedence).
|
|
314
314
|
*/
|
|
315
315
|
includeAll?: boolean;
|
|
316
|
+
/**
|
|
317
|
+
* For a query over several classes (`Ad4mModel.findAllOf` / `queryOf`):
|
|
318
|
+
* the class names a record that conforms to several of them is read as,
|
|
319
|
+
* most wanted first. Without it the most specific requested class wins.
|
|
320
|
+
* Ranks, never excludes. Ignored by a single-class query.
|
|
321
|
+
*/
|
|
322
|
+
preferClasses?: string[];
|
|
316
323
|
where?: Where;
|
|
317
324
|
order?: Order;
|
|
318
325
|
offset?: number;
|
|
@@ -0,0 +1,384 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Peer-to-peer WebRTC mesh transport for the AD4M SDK Session interface.
|
|
3
|
+
*
|
|
4
|
+
* Ported from WE Framework's call module (`mesh.ts` and `protocol.ts`), which
|
|
5
|
+
* stays wire-compatible with it: a WE mesh peer and an SDK mesh peer in the
|
|
6
|
+
* same call negotiate with each other.
|
|
7
|
+
*
|
|
8
|
+
* ## Mesh, not SFU
|
|
9
|
+
*
|
|
10
|
+
* Every participant connects to every other, so N participants means N−1
|
|
11
|
+
* connections each and each peer uploads its video N−1 times. That caps at
|
|
12
|
+
* roughly four to six peers before upstream bandwidth becomes the limit. The
|
|
13
|
+
* SFU path (`SfuManager`) handles larger rooms; this path needs no server.
|
|
14
|
+
*
|
|
15
|
+
* ## Membership comes from the roster; this class only negotiates
|
|
16
|
+
*
|
|
17
|
+
* {@link MeshManager.setRoster} receives whoever presence says is in the call.
|
|
18
|
+
* Connections are reconciled against it: appear → connect, disappear → tear
|
|
19
|
+
* down. There is no join or leave message, because a peer that crashes never
|
|
20
|
+
* sends one.
|
|
21
|
+
*
|
|
22
|
+
* ## Perfect negotiation
|
|
23
|
+
*
|
|
24
|
+
* Both peers see each other join at slightly different moments and both fire
|
|
25
|
+
* `negotiationneeded`, so offers collide. Each pair has a **polite** peer and
|
|
26
|
+
* an **impolite** one, decided by comparing DIDs, which needs no agreement
|
|
27
|
+
* round-trip. On collision the impolite peer ignores the incoming offer and
|
|
28
|
+
* the polite peer rolls back its own.
|
|
29
|
+
*
|
|
30
|
+
* ## The signalling channel is not reliable
|
|
31
|
+
*
|
|
32
|
+
* Perfect negotiation assumes a reliable ordered channel. Telepresence is
|
|
33
|
+
* neither: the executor confirms it took a message and nothing confirms a peer
|
|
34
|
+
* received it, sends are dispatched concurrently, and the first broadcast on a
|
|
35
|
+
* freshly joined neighbourhood has been measured at eighteen seconds. Against
|
|
36
|
+
* that, a lost offer deadlocks a pair, a candidate overtaking its description
|
|
37
|
+
* gets discarded, and concurrent handling corrupts the state machine. Four
|
|
38
|
+
* mechanisms fix that:
|
|
39
|
+
*
|
|
40
|
+
* 1. **Per-peer serialisation.** Signalling for one peer runs one message at a
|
|
41
|
+
* time ({@link MeshManager.enqueue}).
|
|
42
|
+
* 2. **Candidate buffering.** Candidates arriving before a remote description
|
|
43
|
+
* wait for one.
|
|
44
|
+
* 3. **A recovery ladder.** ICE restart → resend the description → rebuild the
|
|
45
|
+
* pair, escalating, on a sweep ({@link MeshManager.tick}).
|
|
46
|
+
* 4. **A `reset` message**, so a rebuild is agreed rather than unilateral.
|
|
47
|
+
*
|
|
48
|
+
* ## Which connection a message is about
|
|
49
|
+
*
|
|
50
|
+
* A pair has many connections over its life — a rebuild, a reset, a peer that
|
|
51
|
+
* reloads — and the two sides routinely disagree for a moment about which one
|
|
52
|
+
* is current. Applied to the wrong connection, a description is refused by the
|
|
53
|
+
* browser ("The order of m-lines in subsequent offer doesn't match order from
|
|
54
|
+
* previous offer/answer"). So every connection names itself
|
|
55
|
+
* ({@link PeerSlot.generation}) and every message says which connection sent it
|
|
56
|
+
* and which it is for ({@link CallGenerations}). See {@link MeshManager.placeOf}.
|
|
57
|
+
*
|
|
58
|
+
* ## Who repairs
|
|
59
|
+
*
|
|
60
|
+
* Recovery uses the same tie-break as offers: the impolite peer acts first.
|
|
61
|
+
* The polite peer runs the same ladder on a doubled deadline, which covers the
|
|
62
|
+
* case where the impolite side has no slot for the pair at all.
|
|
63
|
+
*
|
|
64
|
+
* ## Signalling via telepresence
|
|
65
|
+
*
|
|
66
|
+
* SDP and ICE travel through the neighbourhood's telepresence channel
|
|
67
|
+
* (`sendBroadcastU` / `addSignalHandler`). See {@link createTelepresenceChannel}.
|
|
68
|
+
*/
|
|
69
|
+
import type { PerspectiveExpression, PerspectiveUnsignedInput } from "../perspectives/Perspective";
|
|
70
|
+
import type { SfuDataMessage } from "./SfuTypes";
|
|
71
|
+
/**
|
|
72
|
+
* Checked on receipt; a mismatch is dropped. New message kinds and the
|
|
73
|
+
* generation fields were added without a bump: an old peer ignores a kind it
|
|
74
|
+
* does not know and never reads the generations, so old and new peers still
|
|
75
|
+
* converge. A bump would make them drop every message from each other.
|
|
76
|
+
*/
|
|
77
|
+
export declare const CALL_PROTOCOL_VERSION = 1;
|
|
78
|
+
/**
|
|
79
|
+
* Which of the sender's connections a message comes from, and which of the
|
|
80
|
+
* receiver's it is for. Both are optional; a message without them is read as
|
|
81
|
+
* it was before generations existed.
|
|
82
|
+
*/
|
|
83
|
+
export interface CallGenerations {
|
|
84
|
+
/** The sender's connection, an id it chose when it made the connection. */
|
|
85
|
+
gen?: string;
|
|
86
|
+
/** The receiver's connection as the sender last heard it named. */
|
|
87
|
+
peerGen?: string;
|
|
88
|
+
}
|
|
89
|
+
export type CallBody =
|
|
90
|
+
/**
|
|
91
|
+
* `offer` numbers the offers of one connection: an offer carries its own,
|
|
92
|
+
* an answer the one it answers. An answer to an offer this side has since
|
|
93
|
+
* replaced is refused by the browser, so it is dropped instead. Optional:
|
|
94
|
+
* a peer predating it sends none, and its answers apply as before.
|
|
95
|
+
*/
|
|
96
|
+
{
|
|
97
|
+
kind: "description";
|
|
98
|
+
description: RTCSessionDescriptionInit;
|
|
99
|
+
offer?: number;
|
|
100
|
+
} | {
|
|
101
|
+
kind: "ice";
|
|
102
|
+
candidate: RTCIceCandidateInit;
|
|
103
|
+
}
|
|
104
|
+
/** Throw this pair's connection away and build a new one. */
|
|
105
|
+
| {
|
|
106
|
+
kind: "reset";
|
|
107
|
+
}
|
|
108
|
+
/** Application data, relayed over signalling because the mesh has no server. SDK-only. */
|
|
109
|
+
| {
|
|
110
|
+
kind: "data";
|
|
111
|
+
label: string;
|
|
112
|
+
data: string;
|
|
113
|
+
binary: boolean;
|
|
114
|
+
};
|
|
115
|
+
export interface CallEnvelope extends CallGenerations {
|
|
116
|
+
v: number;
|
|
117
|
+
call: string;
|
|
118
|
+
}
|
|
119
|
+
export type CallMessage = CallEnvelope & CallBody;
|
|
120
|
+
/**
|
|
121
|
+
* Narrow an untrusted payload off the transport.
|
|
122
|
+
*
|
|
123
|
+
* Everything arriving here was published by another agent, so it gets
|
|
124
|
+
* shape-checked before use. The sender id comes from the transport rather
|
|
125
|
+
* than the payload — a self-reported `from` would lack authentication.
|
|
126
|
+
*/
|
|
127
|
+
export declare function parseCallMessage(payload: unknown): CallMessage | null;
|
|
128
|
+
/** Structurally an ephemeral channel, restated so this module carries
|
|
129
|
+
* no import-time dependency on any particular transport. */
|
|
130
|
+
export interface SignallingChannel {
|
|
131
|
+
publish(payload: unknown, to?: {
|
|
132
|
+
agentId?: string;
|
|
133
|
+
}): void;
|
|
134
|
+
onMessage(cb: (from: string, payload: unknown) => void): () => void;
|
|
135
|
+
/**
|
|
136
|
+
* One result per publish, uncorrelated with the message. Optional: a
|
|
137
|
+
* transport that cannot tell what became of a send must not pretend.
|
|
138
|
+
* Where present, the mesh uses it to tell "the message was lost" from
|
|
139
|
+
* "the message has not gone yet" — see {@link MeshManager.outstanding}.
|
|
140
|
+
*/
|
|
141
|
+
onPublishResult?(cb: (result: {
|
|
142
|
+
ok: boolean;
|
|
143
|
+
ms: number;
|
|
144
|
+
}) => void): () => void;
|
|
145
|
+
/**
|
|
146
|
+
* Settles once messages published from now on reach `onMessage`.
|
|
147
|
+
* Optional: a transport that delivers from the moment `onMessage`
|
|
148
|
+
* returns has nothing to wait for. A peer told about this one before it
|
|
149
|
+
* listens would offer into the void until a repair resends.
|
|
150
|
+
*/
|
|
151
|
+
listening?(): Promise<void>;
|
|
152
|
+
}
|
|
153
|
+
/** Minimal telepresence surface the channel bridge needs. */
|
|
154
|
+
export interface TelepresenceProxy {
|
|
155
|
+
sendBroadcastU(status: PerspectiveUnsignedInput): Promise<boolean>;
|
|
156
|
+
addSignalHandler(handler: (payload: PerspectiveExpression) => void): Promise<void>;
|
|
157
|
+
removeSignalHandler(handler: (payload: PerspectiveExpression) => void): void;
|
|
158
|
+
}
|
|
159
|
+
/**
|
|
160
|
+
* Bridge NeighbourhoodProxy telepresence to the SignallingChannel
|
|
161
|
+
* the mesh consumes.
|
|
162
|
+
*
|
|
163
|
+
* ## Why unicast runs emulated over broadcast
|
|
164
|
+
*
|
|
165
|
+
* AD4M exposes real directed send (`sendSignalU`), but it remains
|
|
166
|
+
* broken in current executor builds. This adapter addresses over
|
|
167
|
+
* broadcast: the recipient DID goes in the link's `target` and
|
|
168
|
+
* receivers drop anything not addressed to them. That provides
|
|
169
|
+
* **addressing, not privacy** — every peer still receives the payload.
|
|
170
|
+
*/
|
|
171
|
+
export declare function createTelepresenceChannel(proxy: TelepresenceProxy, selfDid: string): SignallingChannel;
|
|
172
|
+
export type MeshEvent = "participant-joined" | "participant-left"
|
|
173
|
+
/** A participant's stream object or the liveness of its tracks changed:
|
|
174
|
+
* a rebuilt connection, or a remote track muted or unmuted. */
|
|
175
|
+
| "participant-updated" | "stream-added" | "stream-removed"
|
|
176
|
+
/** `(did, RTCPeerConnectionState)` */
|
|
177
|
+
| "peer-state"
|
|
178
|
+
/** `(did, { rung, attempts })` — a repair was attempted on this pair. */
|
|
179
|
+
| "peer-recovery" | "error";
|
|
180
|
+
export type MeshEventCallback = (...args: any[]) => void;
|
|
181
|
+
/** Which rung of the recovery ladder an attempt was on. */
|
|
182
|
+
export type RecoveryRung = "ice-restart" | "resend" | "rebuild";
|
|
183
|
+
export interface MeshParticipant {
|
|
184
|
+
did: string;
|
|
185
|
+
stream: MediaStream;
|
|
186
|
+
hasAudio: boolean;
|
|
187
|
+
hasVideo: boolean;
|
|
188
|
+
isActiveSpeaker: boolean;
|
|
189
|
+
}
|
|
190
|
+
export interface MeshManagerOptions {
|
|
191
|
+
channel: SignallingChannel;
|
|
192
|
+
callId: string;
|
|
193
|
+
selfId: string;
|
|
194
|
+
/** NAT traversal. Defaults to {@link DEFAULT_ICE_SERVERS} — public STUN, no TURN. */
|
|
195
|
+
iceServers?: RTCIceServer[];
|
|
196
|
+
/** Injected so tests can supply a fake. Receives the configuration the mesh decided on. */
|
|
197
|
+
createPeerConnection?: (configuration: RTCConfiguration) => RTCPeerConnection;
|
|
198
|
+
/** Injectable clock, so the recovery ladder is testable without waiting out real deadlines. */
|
|
199
|
+
now?: () => number;
|
|
200
|
+
/** How often the mesh looks at its own connections. `0` disables the timer;
|
|
201
|
+
* {@link MeshManager.tick} still works, which is how tests drive it. */
|
|
202
|
+
sweepMs?: number;
|
|
203
|
+
}
|
|
204
|
+
/** Public STUN, and no TURN. Two servers, because ICE queries them in parallel. */
|
|
205
|
+
export declare const DEFAULT_ICE_SERVERS: RTCIceServer[];
|
|
206
|
+
/**
|
|
207
|
+
* How long a pair may sit unconnected before the impolite side intervenes.
|
|
208
|
+
* Only has to outlast a healthy negotiation: a send still in flight defers
|
|
209
|
+
* repair on its own (see {@link MeshManager.outstanding}).
|
|
210
|
+
*/
|
|
211
|
+
export declare const HANDSHAKE_GRACE_MS = 10000;
|
|
212
|
+
/** How long each rung of the ladder is given before escalating to the next. */
|
|
213
|
+
export declare const RECOVERY_INTERVAL_MS = 8000;
|
|
214
|
+
/**
|
|
215
|
+
* How long `disconnected` is tolerated before an ICE restart. Shorter than the
|
|
216
|
+
* others: `disconnected` often recovers by itself within a second or two.
|
|
217
|
+
*/
|
|
218
|
+
export declare const DISCONNECT_GRACE_MS = 5000;
|
|
219
|
+
/**
|
|
220
|
+
* How many times a pair is repaired before the mesh stops and lets `failed`
|
|
221
|
+
* stand. A pair that failed a full ladder four times needs TURN or a network,
|
|
222
|
+
* and neither is fixed by a fifth attempt. Reset by a successful connection.
|
|
223
|
+
*/
|
|
224
|
+
export declare const MAX_RECOVERY_ATTEMPTS = 4;
|
|
225
|
+
/** How often the mesh looks at its own connections, when not driven by hand. */
|
|
226
|
+
export declare const SWEEP_INTERVAL_MS = 2000;
|
|
227
|
+
/**
|
|
228
|
+
* The shortest gap between two repairs, whatever asks for them. A settled send
|
|
229
|
+
* calls `tick` and a repair publishes, so without a floor the two chase each
|
|
230
|
+
* other through every pair in the call. Below {@link SWEEP_INTERVAL_MS} so the
|
|
231
|
+
* ordinary cadence is never throttled.
|
|
232
|
+
*/
|
|
233
|
+
export declare const REPAIR_SPACING_MS = 1500;
|
|
234
|
+
export declare class MeshManager {
|
|
235
|
+
private channel;
|
|
236
|
+
private callId;
|
|
237
|
+
private selfId;
|
|
238
|
+
private configuration;
|
|
239
|
+
private createPeerConnection;
|
|
240
|
+
private now;
|
|
241
|
+
private sweepMs;
|
|
242
|
+
private sweep;
|
|
243
|
+
private callbacks;
|
|
244
|
+
private slots;
|
|
245
|
+
private states;
|
|
246
|
+
private outbound;
|
|
247
|
+
/** One stream for all outbound tracks, so a peer receives mic and camera grouped. */
|
|
248
|
+
private outboundStream;
|
|
249
|
+
private closed;
|
|
250
|
+
private channelUnsubscribe;
|
|
251
|
+
private unwatchPublish;
|
|
252
|
+
private pending;
|
|
253
|
+
/** The peer connections each peer has replaced. Kept past a slot, so a late message cannot revive one. */
|
|
254
|
+
private retired;
|
|
255
|
+
private dataListeners;
|
|
256
|
+
/**
|
|
257
|
+
* Sends published and not yet reported on. With an unreliable transport,
|
|
258
|
+
* "the peer never answered" and "the message has not left yet" look the
|
|
259
|
+
* same, and repairing the second piles sends onto a stalled executor. Stays
|
|
260
|
+
* zero on a transport without `onPublishResult`.
|
|
261
|
+
*/
|
|
262
|
+
private outstanding;
|
|
263
|
+
/** When a sweep last repaired something — see {@link REPAIR_SPACING_MS}. */
|
|
264
|
+
private lastRepairAt;
|
|
265
|
+
/**
|
|
266
|
+
* Repairs of a connected pair's unanswered renegotiation, per peer, kept
|
|
267
|
+
* across rebuilds. A slot's `attempts` resets when its connection connects,
|
|
268
|
+
* which a rebuilt pair does before it renegotiates again — so a peer that
|
|
269
|
+
* never answers a renegotiation would be resent to and rebuilt forever.
|
|
270
|
+
* Cleared only when a renegotiation is answered.
|
|
271
|
+
*/
|
|
272
|
+
private renegotiationRepairs;
|
|
273
|
+
constructor(options: MeshManagerOptions);
|
|
274
|
+
on(event: MeshEvent, callback: MeshEventCallback): void;
|
|
275
|
+
off(event: MeshEvent, callback?: MeshEventCallback): void;
|
|
276
|
+
private emit;
|
|
277
|
+
private fail;
|
|
278
|
+
private participant;
|
|
279
|
+
join(localStream: MediaStream): Promise<void>;
|
|
280
|
+
leave(): Promise<void>;
|
|
281
|
+
destroy(): Promise<void>;
|
|
282
|
+
/**
|
|
283
|
+
* Reconcile connections against who presence says belongs in the
|
|
284
|
+
* call. Excludes this agent.
|
|
285
|
+
*/
|
|
286
|
+
setRoster(peerIds: string[]): void;
|
|
287
|
+
getParticipants(): MeshParticipant[];
|
|
288
|
+
peerStates(): Map<string, RTCPeerConnectionState>;
|
|
289
|
+
/**
|
|
290
|
+
* Throw one pair's connection away and negotiate it again, telling the
|
|
291
|
+
* peer to do the same. The manual rung of the ladder: reachable from either
|
|
292
|
+
* side regardless of politeness, and it resets the automatic budget.
|
|
293
|
+
*/
|
|
294
|
+
reconnect(peerId: string): void;
|
|
295
|
+
/**
|
|
296
|
+
* How this pair's media reaches the other end — `host` on a LAN, `srflx`
|
|
297
|
+
* through NAT, `relay` through TURN — or `null` when nothing is connected.
|
|
298
|
+
* Separates "this pair needs TURN" from "the handshake never finished".
|
|
299
|
+
*/
|
|
300
|
+
transportOf(peerId: string): Promise<string | null>;
|
|
301
|
+
/**
|
|
302
|
+
* Replace the outbound track of a given kind on every peer connection.
|
|
303
|
+
* Uses `RTCRtpSender.replaceTrack` on the sections declared up front, so
|
|
304
|
+
* muting, unmuting and camera↔screen swaps never renegotiate. Pass `null`
|
|
305
|
+
* to stop sending that kind.
|
|
306
|
+
*/
|
|
307
|
+
replaceTrack(kind: "audio" | "video", track: MediaStreamTrack | null): Promise<void>;
|
|
308
|
+
/**
|
|
309
|
+
* Send data to all other participants via the signalling channel.
|
|
310
|
+
* The mesh has no server-side relay — data rides the same
|
|
311
|
+
* telepresence broadcast the SDP/ICE messages use.
|
|
312
|
+
*/
|
|
313
|
+
sendData(label: string, data: string, binary?: boolean): void;
|
|
314
|
+
subscribeDataChannel(callback: (msg: SfuDataMessage) => void): () => void;
|
|
315
|
+
private handleData;
|
|
316
|
+
/** Every publish goes through here, so {@link outstanding} counts exactly the reported ones. */
|
|
317
|
+
private publish;
|
|
318
|
+
/**
|
|
319
|
+
* Addressed twice, on purpose: `to` on the publish lets a transport with
|
|
320
|
+
* native unicast send to one peer, and `to` in the payload makes a
|
|
321
|
+
* fanout-only transport filter on receipt.
|
|
322
|
+
*/
|
|
323
|
+
private send;
|
|
324
|
+
/** Which connections a message from this slot is between. */
|
|
325
|
+
private stamp;
|
|
326
|
+
private sendFrom;
|
|
327
|
+
/** Send the connection's local description, numbered as {@link CallBody} describes. */
|
|
328
|
+
private sendDescription;
|
|
329
|
+
private retire;
|
|
330
|
+
private connect;
|
|
331
|
+
/** Close one pair's connection, without telling anyone it happened. */
|
|
332
|
+
private disconnect;
|
|
333
|
+
/** The peer left the call. */
|
|
334
|
+
private removePeer;
|
|
335
|
+
/**
|
|
336
|
+
* Signalling that arrived before the roster caught up, kept until it does.
|
|
337
|
+
*
|
|
338
|
+
* A peer who denied the microphone has no outbound tracks, so it never
|
|
339
|
+
* fires `negotiationneeded` again after its offer is dropped. It joined and
|
|
340
|
+
* connected to nobody. Bounded on both axes, because this buffers messages
|
|
341
|
+
* from agents the roster has not vouched for. Overflow drops the oldest.
|
|
342
|
+
*/
|
|
343
|
+
private hold;
|
|
344
|
+
/** Replay what this peer sent while we were still learning it belongs here. */
|
|
345
|
+
private release;
|
|
346
|
+
/** Put one message on this peer's queue. The chain never rejects — `handle` reports its own failures. */
|
|
347
|
+
private enqueue;
|
|
348
|
+
/**
|
|
349
|
+
* Where a message stands against the connection this side holds for its sender.
|
|
350
|
+
*
|
|
351
|
+
* - `current` — from the peer connection this one talks to, or the first to
|
|
352
|
+
* name itself, or it names nothing (a peer predating generations).
|
|
353
|
+
* - `stale` — for a connection of this side's that was replaced, or from
|
|
354
|
+
* one of the peer's that was. Nothing it says applies.
|
|
355
|
+
* - `newer` — from a peer connection this side has not met: the peer has started over.
|
|
356
|
+
*/
|
|
357
|
+
private placeOf;
|
|
358
|
+
private handle;
|
|
359
|
+
private flushCandidates;
|
|
360
|
+
/**
|
|
361
|
+
* Throw this pair away and start again. Attempts carry over to the new
|
|
362
|
+
* slot, or a pair that rebuilds every time would never reach
|
|
363
|
+
* {@link MAX_RECOVERY_ATTEMPTS}.
|
|
364
|
+
*/
|
|
365
|
+
private rebuild;
|
|
366
|
+
/**
|
|
367
|
+
* One pair, one repair, on whichever rung its state calls for, cheapest first:
|
|
368
|
+
*
|
|
369
|
+
* 1. **ICE restart.** Keeps the connection and DTLS session; only
|
|
370
|
+
* re-gathers the transport. For `failed` and a `disconnected` that did
|
|
371
|
+
* not come back.
|
|
372
|
+
* 2. **Resend the description.** For a handshake that never completed,
|
|
373
|
+
* which on this transport means a message was dropped — either half.
|
|
374
|
+
* 3. **Rebuild.** When there is nothing to resend, or the rungs above were tried.
|
|
375
|
+
*/
|
|
376
|
+
private repair;
|
|
377
|
+
/** Whether this pair has been given long enough, and whether it is this side's turn to act. */
|
|
378
|
+
private dueForRepair;
|
|
379
|
+
/**
|
|
380
|
+
* Look at every connection and repair what is stuck. Driven by an internal
|
|
381
|
+
* timer; public because tests drive it by hand.
|
|
382
|
+
*/
|
|
383
|
+
tick(): void;
|
|
384
|
+
}
|