@twilio/video-node-sdk 1.0.0-beta.1
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/CHANGELOG.md +409 -0
- package/FRAME_CONTRACT.md +204 -0
- package/LICENSE.md +3 -0
- package/LIFECYCLE.md +123 -0
- package/README.md +617 -0
- package/SECURITY-PRIVACY.md +25 -0
- package/dist/index.cjs +1822 -0
- package/dist/index.d.cts +1671 -0
- package/dist/index.d.mts +1671 -0
- package/dist/index.mjs +1740 -0
- package/package.json +111 -0
- package/prebuilds/darwin-x64/twilio_video_sdk_node-darwin-x64.node +0 -0
- package/prebuilds/linux-x64/twilio_video_sdk_node-linux-x64.node +0 -0
package/LIFECYCLE.md
ADDED
|
@@ -0,0 +1,123 @@
|
|
|
1
|
+
# Object lifecycle
|
|
2
|
+
|
|
3
|
+
Who owns which objects, what `disconnect()` and `dispose()` each release, and
|
|
4
|
+
the ordering the SDK guarantees while a Room tears down.
|
|
5
|
+
[README.md](README.md) covers usage, and
|
|
6
|
+
[FRAME_CONTRACT.md](FRAME_CONTRACT.md) covers frame delivery.
|
|
7
|
+
|
|
8
|
+
## What you own
|
|
9
|
+
|
|
10
|
+
Local tracks are the only SDK objects you construct. Everything else is handed
|
|
11
|
+
to you by the Room that produced it: participants, remote tracks, and `frames()`
|
|
12
|
+
iterators, all released by `room.dispose()`. Local tracks stay yours. They have
|
|
13
|
+
no release method, and disposing the Room does not touch them.
|
|
14
|
+
|
|
15
|
+
Each Room caches its remote track wrappers by Track SID, so a `trackSubscribed`
|
|
16
|
+
event and a read of `publication.track` give you the same object, and the
|
|
17
|
+
`frames()` iterator running on it is the one the SDK ends. The cache entry is
|
|
18
|
+
dropped when the track is unsubscribed or the Room tears down, so a read after
|
|
19
|
+
that point mints a fresh wrapper. Two Rooms subscribed to the same publication
|
|
20
|
+
each get their own wrapper.
|
|
21
|
+
|
|
22
|
+
`participant.videoTracks` and `participant.audioTracks` hold publications, not
|
|
23
|
+
tracks; `publication.track` is what resolves through the cache.
|
|
24
|
+
|
|
25
|
+
## Ending a Room
|
|
26
|
+
|
|
27
|
+
`room.disconnect()` leaves the session and returns right away; the
|
|
28
|
+
`disconnected` event follows. The Room object stays readable, but it still holds
|
|
29
|
+
the native resources behind it, so the process does not exit on its own.
|
|
30
|
+
|
|
31
|
+
`room.dispose()` releases everything the Room owns: participant wrappers, active
|
|
32
|
+
`frames()` iterators, the native Room, and every listener. It disconnects first if the
|
|
33
|
+
session is still up, so `dispose()` on its own is a complete teardown. A
|
|
34
|
+
disposed Room is no longer usable.
|
|
35
|
+
|
|
36
|
+
Call either one more than once, in either order, without harm.
|
|
37
|
+
|
|
38
|
+
`dispose()` also ends the Room's event delivery. It closes the event queue
|
|
39
|
+
before it disconnects, so an application that calls `dispose()` directly never
|
|
40
|
+
receives `disconnected`, and a `disconnected` raised by an earlier
|
|
41
|
+
`disconnect()` is discarded if it has not been delivered yet.
|
|
42
|
+
|
|
43
|
+
Two shutdown shapes follow from that. To act on the event, dispose from the
|
|
44
|
+
handler:
|
|
45
|
+
|
|
46
|
+
```js
|
|
47
|
+
room.on('disconnected', () => {
|
|
48
|
+
room.dispose();
|
|
49
|
+
});
|
|
50
|
+
room.disconnect();
|
|
51
|
+
```
|
|
52
|
+
|
|
53
|
+
To shut down without waiting, dispose directly:
|
|
54
|
+
|
|
55
|
+
```js
|
|
56
|
+
process.on('SIGINT', () => {
|
|
57
|
+
room.dispose();
|
|
58
|
+
});
|
|
59
|
+
```
|
|
60
|
+
|
|
61
|
+
The second reports no `disconnected`. Since `dispose()` is also what lets the
|
|
62
|
+
process exit, it is the call to make from a signal handler or a timeout.
|
|
63
|
+
|
|
64
|
+
Calling `disconnect()` or `dispose()` from inside the `disconnected` handler is
|
|
65
|
+
supported, as it is from any other Room or Participant event handler. You do not
|
|
66
|
+
need to defer the call to a later tick. One consequence to plan for: disposing
|
|
67
|
+
from a handler discards Room events still queued behind the one you are
|
|
68
|
+
handling, such as a
|
|
69
|
+
`participantDisconnected` that a remotely ended Room raised at the same moment.
|
|
70
|
+
If your application needs those events, let the handler return and dispose on a
|
|
71
|
+
later tick.
|
|
72
|
+
|
|
73
|
+
A handler that throws stops that delivery, the way a throwing `EventEmitter`
|
|
74
|
+
listener stops an `emit`. The exception reaches the process as an
|
|
75
|
+
`uncaughtException`, and the events queued behind it are delivered afterward.
|
|
76
|
+
|
|
77
|
+
## Ending a receiver
|
|
78
|
+
|
|
79
|
+
A receiver is the active `frames()` iterator on a track: the single consumer
|
|
80
|
+
pulling decoded frames from it. `track.frames()` starts one, and a track
|
|
81
|
+
supports one at a time.
|
|
82
|
+
|
|
83
|
+
A receiver ends on its own when the track is unsubscribed or the Room
|
|
84
|
+
disconnects, so a `for await` loop exits instead of hanging. Leaving the loop
|
|
85
|
+
ends it early.
|
|
86
|
+
|
|
87
|
+
Once a receiver ends, its frames stop: the SDK unregisters the sink and closes
|
|
88
|
+
it, so a frame in flight on a decoder thread is dropped, and frames already
|
|
89
|
+
queued for the JavaScript thread are discarded rather than delivered. This holds
|
|
90
|
+
after a remote Room end as well, when there is no longer a media track to
|
|
91
|
+
unregister from.
|
|
92
|
+
|
|
93
|
+
Ending a receiver is idempotent, and safe from inside a `trackUnsubscribed`
|
|
94
|
+
handler: the SDK ends the receiver itself as soon as that handler returns.
|
|
95
|
+
|
|
96
|
+
`track.getStats()` keeps reporting the final counts after a receiver ends, for
|
|
97
|
+
as long as you hold that track wrapper. A wrapper minted after the cache entry
|
|
98
|
+
was dropped has no history and reports zeros.
|
|
99
|
+
|
|
100
|
+
Two limits apply to that final report today. The `queueDepth` it carries can be
|
|
101
|
+
nonzero although nothing is queued any more, and frames still held at the native
|
|
102
|
+
boundary when the receiver ended are not counted in `framesDropped`.
|
|
103
|
+
|
|
104
|
+
## Event sequencing
|
|
105
|
+
|
|
106
|
+
The SDK guarantees this ordering during teardown:
|
|
107
|
+
|
|
108
|
+
- `trackUnsubscribed` arrives before the SDK ends that track's receiver, so the
|
|
109
|
+
handler still sees a live track. This holds while the Room is up. If the Room
|
|
110
|
+
ends at the same moment, the `disconnected` path may end every receiver and
|
|
111
|
+
drop the wrapper cache first, and the `trackUnsubscribed` that follows carries
|
|
112
|
+
a fresh wrapper with no receiver and zeroed stats: Room events and
|
|
113
|
+
per-participant events ride independent queues with no ordering between them.
|
|
114
|
+
- `participantDisconnected` arrives after every `trackUnsubscribed` raised for
|
|
115
|
+
that participant's tracks.
|
|
116
|
+
- `disconnected` arrives after every active receiver has ended, so a `for await`
|
|
117
|
+
loop is guaranteed to exit rather than hang on a dead Room. The handler still
|
|
118
|
+
runs first: ending a receiver resolves its parked `next()` promise, and the
|
|
119
|
+
loop resumes on a later microtask. Results a loop tallies as it finishes are
|
|
120
|
+
not final while the `disconnected` handler is running.
|
|
121
|
+
|
|
122
|
+
A track supports one receiver at a time, and `frames()` throws while one is
|
|
123
|
+
active. Ending a receiver releases the track for the next one.
|