|
| 1 | +Migration from Manifest v2 (MV2) to v3 (MV3) |
| 2 | + |
| 3 | +In MV2, the scripts included from options.html and popup.html and the |
| 4 | +background script all share the same persistent storage, |
| 5 | +window.localStorage, which is initialized when the JS pages are |
| 6 | +loaded. Changes to the localStorage object are persisted automatically. |
| 7 | + |
| 8 | +In MV3, the background script is migrated to service worker, and it |
| 9 | +does not share the localStorage with the other scripts. Instead, |
| 10 | +persistent data storage is managed separately by the chrome.storage |
| 11 | +API, which must be loaded and saved explicitly via the async API |
| 12 | +calls. Additionally, the service worker lifecycle is managed by the |
| 13 | +browser with the browser terminating the instance after some amount of |
| 14 | +inactivity, and re-creating when needed. |
| 15 | + |
| 16 | + |
| 17 | +Extension storage design |
| 18 | + |
| 19 | +In order to make the migration simple, for understanding and reviewing |
| 20 | +the changes, the persistent storage strategy is chosen for minimal |
| 21 | +changes from the existing design. |
| 22 | + |
| 23 | +In MV2, the extension's main logic and data storage is handled by |
| 24 | +options.html and popup.html, and the background script only deals with |
| 25 | +supplying the Proxy Authorization credentials when asked by the |
| 26 | +browser. In MV3, this is still the case, and so the service worker |
| 27 | +must be notified of changes to the credential information that is |
| 28 | +managed by the user via options.html. This credential information |
| 29 | +must be persisted, and used by the service worker when the browser |
| 30 | +needs to access a proxy that requires authorization. |
| 31 | + |
| 32 | +As a matter of fact, this information is all that is needed to be |
| 33 | +managed by the service worker with the chrome.storage API. However, |
| 34 | +since this information is part of the proxySetting object, the service |
| 35 | +worker will save the whole object. The only data that is relevant for |
| 36 | +actual usage, thus, is the 'auth' property. |
| 37 | + |
| 38 | +When the extension is first installed, the background.js in MV2 |
| 39 | +creates a proxySetting object from its template and store in the |
| 40 | +shared localStorage. The options.js and popup.js use this initialized |
| 41 | +object for their operations. In MV3, the service worker still |
| 42 | +initializes this object from its template, but this object is not |
| 43 | +shared automatically with options.js and popup.js. Instead, it |
| 44 | +persists this template into chrome.storage. When options.js first |
| 45 | +runs, it retrieves this initial object from chrome.storage and loads |
| 46 | +it into the shared localStorage. This is the only time where the |
| 47 | +non-service workers JS scripts interacts with the chrome.storage API. |
| 48 | +This is another reason of persisting the whole proxySetting object into |
| 49 | +chrome.storage. |
| 50 | + |
| 51 | + |
| 52 | +Storage usage scenario |
| 53 | + |
| 54 | +When the extension is first installed: |
| 55 | + - both chrome.storage and localStorage are empty |
| 56 | + - service worker initializes, creates, and persists the default |
| 57 | + proxySetting into chrome.storage |
| 58 | + - options.js starts, retrieves the initial proxySetting from |
| 59 | + chrome.storage, and populates to localStorage |
| 60 | + - options.js and other JS scripts use localStorage as normal |
| 61 | + |
| 62 | +When the extension restarts (due to browser restarts) or reloads |
| 63 | +(extension update): |
| 64 | + - both chrome.storage and localStorage are populated. No special |
| 65 | + handling needed |
| 66 | + |
| 67 | +During normal operation: |
| 68 | + - options.js notifies the service worker of any changes to the |
| 69 | + proxy authorization credentials by message passing. Service worker |
| 70 | + persists this into chrome.storage |
| 71 | + - When asked by the browser, service worker provides the |
| 72 | + credentials to access the proxy in use |
| 73 | + - Service worker comes and goes, and credential information is |
| 74 | + lazy-loaded only when needed |
| 75 | + |
| 76 | +After migration of installed MV2 extension to MV3, on the first run: |
| 77 | + - localStorage is populated with valid data |
| 78 | + - chrome.storage is empty, and the service worker populates the |
| 79 | + template proxySetting into chrome.storage, but this does not have |
| 80 | + valid proxy authorization credentials |
| 81 | + - proxy authorization will fail, and the browser presents a popup |
| 82 | + dialog to prompt user to enter proxy credentials |
| 83 | + - the option page still displays the correct credentials |
| 84 | + - this migration issue can be fixed by deleting and re-entering the |
| 85 | + credential information (both the username and password) in the |
| 86 | + options page to force the service worker receive and persist the |
| 87 | + correct data for its use |
0 commit comments