DRM: Second attempt to manage a maxSessionCacheSize on contents going over the limit

This is a retry of #1511 (I even re-used the same git branch) because
I found the work in that PR to be too complex.

If you already read the previous PR, you can skip the `The issue` below.

The issue
=========

Conditions
----------

This work is about a specific and for now never seen issue that has chance to pop up under the following conditions:

  - The current content make use of per-Period key rotation (NOTE: this is also possible without key rotation, but this is made much more probable by it).

  - The device on which we we play that content has a very limited number of key slots available simultaneously for decryption  (sometimes **VERY** limited, e.g. `6`, so we can at most rely on 6 keys simultaneously.

    We for now know of four different set-top boxes with that type of limitation, from two constructors.

The `maxSessionCacheSize` option
---------------------------------------------

Theoretically, an application can rely there on the `keySystems[].maxSessionCacheSize` option to set a maximum number of `MediaKeySession` we may keep at at the same time.

_Note that we prefer here to rely on a number of `MediaKeySession` and not of keys, because the RxPlayer is not able to predict how many keys it will find inside a license (NOTE: to simplify, let's just say that 1 `MediaKeySession` == 1 license here, as it's very predominantly the case) nor is it able to not communicate some keys that are found in a given license._
_Yet an application generally has a rough idea of how many keys it's going to find in a license a most, and can set up its `maxSessionCacheSize` accordingly (e.g. if there's max `10` key slots available on the device and `5` keys per license maximum, it could just communicate to us a `maxSessionCacheSize` of `2`)._

So problem solved right? WRONG!

The RxPlayer, when exploiting the `maxSessionCacheSize` property, will when that limit is reached just close the `MediaKeySession` it has least recently seen the need for (basically, when the RxPlayer loads segment for a new Period/track/Representation, it asks our decryption logic to make sure it has the right key, this is how our decryption logic know that a `MediaKeySession` or more precizely a key it can make use of, has been needed recently).

Example scenario
----------------

So let's just imagine a simple scenario:

  1. we're currently loading a Period `A` with encrypted content and buffering a future Period `B` with content encrypted with a different key.

  2. we're asking the decryption logic to make sure the key is loaded for future Period `B`

  3. The decryption logic sees that it doesn't have the key yet, and thus has to create a new `MediaKeySession`.

     Yet, it sees that it cannot create a new `MediaKeySession` for that new key without closing an old one to respect the `keySystems[].maxSessionCacheSize` option, and it turns out one relied on to play Period A was the least recently needed for some reason.

  4. The decryption logic closes a `MediaKeySession` for Period `A` that was currently relied on.

  5. ??? I don't know what happens, the `MediaKeySession` closure may fail in which case we could be left with too many key slots used on the device and some random error, or content playback may just fail directly.

     In any case, I wouldn't bet on something good happening.

Other types of scenarios are possible, e.g. we could be closing a `MediaKeySession` needed in the future and not think to re-create it when playing that future Period, potentially leading to a future infinite rebuffering.

Solution I'm proposing here
===========================

In a previous PR, I tried to handle all cases but that became too
complex and I know think that doing it in multiple steps may be easier
to architects: we handle first the "simple" cases (which sadly are not
the most frequent ones), we'll then see the harder cases.

The simpler case it to just close `MediaKeySession` that are known to
not be needed anymore if we go over the `maxSessionCacheSize` limit on
the current content.

To have a vague non-perfect idea of what is currently needed, we look
at all `Period`s from the current position onward, list their key ids,
compare with the keys currently handled by our DRM logic, and just
close the ones that haven't been found.

How I'm implementing this
=========================

Detecting the issue
-------------------

As we now have a difference in our `MediaKeySession`-closing algorithm depending on if the `MediaKeySession` is linked to the current content or not, I chose in our `ContentDecryptor` module that:

  1. `MediaKeySession` that are not linked to the current content keep being closed like they were before: least recently needed first.

  2. `MediaKeySession` that are linked to the current content are never directly closed by the `ContentDecryptor`.

     Instead, the `ContentDecryptor` module basically signals a `tooMuchSessions` event when only left with `MediaKeySession` for the current content yet going over the `maxSessionCacheSize` limit.

     It also doesn't create the `MediaKeySession` in that case.

Fixing the situation
--------------------

