[EME] MediaKeyError codes proposal (bug 21798)

This e <https://www.w3.org/Bugs/Public/show_bug.cgi?id=21798>mail provides
a framework and suggestions for resolving Bug
21798<https://www.w3.org/Bugs/Public/show_bug.cgi?id=21798>- Revisit
MediaKeyError codes.

I think we should have the following goals:

   -

   Codes should be for things that would allow the application do one of
   the following:
   -

      Adapt/respond to enable playback to continue
      -

      Give the user a useful/actionable message.
      -

   Codes should be commonly useful across implementations.
   -

   Codes should generally be for things that are only known to the user
   agent/CDM. (In contrast, there are other ways to report errors known to the
   server.)
   -

   Codes should be described in sufficient detail that they can interpreted
   unambiguously by different implementers and it is clear how an application
   should respond.
   -

   Start with codes we know will be useful. We can always add them later
   based on implementation experience.


With that in mind, I’ve identified the following categories of errors I
think we must include. Some may make sense to split into separate codes,
and I’ve mentioned potential individual cases where applicable. I’ve also
included the expected application behavior for each, which I think is an
important consideration for any error code.


   1.

   Unknown/Other - “An unspecified error occurred. This value is used for
   errors that don't match any of the following codes.”
   1.

      Expected application behavior: General failure message. It is not
      possible to recover since there is no specified cause.
      2.

   Output [protection]
   1.

      The current description is “There is no available output device with
      the required characteristics for the content protection system.”
That seems
      like a subset or inaccurate description of cases that should be covered.
      2.

      Is it useful to differentiate the case where the error resulted from
      a display change (new display, player window moved, etc.)? (An
application
      might be able to infer this based on the amount of time it has
been playing
      without such a separation.)
      3.

      Expected application behavior: Inform the user of the problem and/or
      try a different license, possibly using alternate streams. (The response
      may be different depending on whether the error resulted from a change.)
      3.

   Expired
   1.

      The key/license is no longer valid.
      2.

      This could be broken up into multiple scenarios:
      1.

         Renewal failed
         2.

         The time window has passed
         3.

         Number of plays exceeded
         4.

         Instructed to stop by license server
         3.

      Expected application behavior: Inform the user there was a problem
      (renewing, rental expired, etc.).
      4.

      If we use a single error code, the application will need to derive
      the messaging based on knowledge of the application, licensing, etc.
      4.

   Key System/CDM cannot be used
   1.

      There are potentially several classes of causes that could potentiall
      be separate codes:
      1.

         Key System (CDM) is disabled (by the user)
         1.

            I can imagine this being useful as it allows applications to
            provide the user with specific instructions, but it also enables
            fingerprinting and exposes something about a user that is probably
            concerned about privacy.
            2.

         Identifiers are disabled (by the user)
         1.

            Similar issues to above.
            3.

         CDM could not be found, failed to load (i.e. due to dependencies),
         has not been initialized/enabled.
         1.

            Similar to or could be merged with to “Key System (CDM) is
            disabled”, though the desired messaging for each scenario
would be very
            different.
            2.

      Expected application behavior: Inform the user that there is a
      problem and possibly general text about how to address it.
      1.

         For the latter, it may be useful to at least differentiate user
         controllable/resolvable issues vs. more complex issues (i.e.
CDM failed to
         load).
         3.

      If we want to use a single code, we might just use “client” (where
      client refers to the CDM). Maybe there is an even better name.


I think the following would also be useful:

   1.

   Platform capabilities not available
   1.

      Similar to Output [Protection], but this device can never meet the
      license requirements.
      2.

      Expected application behavior: Try a different license, possibly
      using alternate streams.
      2.

   Initialization failure (needs a better name)
   1.

      Some implementations have various individualization, etc. steps.
      2.

      Expected application behavior: Inform the user, possibly telling them
      to try again or contact the device manufacturer.


Another possibility - this really depends on how we want to handle such
delays.

   1.

   Deferred/Delayed (more of a status than an error)
   1.

      This mostly relates to initial use [on an origin], which may take
      longer in some implementations.
      2.

      The code is an indication that the operation is not possible now but
      should be soon. As a status, it just means the operation (likely
      createSession()) is pending. Alternatively, the error could be fatal and
      the application should try again (calling createSession() again).
      3.

      Expected application behavior: This is mostly a hint that the
      application should not time out in cases where message or ready
events may
      not be fired soon.


The following codes are currently in the spec but not included above. If
someone would like to make an argument for one of these, please consider
the goals above and the “expected application behavior”.

   -

   Client - “The Key System could not be installed or updated.”
   -

      Since CDMs should not be installed, the first part of the error
      definition is obsolete. It’s unclear what would cause a “not
updated” error.
      -

      We could reuse “client” for the “Key System/CDM cannot be used” class
      above.
      -

   Service - “The message passed into update indicated an error from the
   license service.”
   -

      What would be reported here that a) couldn’t be reported directly to
      the app and b) isn’t in the list above?
      -

   Hardware Change - “A hardware configuration change caused a content
   protection error.”
   -

      What would cause this to be fired? Are there cases other than the
      Output error? Would this be detected on the client or server? Is this
      common enough to warrant its own code?
      -

   Domain - “An error occurred in a multi-device domain licensing
   configuration. The most common error is a failure to join the domain.”
   - It seems to be TBD how “domain keys” would be supported. If this is
      handled at the application level, do we need a specific domain
error? Or is
      this something different?