@twilio/video-node-sdk 1.0.0-rc.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/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.