*** Bug 20688 has been marked as a duplicate of this bug. ***

*** Bug 20689 has been marked as a duplicate of this bug. ***

Bug 21855 to avoid network traffic and duplicate sessions for the same key(s) is likely to be closely related to this issue. (Note: Bug 16553 and bug 19208 mentioned in the original description of this bug were actually closed as duplicates of 21855 instead.)

Bug 20688 #c4 and #c5 have some useful information about possible states/events from the April 23 f2f.

Updated diagram:

http://www.websequencediagrams.com/cgi-bin/cdraw?lz=dGl0bGUgQ0RNIFN0YXRlIFByb2dyZXNzaW9uCgpub3RlIG92ZXIgQ0RNOiBVbmluaXRpYWxpemVkAA8OLCBBcHA6IHRpbWUgcGFzc2VzAC0QSQAwC0NETS0-ACwFa2V5bWVzc2FnZQBdEFdhaXRpbmcKQXBwLT4AegV1cGRhdGUoKQpvcHQAA0BlbgCBMg86IHJlYWR5AIFBFXBsYXliYWNrACRVAFQQAIFmCmNsb3NlKCkAghkVIChrZXkgcmVsZWFzZSkAgxkQQ2xvcwCCJRcAFxNlZAo&s=napkin

Thanks, Mark. The diagram makes sense. I would put the last keymessage-closing-update() series in an opt box. close() might be implicit, but I'm not sure we need to be explicit about that here.

Assuming we roughly agree on what the states are, we need to decide:
 * If/how to expose (a subset of?) the states.
 * If/how to document this. (i.e. Is it just informative to help in understanding? If so, does it go in a primer, etc.?)

Expanding on a couple things mentioned in the telecon today:
 * The important question to ask is whether the application needs to know the states or does it have enough information from events to behave correctly without explicit states. (Are there additional events necessary to achieve this?)
 * The diagram should probably be a state machine. (When specifying implementations, this probably makes the sense. However, the sequence diagram is probably useful as an introduction/primer for someone to understand how a typical flow might look.)

Having thought about this a bit more now, I am not sure this is needed. I may track the state like this internally in the CDM, but the useful state information (e.g. waiting for a key) can be deduced from the sequence of events as David mentioned. My second thought is that this could be useful to the UA (as opposed to the app) but I think the UA can do the same deduction that the app can since it will see all the events. 

This would be a good bit of information to put in a primer though.

Created attachment 1374 [details]
State transition diagram

Our proposal is to have session state as shown in the attached state transition diagram.

A session will start in the CREATED state. A keyerror event might fire taking the session to the ERROR state. Alternatively a keyready event might fire taking the session to the READY state. READY means that the session does not expect to block playback if encrypted content is encountered.

During key acquisition, the session moves to the PENDING state when a keymessage event fires. PENDING means that if encrypted content is encountered that needs the key or keys being acquired in this session then playback will stall. Zero or more keymessage events might fire while in the PENDING state. keyready will move the session to the READY state. keyerror to the ERROR state.

At any time, for CDM specific reasons, it may be necessary to return from the READY state to the PENDING state. This might occur for some form of key rotation, for example.

We propose to add a state attribute to the session and a new keyready event.

It is an open question whether we should keep the keyadded event. It's not clear what action someone might take from keyadded but it also doesn't seem cause harm to include it.

LGTM

We could add a CLOSED state for when the keys have been destroyed but there may still be state (key release messages, if supported).

...Mark

Are you proposing a specific "key ready" event or a general "key status" event that indicates a state change? The latter would be more useful IMO and would cover the "closed" case Mark mentioned as well. If you have a general key status event, you can drop the need for an attribute to reflect the status as well.

Actually I suppose that having "key ready", "key pending" and "key closed" all as separate events would be the way to go. That way if we have multiple sessions on a media element and one session has already requested the key that another session will use as well, the "key pending" event will be sent instead of a "need key" event.

