Draft: draft-ietf-rtcweb-jsep

Commentary: I left out the unqualified / , since these are redundant , and only exist in the WebRTC spec as a convenience and for backwards compatibility . 
 I need to read this carefully at some point but just quickly scanning the diff .. it looks workable . Thanks . 
 LGTM . I did n't look to see if there were other references to the local / remote desc that need to be updated , but I assume that you already scanned carefully . 
 I think everything should be covered now . I 've gone through twice looking at every place the word " description " is used . Though when talking about rollback , I think " return to the previous description " sounds less confusing than " return to the current description " , so I left that wording alone . 
 LGTM 
 JSEP S 4.1.7 and 4.1.8 read : " TODO : Do we need to expose accessors for both the current and proposed local description ? " and " TODO : Do we need to expose accessors for both the current and proposed remote description ? " 
 DC plan - we add these to W3c spec . 
 Discussed in DC : Values will be created for surfacing both proposed and current descriptions . Ultimately , this is a matter for the WebRTC group , where the names can be selected and decisions like what to do with existing values can be made . 
 This is bug 
 Can we close this ? 
 I would prefer to keep it until the text is written 
 For the purposes of this comment , let 's call the needed APIs .currentLocalDesc and .pendingLocalDesc . On the offerer side , setLocal(desc ) updates .pendingLocalDesc to be ( desc ) . On the offerer side , setLocal(rollback ) updates .pendingLocalDesc to be NULL . On the answerer side , setRemote(desc ) updates .pendingRemoteDesc to be ( desc ) . On the answerer side , setRemote(rollback ) updates .pendingRemoteDesc to NULL . On the answerer side , setLocal(desc ) updates .currentLocalDesc to be ( desc ) , .currentRemoteDesc to .pendingRemoteDesc , and .pendingRemoteDesc to NULL . On the offerer side , setRemote(desc ) updates .currentRemoteDesc to be ( desc ) , .currentLocalDesc to be .pendingLocalDesc , and .pendingLocalDesc to be NULL . Unfortunately , both .pending and .current have slightly different semantics than the existing .local/.remoteDescription properties , so I think we would need to retain .local / remote for now . However , they could be polyfilled as propX = ( pendingX ) ? pendingX : currentX. 
 This looks good and need to be clear that some while the pending is out , you need to receive on both current and pending . 
 Not done yet but started putting this into PC spec on branch - have a look and see if it is going the right direction 
 ( Moved my comment to PR ) 
 Hi , why not a simpler 2 - arg rather than 3 - arg solution ? For the purposes of this comment , let 's call the needed APIs .localDescription and .stableLocalDescription . On the offerer side , setLocal(desc ) updates .localDescription to be ( desc ) . On the offerer side , setLocal(rollback ) updates .localDescription to be .stableLocalDescription . On the answerer side , setRemote(desc ) updates .remoteDescription to be ( desc ) . On the answerer side , setRemote(rollback ) updates .remoteDescription to be .stableRemoteDescription . On the answerer side , setLocal(desc ) updates .localDescription and .stableLocalDescription to be ( desc ) , and .stableRemoteDescription to be .remoteDescription . On the offerer side , setRemote(desc ) updates .remoteDescription and .stableRemoteDescription to be ( desc ) , and .stableLocalDescription to be .localDescription . 
 I see what you are trying to do , and I think this would work OK , but the fact that the semantics of .localDescription/.remoteDescription mutate depending on the current state make this confusing . ( IOW , sometimes localDescription is the stable desc , sometimes it is the pending desc ) . I think .current/.pending is the clearest approach , but open to other opinions . 
 I would argue the semantics do n't mutate and their availability transcend state : is the last - set description always is the last negotiated description always 
 From the point of view of a programmer using the API , I think that what I want to get is the SDP to do with the current negotiation , and the old SDP that I would roll back to . I tend to think of it as old and new . During transition time , the stuff in use is the combination of the old offer / answer pair plus the new offer . The stuff .current/.pending is close enough to this and seems fine to me . 
 Do you realize you just used " current " to refer to " pending " , and " old " to refer to " current " ? You want to roll back to the last stable state . 
 Uh , I used current to refer to old and pending to refer to new . 
 My point is that these relative words " current " and " pending " are not well - defined , whereas " stable " is .  . 
 I 'm not sure stable is a word that makes as much sense as you might hope to developers . It is not used int he SDP or Offer / Answer spec . Anyways , I do n't feel strongly about this . None of the names are perfect . 
 Forgetting about the accessors for a second , the world can be in three basic states . There is an initial offer which has not been answered There is an offer which has been answered and no outstanding offers There is an offer which has been answered and an outstanding offer In the first two cases , there is only one localdesc , which is either answered or not . In the second case , there are two localdescs , one confirmed and one answered or not . As Justin observes , currently localdesc is the most recent description set , regardless of whether it 's answered . I find his argument persuasive here . I would prefer that we have two variables : Most recent answered description Most recent non - answered description And in some cases either or both of these can be null . We can obviously keep localdescription around for a while for compat . I do n't feel strongly about the names here , so I wo n't suggest some just yet . Let 's agree on the principle one way or the other . 
 The world can be in four basic states , the fourth being the initial state of no offer at all , which is the only state where " Most recent answered description " would be I hope ? This would fit my understanding of " most recent " : while it may be initially ( meaning " never been set " ) , it will never go to after that ( which would surprise me ) . I think we 're on the same page here . Can " Most recent non - answered description " ever go from non- to ? If it can , then lets avoid the false symmetry with the first one : Most recent answered description , or if never set . Most recent non - answered description if there is one since the last answered description , or . The first one is a.k.a . . The second one is a temporal variable : it 'll only ever be non- during re - negotiation , correct ? Moreover , during re - negotiation , it 's indistinguishable from , do I have that right ? So , counting which we have today , why add a redundant third temporal variable that all it brings to the table is that it is outside of renegotiation ? 
 , jan - ivar wrote : Yes , then everything is null . No . So , counting localDescription which we have today , we 're adding a redundant 
 What 's the value of " most recent non - answered description " after rollback ? ( matters for the question of whether it can go from non - null to null ) 
 Right , hanging on to a failed description does n't make much sense , so I see how we got to . So lets not cut it that way . I think a JS writer cares about : last set value , and reigning value . Where rollback rolls back failed set values to the known - good reigning value . Having itself be the last - set - value matches most attribute patterns I 've seen . ( e.g. ) . 
 The problem with this categorization is that in the case of re - offer , there is n't " the reigning value " . Rather , the offerer has two values which are simultaneously valid , so I think Justin 's approach is superior . In any case , rather than debate this here , let 's discuss it at the interim . 
 So , given what is being discussed here is about PC spec , I 'd sort of like to close this and move the conversation over to PC and not jsep . 
 I agree this overlaps with PC , but given the relevance of this to the overall JSEP O - A model , I think we need to have some description of this in Section 4.1 . * 
 Personal opinion ( not claiming to represent any consensus ): JSEP needs to describe the procedures followed to get the SDP we want .  should n't need to talk about accessors at all ; we can leave that to WEBRTC . What 's specified in only one place has a greater chance of being consistent . 
 I find that logic persuasive , in that the accessors are not relevant to the state machine or any other fundamental part of JSEP . That would imply that 4.1.7 and 4.1.8 ought to be removed from this document , and probably also 4.1.9 ( canTrickleIceCandidates , another accessor - like API ) .  ? 
 I can live with that , but I thought that we had agreed previously that JSEP would document this stuff and place requirements on the WebRTC API . ,   wrote : 
 It 's perfectly reasonable to have a sentence saying " the API will give access to current and pending SDP and whether or not trickleIce is supported " . It 's when we get the discussion about what the accessor names should be in 2 different places that I feel like we 're not using our time optimally . 
 Well , I suggest we have one discussion and then put it in both places . ,   
 Consensus in W3C was to have two new accessors . This is editor ready . 
 Resolved by
