WebRTC-HTTP Egress Protocol (WHEP)

4.1. ICE and NAT support

The SDP provided by the WHEP Player MAY be sent after the full ICE gathering is complete with the full list of ICE candidates, or it MAY only contain local candidates (or even an empty list of candidates) as per [RFC8863].¶

In order to simplify the protocol, there is no support for exchanging gathered trickle candidates from Media Server ICE candidates once the SDP answer is sent. The WHEP Endpoint SHALL gather all the ICE candidates for the Media Server before responding to the client request and the SDP answer SHALL contain the full list of ICE candidates of the Media Server. The Media Server MAY use ICE lite, while the WHEP player MUST implement full ICE.¶

Trickle ICE and ICE restart support is OPTIONAL for a WHEP resource.¶

If the WHEP resource supports either Trickle ICE or ICE restarts, the WHEP player MUST include an "Accept-Patch" header with a mime type value of "application/trickle-ice-sdpfrag" in the "201 Created" of the POST request that creates the WHEP resource as per [RFC5789] section 3.1.¶

If the WHEP resource supports either Trickle ICE or ICE restarts, but not both, it MUST return a "405 Not Implemented" response for the HTTP PATCH requests that are not supported.¶

If the WHEP resource does not support the PATCH method for any purpose, it MUST return a "501 Not Implemented" response, as described in [RFC9110] section 6.6.2.¶

As the HTTP PATCH request sent by a WHEP player may be received out-of-order by the WHEP resource, the WHEP resource MUST generate a unique strong entity-tag identifying the ICE session as per [RFC9110] section 2.3. The initial value of the entity-tag identifying the initial ICE session MUST be returned in an ETag header field in the "201 Created" response to the initial POST request to the WHEP endpoint. It MUST also be returned in the "200 OK" of any PATCH request that triggers an ICE restart. Note that including the ETag in the original "201 Created" response is only REQUIRED if the WHEP resource supports ICE restarts and OPTIONAL otherwise.¶

A WHEP player sending a PATCH request for performing trickle ICE MUST include an "If-Match" header field with the latest known entity-tag as per [RFC9110] section 3.1. When the PATCH request is received by the WHEP resource, it MUST compare the indicated entity-tag value with the current entity-tag of the resource as per [RFC9110] section 3.1 and return a "412 Precondition Failed" response if they do not match.¶

WHEP players SHOULD NOT use entity-tag validation when matching a specific ICE session is not required, such as for example when initiating a DELETE request to terminate a session.¶

A WHEP resource receiving a PATCH request with new ICE candidates, but which does not perform an ICE restart, MUST return a "204 No Content" response without body. If the Media Server does not support a candidate transport or is not able to resolve the connection address, it MUST accept the HTTP request with the "204 No Content" response and silently discard the candidate.¶

PATCH /resource/id HTTP/1.1
Host: whep.example.com
If-Match: "38sdf4fdsf54:EsAw"
Content-Type: application/trickle-ice-sdpfrag
Content-Length: 548

a=ice-ufrag:EsAw
a=ice-pwd:P2uYro0UCOQ4zxjKXaWCBui1
m=audio RTP/AVP 0
a=mid:0
a=candidate:1387637174 1 udp 2122260223 192.0.2.1 61764 typ host generation 0 ufrag EsAw network-id 1
a=candidate:3471623853 1 udp 2122194687 198.51.100.1 61765 typ host generation 0 ufrag EsAw network-id 2
a=candidate:473322822 1 tcp 1518280447 192.0.2.1 9 typ host tcptype active generation 0 ufrag EsAw network-id 1
a=candidate:2154773085 1 tcp 1518214911 198.51.100.2 9 typ host tcptype active generation 0 ufrag EsAw network-id 2
a=end-of-candidates

HTTP/1.1 204 No Content

A WHEP Player sending a PATCH request for performing ICE restart MUST contain an "If-Match" header field with a field-value "*" as per [RFC9110] section 3.1.¶