The `ContentDecryptor` now exposes a new method, `freeKeyIds`. The idea is that you communicate to it the key id you don't need anymore, then the `ContentDecryptor` will see if can consequently close some `MediaKeySession`.

It is the role of the `ContentInitializer` to call this `freeKeyIds` method on key ids it doesn't seem to have the use of anymore (all key ids are in the payload of the `tooMuchSessions` event).

Note: the new `ActiveSessionsStore`
-----------------------------------

To allow the `ContentDecryptor` to easily know when it can restart creating
`MediaKeySession` after encountering this `tooMuchSessions` situation
and then having its `freeKeyIds` method called, I replaced its simple `_currentSessions` private array into a new kind of "MediaKeySession store" (a third one after the `LoadedSessionsStore` and the `PersistentSessionsStore`), called the `ActiveSessionsStore`, which also keeps a `isFull` boolean around.

This new store's difference with the `LoadedSessionsStore` may be unclear
at first but there's one:

  - The `LoadedSessionsStore` stores information on all `MediaKeySession`
    currently attached to a `MediaKeys` (and also creates / close them).

  - The `ActiveSessionsStore` is technically just an array of
    `MediaKeySession` information and a `isFull` flag, and its intended
    semantic is to represent all `MediaKeySession` that are "actively-used"
    by the `ContentDecryptor` (in implementation, it basically means all
    `MediaKeySession` linked to the current content).

If you followed, note that the session information stored by the `LoadedSessionsStore` is a superset of the ones stored by the
`ActiveSessionsStore` (the former contains all information from the
latter) as "active" sessions are all currently "loaded".

Writing that, I'm still unsure if the `isFull` flag would have more its place on
the `LoadedSessionsStore` instead. After all `maxSessionCacheSize` technically
applies to all "loaded" sessions, not just the "active" ones which is a
concept only relied on by RxPlayer internals.

We may discuss on what makes the most sense here.

Remaining issues
================

This PR only fixes a fraction of the issue, actually the simpler part
where we can close older `MediaKeySession` linked to the current content
that we don't need anymore, like for example for a previous DASH Period.

But there's also the risk of encountering that limit while preloading
future contents encrypted through a different keys, or when seeking back
at a previous DASH Period with different keys. In all those scenarios
(which actually seems more probable), there's currently no fix, just
error logs and multiple FIXME mentions in the code.

Fixing this issue while keeping a readable code is very hard right now,
moreover for what is only a suite of theoretical problems that has
never been observed for now.

So I sometimes wonder if the best compromise would not be to just let
it happen, and have an heuristic somewhere else detecting the issue and
fixing it by slightly reducing the experience (e.g. by reloading +
disabling future Period pre-loading)...

Author: peaBerberian

src/main_thread/decrypt/content_decryptor.ts

@@ -20,10 +20,14 @@ import type { CancellationSignal } from "../../utils/task_canceller";
 import createSession from "./create_session";
 import type { IProcessedProtectionData, IMediaKeySessionStores } from "./types";
 import { MediaKeySessionLoadingType } from "./types";
-import cleanOldLoadedSessions from "./utils/clean_old_loaded_sessions";
+import cleanOldLoadedSessions, {
+  NoSessionSpaceError,
+} from "./utils/clean_old_loaded_sessions";
 import isSessionUsable from "./utils/is_session_usable";
 import type KeySessionRecord from "./utils/key_session_record";
 
