Proposal for error handling (programming vs runtime errors)

Following up on a previously assigned action. Some of this is already in
the spec, but there were enough gray areas that I think we need to add more
detail. Please comment, either via mail or in the document at
https://docs.google.com/document/d/1_npj3RJmPcPwo4jLD44VcTW-juRBAKJdjJceGOw6sRg/edit#
.

----
*WebRTC Error Handling
WebRTC provides two mechanisms for errors to be returned to the application
- exceptions, which are returned synchronously, and completion callbacks,
which are returned asynchronously.

The operations that are async in the WebRTC API use this technique because
they may take nontrivial time to complete, and/or require inter-thread or
inter-process and communication. The callback informs the application that
the operation is complete (and can now do something else), and what the
result of the operation was.

To understand when an error should be returned via an exception, or via an
async callback, the guideline is simple: programming errors (e.g. API
called at wrong time or with parameters of the wrong type) should always
result in an exception. Runtime errors, such as an error in the syntax of a
parameter, or failure to apply a desired operation, should always result in
a callback.

Programming errors are explicitly defined as the following conditions:

   - The state of the object does not match the preconditions for the API
   call (e.g. setLocalDescription on a closed PeerConnection)
   - The type of a parameter does not match the defined type (e.g.
   setLocalDescription("foo"), setLocalDescription(null),
   setLocalDescription({foo:42}).


All other errors are considered runtime errors, including:

   - Malformed parameters, or parameters that are incorrect for the given
   object state (e.g. setLocalDescription({type:"answer", sdp:<sdp>} on a
   PeerConnection in the "stable" state; setLocalDescription({type:"answer",
   sdp:"barf"})
   - Failure to parse SDP
   - Failure when applying SDP


Programming errors result in an exception being thrown with either:

   - INVALID_STATE_ERR as the name (a generic DOM exception), or
   - INVALID_PARAMETER_ERR (TBD where this is defined).


Programming errors prevent any state change and are always recoverable.

Runtime errors result in a error callback with an RTCError object. The
RTCError object may use the following names:

   - INVALID_STATE(?) (Incorrect type of SDP for current state, recoverable)
   - INVALID_SESSION_DESCRIPTION (SDP failed to parse, or not suitable,
   recoverable)
   - INCOMPATIBLE_CONSTRAINTS (Unsatisfiable constraints to async function,
   recoverable)
   - INCOMPATIBLE_MEDIASTREAMTRACK (MediaStreamTrack is not part of
   PeerConnection, recoverable)
   - INTERNAL_ERROR (Failure occurred when setting local or remote
   description, media subsystem is in bad state, not recoverable)


Runtime errors may occur after state has already changed, and may not be
recoverable.

References:
WebRTC spec, section 4.6, Error
Handling<http://dev.w3.org/2011/webrtc/editor/webrtc.html#general-principles>
*