If the HTTP PATCH request results in an ICE restart, the WHEP resource SHALL return a "200 OK" with an "application/trickle-ice-sdpfrag" body containing the new ICE username fragment and password and OPTIONALLY a new set of ICE candidates for the WHIP client . Also, the "200 OK" response for a successful ICE restart MUST contain the new entity-tag corresponding to the new ICE session in an ETag response header field and MAY contain a new set of ICE candidates for the Media Server.¶

If the ICE request cannot be satisfied by the WHEP resource, the resource MUST return an appropriate HTTP error code and MUST NOT terminate the session immediately. The WHEP player MAY retry performing a new ICE restart or terminate the session by issuing an HTTP DELETE request instead. In either case, the session MUST be terminated if the ICE consent expires as a consequence of the failed ICE restart as per [RFC7675] section 5.1.¶

PATCH /resource/id HTTP/1.1
Host: whep.example.com
If-Match: "*"
Content-Type: application/trickle-ice-sdpfrag
Content-Length: 54

a=ice-ufrag:ysXw
a=ice-pwd:vw5LmwG4y/e6dPP/zAP9Gp5k

HTTP/1.1 200 OK
ETag: "289b31b754eaa438:ysXw"
Content-Type: application/trickle-ice-sdpfrag
Content-Length: 102

a=ice-lite
a=ice-ufrag:289b31b754eaa438
a=ice-pwd:0b66f472495ef0ccac7bda653ab6be49ea13114472a5d10a

Because the WHEP Player needs to know the entity-tag associated with the ICE session in order to send new ICE candidates, it MUST buffer any gathered candidates before it receives the HTTP response to the initial POST request or the PATCH request with the new entity-tag value. Once it knows the entity-tag value, the WHEP Player SHOULD send a single aggregated HTTP PATCH request with all the ICE candidates it has buffered so far.¶

In case of unstable network conditions, the ICE restart HTTP PATCH requests and responses might be received out of order. n order to mitigate this scenario, when the client performs an ICE restart, it MUST discard any previous ice username and passwords fragments and ignore any further HTTP PATCH response received from a pending HTTP PATCH request. WHEP Players MUST apply only the ICE information received in the response to the last sent request. If there is a mismatch between the ICE information at the client and at the server (because of an out-of-order request), the STUN requests will contain invalid ICE information and will be rejected by the server. When this situation is detected by the WHEP Player, it SHOULD send a new ICE restart request to the server.¶

4.2. WebRTC constraints

In the specific case of media consumption from a streaming service, some assumptions can be made about the server-side which simplifies the WebRTC compliance burden, as detailed in WebRTC-gateway document [I-D.draft-ietf-rtcweb-gateways].¶

In order to reduce the complexity of implementing WHEP in both players and Media Servers, WHEP imposes the following restrictions regarding WebRTC usage:¶

Both the WHEP Player and the WHEP Endpoint SHALL use SDP bundle [RFC9143]. Each "m=" section MUST be part of a single BUNDLE group. Hence, when a WHEP Playersends an SDP offer, it MUST include a "bundle-only" attribute in each bundled "m=" section. The WHEP player and the Media Server MUST support multiplexed media associated with the BUNDLE group as per [RFC9143] section 9. In addition, per [RFC9143] the WHEP Player and Media Server will use RTP/RTCP multiplexing for all bundled media. The WHEP Player and Media Server SHOULD include the "rtcp-mux-only" attribute in each bundled "m=" section as per [RFC8858].¶

Trickle ICE and ICE restarts support is OPTIONAL for both the WHEP Players and Media Servers as explained in section 4.1.¶

4.3. Load balancing and redirections

WHEP Endpoints and Media Servers might not be co-located on the same server, so it is possible to load balance incoming requests to different Media Servers. WHEP Players SHALL support HTTP redirection via the "307 Temporary Redirect" response as described in [RFC9110] section 6.4.7. The WHEP Resource URL MUST be a final one, and redirections are not required to be supported for the PATCH and DELETE requests sent to it.¶

