Skip to content
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.

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

RTCTransportStats - updates #37158

Draft
wants to merge 7 commits into
base: main
Choose a base branch
from
Draft
Show file tree
Hide file tree
Changes from all commits
Commits
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
25 changes: 25 additions & 0 deletions files/en-us/web/api/rtctransportstats/bytesreceived/index.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,25 @@
---
title: "RTCTransportStats: bytesReceived property"
short-title: bytesReceived
slug: Web/API/RTCTransportStats/bytesReceived
page-type: web-api-instance-property
browser-compat: api.RTCStatsReport.type_transport.bytesReceived
---

{{APIRef("WebRTC")}}

The **`bytesReceived`** property of the {{domxref("RTCTransportStats")}} dictionary indicates the total number of payload bytes received on this transport.

Only data bytes are counted; overhead such as padding, headers, and so on are not included in this count.

## Value

A positive integer indicating the number of received payload bytes.

## Specifications

{{Specifications}}

## Browser compatibility

{{Compat}}
25 changes: 25 additions & 0 deletions files/en-us/web/api/rtctransportstats/bytessent/index.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,25 @@
---
title: "RTCTransportStats: bytesSent property"
short-title: bytesSent
slug: Web/API/RTCTransportStats/bytesSent
page-type: web-api-instance-property
browser-compat: api.RTCStatsReport.type_transport.bytesSent
---

{{APIRef("WebRTC")}}

The **`bytesSent`** property of the {{domxref("RTCTransportStats")}} dictionary indicates the total number of payload bytes sent on this transport.

Only data bytes are counted; overhead such as padding, headers, and so on are not included in this count.

## Value

A positive integer indicating the number of sent payload bytes.

## Specifications

{{Specifications}}

## Browser compatibility

{{Compat}}
26 changes: 26 additions & 0 deletions files/en-us/web/api/rtctransportstats/dtlscipher/index.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,26 @@
---
title: "RTCTransportStats: dtlsCipher property"
short-title: dtlsCipher
slug: Web/API/RTCTransportStats/dtlsCipher
page-type: web-api-instance-property
browser-compat: api.RTCStatsReport.type_transport.dtlsCipher
---

{{APIRef("WebRTC")}}

The **`dtlsCipher`** property of the {{domxref("RTCTransportStats")}} dictionary is a string that indicates the descriptive name of the cipher suite used for the DTLS transport.

