Shaka-player: [Announcement] Offline Storage upgrades in v2.3 will be temporarily unavailable

[joeyparrish]

TL;DR: If you use offline storage, you may have to delete existing offline content to upgrade to current v2.3 releases. Future releases will fix this. You may want to delay upgrade to v2.3 if deleting content is not acceptable.

In #1230, a user notified us that they were unable to store new content offline. We tracked this to an issue caused by upgrading an application from v2.2 (or earlier) to v2.3.x.

While working on a fix, we have discovered many complicating factors, including:

• IndexedDB schema updates must happen in a transaction
• Transactions have a maximum size which is easy to surpass with media content
• Limitations differ across browsers

Because of these complexities, we have decided on a short-term fix and a long-term fix.

The short-term fix is to offer developers a new error code to detect upgrade issues and a new method to delete the existing database. This will allow applications to recover from this issue, albeit at the expense of any content already stored by end-users. When this is done, we will close #1230. The changes will appear in our next release, v2.3.2.

The long-term fix is to change the way we deal with the storage databases. We will continue to read old data from the old tables, and new data will be stored into new tables. We will avoid database upgrades completely and we will not be hampered by the various complexities of IndexedDB upgrades. When this is done, we will close this issue.

The long-term fix will be made available in a future v2.3.x release. (As soon as we can complete the work.) If deleting a user's existing content is unacceptable in your application, we recommend you avoid updating to v2.3.x until the long-term fix is in.

[vaage]

UPDATE

We have removed the upgrade code using this list of CLs:

• 965dc8e1007324540c0ce885c5c346be3b9b3ea4
• c168ee86ad61ae856d4d71cee6264622c151db91
• 9e89a90d3cdbe5c13eb9b2f8e11612b99a739894
• 4147e77f051fea715a5939da29de2ce632235926
• bd2b163743c0fcc8ddc358f916a4356d0b1cdf04

With these CLs, if your storage needs to upgrade, the storage operation will fail with the error UNSUPPORTED_UPGRADE_REQUEST. If you catch this you can delete the database backing storage by using shaka.offline.Storage.deleteAll. In the error, data[0] will have a list of original content uris so that you can re-download all the content again.

[joeyparrish]

Fixes to date cherry-picked for v2.3.2

[joeyparrish]

I used the phrase "when we resolve" in a commit, and referred to this bug, which means I accidentally closed it. Whoops!

[joeyparrish]

Backward compatibility for v2.2.x's offline storage system has finally been restored in the master branch. I will be cherry-picking all of this work to v2.3.x for release in v2.3.8 soon.

[joeyparrish]

All fixes will appear in v2.3.8 and v2.4.0 this week.

[odedhutzler]

Hey @joeyparrish,

Upon closing this issue, are you considering the pause / resume & renew license features?

We also thought of constantly updating the manifest in the DB, so if the browser / tab is closed accidentally, the user will be able to continue the download from where it ended. Are you considering some kind of anti-failure mechanism?

[joeyparrish]

@odedhutzler, this issue was about backward compatibility for upgrades. Please file feature requests for those new features. Thanks!