In case of high load, the WHEP endpoints MAY return a "503 Service Unavailable" response indicating that the server is currently unable to handle the request due to a temporary overload or scheduled maintenance, which will likely be alleviated after some delay. The WHEP Endpoint might send a Retry-After header field indicating the minimum time that the user agent ought to wait before making a follow-up request.¶

4.4. STUN/TURN server configuration

The WHEP Endpoint MAY return STUN/TURN server configuration URLs and credentials usable by the client in the "201 Created" response to the HTTP POST request to the WHEP Endpoint URL.¶

Each STUN/TURN server will be returned using the "Link" header field [RFC8288] with a "rel" attribute value of "ice-server" as specified in [I-D.draft-ietf-wish-whip]¶

It might be also possible to configure the STUN/TURN server URLs with long-term credentials provided by either the broadcasting service or an external TURN provider on the WHEP Player, overriding the values provided by the WHEP Endpoint.¶

4.5. Authentication and authorization

WHEP Endpoints and Resources MAY require the HTTP request to be authenticated using an HTTP Authorization header field with a Bearer token as specified in [RFC6750] section 2.1. WHEP players MUST implement this authentication and authorization mechanism and send the HTTP Authorization header field in all HTTP requests sent to either the WHEP endpoint or resource except the preflight OPTIONS requests for CORS.¶

The nature, syntax, and semantics of the bearer token, as well as how to distribute it to the client, is outside the scope of this document. Some examples of the kind of tokens that could be used are, but are not limited to, JWT tokens as per [RFC6750] and [RFC8725] or a shared secret stored on a database.¶

WHEP Endpoints and Resources could perform the authentication and authorization by encoding an authentication token within the URLs for the WHEP Endpoints or Resources instead. In case the WHEP Player is not configured to use a bearer token, the HTTP Authorization header field must not be sent in any request.¶

4.6. Protocol extensions

In order to support future extensions to be defined for the WHEP protocol, a common procedure for registering and announcing the new extensions is defined.¶

Protocol extensions supported by the WHEP server MUST be advertised to the WHEP Player in the "201 Created" response to the initial HTTP POST request sent to the WHEP Endpoint. The WHEP Endpoint MUST return one "Link" header field for each extension, with the extension "rel" type attribute and the URI for the HTTP resource that will be available for receiving requests related to that extension.¶

Protocol extensions are optional for both WHEP Players and WHEP Endpoints and Resources. WHEP Players MUST ignore any Link attribute with an unknown "rel" attribute value and WHEP Endpoints and Resources MUST NOT require the usage of any of the extensions.¶

Each protocol extension MUST register a unique "rel" attribute value at IANA starting with the prefix: "urn:ietf:params:whep:ext" as specified in Section 6.2.¶

In the first version of the WHEP specification, two optional extensions are defined: the Server Sent Events and the Video Layer Selection.¶

HTTP/1.1 201 Created
Content-Type: application/sdp
Location: https://whep.example.org/resource/213786HF
Link: <https://whep.ietf.org/resource/213786HF/sse>;
      rel="urn:ietf:params:whep:ext:core:server-sent-events"
      events="active,inactive,layers,viewercount"

POST /resource/213786HF/sse HTTP/1.1
Host: whep.example.com
Content-Type: application/sjon

["active","inactive","layers","viewercount"]

HTTP/1.1 201 Created
Location: https://whep.example.org/resource/213786HF/sse/event-stream

event: viewercount
data: {"viewercount":3}