(In reply to comment #12)
> Actually I suppose that having "key ready", "key pending" and "key closed"
> all as separate events would be the way to go. That way if we have multiple
> sessions on a media element and one session has already requested the key
> that another session will use as well, the "key pending" event will be sent
> instead of a "need key" event.

Since needkey fires independently from the key system, we're not proposing to use pending instead of needkey. See bug 21855.

So if the app wants to display a progress indicator, they will listen for needkey (which always happens) and then listen for keyready (which always happens)?

If this is correct I don't understand the use case for the status attribute. It seems like the application knows exactly what the state is based on the messages it has seen.

(In reply to comment #14)
> So if the app wants to display a progress indicator, they will listen for
> needkey (which always happens) and then listen for keyready (which always
> happens)?

needkey fires on the media element. Then a session is created and then keyready will eventually fire on the session (usually after keymessage/update exchanges).

> If this is correct I don't understand the use case for the status attribute.
> It seems like the application knows exactly what the state is based on the
> messages it has seen.

Yes, you can determine the state by knowing what messages you've seen. We don't have to expose the state but it is a low cost attribute assuming that generally implementations will want to implement as a state machine of some kind and this is a common pattern for APIs that have some kind of progress/state.

My thoughts:

There should be a transition from the READY state to the ERROR state.

I think keyadded should be eliminated (replaced by keyready) unless there is a good use case for knowing that a (new?) key was added.

Since every transition already has an event, it's unclear what purpose a state attribute would serve. Since it could just restrict or complicate implementations, I do not believe we should expose it unless there are good use cases. Are there other examples of _redundant_ events and state attributes (vs. a single statechange/progress event with a corresponding state attribute)?

I don't know that it matters, but note that not all events in the state diagram are equal. Specifically, keyerror and keyready are simple events, but keymessage is a custom event type.

There is no change from the current events [1]; we've just made them all represent state transitions.

https://dvcs.w3.org/hg/html-media/raw-file/default/encrypted-media/encrypted-media.html#event-summary

(In reply to comment #16)
> Are there other examples of _redundant_ events and state
> attributes (vs. a single statechange/progress event with a corresponding
> state attribute)?

A few that come to mind:

FileReader readyState
http://www.w3.org/TR/FileAPI/#dfn-filereader

HTMLImageElement complete
http://www.w3.org/TR/html5/embedded-content-0.html#the-img-element

Document readyState
http://www.w3.org/TR/html5/dom.html#dom-document-readystate

I added text describing the internal state of the media key session:
https://dvcs.w3.org/hg/html-media/rev/83629aec22e1

Issues still unresolved:
1) I did not remove keyadded. We should decide whether this is now removed. I don't believe it has any purpose.

2) I did not add the state variable as an attribute. If we add this, we need to decide is it a string or integer.

3) I did not add the transition from READY to ERROR. I'm not sure where in the text this transition should be described.

(In reply to Adrian Bateman [MSFT] from comment #19)
> Issues still unresolved:
> 1) I did not remove keyadded. We should decide whether this is now removed.
> I don't believe it has any purpose.

I propose that we remove keyadded. It is not needed.

> 2) I did not add the state variable as an attribute. If we add this, we need
> to decide is it a string or integer.

I seem to be the only one arguing for this. It seems like there consensus is "don't care" and I'm happy to leave it out for now.

> 3) I did not add the transition from READY to ERROR. I'm not sure where in
> the text this transition should be described.

I don't think there needs to be a transition from READY to ERROR. I think errors should only occur on the MediaKeySession that are related to in-flight key exchanges either after creating the session or while it is PENDING. If an error occurs in the READY state then this should be thrown against the media element since it presumably is going to cause playback to halt.

Discussed on telcon 2013-10-01:

Agreed to issues 1 and 2. Moving issue 3 to be part of bug 21798.

Removed keyadded event. This bug is now resolved.
https://dvcs.w3.org/hg/html-media/rev/4b466f3beae3

