Draft: draft-ietf-rtcweb-jsep

Commentary: Various fixes for 60.2 : Removed parens from API names , removed comment . - put the term stable in quotes , removed comment . - put the term sess - id in angle brackets to match SDP spec , removed comment . - made the tls - id attribute consistent with other SDP attributes , removed comment . - removed quotes from IceRestart option , removed comment . 
 " IceRestart " option / IceRestart option Justin : LGTM 
 tls - id value / " a = tls - id " value  : The source RFC seems to prefer " tls - id " when discussing values . 
 During the editing of the Cluster 238 docs , it was decided that it 's author 's choice when formatting SDP attributes . Although RFC 8842 uses the format ' " tls - id " attribute ' , this document more consistently uses " a = attribute - name " format for SDP attributes , which is the format that the SDP spec [ RFC8866 ] uses . I 'll update this document to consistently use " a = tls - id " 
 sess - id / ( Section 5.2.1 , second bullet item )  : LGTM 
 the stable state ( 1 instance ) / the " stable " state ( 3 instances ) ( Also , should ' the previous stable state ' be ' a previous stable state ' ( per Section 5.7 ) or ' the previous " stable " state ' ? )  : The quoted form is preferred , including the case of " previous stable state " . 
 [ Breaking up issue /60 into smaller bites ] The following terms appear to be used inconsistently in this document . Please let us know which form is preferred .  : There seems to be a pretty clear preponderance for the non - parenthetical form , so let 's keep that . W3C also does not use ( ) .  : We 'll remove the parens ( camelCase is sufficient formatting ) .
