From f5d1e9a2d1c371d07313932810dcd04bc3d4645f Mon Sep 17 00:00:00 2001 From: Sonu Kapoor Date: Sun, 2 Aug 2020 19:31:01 -0400 Subject: [PATCH] docs(service-worker): add section to explain unrecoverable state (#36847) PR Close #36847 --- .../app/handle-unrecoverable-state.service.ts | 17 ++++++++++++ .../guide/service-worker-communications.md | 27 +++++++++++++++++++ 2 files changed, 44 insertions(+) create mode 100644 aio/content/examples/service-worker-getting-started/src/app/handle-unrecoverable-state.service.ts diff --git a/aio/content/examples/service-worker-getting-started/src/app/handle-unrecoverable-state.service.ts b/aio/content/examples/service-worker-getting-started/src/app/handle-unrecoverable-state.service.ts new file mode 100644 index 0000000000..2754fa052a --- /dev/null +++ b/aio/content/examples/service-worker-getting-started/src/app/handle-unrecoverable-state.service.ts @@ -0,0 +1,17 @@ +import { Injectable } from '@angular/core'; +import { SwUpdate } from '@angular/service-worker'; + +function notifyUser(message: string): void { } + +// #docregion sw-unrecoverable-state +@Injectable() +export class HandleUnrecoverableStateService { + constructor(updates: SwUpdate) { + updates.unrecoverable.subscribe(event => { + notifyUser( + `An error occurred that we cannot recover from:\n${event.reason}\n\n` + + 'Please reload the page.'); + }); + } +} +// #enddocregion sw-unrecoverable-state diff --git a/aio/content/guide/service-worker-communications.md b/aio/content/guide/service-worker-communications.md index 384803216b..d38287973b 100644 --- a/aio/content/guide/service-worker-communications.md +++ b/aio/content/guide/service-worker-communications.md @@ -67,6 +67,33 @@ Therefore, it is recommended to reload the page once the promise returned by `ac +### Handling an unrecoverable state + +In some cases, the version of the app used by the service worker to serve a client might be in a broken state that cannot be recovered from without a full page reload. + +For example, imagine the following scenario: +- A user opens the app for the first time and the service worker caches the latest version of the app. + Let's assume the app's cached assets include `index.html`, `main..js` and `lazy-chunk..js`. +- The user closes the app and does not open it for a while. +- After some time, a new version of the app is deployed to the server. + This newer version includes the files `index.html`, `main..js` and `lazy-chunk..js` (note that the hashes are different now, because the content of the files has changed). + The old version is no longer available on the server. +- In the meantime, the user's browser decides to evict `lazy-chunk..js` from its cache. + Browsers may decide to evict specific (or all) resources from a cache in order to reclaim disk space. +- The user opens the app again. + The service worker serves the latest version known to it at this point, namely the old version (`index.html` and `main..js`). +- At some later point, the app requests the lazy bundle, `lazy-chunk..js`. +- The service worker is unable to find the asset in the cache (remember that the browser evicted it). + Nor is it able to retrieve it from the server (since the server now only has `lazy-chunk..js` from the newer version). + +In the above scenario, the service worker is not able to serve an asset that would normally be cached. +That particular app version is broken and there is no way to fix the state of the client without reloading the page. +In such cases, the service worker notifies the client by sending an `UnrecoverableStateEvent` event. +You can subscribe to `SwUpdate#unrecoverable` to be notified and handle these errors. + + + + ## More on Angular service workers You may also be interested in the following: