dom/localstorage/PBackgroundLSDatabase.ipdl

   1 /* This Source Code Form is subject to the terms of the Mozilla Public
   2  * License, v. 2.0. If a copy of the MPL was not distributed with this file,
   3  * You can obtain one at http://mozilla.org/MPL/2.0/. */
   4
   5 include protocol PBackground;
   6 include protocol PBackgroundLSSnapshot;
   7
   8 include PBackgroundLSSharedTypes;
   9
  10 include "mozilla/dom/localstorage/SerializationHelpers.h";
  11
  12 using mozilla::dom::LSSnapshot::LoadState
  13   from "mozilla/dom/LSSnapshot.h";
  14
  15 namespace mozilla {
  16 namespace dom {
  17
  18 /**
  19  * Initial LSSnapshot state as produced by Datastore::GetSnapshotLoadInfo.  See
  20  * `LSSnapshot::LoadState` for more details about the possible states and a
  21  * high level overview.
  22  */
  23 struct LSSnapshotInitInfo
  24 {
  25   /**
  26    * Boolean indicating whether the `key` provided as an argument to the
  27    * PBackgroundLSSnapshot constructor did not exist in the Datastore and should
  28    * be treated as an unknown and therefore undefined value. Note that `key` may
  29    * have been provided as a void string, in which case this value is forced to
  30    * be false.
  31    */
  32   bool addKeyToUnknownItems;
  33
  34   /**
  35    * As many key/value or key/void pairs as the snapshot prefill byte budget
  36    * allowed.
  37    */
  38   LSItemInfo[] itemInfos;
  39
  40   /**
  41    * The total number of key/value pairs in LocalStorage for this origin at the
  42    * time the snapshot was created.  (And the point of the snapshot is to
  43    * conceptually freeze the state of the Datastore in time, so this value does
  44    * not change despite what other LSDatabase objects get up to in other
  45    * processes.)
  46    */
  47   uint32_t totalLength;
  48
  49   /**
  50    * The current amount of LocalStorage usage as measured by the summing the
  51    * nsString Length() of both the key and the value over all stored pairs.
  52    */
  53   int64_t usage;
  54
  55   /**
  56    * The amount of storage allowed to be used by the Snapshot without requesting
  57    * more storage space via IncreasePeakUsage.  This is the `usage` plus 0 or
  58    * more bytes of space.  If space was available, the increase will be the
  59    * `minSize` from the PBackgroundLSSnapshot constructor plus the configured
  60    * pre-increment (via "dom.storage.snapshot_peak_usage.initial_preincrement").
  61    * If the LocalStorage total usage was already close to the limit, then the
  62    * fallback is either the `minSize` plus the configured reduced pre-increment
  63    * (via "dom.storage.snapshot_peak_usage.reduced_initial_preincrement"), or
  64    * `minSize`, or 0 depending on remaining available space.
  65    */
  66   int64_t peakUsage;
  67
  68   // See `LSSnapshot::LoadState` in `LSSnapshot.h`
  69   LoadState loadState;
  70
  71   /**
  72    * Boolean indicating whether there where cross-process databases registered
  73    * for this origin at the time the snapshot was created.
  74    */
  75   bool hasOtherProcessDatabases;
  76
  77   /**
  78    * Boolean indicating whether there where cross-process observers registered
  79    * for this origin at the time the snapshot was created.
  80    */
  81   bool hasOtherProcessObservers;
  82 };
  83
  84 /**
  85  * This protocol is asynchronously created via constructor on PBackground but
  86  * has synchronous semantics from the perspective of content on the main thread.
  87  * The construction potentially involves waiting for disk I/O to load the
  88  * LocalStorage data from disk as well as related QuotaManager checks, so async
  89  * calls to PBackground are the only viable mechanism because blocking
  90  * PBackground is not acceptable.  (Note that an attempt is made to minimize any
  91  * I/O latency by triggering preloading from
  92  * ContentParent::AboutToLoadHttpDocumentForChild, the central place
  93  * for pre-loading.)
  94  */
  95 [ChildImpl=virtual, ParentImpl=virtual]
  96 sync protocol PBackgroundLSDatabase
  97 {
  98   manager PBackground;
  99   manages PBackgroundLSSnapshot;
 100
 101 parent:
 102   // The DeleteMe message is used to avoid a race condition between the parent
 103   // actor and the child actor. The PBackgroundLSDatabase protocol could be
 104   // simply destroyed by sending the __delete__ message from the child side.
 105   // However, that would destroy the child actor immediatelly and the parent
 106   // could be sending a message to the child at the same time resulting in a
 107   // routing error since the child actor wouldn't exist anymore. A routing
 108   // error typically causes a crash. The race can be prevented by doing the
 109   // teardown in two steps. First, we send the DeleteMe message to the parent
 110   // and the parent then sends the __delete__ message to the child.
 111   async DeleteMe();
 112
 113   /**
 114    * Sent in response to a `RequestAllowToClose` message once the snapshot
 115    * cleanup has happened OR from LSDatabase's destructor if AllowToClose has
 116    * not already been reported.
 117    */
 118   async AllowToClose();
 119
 120   /**
 121    * Invoked to create an LSSnapshot backed by a Snapshot in PBackground that
 122    * presents an atomic and consistent view of the state of the authoritative
 123    * Datastore state in the parent.
 124    *
 125    * This needs to be synchronous because LocalStorage's semantics are
 126    * synchronous.  Note that the Datastore in the PBackground parent already
 127    * has the answers to this request immediately available without needing to
 128    * consult any other threads or perform any I/O.  Additionally, the response
 129    * is explicitly bounded in size by the tunable snapshot prefill byte limit.
 130    *
 131    * @param key
 132    *   If key is non-void, then the snapshot is being triggered by a direct
 133    *   access to a localStorage key (get, set, or removal, with set/removal
 134    *   requiring the old value in order to properly populate the "storage"
 135    *   event), the key being requested. It's possible the key is not present in
 136    *   localStorage, in which case LSSnapshotInitInfo::addKeyToUnknownItems will
 137    *   be true indicating that there is no such key/value pair, otherwise it
 138    *   will be false.
 139    * @param increasePeakUsage
 140    *   Whether the parent should increase initial peak uage of the Snapshot.
 141    *   See also the comment for LSSnapshotInitInfo::peakUsage above.
 142    */
 143   sync PBackgroundLSSnapshot(nsString documentURI,
 144                              nsString key,
 145                              bool increasePeakUsage,
 146                              int64_t minSize)
 147     returns (LSSnapshotInitInfo initInfo);
 148
 149 child:
 150   /**
 151    * Only sent by the parent in response to the child's DeleteMe request.
 152    */
 153   async __delete__();
 154
 155   /**
 156    * Request to close the LSDatabase, checkpointing and finishing any
 157    * outstanding snapshots so no state is lost.  This request is issued when
 158    * QuotaManager is shutting down or is aborting operations for an origin or
 159    * process.  Once the snapshot has cleaned up, AllowToClose will be sent to
 160    * the parent.
 161    *
 162    * Note that the QuotaManager shutdown process is more likely to happen in
 163    * unit tests where we explicitly reset the QuotaManager.  At runtime, we
 164    * expect windows to be closed and content processes terminated well before
 165    * QuotaManager shutdown would actually occur.
 166    *
 167    * Also, Operations are usually aborted for an origin due to privacy API's
 168    * clearing data for an origin.  Operations are aborted for a process by
 169    * ContentParent::ShutDownProcess.
 170    */
 171   async RequestAllowToClose();
 172 };
 173
 174 } // namespace dom
 175 } // namespace mozilla