Skip to content

Feature add close signaling #807

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
ocampana-videotec merged 6 commits into from
Sep 11, 2026
Merged

Feature add close signaling #807

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
6 commits
Select commit Hold shift + click to select a range
cae06e4
Add close signaling method to WebRTC signaling protocol
WANGXIAOMIN-HIK Jul 22, 2026
d69b4d9
Add close exchange to WebRTC example flow
WANGXIAOMIN-HIK Jul 22, 2026
f8ff11b
Add close cross-reference to trickle section's session-termination note
WANGXIAOMIN-HIK Jul 22, 2026
e05298d
Add close command description for resource release and session signaling
WANGXIAOMIN-HIK Aug 13, 2026
0cc96eb
Improve signaling handling for closed sessions and add behavior descr…
WANGXIAOMIN-HIK Aug 13, 2026
c87ca8c
Update WebRTC signaling flow diagram: Adjust dimensions, add close co…
WANGXIAOMIN-HIK Aug 20, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
79 changes: 77 additions & 2 deletions doc/WebRTC.xml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -646,7 +646,8 @@
<varlistentry>
<term>faults</term>
<listitem>
<para role="text">&lt;none&gt;</para>
<para role="text">No faults are defined for a malformed-but-transportable request; see
the handling of already-closed sessions below.</para>
</listitem>
</varlistentry>
</variablelist>
Expand All @@ -657,10 +658,19 @@
<para><emphasis role="bold">NOTE</emphasis>: Note that ICE candidates can arrive <emphasis
role="bold">before</emphasis> the SDP offer and the implementing client needs to handle
this.</para>
<para>If a trickle command is received for a session that has already been closed, the
signaling server shall respond successfully to the requester and shall not relay the
candidate to the peer. This is an exception to the relay requirement above and accounts
for in-flight candidates that are still in transit when a session is being torn down; it
is consistent with the idempotent design of the close command, under which an
already-closed session is not treated as an error.</para>
<para>If everything works as it should, a peer-to-peer WebRTC session can be set up between
client and device. After the session has been established the client can terminate the
WebSocket session to the signaling server and the peer-to-peer connection will not be
affected. The only reason to keep the connection to the server is if the client needs to extend the session.</para>
<para>To actively release device resources such as ICE candidates and TURN connections, the
client may send the <literal>close</literal> command (see <xref linkend="section_close"/>)
before terminating the WebSocket session.</para>
</section>
<section xml:id="section_extend">
<title>extend</title>
Expand Down Expand Up @@ -694,9 +704,16 @@
<para role="text">The authorization token cannot be verified. The authorization token may not include the required claims, or has expired.</para>
<para role="param">403 Forbidden</para>
<para role="text">The client is not authorized to connect to the provided peer.</para>
<para role="param">404 Not Found</para>
<para role="text">The session does not exist or has already been closed.</para>
</listitem>
</varlistentry>
</variablelist>
<para>Unlike the close command, which is idempotent by design, an extend command
received for a session that has already been closed shall be rejected with 404, so the
client is not left believing a dead session is still alive. An extend for an
already-closed session is a state-change request with no valid target, not a retryable
notification.</para>
</section>
<section xml:id="section_extend_device">
<title>extend - Signaling Server to Device</title>
Expand Down Expand Up @@ -729,7 +746,60 @@
</varlistentry>
</variablelist>
</section>
</section>
</section>
<section xml:id="section_close">

@venki5685 venki5685 Aug 20, 2026

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

update Figure 2: Signaling flow sequence diagram with close command flow i.e from client->signaling server->device as a request, device->signaling server->client as a response. Also the current sequence diagram shows closed() optional sequence cmd at the end which is confusing.

@WANGXIAOMIN-HIK WANGXIAOMIN-HIK Aug 20, 2026

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Thank you for your feedback,
Update WebRTC signaling flow diagram: Adjust dimensions, add close command paths, and refine text elements.
Image20260820154004240

<title>close</title>
<para>An ONVIF compliant signaling server, device and client shall support this
command to actively terminate a streaming session.</para>
<para>A signaling server shall relay this command unaltered to the peer. Upon
receiving the close command the device shall stop media streaming and release
resources such as ICE candidates and TURN connections.</para>
<variablelist role="op">
<varlistentry>
<term>request</term>
<listitem>
<para role="param">session [string]</para>
<para role="text">The ID assigned by the signaling server to the session.</para>
<para role="param">reason optional [string]</para>
<para role="text">A short description of why the session is closed.</para>
</listitem>
</varlistentry>
<varlistentry>
<term>response</term>
<listitem>
<para role="text">&lt;none&gt;</para>
</listitem>
</varlistentry>
<varlistentry>
<term>faults</term>
<listitem>
<para role="param">400 Bad Request</para>
<para role="text">Invalid session ID.</para>
<para role="param">404 Not Found</para>
<para role="text">The session does not exist.</para>
</listitem>
</varlistentry>
</variablelist>
<para>The close command is idempotent: if the session has already been closed, the
signaling server shall return a successful response rather than 404, so a client
can retry safely after a network interruption. The 404 fault applies only when the
session ID was never valid.</para>
<para>The close command is an optimization for prompt, graceful resource release and
explicit session-lifecycle signaling; it is not the sole mechanism by which resources
are reclaimed. A client may disappear at any time without sending close (for example, a
browser tab being closed by a user, or a network failure), in which case the close
command will never arrive. Devices and signaling servers shall therefore implement
automatic cleanup as a fallback: a signaling server shall detect a dropped WebSocket
connection (see the "Peer disconnected" error, <xref linkend="_Ref_possible_error_codes"
/>), and may enforce session expiration using the expiryTimeSeconds property of the
connect command together with the extend command. Upon such detection, the device shall
stop media streaming and release resources such as ICE candidates and TURN connections
exactly as if a close command had been received. Implementations shall not assume that a
close command will always be delivered.</para>
<para>Behavior for trickle and extend commands received after a session has closed is
defined in their respective sections; implementations shall not assume the peer has seen
the close before such messages arrive.</para>
</section>

@sujithhanwha sujithhanwha Aug 13, 2026

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

It would also be helpful to clarify the expected behavior if a trickle or extend command is received for an already closed session—specifically, whether the signaling server should return a 404 Not Found fault or silently drop/ignore the message.

@WANGXIAOMIN-HIK WANGXIAOMIN-HIK Aug 13, 2026

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

trickle: Returns success but does not forward (avoids flooding the client with errors, consistent with idempotent design).
extend: Returns 404 (clearly signals the session has ended, preventing "ghost sessions").

<section xml:id="section_error_notification">
<title>error</title>
<para>An ONVIF compliant signaling server, device and client shall support sending or receiving notifications signaling that an error has occurred.</para>
Expand Down Expand Up @@ -859,6 +929,11 @@ Client -> Server: { "method": "extend", "params": {"session": "s1", "authorizati
"id": 4}
Server -> Client: { "error": {"code": -32601, "message": "Method not found"}, "id": "4"}
...
Client -> Server: { "method": "close", "params": {"session": "s1"}, "id": 5}
Server -> Device: { "method": "close", "params": {"session": "s1"}, "id": 5}
Device -> Server: { "result": {}, "id": 5}
Server -> Client: { "result": {}, "id": 5}
...
Device -> Server: { "error": {"code": 1001, "message": "Insufficient resources"}}
Server -> Client: { "error": {"code": 1001, "message": "Insufficient resources"}}

Expand Down
124 changes: 105 additions & 19 deletions doc/media/WebRTC/webrtc_signaling_flow.svg
View file
Open in desktop
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.