Draft: draft-ietf-wish-whip

Commentary: Minor change here : SDP BUNDLE is used by the WHIP endpoint , not the media server . The Media Server receives the bundled media but is not involved in the SDP ( according to the definition of WHIP enpoints and Media Server in the draft ) 
 In the example ICE server configuration of , every  header is having a trailing semicolon . But as per and it seems there wo n't be any trailing semicolon in the  header . This trailing semicolon could cause the parsing libraries ( ) to create an extra param with empty string 
 thank you ! already fixed that in his editorial PR 
 The text says : " o As easy to use as current RTMP URIs . " It says a little strange to say that a protocol is as easy to use as curent RTMP URIs . 
 fixed by in 
 The text says : " RTSP , which is based on RTP and maybe the closest in terms of features to webrtc , is not compatible with WebRTC SDP offer / answer model . " I think I commented on this earlier , but what is the " WebRTC SDP offer / answer model " ? 
 This has been reworded by in , does the new text address this issue ? 
 The text says : " while RTCWEB standardized the signalling protocol itself ( JSEP , SDP O / A ) "  is not a singlalling protocol , and RTCWEB did not standardize any SDP O / A signalling . 
 This has been reworded by in , does the new text address this issue ? 
 I think the Abstract is too long ( I think  gave the same comment ) . You do n't need the background and justification in the Abstract - just say what the document does . The rest can be moved to the Introduction . 
 This has been reworded by in , does the new text address this issue ? 
 Offer / Answer has only been standardized for SDP ( and , one may claim , for JSEP ) . I think you need some text on how you are now defining the usage of Offer / Answer ( if only for a specific use - case ) with HTTP . 
 This has been reworded by in , does the new text address this issue ? 
 The abstract does n't read like an abstract , it 's more like an introduction . While it contains interesting material , I think most of the discourse should be moved into the introduction and the abstract rewritten . 
 This has been reworded by in , does the new text address this issue ?