+export { NoSessionSpaceError };
+
 /**
  * Handle MediaEncryptedEvents sent by a HTMLMediaElement:
  * Either create a MediaKeySession, recuperate a previous MediaKeySession or
@@ -34,24 +38,34 @@ import type KeySessionRecord from "./utils/key_session_record";
  * `EME_MAX_SIMULTANEOUS_MEDIA_KEY_SESSIONS` config property.
  *
  * You can refer to the events emitted to know about the current situation.
- * @param {Object} initializationData
- * @param {Object} stores
- * @param {string} wantedSessionType
- * @param {number} maxSessionCacheSize
+ * @param {Object} arg
+ * @param {Object} arg.initializationData
+ * @param {Object} arg.sessionStores
+ * @param {string} arg.sessionType
+ * @param {number} arg.maxSessionCacheSize
  * @param {Object} cancelSignal
  * @returns {Promise}
  */
 export default async function createOrLoadSession(
-  initializationData: IProcessedProtectionData,
-  stores: IMediaKeySessionStores,
-  wantedSessionType: MediaKeySessionType,
-  maxSessionCacheSize: number,
+  {
+    initializationData,
+    sessionStores,
+    sessionType,
+    activeRecords,
+    maxSessionCacheSize,
+  }: {
+    initializationData: IProcessedProtectionData;
+    sessionStores: IMediaKeySessionStores;
+    sessionType: MediaKeySessionType;
+    activeRecords: KeySessionRecord[];
+    maxSessionCacheSize: number;
+  },
   cancelSignal: CancellationSignal,
 ): Promise<ICreateOrLoadSessionResult> {
   /** Store previously-loaded compatible MediaKeySession, if one. */
   let previousLoadedSession: IMediaKeySession | null = null;
 
-  const { loadedSessionsStore, persistentSessionsStore } = stores;
+  const { loadedSessionsStore, persistentSessionsStore } = sessionStores;
   const entry = loadedSessionsStore.reuse(initializationData);
   if (entry !== null) {
     previousLoadedSession = entry.mediaKeySession;
@@ -84,6 +98,7 @@ export default async function createOrLoadSession(
 
   await cleanOldLoadedSessions(
     loadedSessionsStore,
+    activeRecords,
     // Account for the next session we will be creating
     // Note that `maxSessionCacheSize < 0 has special semantic (no limit)`
     maxSessionCacheSize <= 0 ? maxSessionCacheSize : maxSessionCacheSize - 1,
@@ -93,9 +108,9 @@ export default async function createOrLoadSession(
   }
 
   const evt = await createSession(
-    stores,
+    sessionStores,
     initializationData,
-    wantedSessionType,
+    sessionType,
     cancelSignal,
   );
   return {

src/main_thread/decrypt/create_or_load_session.ts

@@ -41,6 +41,11 @@ export interface IContentDecryptorEvent {
    */
   warning: IPlayerError;
 
+  tooMuchSessions: {
+    waitingKeyIds: Uint8Array[];
+    activeKeyIds: Uint8Array[];
+  };
+
   /**
    * Event emitted when the `ContentDecryptor`'s state changed.
    * States are a central aspect of the `ContentDecryptor`, be sure to check the

src/main_thread/decrypt/types.ts

@@ -1,24 +1,38 @@
 import { describe, it, expect, vi } from "vitest";
 
 import cleanOldLoadedSessions from "../clean_old_loaded_sessions";
+import InitDataValuesContainer from "../init_data_values_container";
+import KeySessionRecord from "../key_session_record";
 import type LoadedSessionsStore from "../loaded_sessions_store";
 
 const entry1 = {
   initializationData: { data: new Uint8Array([1, 6, 9]), type: "test" },
   mediaKeySession: { sessionId: "toto" },
   sessionType: "",
+  keySessionRecord: new KeySessionRecord({
+    type: undefined,
+    values: new InitDataValuesContainer([]),
+  }),
 };
 
 const entry2 = {
   initializationData: { data: new Uint8Array([4, 8]), type: "foo" },
   mediaKeySession: { sessionId: "titi" },
   sessionType: "",
+  keySessionRecord: new KeySessionRecord({
+    type: undefined,
+    values: new InitDataValuesContainer([]),
+  }),
 };
 
 const entry3 = {
   initializationData: { data: new Uint8Array([7, 3, 121, 87]), type: "bar" },
   mediaKeySession: { sessionId: "tutu" },
   sessionType: "",
+  keySessionRecord: new KeySessionRecord({
+    type: undefined,
+    values: new InitDataValuesContainer([]),
+  }),
 };
 
 function createLoadedSessionsStore(): LoadedSessionsStore {
@@ -64,7 +78,7 @@ async function checkNothingHappen(
   limit: number,
 ): Promise<void> {
   const mockCloseSession = vi.spyOn(loadedSessionsStore, "closeSession");
-  await cleanOldLoadedSessions(loadedSessionsStore, limit);
+  await cleanOldLoadedSessions(loadedSessionsStore, [], limit);
   expect(mockCloseSession).not.toHaveBeenCalled();
   mockCloseSession.mockRestore();
 }
@@ -85,7 +99,7 @@ async function checkEntriesCleaned(
   entries: Array<{ sessionId: string }>,
 ): Promise<void> {
   const mockCloseSession = vi.spyOn(loadedSessionsStore, "closeSession");
-  const prom = cleanOldLoadedSessions(loadedSessionsStore, limit).then(() => {
+  const prom = cleanOldLoadedSessions(loadedSessionsStore, [], limit).then(() => {
     expect(mockCloseSession).toHaveBeenCalledTimes(entries.length);
     mockCloseSession.mockRestore();
   });

src/main_thread/decrypt/utils/__tests__/clean_old_loaded_sessions.test.ts

@@ -0,0 +1,139 @@
+import type { BlacklistedSessionError } from "../session_events_listener";
+import type { MediaKeySessionLoadingType } from "../types";
+import type KeySessionRecord from "./key_session_record";
+
+/**
+ * Contains information about all key sessions loaded for the current
+ * content.
+ * This object is most notably used to check which keys are already obtained,
+ * thus avoiding to perform new unnecessary license requests and CDM
+ * interactions.
+ *
+ * It is important to create only one `ActiveSessionsStore` for a given
+ * `MediaKeys` to prevent conflicts.
+ *
+ * An `ActiveSessionsStore` instance can also be "marked" as full with the
+ * `markAsFull` method.
+ * "Marking as full" this way does not change your ability do add new session,
+ * but the `isFull` method will return `true` until at least a single session is
+ * removed from this `ActiveSessionsInfo`.
+ * This "full" flag allows to simplify the management of having too many
+ * simultaneous `MediaKeySession` on the current device, by storing in a single
+ * place whether this event has been encountered and whether it had chance to
+ * be resolved since.
+ *
+ * @class ActiveSessionsInfo
+ */
+export default class ActiveSessionsStore {
+  /** Metadata on each `MediaKeySession` stored here. */
+  private _sessions: IActiveSessionInfo[];
+
+  /**
+   * `true` after the `markAsFull` method has been called, until `removeSession`
+   * is called **and** led to a `MediaKeySession` has been removed.
+   *
+   * This boolean has no impact on the creation of new `MediaKeySession`, it is
+   * only here as a flag to indicate that a surplus of `MediaKeySession`
+   * linked to this `ActiveSessionsStore` has been detected and only resets to
+   * `false` when it has chances to be resolved (when a `MediaKeySession` has
+   * since been removed).
+   */
+  private _isFull: boolean;
+
+  constructor() {
+    this._sessions = [];
+    this._isFull = false;
+  }
+
+  /**
+   * Set the `isFull` flag to true meaning that the `isFull` method will from
+   * now on return `true` until at least one `MediaKeySession` has been removed
+   * from this `ActiveSessionsStore` (through the `removeSession` method).
+   *
+   * This flag allows to store the information of whether too much
+   * `MediaKeySession` seems to be created right now.
+   */
+  public markAsFull(): void {
+    this._isFull = true;
+  }
+
+  /**
+   * Add a new `MediaKeySession`, and its associated information, to the
+   * `ActiveSessionsStore`.
+   * @param {Object} sessionInfo
+   */
+  public addSession(sessionInfo: IActiveSessionInfo) {
+    this._sessions.push(sessionInfo);
+  }
+
+  /**
+   * Returns all information in the `ActiveSessionsStore` by order of insertion.
+   * @returns {Array.<Object>}
+   */
+  public getSessions(): IActiveSessionInfo[] {
+    return this._sessions;
+  }
+
+  /**
+   * Remove element with the corresponding `MediaKeySession` information from
+   * the `ActiveSessionsStore` if found.
+   *
+   * Returns `true` if the corresponding element has been found and removed, or
+   * `false` if it wasn't found.
+   *
+   * @param {Object} sessionInfo
+   * @returns {boolean}
+   */
+  public removeSession(sessionInfo: IActiveSessionInfo): boolean {
+    const indexOf = this._sessions.indexOf(sessionInfo);
+    if (indexOf >= 0) {
+      this._sessions.splice(indexOf, 1);
+      this._isFull = false;
+      return true;
+    }
+    return false;
+  }
+
+  /**
+   * If `true`, we know that there's too much `MediaKeySession` currently
+   * created.
+   *
+   * @see `markAsFull` method.
+   * @returns {boolean}
+   */
+  public isFull(): boolean {
+    return this._isFull;
+  }
+}
+
+/** Information linked to a session created by the `ContentDecryptor`. */
+export interface IActiveSessionInfo {
+  /**
+   * Record associated to the session.
+   * Most notably, it allows both to identify the session as well as to
+   * anounce and find out which key ids are already handled.
+   */
+  record: KeySessionRecord;
+
+  /** Current keys' statuses linked that session. */
+  keyStatuses: {
+    /** Key ids linked to keys that are "usable". */
+    whitelisted: Uint8Array[];
+    /**
+     * Key ids linked to keys that are not considered "usable".
+     * Content linked to those keys are not decipherable and may thus be
+     * fallbacked from.
+     */
+    blacklisted: Uint8Array[];
+  };
+
+  /** Source of the MediaKeySession linked to that record. */
+  source: MediaKeySessionLoadingType;
+
+  /**
+   * If different than `null`, all initialization data compatible with this
+   * processed initialization data has been blacklisted with this corresponding
+   * error.
+   */
+  blacklistedSessionError: BlacklistedSessionError | null;
+}

src/main_thread/decrypt/utils/active_sessions_store.ts

@@ -15,6 +15,8 @@
  */
 
 import log from "../../../log";
+import arrayIncludes from "../../../utils/array_includes";
+import type KeySessionRecord from "./key_session_record";
 import type LoadedSessionsStore from "./loaded_sessions_store";
 
 /**
@@ -28,18 +30,44 @@ import type LoadedSessionsStore from "./loaded_sessions_store";
  */
 export default async function cleanOldLoadedSessions(
   loadedSessionsStore: LoadedSessionsStore,
+  activeRecords: KeySessionRecord[],
   limit: number,
 ): Promise<void> {
   if (limit < 0 || limit >= loadedSessionsStore.getLength()) {
     return;
   }
   log.info("DRM: LSS cache limit exceeded", limit, loadedSessionsStore.getLength());
   const proms: Array<Promise<unknown>> = [];
-  const entries = loadedSessionsStore.getAll().slice(); // clone
-  const toDelete = entries.length - limit;
-  for (let i = 0; i < toDelete; i++) {
-    const entry = entries[i];
-    proms.push(loadedSessionsStore.closeSession(entry.mediaKeySession));
+  const sessionsMetadata = loadedSessionsStore.getAll().slice(); // clone
+  let toDelete = sessionsMetadata.length - limit;
+  for (let i = 0; toDelete > 0 && i < sessionsMetadata.length; i++) {
+    const metadata = sessionsMetadata[i];
+    if (!arrayIncludes(activeRecords, metadata.keySessionRecord)) {
+      proms.push(loadedSessionsStore.closeSession(metadata.mediaKeySession));
+      toDelete--;
+    }
+  }
+  if (toDelete > 0) {
+    return Promise.all(proms).then(() => {
+      return Promise.reject(
+        new NoSessionSpaceError("Could not remove all sessions: some are still active"),
+      );
+    });
   }
   await Promise.all(proms);
 }
+
+/**
+ * Error thrown when the MediaKeySession is blacklisted.
+ * Such MediaKeySession should not be re-used but other MediaKeySession for the
+ * same content can still be used.
+ * @class NoSessionSpaceError
+ * @extends Error
+ */
+export class NoSessionSpaceError extends Error {
+  constructor(message: string) {
+    super(message);
+    // @see https://stackoverflow.com/questions/41102060/typescript-extending-error-class
+    Object.setPrototypeOf(this, NoSessionSpaceError.prototype);
+  }
+}

src/main_thread/decrypt/utils/clean_old_loaded_sessions.ts

@@ -123,6 +123,15 @@ export default class LoadedSessionsStore {
     return null;
   }
 
+  public hasEntryForRecord(keySessionRecord: KeySessionRecord): boolean {
+    for (const stored of this._storage) {
+      if (stored.keySessionRecord === keySessionRecord) {
+        return true;
+      }
+    }
+    return false;
+  }
+
   /**
    * Get `LoadedSessionsStore`'s entry for a given MediaKeySession.
    * Returns `null` if the given MediaKeySession is not stored in the

src/main_thread/decrypt/utils/loaded_sessions_store.ts

@@ -101,6 +101,9 @@ export default class DirectFileContentInitializer extends ContentInitializer {
         onWarning: (err: IPlayerError) => this.trigger("warning", err),
         onBlackListProtectionData: noop,
         onKeyIdsCompatibilityUpdate: noop,
+        onTooMuchSessions: () => {
+          log.error("Init: There's currently too much MediaKeySession created");
+        },
       },
       cancelSignal,
     );