Allowed names are defined in the "Description" column of the [TLS Cipher Suites](https://www.iana.org/assignments/tls-parameters/tls-parameters.xhtml#table-tls-parameters-4) section in the _IANA cipher suite registry_.
For example `"TLS_ECDHE_ECDSA_WITH_AES_128_GCM_SHA256"`.

## Value

A string indicating the name of the DTLS cipher.

## Specifications

{{Specifications}}

## Browser compatibility

{{Compat}}
33 changes: 33 additions & 0 deletions files/en-us/web/api/rtctransportstats/dtlsrole/index.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,33 @@
---
title: "RTCTransportStats: dtlsRole property"
short-title: dtlsRole
slug: Web/API/RTCTransportStats/dtlsRole
page-type: web-api-instance-property
browser-compat: api.RTCStatsReport.type_transport.dtlsRole
---

{{APIRef("WebRTC")}}

The **`dtlsRole`** property of the {{domxref("RTCTransportStats")}} dictionary is a string that indicates the role of the associated {{domxref("RTCPeerConnection")}} in the DTLS negotiation.

Specifically, whether it acted like a server and listened for connections, or like a client and initiated the connection, or that negotiation has not yet started.

## Value

A string indicating the DTLS role.
This will be one of:

- `client`
- : The peer initiated the DTLS handshake.
- `server`
- : The peer waited for the DTLS handshake.
- `unknown`
- : DTLS negotiation has not started.

## Specifications

{{Specifications}}

## Browser compatibility

{{Compat}}
34 changes: 34 additions & 0 deletions files/en-us/web/api/rtctransportstats/dtlsstate/index.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,34 @@
---
title: "RTCTransportStats: dtlsState property"
short-title: dtlsState
slug: Web/API/RTCTransportStats/dtlsState
page-type: web-api-instance-property
browser-compat: api.RTCStatsReport.type_transport.dtlsState
---

{{APIRef("WebRTC")}}

The **`dtlsState`** property of the {{domxref("RTCTransportStats")}} dictionary is a string that indicates the current state of the underlying {{domxref("RTCDtlsTransport")}}.

## Value

This has the same values as the corresponding {{domxref("RTCDtlsTransport.state")}} property:

- `new`
- : The initial state when DTLS has not started negotiating yet.
- `connecting`
- : DTLS is in the process of negotiating a secure connection and verifying the remote fingerprint.
- `connected`
- : DTLS has completed negotiation of a secure connection and verified the remote fingerprint.
- `closed`
- : The transport has been closed intentionally as the result of receipt of a `close_notify` alert, or calling {{DOMxRef("RTCPeerConnection.close()")}}.
- `failed`
- : The transport has failed as the result of an error (such as receipt of an error alert or failure to validate the remote fingerprint).

## Specifications

{{Specifications}}

## Browser compatibility

{{Compat}}
Original file line number Diff line number Diff line change
@@ -0,0 +1,28 @@
---
title: "RTCTransportStats: iceLocalUsernameFragment property"
short-title: iceLocalUsernameFragment
slug: Web/API/RTCTransportStats/iceLocalUsernameFragment
page-type: web-api-instance-property
browser-compat: api.RTCStatsReport.type_transport.iceLocalUsernameFragment
---

{{APIRef("WebRTC")}}

The **`iceLocalUsernameFragment`** property of the {{domxref("RTCTransportStats")}} dictionary is a string that indicates the local username fragment ("ufrag" or "ice-ufrag") that uniquely identifies the ICE interaction session managed by this transport.

## Value

A string containing the username fragment that uniquely identifies the ongoing ICE session on the transport.
The same fragment is used to identify the session for any communication with the STUN server.
The string may be up to 256 characters long, and has no default value.

This has the same values as the corresponding local {{domxref("RTCIceCandidate.usernameFragment")}} property.
It will change if the connection is renegotiated, for example on ICE restart, or if {{domxref("RTCPeerConnection.setLocalDescription()")}} is called.

## Specifications

{{Specifications}}

## Browser compatibility

{{Compat}}
61 changes: 23 additions & 38 deletions files/en-us/web/api/rtctransportstats/index.md
Original file line number Diff line number Diff line change
Expand Up @@ -18,37 +18,22 @@ These statistics can be obtained by iterating the {{domxref("RTCStatsReport")}}

## Instance properties

- `bytesReceived` {{optional_inline}}
- {{domxref("RTCTransportStats.bytesReceived", "bytesReceived")}} {{optional_inline}}
- : The total number of payload bytes received on this transport (bytes received, not including headers, padding or ICE connectivity checks).
- `bytesSent` {{optional_inline}}
- {{domxref("RTCTransportStats.bytesSent", "bytesSent")}} {{optional_inline}}
- : The total number of payload bytes sent on this transport (bytes sent, not including headers, padding or ICE connectivity checks).
- `dtlsCipher` {{optional_inline}}
- : A string indicating the name of the cipher suite used for the DTLS transport, as defined in the "Description" column of the [TLS Cipher Suites](https://www.iana.org/assignments/tls-parameters/tls-parameters.xhtml#tls-parameters-4) section in the _IANA cipher suite registry_.
For example `"TLS_ECDHE_ECDSA_WITH_AES_128_GCM_SHA256"`.
- `dtlsRole` {{optional_inline}} {{experimental_inline}}

- : The DTLS role of the associated {{domxref("RTCPeerConnection")}}.
This is one of:

- `client`
- `server`
- `unknown` (before the DTLS negotiation starts).

- `dtlsState`

- {{domxref("RTCTransportStats.dtlsCipher", "dtlsCipher")}} {{optional_inline}}
- : A string indicating the name of the cipher suite used for the DTLS transport, such as `TLS_ECDHE_ECDSA_WITH_AES_128_GCM_SHA256`.
- {{domxref("RTCTransportStats.dtlsRole", "dtlsRole")}} {{optional_inline}} {{experimental_inline}}
- : A string indicating the DTLS role of the associated {{domxref("RTCPeerConnection")}}.
This is one of: `client`, `server`, `unknown` (before the DTLS negotiation starts).
- {{domxref("RTCTransportStats.dtlsState", "dtlsState")}}
- : A string indicating the current {{domxref("RTCDtlsTransport.state","state")}} of the underlying {{domxref("RTCDtlsTransport")}}.
This is one of:

- [`new`](/en-US/docs/Web/API/RTCDtlsTransport/state#new)
- [`connecting`](/en-US/docs/Web/API/RTCDtlsTransport/state#connecting)
- [`connected`](/en-US/docs/Web/API/RTCDtlsTransport/state#connected)
- [`closed`](/en-US/docs/Web/API/RTCDtlsTransport/state#closed)
- [`failed`](/en-US/docs/Web/API/RTCDtlsTransport/state#failed)

- `iceLocalUsernameFragment` {{optional_inline}} {{experimental_inline}}
- : A string indicating the local username fragment used in message validation procedures for this transport.
This is one of: `new`, `connecting`, `connected`, `closed`, `failed`.
- {{domxref("RTCTransportStats.iceLocalUsernameFragment", "iceLocalUsernameFragment")}} {{optional_inline}} {{experimental_inline}}
- : A string indicating the local username fragment that uniquely identifies the ICE interaction session managed by this transport.
This is the same value as the local {{domxref("RTCIceCandidate.usernameFragment")}}, and will change if the connection is renegotiated.
Comment on lines +33 to 35
Copy link
Collaborator Author

@hamishwillee hamishwillee Dec 13, 2024

Choose a reason for hiding this comment

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

Note, the spec says

Set to the current value of the local username fragment used in message validation procedures [RFC5245] for this RTCIceTransport. It may be updated on setLocalDescription() and on ICE restart.

it is not clear if that validation is something the browser does or the developer does (to me). I THINK that the fragment is used to associate the transport to the messages on it, so at this point the validation has already happened. i.e. that is of interest to browser developers, not end users.

I am not sure what a developer would do with this stat, though presumably they can map it to other stats that are part of the same session.

- `iceRole` {{optional_inline}} {{experimental_inline}}
- {{domxref("RTCTransportStats.iceRole", "iceRole")}} {{optional_inline}} {{experimental_inline}}

- : A string indicating the [ICE `role`](/en-US/docs/Web/API/RTCIceTransport/role) of the underlying {{domxref("RTCDtlsTransport.iceTransport")}}.
This is one of:
Expand All @@ -57,7 +42,7 @@ These statistics can be obtained by iterating the {{domxref("RTCStatsReport")}}
- [`controlling`](/en-US/docs/Web/API/RTCIceTransport/role#controlling)
- [`unknown`](/en-US/docs/Web/API/RTCIceTransport/role#unknown)

- `iceState` {{optional_inline}} {{experimental_inline}}
- {{domxref("RTCTransportStats.iceState", "iceState")}} {{optional_inline}} {{experimental_inline}}

- : A string indicating the current {{domxref("RTCIceTransport.state","state")}} of the underlying {{domxref("RTCIceTransport")}}.
This is one of:
Expand All @@ -70,22 +55,22 @@ These statistics can be obtained by iterating the {{domxref("RTCStatsReport")}}
- [`failed`](/en-US/docs/Web/API/RTCIceTransport/state#failed)
- [`closed`](/en-US/docs/Web/API/RTCIceTransport/state#closed)

- `selectedCandidatePairId` {{optional_inline}}
- : A string containing the unique identifier for the object that was inspected to produce the {{domxref("RTCIceCandidatePairStats")}} associated with this transport.
- `localCertificateId` {{optional_inline}}
- {{domxref("RTCTransportStats.localCertificateId", "localCertificateId")}} {{optional_inline}}
- : A string containing the id of the local certificate used by this transport.
Only present for DTLS transports, and after DTLS has been negotiated.
- `packetsSent` {{optional_inline}} {{experimental_inline}}
- : The total number of packets sent over this transport.
- `packetsReceived` {{optional_inline}} {{experimental_inline}}
- {{domxref("RTCTransportStats.packetsReceived", "packetsReceived")}} {{optional_inline}} {{experimental_inline}}
- : The total number of packets received on this transport.
- `remoteCertificateId` {{optional_inline}}
- {{domxref("RTCTransportStats.packetsSent", "packetsSent")}} {{optional_inline}} {{experimental_inline}}
- : The total number of packets sent over this transport.
- {{domxref("RTCTransportStats.remoteCertificateId", "remoteCertificateId")}} {{optional_inline}}
- : A string containing the id or the remote certificate used by this transport.
Only present for DTLS transports, and after DTLS has been negotiated.
- `selectedCandidatePairChanges` {{optional_inline}}
- {{domxref("RTCTransportStats.selectedCandidatePairChanges", "selectedCandidatePairChanges")}} {{optional_inline}}
- : The number of times that the selected candidate pair of this transport has changed.
The value is initially zero and increases whenever a candidate pair selected or lost.
- `srtpCipher` {{optional_inline}}
- {{domxref("RTCTransportStats.selectedCandidatePairId", "selectedCandidatePairId")}} {{optional_inline}}
- : A string containing the unique identifier for the object that was inspected to produce the {{domxref("RTCIceCandidatePairStats")}} associated with this transport.
- {{domxref("RTCTransportStats.srtpCipher", "srtpCipher")}} {{optional_inline}}

- : A string indicating the descriptive name of the protection profile used for the [Secure Real-time Transport Protocol (SRTP)](/en-US/docs/Glossary/RTP) transport, as defined in the "Profile" column of the [IANA DTLS-SRTP protection profile registry](https://www.iana.org/assignments/srtp-protection/srtp-protection.xhtml#srtp-protection-1) and [RFC5764](https://www.rfc-editor.org/rfc/rfc5764.html#section-4.1.2).

Expand All @@ -102,7 +87,7 @@ These statistics can be obtained by iterating the {{domxref("RTCStatsReport")}}
auth_tag_length: 80
```

- `tlsVersion` {{optional_inline}}
- {{domxref("RTCTransportStats.tlsVersion", "tlsVersion")}} {{optional_inline}}

- : A string containing the negotiated TLS version.
This is present for DTLS transports, and only exists after DTLS has been negotiated.
Expand Down
Loading