{
  "0": {
    "active": [
      {
        "id": "1", "simulcastIdx": 1, "bitrate": 538288, width: 640, height: 360
      },
      {
        "id": "0", "simulcastIdx": 0, "bitrate": 111600, width: 320, height: 180
      }
    ],
    "inactive": [
      {
        "id": "2", "simulcastIdx": 2
      },
    ],
    "layers": [
      { "encodingId": "1", "simulcastIdx": 1, "spatialLayerId": 0, "temporalLayerId": 1, "bitrate": 557112, width: 640, height: 360 },
      { "encodingId": "1", "simulcastIdx": 1, "spatialLayerId": 0, "temporalLayerId": 0, "bitrate": 343592, width: 640, height: 360 },
      { "encodingId": "0", "simulcastIdx": 0, "spatialLayerId": 0, "temporalLayerId": 1, "bitrate": 116352, width: 320, height: 180 },
      { "encodingId": "0", "simulcastIdx": 0, "spatialLayerId": 0, "temporalLayerId": 0, "bitrate": 67464 , width: 320, height: 180 }
    ]
  }
}

HTTP/1.1 201 Created
Content-Type: application/sdp
Location: https://whep.example.org/resource/213786HF
Link: <https://whep.ietf.org/resource/213786HF/layer>;
      rel="urn:ietf:params:whep:ext:core:layer"
Link: <https://whep.ietf.org/resource/213786HF/layer>;
      rel="urn:ietf:params:whep:ext:core:server-sent-events"
      events="layers"

POST /resource/213786HF/layer HTTP/1.1
Host: whep.example.com
Content-Type: application/sjon

{mediaId:"0", "encodingId": "hd"}

HTTP/1.1 200 OK

POST /resource/213786HF/layer HTTP/1.1
Host: whep.example.com
Content-Type: application/sjon

{}

HTTP/1.1 200 OK

6.1. Registration of WHEP URN Sub-namespace and whep Registry

IANA has added an entry to the "IETF URN Sub-namespace for Registered Protocol Parameter Identifiers" registry and created a sub-namespace for the Registered Parameter Identifier as per [RFC3553]: "urn:ietf:params:whep".¶

To manage this sub-namespace, IANA has created the "System for Cross-domain Identity Management (WHEP) Schema URIs" registry, which is used to manage entries within the "urn:ietf:params:whep" namespace. The registry description is as follows:¶

• Registry name: WHEP¶
• Specification: this document (RFC TBD)¶
• Repository: See Section Section 6.2¶
• Index value: See Section Section 6.2¶

6.2. URN Sub-namespace for whep

whep Endpoint utilize URIs to identify the supported whep protocol extensions on the "rel" attribute of the Link header as defined in Section 4.6. This section creates and registers an IETF URN Sub-namespace for use in the whep specifications and future extensions.¶

  The Namespace ID "whep" has been assigned.

  Version: 1

  Date: TBD

  The Internet Engineering Task Force.

   A designated expert will monitor the whep public mailing list, "wish@ietf.org".

  The Namespace Specific String (NSS) of all URNs that use the "whep" Namespace ID shall have the following structure: urn:ietf:params:whep:{type}:{name}:{other}

  The keywords have the following meaning:

  - type: The entity type. This specification only defines the "ext" type.

  - name: A required US-ASCII string that conforms to the URN syntax requirements (see {{RFC8141}}) and defines a major namespace of a whep protocol extension. The value MAY also be an industry name or organization name.

  - other: Any US-ASCII string that conforms to the URN syntax requirements (see {{RFC8141}}) and defines the sub-namespace (which MAY be further broken down in namespaces delimited by colons) as needed to uniquely identify an whep protocol extension.

  None

  The designated contact shall be responsible for reviewing and enforcing uniqueness.

  Once a name has been allocated, it MUST NOT be reallocated for a different purpose.
  The rules provided for assignments of values within a sub-namespace MUST be constructed so that the meanings of values cannot change.
  This registration mechanism is not appropriate for naming values whose meanings may change over time.

  Namespace with type "ext" (e.g., "urn:ietf:params:whep:ext") is reserved for IETF-approved whep specifications.

  None specified.

  No special considerations; the rules for lexical equivalence specified in {{RFC8141}} apply.

  No special considerations.

  None specified.

  Global.