devtools/docs/contributor/tools/storage.md

   1 # Storage Panel Architecture
   2
   3 ## Actor structure
   4
   5 This is the new architecture that is being implemented to support Fission. It's currently used when inspecting tabs.
   6
   7 ![Class structure architecture (resource-based)](storage/resources.svg)
   8
   9 - We no longer have a global `Storage` actor.
  10 - The specific actors for each storage type are spawned by watchers instead.
  11 - The reference to a global `Storage` actor that each actor has now points to a mock instead.
  12 - Some watchers require to be run in the parent process, while others can be run in the content process.
  13   - Parent process: Cookies, IndexedDB, Web Extension.
  14   - Content process: LocalStorage, SessionStorage, Cache.
  15
  16 ## Flow
  17
  18 Some considerations to keep in mind:
  19
  20 - In the Storage Panel, **resources are fronts**.
  21 - These fronts contain a `hosts` object, which is populated with the host name, and the actual storage data it contains.
  22 - In the client, we get as part of the `onAvailable` callback of `ResourceCommand.watchResources`:
  23   - Content process storage types: multiple resources, one per target
  24   - Parent process storage types: a single resource
  25
  26 ### Initial load
  27
  28 Web page loaded, open toolbox. Later on, we see what happens if a new remote target is added (for instance, an iframe is created that points to a different host).
  29
  30 #### Fission OFF
  31
  32 ![Initial load diagram, fission off](storage/flow-fission-off.svg)
  33
  34 - We get all the storage fronts as new resources sent in the `onAvailable` callback for `watchResources`.
  35 - After a remote target has been added, we get new additions as `"single-store-update"` events.
  36
  37 #### Fission ON
  38
  39 ![Initial load diagram, fission on](storage/flow-fission-on.svg)
  40
  41 Similar to the previous scenario (fission off), but now when a new remote target is added:
  42
  43 - We get content process storage resources in a new `onAvailable` callback, instead of `"single-store-update"`.
  44 - Parent process storage resources keep using the `"single-store-update"` method. This is possible due to their `StorageMock` actors emitting a fake `"window-ready"` event after a `"window-global-created"`.
  45
  46 ### Navigation
  47
  48 #### Fission ON, target switching OFF
  49
  50 ![Navigation diagram, fission on, target switching off](storage/navigation-fission-on-target-switching-off.svg)
  51
  52 - Deletion of content process storage hosts is handled within the `onTargetDestroyed` callback.
  53 - Deletion of parent process storage hosts is handled with `"single-store-update"` events, fired when the `StorageMock` detects a `"window-global-destroyed"` event.
  54 - When the new target is available, new storage actors are spawned from their watchers' `watch` method and are sent as resources in the `onAvailable` callback.
  55
  56 #### Fission ON, target switching ON
  57
  58 ![Navigation diagram, fission on, target switching off](storage/navigation-fission-on-target-switching-on.svg)
  59
  60 Similar to the previous scenario (fission on, target switching off), but parent process storage resources are handled differently, since their watchers remain instantiated.
  61
  62 - New actors for parent process resources are not spawned by their watchers `watch`, but as a callback of `"window-global-created"`.
  63 - Some times there's a race condition between a target being available and firing `"window-global-created"`. There is a delay to send the resource to the client, to ensure that any `onTargetAvailable` callback is processed first.
  64   - The new actor/resource is sent after a `"target-available-form"` event.
  65
  66 ### CRUD operations
  67
  68 #### Add a new cookie
  69
  70 Other CRUD operations work very similar to this one.
  71
  72 ![CRUD operation diagram, add a new cookie](storage/crud-cookie.svg)
  73
  74 - We call `StorageMock.getWindowFromHost` so we can get the storage principal. Since this is a parent process resource, it doesn't have access to an actual window, so it returns a mock instead (but with a real principal).
  75 - To detect changes in storage, we subscribe to different events that platform provides via `Services.obs.addObserver`.
  76 - To manipulate storage data, we use different methods depending on the storage type. For cookies, we use the API provided by `Services.cookies`.