While WebRTC has been very successful in a wide range of scenarios,
its adoption in the broadcasting/streaming industry is lagging
behind.  Currently there is no standard protocol (like SIP or RTSP)
designed for ingesting media into a streaming service using WebRTC
and so content providers still rely heavily on protocols like RTMP
for it.
This document describes a simple HTTP-based protocol that will allow
WebRTC-based ingest of content into streaming services and/or CDNs.
While WebRTC has been very successful in a wide range of scenarios,
its adoption in the broadcasting/streaming industry is lagging
behind.  Currently, there is no standard protocol (like SIP or RTSP)
designed for ingesting media into a streaming service using WebRTC
and so content providers still rely heavily on protocols like RTMP
for doing so.
This document proposes a simple HTTP based protocol that will allow
WebRTC based ingest of content into streaming services and/or CDNs.
RTCWEB standardized JSEP (RFC8829), a mechanism used to control the
setup, management, and teardown of a multimedia session, how to apply
it using the SDP Offer/Answer model and all the formats for the data
sent over the wire (media, codec, encryption, ...).  Also, WebRTC
intentionally does not specify a signaling transport protocol at
application level.  This flexibility has allowed the implementation
of a wide range of services.  However, those services are typically
standalone silos which don't require interoperability with other
services or leverage the existence of tools that can communicate with
them.
In the broadcasting/streaming world, the usage of hardware encoders
that make it very simple to plug in (SDI) cables carrying raw media,
encode it in place, and push it to any streaming service or CDN
ingest is already ubiquitous.  It is the adoption of a custom
signaling transport protocol for each WebRTC service has hindered
broader adoption as an ingestion protocol.
While some standard signaling protocols are available that can be
integrated with WebRTC, like SIP or XMPP, they are not designed to be
used in broadcasting/streaming services, and there also is no sign of
adoption in that industry.  RTSP, which is based on RTP and may be
the closest in terms of features to WebRTC, is not compatible with
the WebRTC SDP offer/answer model.
Easy to implement,
As easy to use as current RTMP URIs.
Fully compliant with WebRTC and RTCWEB specs.
Allows for both ingest in traditional media platforms and ingest
in WebRTC end-to-end platforms with the lowest possible latency.
Usable both in web browsers and in native encoders.
The IETF RTCWEB working group standardized JSEP (RFC8829), a
mechanism used to control the setup, management, and teardown of a
multimedia session.  It also describes how to negotiate media flows
using the SDP Offer/Answer model as well as the formats for data sent
over the wire (e.g., media types, codec parameters, and encryption).
WebRTC intentionally does not specify a signaling transport protocol
at application level.  This flexibility has allowed the
implementation of a wide range of services.  However, those services
are typically standalone silos which don't require interoperability
with other services or leverage the existence of tools that can
communicate with them.
In the broadcasting/streaming world, the use of hardware encoders
that make it very simple to plug in cables carrying raw media, encode
it in-place, and push it to any streaming service or CDN ingest is
already ubiquitous.  It is the adoption of a custom signaling
transport protocol for each WebRTC service has hindered broader
adoption as an ingestion protocol.
While some standard signaling protocols are available that can be
integrated with WebRTC, like SIP or XMPP, they are not designed to be
used in broadcasting/streaming services, and there also is no sign of
adoption in that industry.  RTSP, which is based on RTP and may be
the closest in terms of features to WebRTC, is not compatible with
the WebRTC SDP offer/answer model RFC3264.
Is easy to implement,
Allows for ingest both in traditional media platforms and in
WebRTC end-to-end platforms with the lowest possible latency.
Is usable both in web browsers and in native encoders.
The WebRTC-HTTP ingest protocol (WHIP) uses an HTTP POST request to
perform a single shot SDP offer/answer so an ICE/DTLS session can be
established between the encoder/media producer (WHIP client) and the
broadcasting ingestion endpoint (media server).
The WebRTC-HTTP Ingest Protocol (WHIP) uses an HTTP POST request to
perform a single-shot SDP offer/answer so an ICE/DTLS session can be
established between the encoder/media producer (WHIP client) and the
broadcasting ingestion endpoint (media server).
In order to setup an ingestion session, the WHIP client will generate
an SDP offer according to the JSEP rules and do an HTTP POST request
to the WHIP endpoint configured URL.
The HTTP POST request will have a content type of application/sdp and
contain the SDP offer as the body.  The WHIP endpoint will generate
an SDP answer and return a 201 Created response with a content type
of application/sdp and the SDP answer as the body and a Location
header pointing to the newly created resource.
The SDP offer SHOULD use the sendonly attribute and the SDP answer
MUST use the recvonly attribute.
To explicitly terminate the session, the WHIP client MUST perform an
HTTP DELETE request to the resource URL returned in the Location
header of the initial HTTP POST.  Upon receiving the HTTP DELETE
request, the WHIP resource will be removed and the resources freed on
the media server, terminating the ICE and DTLS sessions.
In order to setup an ingestion session, the WHIP client will generate
an SDP offer according to the JSEP rules and perform an HTTP POST
request to the configured WHIP endpoint URL.
The HTTP POST request will have a content type of "application/sdp"
and contain the SDP offer as the body.  The WHIP endpoint will
generate an SDP answer and return a "201 Created" response with a
content type of "application/sdp", the SDP answer as the body, and a
Location header field pointing to the newly created resource.
The SDP offer SHOULD use the "sendonly" attribute and the SDP answer
MUST use the "recvonly" attribute.
To explicitly terminate a session, the WHIP client MUST perform an
HTTP DELETE request to the resource URL returned in the Location
header field of the initial HTTP POST.  Upon receiving the HTTP
DELETE request, the WHIP resource will be removed and the resources
freed on the media server, terminating the ICE and DTLS sessions.
The initial offer by the WHIP client MAY be sent after the full ICE
gathering is complete with the full list of ICE candidates, or only
contain local candidates or even an empty list of candidates.
The initial offer by the WHIP client 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).
The WHIP client MAY perform trickle ICE or an ICE restarts RFC8863 by
sending a HTTP PATCH request to the WHIP resource URL with a body
containing a SDP fragment with MIME type "application/trickle-ice-
sdpfrag" as specified in RFC8840 with the new ICE candidate or ICE
ufrag/pwd for ICE restarts.
As the HTTP PATCH request sent by a WHIP client may be received out
of order by the WHIP resource, the WHIP resource MUST generate a
unique strong entity-tag identifying the ICE session as per RFC7232
section 2.3.  The initial value of the entity-tag identifying the
initial ICE session MUST be returned in an ETag header in the 201
response to the initial POST request to the WHIP endpoint and in the
200 OK of a PATCH request that triggers an ICE restart.
A WHIP client sending a PATCH request for performing trickle ICE MUST
contain an If-Match header with the latest known entity-tag as per
RFC7232 section 3.1.  When the PATCH request is received by the WHIP
resource, it MUST compare the entity-tag value requested with the
current entity-tag of the resource as per RFC7232 section 3.1 and
return a 412 Precondition Failed response if they do not match.
WHIP clients SHOULD NOT use entity-tag validation when matching a
specific ICE session is not required, such as for example when
initiating a DELETE request in order to terminate a session.
A WHIP 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 response and
silently discard the candidate.
A WHIP client sending a PATCH request for performing ICE restart MUST
contain an If-Match header with a field-value "*" as per RFC7232
section 3.1.
If the HTTP PATCH request results in an ICE restart, the WHIP
resource SHALL return a 200 OK with an "application/trickle-ice-
sdpfrag" body containing the new ICE username fragment and password
and, optionally, the new set of ICE candidates for the media server
and the new entity-tag correspond to the new ICE session in an ETag
response header.
If the ICE request can not be performed by the WHIP resource it MUST
return an appropriate HTTP error code but MUST NOT terminate the
session immediately.  The WHIP client MAY try again to perform a new
ICE restart or terminate the session issuing a HTTP DELETE request
instead.  In any 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.
Given that in order to send new ICE candidates to the WHIP resource,
the WHIP client needs to know the entity-tag associated to the ICE
session, it MUST buffer any gathered candidates before the HTTP
response to the initial PUT request or the PATCH request with the new
entity-tag value is received.  Once the entity-tag value is known the
WHIP client 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.  In order to
mitigate this scenario, when the client performs an ICE restart, it
MUST discard any previous ice username/pwd frags and ignore any
further HTTP PATCH response received from a pending HTTP PATCH
request and 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 info and
will be rejected by the server.  When this situation is detected by
the WHIP Client it SHOULD send a new ICE restart request to the
server.
In order to reduce the complexity of implementing WHIP in both
clients and media servers, some restrictions regarding WebRTC usage
are made.
SDP bundle SHALL be used by both the WHIP client and the media
server.  The SDP offer created by the WHIP client must include the
bundle-only attribute in all m-lines as per RFC8843.  Also, RTCP
muxing SHALL be supported by both the WHIP client and the media
server.
Unlike RFC5763 a WHIP client MAY use a setup attribute value of
setup:active in the SDP offer, in which case the WHIP endpoint MUST
use a setup attribute value of setup:passive in the SDP answer.
WHIP endpoints and media servers might not be colocated on the same
server so it is possible to load balance incoming requests to
different media servers.  WHIP clients SHALL support HTTP redirection
via the 307 Temporary Redirect response code in the initial HTTP
response to the WHIP endpoint URL.  The WHIP resource URL MUST be a
final one, and redirections are not required to be supported for the
PATCH and DELETE request sent to it.
The WHIP client MAY perform trickle ICE or ICE restarts RFC8863 by
sending an HTTP PATCH request to the WHIP resource URL with a body
containing a SDP fragment with MIME type "application/trickle-ice-
sdpfrag" as specified in RFC8840.  When used for trickle ICE, the
body of this PATCH message will contain the new ICE candidate; when
used for ICE restarts, it will contain a new ICE ufrag/pwd pair.
As the HTTP PATCH request sent by a WHIP client may be received out-
of-order by the WHIP resource, the WHIP resource MUST generate a
unique strong entity-tag identifying the ICE session as per RFC7232
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 response to the initial POST request to the WHIP endpoint.  It
MUST also be returned in the 200 OK of any PATCH request that
triggers an ICE restart.
A WHIP client sending a PATCH request for performing trickle ICE MUST
include an "If-Match" header field with the latest known entity-tag
as per RFC7232 section 3.1.  When the PATCH request is received by
the WHIP resource, it MUST compare the indicated entity-tag value
with the current entity-tag of the resource as per RFC7232 section
3.1 and return a "412 Precondition Failed" response if they do not
match.
WHIP clients 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 WHIP 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 response and
silently discard the candidate.
A WHIP client sending a PATCH request for performing ICE restart MUST
contain an "If-Match" header field with a field-value "*" as per
RFC7232 section 3.1.
If the HTTP PATCH request results in an ICE restart, the WHIP
resource SHALL return a "200 OK" with an "application/trickle-ice-
sdpfrag" body containing the new ICE username fragment and password.
The response may optionally contain the new set of ICE candidates for
the media server and the new entity-tag correspond to the new ICE
session in an ETag response header field.
If the ICE request cannot be satisfied by the WHIP resource, the
resource MUST return an appropriate HTTP error code and MUST NOT
terminate the session immediately.  The WHIP client 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.
Because the WHIP client 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 PUT request or the PATCH request with the new entity-tag
value.  Once it knows the entity-tag value, the WHIP client 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.  In order to
mitigate this scenario, when the client performs an ICE restart, it
MUST discard any previous ice username/pwd frags and ignore any
further HTTP PATCH response received from a pending HTTP PATCH
request.  Clients 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 WHIP Client, it SHOULD send a new ICE restart
request to the server.
Bothe the WHIP client and the media server SHALL use SDP bundle
RFC8843.  The SDP offer created by the WHIP client must include the
bundle-only attribute in all m-lines as per RFC8843.  Also, RTCP
muxing SHALL be supported by both the WHIP client and the media
server.
Unlike the behavior defined by RFC5763, a WHIP client MAY use a setup
attribute value of setup:active in the SDP offer, in which case the
WHIP endpoint MUST use a setup attribute value of setup:passive in
the SDP answer.
WHIP endpoints and media servers might not be colocated on the same
server, so it is possible to load balance incoming requests to
different media servers.  WHIP clients SHALL support HTTP redirection
via the "307 Temporary Redirect response code" as described in
RFC7231 section 6.4.7.  The WHIP resource URL MUST be a final one,
and redirections are not required to be supported for the PATCH and
DELETE requests sent to it.
The WHIP endpoint MAY return ICE server configuration urls and
credentials usable by the client in the 201 Created response to the
HTTP POST request to the WHIP endpoint url.
username: If the Link header represents a TURN server, and
credential-type is "password", then this attribute specifies the
username to use with that TURN server.
credential: If credential-type attribute is missing or has a
"password" value, the credential attribute represents a long-term
authentication password, as described in RFC8489, Section 10.2.
credential-type: If the Link header represents a TURN server, then
this attribute specifies how the credential attribute value should
be used when that TURN server requests authorization.  The default
value if the attribute is not present is "password".
The WHIP endpoint MAY return ICE server configuration URLs and
credentials usable by the client in the "201 Created" response to the
HTTP POST request to the WHIP endpoint URL.
username: If the Link header field represents a TURN server, and
credential-type is "password", then this attribute specifies the
username to use with that TURN server.
credential: If the "credential-type" attribute is missing or has a
"password" value, the credential attribute represents a long-term
authentication password, as described in RFC8489, Section 10.2.
credential-type: If the Link header field represents a TURN
server, then this attribute specifies how the credential attribute
value should be used when that TURN server requests authorization.
The default value if the attribute is not present is "password".
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 WHIP client overriding the values
provided by the WHIP endpoint.
WHIP endpoints and resources MAY require the HTTP request to be
authenticated using an HTTP Authorization header with a Bearer token
as specified in RFC6750 section 2.1.  WHIP clients MUST implement
this authentication and authorization mechanism and send the HTTP
Authorization header in all HTTP requests sent to either the WHIP
endpoint or resource.
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.  The tokens are typically made available
to the end user alongside the WHIP endpoint url and configured on the
WHIP clients.
WHIP endpoints and resources could perform the authentication and
authorization by encoding an authentication token within the urls for
the WHIP endpoints or resources instead.  In case the WHIP client is
not configured to use a bearer token the HTTP Authorization header
must not be sent in any request.
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 WHIP client, overriding the values
provided by the WHIP endpoint.
WHIP 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.  WHIP clients MUST
implement this authentication and authorization mechanism and send
the HTTP Authorization header field in all HTTP requests sent to
either the WHIP endpoint or resource.
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.  The tokens are typically made
available to the end user alongside the WHIP endpoint URL and
configured on the WHIP clients (similar to the way RTMP URLs and
Stream Keys are distributed).
WHIP endpoints and resources could perform the authentication and
authorization by encoding an authentication token within the URLs for
the WHIP endpoints or resources instead.  In case the WHIP client is
not configured to use a bearer token, the HTTP Authorization header
field must not be sent in any request.
Protocol extensions supported by the WHIP server MUST be advertised
to the WHIP client on the 201 Created response to the initial HTTP
POST request sent to the WHIP endpoint.  The WHIP endpoint MUST
return one Link header 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 supported by the WHIP server MUST be advertised
to the WHIP client in the "201 Created" response to the initial HTTP
POST request sent to the WHIP endpoint.  The WHIP 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.
For example, taking a potential extension of server to client
communication using server sent events as specified in
https://html.spec.whatwg.org/multipage/server-sent-
events.html#server-sent-events, the URL for connecting to the server
side event resource for the published stream will be returned in the
initial HTTP "201 Created" response with a "Link" header and a "rel"
attribute of "urn:ietf:params:whip:server-sent-events".
The link relation types below have been registered by IANA per
Section 4.2 of RFC8288.
Description: Describe the STUN and TURN servers that can be used by
the ICE Agent to establish a connection with a peer.
The link relation type below has been registered by IANA per
Section 4.2 of RFC8288.
Description: For the WHIP protocol, conveys the STUN and TURN servers
that can be used by an ICE Agent to establish a connection with a
peer.