Paragraph (version A):
When a new gathering phase starts, the ICE Agent will notify the
application that gathering is occurring through an event.  Then, when
each new ICE candidate becomes available, the ICE Agent will supply
it to the application via an additional event; these candidates will
also automatically be added to the local session description.
Finally, when all candidates have been gathered, an event will be
dispatched to signal that the gathering process is complete.
Paragraph (version B):
When a new gathering phase starts, the ICE Agent will notify the
application that gathering is occurring through an event.  Then, when
each new ICE candidate becomes available, the ICE Agent will supply
it to the application via an additional event; these candidates will
also automatically be added to the current and/or pending local
session description.  Finally, when all candidates have been
gathered, an event will be dispatched to signal that the gathering
process is complete.
Paragraph (version A):
In a "last-one-wins" situation, all answers would be applied as
provisional answers, and any previous call leg will be terminated.
At some point, the application will end the setup process, perhaps
with a timer; at this point, the application could reapply the
existing remote description as a final answer.
Paragraph (version B):
In a "last-one-wins" situation, all answers would be applied as
provisional answers, and any previous call leg will be terminated.
At some point, the application will end the setup process, perhaps
with a timer; at this point, the application could reapply the
pending remote description as a final answer.
Paragraph (version A):
A rollback discards any proposed changes to the session, returning
the state machine to the stable state, and setting the modified local
and/or remote description back to their previous values.  Any
resources or candidates that were allocated by the abandoned local
description are discarded; any media that is received will be
processed according to the previous local and remote descriptions.
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.  Note that this implies that once the answerer has performed
setLocalDescription with his answer, this cannot be rolled back.
Paragraph (version B):
A rollback discards any proposed changes to the session, returning
the state machine to the stable state, and setting the pending local
and/or remote description back to null.  Any resources or candidates
that were allocated by the abandoned local description are discarded;
any media that is received will be processed according to the
previous local and remote descriptions.  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.  Note that this implies that
once the answerer has performed setLocalDescription with his answer,
this cannot be rolled back.
Paragraph (version A):
This API changes the local media state; among other things, it sets
up local resources for receiving and decoding media.  In order to
successfully handle scenarios where the application wants to offer to
change from one media format to a different, incompatible format, the
PeerConnection must be able to simultaneously support use of both the
old and new local descriptions (e.g. support codecs that exist in
both descriptions) until a final answer is received, at which point
the PeerConnection can fully adopt the new local description, or roll
back to the old description if the remote side denied the change.
Paragraph (version B):
This API changes the local media state; among other things, it sets
up local resources for receiving and decoding media.  In order to
successfully handle scenarios where the application wants to offer to
change from one media format to a different, incompatible format, the
PeerConnection must be able to simultaneously support use of both the
current and pending local descriptions (e.g. support codecs that
exist in both descriptions) until a final answer is received, at
which point the PeerConnection can fully adopt the pending local
description, or roll back to the current description if the remote
side denied the change.
Paragraph (version A):
If setRemoteDescription was previous called with an offer, and
setLocalDescription is called with an answer (provisional or final),
and the media directions are compatible, and media are available to
send, this will result in the starting of media transmission.
Paragraph (version B):
If setRemoteDescription was previously called with an offer, and
setLocalDescription is called with an answer (provisional or final),
and the media directions are compatible, and media are available to
send, this will result in the starting of media transmission.
Paragraph (version A):
The localDescription method returns a copy of the current local
configuration, i.e. what was most recently passed to
setLocalDescription, plus any local candidates that have been
generated by the ICE Agent.
Paragraph (version A):
A null object will be returned if the local description has not yet
been established.
Paragraph (version A):
The remoteDescription method returns a copy of the current remote
configuration, i.e. what was most recently passed to
setRemoteDescription, plus any remote candidates that have been
supplied via processIceMessage.
Paragraph (version A):
A null object will be returned if the remote description has not yet
been established.
Paragraph (version B):
The currentLocalDescription method returns a copy of the current
negotiated local description - i.e., the local description from the
last successful offer/answer exchange - in addition to any local
candidates that have been generated by the ICE Agent since the local
description was set.
Paragraph (version B):
The pendingLocalDescription method returns a copy of the local
description currently in negotiation - i.e., a local offer set
without any corresponding remote answer - in addition to any local
candidates that have been generated by the ICE Agent since the local
description was set.
Paragraph (version B):
A null object will be returned if the state of the PeerConnection is
"stable" or "have-remote-offer".
Paragraph (version B):
The currentRemoteDescription method returns a copy of the current
negotiated remote description - i.e., the remote description from the
last successful offer/answer exchange - in addition to any remote
candidates that have been supplied via processIceMessage since the
remote description was set.
Paragraph (version B):
The pendingRemoteDescription method returns a copy of the remote
description currently in negotiation - i.e., a remote offer set
without any corresponding local answer - in addition to any remote
candidates that have been supplied via processIceMessage since the
remote description was set.
Paragraph (version B):
A null object will be returned if the state of the PeerConnection is
"stable" or "have-local-offer".
Paragraph (version A):
The addIceCandidate method provides a remote candidate to the ICE
Agent, which, if parsed successfully, will be added to the remote
description according to the rules defined for Trickle ICE.
Connectivity checks will be sent to the new candidate.
Paragraph (version B):
The addIceCandidate method provides a remote candidate to the ICE
Agent, which, if parsed successfully, will be added to the current
and/or pending remote description according to the rules defined for
Trickle ICE.  Connectivity checks will be sent to the new candidate.