(In reply to Adrian Bateman [MSFT] from comment #19)
> I added text describing the internal state of the media key session:
> https://dvcs.w3.org/hg/html-media/rev/83629aec22e1

This change added the following text to the update() algorithm:
> If the session is not in the PENDING state, throw an INVALID_STATE_ERR.

I don't think this should be the case. There are probably legitimate reasons for the application to provide a new message without the session requesting it (and thus being in the PENDING state) - in other words, in the READY state.

There may even be use cases for calling update() in the CREATED, ERROR, or CLOSED states.


This change also included the following text describing the new keyready event:
> The media element should not be blocked if encrypted data is encountered associated with the initData used to create the session.

I don’t think we can say this. Output protection or other issues could cause the key(s) in the session to be unusable and thus for the media element to be blocked.

(In reply to David Dorwin from comment #23)
> This change added the following text to the update() algorithm:
> > If the session is not in the PENDING state, throw an INVALID_STATE_ERR.
> 
> I don't think this should be the case. There are probably legitimate reasons
> for the application to provide a new message without the session requesting
> it (and thus being in the PENDING state) - in other words, in the READY
> state.
> 
> There may even be use cases for calling update() in the CREATED, ERROR, or
> CLOSED states.

update() is intended to provide a message in response to the keymessage payload. I'm not sure we should change the spec unless we know of specific use cases where we don't want to limit it to this. We could wait to see if implementation experience suggests this is actually needed? I think we need to specify what to do if you call update() and it is not expected. Should it be silently ignored or should you get a state error.

> This change also included the following text describing the new keyready
> event:
> > The media element should not be blocked if encrypted data is encountered associated with the initData used to create the session.
> 
> I don’t think we can say this. Output protection or other issues could cause
> the key(s) in the session to be unusable and thus for the media element to
> be blocked.

This is a should rather than a must. The intent is that you move to READY when you don't expect to be blocked waiting for key material. Are you proposing to remove or revise this text? Perhaps we can change it into informative text?

(In reply to Adrian Bateman [MSFT] from comment #24)
> (In reply to David Dorwin from comment #23)
> > This change added the following text to the update() algorithm:
> > > If the session is not in the PENDING state, throw an INVALID_STATE_ERR.
> > 
> > I don't think this should be the case. There are probably legitimate reasons
> > for the application to provide a new message without the session requesting
> > it (and thus being in the PENDING state) - in other words, in the READY
> > state.
> > 
> > There may even be use cases for calling update() in the CREATED, ERROR, or
> > CLOSED states.
> 
> update() is intended to provide a message in response to the keymessage
> payload.
That's the basic model, but I never assumed it was the only model.

> I'm not sure we should change the spec unless we know of specific
> use cases where we don't want to limit it to this. We could wait to see if
> implementation experience suggests this is actually needed? I think we need
> to specify what to do if you call update() and it is not expected. Should it
> be silently ignored or should you get a state error.

Why do UAs/CDMs need to be "expecting" an update() call? I assumed they would just always process the input and decide what to do?

As for use cases, an app could proactively provide a renewal message, a new key, etc. I imagine there might be some more complex uses cases where operations need to be performed on the session as well.

> > This change also included the following text describing the new keyready
> > event:
> > > The media element should not be blocked if encrypted data is encountered associated with the initData used to create the session.
> > 
> > I don’t think we can say this. Output protection or other issues could cause
> > the key(s) in the session to be unusable and thus for the media element to
> > be blocked.
> 
> This is a should rather than a must. The intent is that you move to READY
> when you don't expect to be blocked waiting for key material. Are you
> proposing to remove or revise this text? Perhaps we can change it into
> informative text?

I agree that this is the expected behavior in the happy case and it may be useful in understanding the general flow. The problem I see is that the text implies that playback will not be blocked, but there are expected scenarios when the key/license will be unusable when such media data is encountered (output protection, expired license, etc.)

I think we can probably reword the text to provide the helpful information without implying the media element can't be blocked. Maybe we should just say the license/key is ready for use. "Use" may include checking validity.

(In reply to David Dorwin from comment #25)
> (In reply to Adrian Bateman [MSFT] from comment #24)
> > I'm not sure we should change the spec unless we know of specific
> > use cases where we don't want to limit it to this. We could wait to see if
> > implementation experience suggests this is actually needed? I think we need
> > to specify what to do if you call update() and it is not expected. Should it
> > be silently ignored or should you get a state error.
> 
> Why do UAs/CDMs need to be "expecting" an update() call? I assumed they
> would just always process the input and decide what to do?
> 
> As for use cases, an app could proactively provide a renewal message, a new
> key, etc. I imagine there might be some more complex uses cases where
> operations need to be performed on the session as well.

I have filed Bug 24081 to track this issue.

(In reply to David Dorwin from comment #25)
> I agree that this is the expected behavior in the happy case and it may be
> useful in understanding the general flow. The problem I see is that the text
> implies that playback will not be blocked, but there are expected scenarios
> when the key/license will be unusable when such media data is encountered
> (output protection, expired license, etc.)
> 
> I think we can probably reword the text to provide the helpful information
> without implying the media element can't be blocked. Maybe we should just
> say the license/key is ready for use. "Use" may include checking validity.

I have updated the spec with new language to address this case.
https://dvcs.w3.org/hg/html-media/rev/d9c9406a821f