Draft: draft-ietf-rtcweb-jsep

Commentary: Explain more about use of  - bundle by implementations Explain sess - id limits  use of " we " throughout
Paragraph (version A):
However, to provide for future flexibility, the SDP syntax is
encapsulated within a SessionDescription object, which can be
constructed from SDP and be serialized out to SDP.  If future
specifications agree on a JSON format for session descriptions, we
could easily enable this object to generate and consume that JSON.
Paragraph (version A):
As detailed below, most applications should be able to treat the
SessionDescriptions produced and consumed by these various API calls
as opaque blobs; that is, the application will not need to read or
change them.
Paragraph (version A):
In order to give the application control over various common session
parameters, JSEP provides control surfaces that tell the JSEP
implementation how to generate session descriptions.  This avoids the
need for JavaScript to modify session descriptions in most cases.
Paragraph (version B):
However, to provide for future flexibility, the SDP syntax is
encapsulated within a SessionDescription object, which can be
constructed from SDP and be serialized out to SDP.  If future
specifications agree on a JSON format for session descriptions, this
object could be enhanced to generate and consume that JSON.
Paragraph (version B):
As detailed below, most applications should be able to treat the
SessionDescriptions produced and consumed by these various API calls
as opaque blobs; that is, the application will not need to parse or
understand them.
Paragraph (version B):
In order to give the application control over various common session
parameters, JSEP provides control surfaces that tell the JSEP
implementation how to generate session descriptions.  In most cases,
this removes the need for applications to modify session descriptions
after they are created.
Paragraph (version A):
Implementations MUST be prepared to receive objects with some fields
missing, as mentioned above.
Paragraph (version B):
Other than the "m=" section index, all IceCandidate fields are
optional, and implementations MUST NOT reject a candidate simply
because an optional field is missing.
Paragraph (version A):
RFC8829 defined a policy known as "max-bundle", which, while defined
identically to the "must-bundle" policy described above, was
implemented by some implementations according to an earlier, pre-
standard definition (in which, for example, no "m=" sections were
marked as bundle-only).  As a result, "max-bundle" is considered
deprecated, and new applications should use the "must-bundle" policy
instead.
Paragraph (version B):
RFC8829 defined a policy known as "max-bundle", which, while defined
identically to the "must-bundle" policy described above, was
implemented by some implementations according to an earlier, pre-
standard definition (in which, for example, no "m=" sections were
marked as bundle-only).  As a result, "max-bundle" is considered
deprecated, and implementations compliant with this specification
SHOULD ignore attempts by the application to select this bundle
policy (although some phase-out period may be necessary to avoid
application breakage).
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, this specification introduces 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):
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 one considers 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.