Paragraph (version A):
JSEP's handling of session descriptions is simple and
straightforward.  Whenever an offer/answer exchange is needed, the
initiating side creates an offer by calling a createOffer() API.  The
application then uses that offer to set up its local config via the
setLocalDescription() API.  The offer is finally sent off to the
remote side over its preferred signaling mechanism (e.g.,
WebSockets); upon receipt of that offer, the remote party installs it
using the setRemoteDescription() API.
Paragraph (version A):
To complete the offer/answer exchange, the remote party uses the
createAnswer() API to generate an appropriate answer, applies it
using the setLocalDescription() API, and sends the answer back to the
initiator over the signaling channel.  When the initiator gets that
answer, it installs it using the setRemoteDescription() API, and
initial setup is complete.  This process can be repeated for
additional offer/answer exchanges.
Paragraph (version B):
JSEP's handling of session descriptions is simple and
straightforward.  Whenever an offer/answer exchange is needed, the
initiating side creates an offer by calling a createOffer API.  The
application then uses that offer to set up its local config via the
setLocalDescription API.  The offer is finally sent off to the remote
side over its preferred signaling mechanism (e.g., WebSockets); upon
receipt of that offer, the remote party installs it using the
setRemoteDescription API.
Paragraph (version B):
To complete the offer/answer exchange, the remote party uses the
createAnswer API to generate an appropriate answer, applies it using
the setLocalDescription API, and sends the answer back to the
initiator over the signaling channel.  When the initiator gets that
answer, it installs it using the setRemoteDescription API, and
initial setup is complete.  This process can be repeated for
additional offer/answer exchanges.
Paragraph (version A):
The addTrack method adds a MediaStreamTrack to the PeerConnection,
using the MediaStream argument to associate the track with other
tracks in the same MediaStream, so that they can be added to the same
"LS" (Lip Synchronization) group when creating an offer or answer.
Adding tracks to the same "LS" group indicates that the playback of
these tracks should be synchronized for proper lip sync, as described
in RFC5888.  addTrack attempts to minimize the number of transceivers
as follows: if the PeerConnection is in the "have-remote-offer"
state, the track will be attached to the first compatible transceiver
that was created by the most recent call to setRemoteDescription()
and does not have a local track.  Otherwise, a new transceiver will
be created, as described in sec.addTransceiver.
Paragraph (version B):
The addTrack method adds a MediaStreamTrack to the PeerConnection,
using the MediaStream argument to associate the track with other
tracks in the same MediaStream, so that they can be added to the same
"LS" (Lip Synchronization) group when creating an offer or answer.
Adding tracks to the same "LS" group indicates that the playback of
these tracks should be synchronized for proper lip sync, as described
in RFC5888.  addTrack attempts to minimize the number of transceivers
as follows: if the PeerConnection is in the "have-remote-offer"
state, the track will be attached to the first compatible transceiver
that was created by the most recent call to setRemoteDescription and
does not have a local track.  Otherwise, a new transceiver will be
created, as described in sec.addTransceiver.
Paragraph (version A):
"offer" indicates that a description should be parsed as an offer;
said description may include many possible media configurations.  A
description used as an "offer" may be applied any time the
PeerConnection is in a stable state or applied as an update to a
previously supplied but unanswered "offer".
Paragraph (version B):
"offer" indicates that a description should be parsed as an offer;
said description may include many possible media configurations.  A
description used as an "offer" may be applied any time the
PeerConnection is in a "stable" state or applied as an update to a
previously supplied but unanswered "offer".
Paragraph (version A):
"rollback" is a special session description type implying that the
state machine should be rolled back to the previous stable state, as
described in sec.rollback.  The contents MUST be empty.
Paragraph (version B):
"rollback" is a special session description type implying that the
state machine should be rolled back to the previous "stable" state,
as described in sec.rollback.  The contents MUST be empty.
Paragraph (version A):
In certain situations, it may be desirable to "undo" a change made to
setLocalDescription or setRemoteDescription.  Consider a case where a
call is ongoing and one side wants to change some of the session
parameters; that side generates an updated offer and then calls
setLocalDescription.  However, the remote side, either before or
after setRemoteDescription, decides it does not want to accept the
new parameters and sends a reject message back to the offerer.  Now,
the offerer, and possibly the answerer as well, needs to return to a
stable state and the previous local/remote description.  To support
this, we introduce the concept of "rollback", which discards any
proposed changes to the session, returning the state machine to the
stable state.  A rollback is performed by supplying a session
description of type "rollback" with empty contents to either
setLocalDescription or setRemoteDescription.
Paragraph (version B):
In certain situations, it may be desirable to "undo" a change made to
setLocalDescription or setRemoteDescription.  Consider a case where a
call is ongoing and one side wants to change some of the session
parameters; that side generates an updated offer and then calls
setLocalDescription.  However, the remote side, either before or
after setRemoteDescription, decides it does not want to accept the
new parameters and sends a reject message back to the offerer.  Now,
the offerer, and possibly the answerer as well, needs to return to a
"stable" state and the previous local/remote description.  To support
this, we introduce the concept of "rollback", which discards any
proposed changes to the session, returning the state machine to the
"stable" state.  A rollback is performed by supplying a session
description of type "rollback" with empty contents to either
setLocalDescription or setRemoteDescription.
Paragraph (version A):
If the "IceRestart" option is specified, with a value of "true", the
offer MUST indicate an ICE restart by generating new ICE ufrag and
pwd attributes, as specified in RFC8839.  If this option is specified
on an initial offer, it has no effect (since a new ICE ufrag and pwd
are already generated).  Similarly, if the ICE configuration has
changed, this option has no effect, since new ufrag and pwd
attributes will be generated automatically.  This option is primarily
useful for reestablishing connectivity in cases where failures are
detected by the application.
Paragraph (version B):
If the IceRestart option is specified, with a value of "true", the
offer MUST indicate an ICE restart by generating new ICE ufrag and
pwd attributes, as specified in RFC8839.  If this option is specified
on an initial offer, it has no effect (since a new ICE ufrag and pwd
are already generated).  Similarly, if the ICE configuration has
changed, this option has no effect, since new ufrag and pwd
attributes will be generated automatically.  This option is primarily
useful for reestablishing connectivity in cases where failures are
detected by the application.
Paragraph (version A):
A rollback may be performed if the PeerConnection is in any state
except for "stable".  This means that both offers and provisional
answers can be rolled back.  Rollback can only be used to cancel
proposed changes; there is no support for rolling back from a stable
state to a previous stable state.  If a rollback is attempted in the
"stable" state, processing MUST stop and an error MUST be returned.
Note that this implies that once the answerer has performed
setLocalDescription with its answer, this cannot be rolled back.
Paragraph (version B):
A rollback may be performed if the PeerConnection is in any state
except for "stable".  This means that both offers and provisional
answers can be rolled back.  Rollback can only be used to cancel
proposed changes; there is no support for rolling back from a
"stable" state to a previous "stable" state.  If a rollback is
attempted in the "stable" state, processing MUST stop and an error
MUST be returned.  Note that this implies that once the answerer has
performed setLocalDescription with its answer, this cannot be rolled
back.
Paragraph (version A):
While formally the JSEP interface is an API, it is better to think of
it as an Internet protocol, with the application JavaScript being
untrustworthy from the perspective of the JSEP implementation.  Thus,
the threat model of RFC3552 applies.  In particular, JavaScript can
call the API in any order and with any inputs, including malicious
ones.  This is particularly relevant when we consider the SDP that is
passed to setLocalDescription().  While correct API usage requires
that the application pass in SDP that was derived from createOffer()
or createAnswer(), there is no guarantee that applications do so.
The JSEP implementation MUST be prepared for the JavaScript to pass
in bogus data instead.
Paragraph (version B):
While formally the JSEP interface is an API, it is better to think of
it as an Internet protocol, with the application JavaScript being
untrustworthy from the perspective of the JSEP implementation.  Thus,
the threat model of RFC3552 applies.  In particular, JavaScript can
call the API in any order and with any inputs, including malicious
ones.  This is particularly relevant when we consider the SDP that is
passed to setLocalDescription.  While correct API usage requires that
the application pass in SDP that was derived from createOffer or
createAnswer, there is no guarantee that applications do so.  The
JSEP implementation MUST be prepared for the JavaScript to pass in
bogus data instead.