Adding upstream version 124.0.1.upstream/124.0.1

Signed-off-by: Daniel Baumann <daniel.baumann@progress-linux.org>

1 files changed, 119 insertions, 0 deletions

diff --git a/security/manager/ssl/nsIDataStorage.idl b/security/manager/ssl/nsIDataStorage.idl
new file mode 100644
index 0000000000..3fe2c87f77
--- /dev/null
+++ b/security/manager/ssl/nsIDataStorage.idl
@@ -0,0 +1,119 @@
+/* -*- Mode: C++; tab-width: 2; indent-tabs-mode: nil; c-basic-offset: 2 -*-
+ *
+ * This Source Code Form is subject to the terms of the Mozilla Public
+ * License, v. 2.0. If a copy of the MPL was not distributed with this
+ * file, You can obtain one at http://mozilla.org/MPL/2.0/. */
+
+#include "nsISupports.idl"
+
+interface nsIDataStorage;
+interface nsIDataStorageItem;
+
+[scriptable, uuid(71b49926-fd4e-43e2-ab8d-d9b049413c0b)]
+interface nsIDataStorageManager : nsISupports {
+  // Because of its specialized nature, nsIDataStorage instances are limited to
+  // the following pre-defined set. To add a new type of data storage, add an
+  // entry to the enum and get review from someone on the security and privacy
+  // engineering team.
+  cenum DataStorage : 8 {
+    AlternateServices,
+    ClientAuthRememberList,
+    SiteSecurityServiceState,
+  };
+
+  nsIDataStorage get(in nsIDataStorageManager_DataStorage dataStorage);
+};
+
+/**
+ * nsIDataStorage is a threadsafe, generic, narrow string-based hash map that
+ * persists data on disk and additionally handles private (temporary) data.
+ * The file format is portable across architectures. If used in a context where
+ * there is no profile directory, data will not be persisted.
+ *
+ * Its lifecycle is as follows:
+ * - Use nsIDataStorageManager to obtain the nsIDataStorage of a particular
+ *   purpose. Its backing file will be read on a background thread.
+ * - Should the profile directory not be available, (e.g. in xpcshell),
+ *   nsIDataStorage will not read any persistent data.
+ * - When data in the nsIDataStorage changes, those changes will be written
+ *   to the backing file on a background thread. If the program crashes or is
+ *   closed unexpectedly before the write completes, the changes may be lost.
+ *   If the changes were an update to previously stored data, the original data
+ *   may be lost as well. A checksum associated with each entry helps identify
+ *   incompletely written entries.
+ * - nsIDataStorage does not support transactions. Each entry is independent of
+ *   the others.
+ * - When an nsIDataStorage instance observes the topic "profile-before-change"
+ *   in anticipation of shutdown, no more changes will be written to the
+ *   backing file. To ensure no data is lost, users of nsIDataStorage should
+ *   not attempt to change any data after this point.
+ *   If "profile-before-change" is not observed, this happens upon observing
+ *   "xpcom-shutdown-threads".
+ * - To prevent unbounded memory and disk use, the number of entries in each
+ *   table is limited to 2048. Evictions are handled in by a modified LRU scheme
+ *   (see implementation comments).
+ * - Note that instances of nsIDataStorage have long lifetimes because they are
+ *   strong observers of events and won't go away until the observer service
+ *   does.
+ *
+ * For each key/value:
+ * - The key must have a length no more than 256.
+ * - The value have a length no more than 1024 (24 for the site security
+ *   service state).
+ *   The length limits are to prevent unbounded disk and memory usage, and
+ *   nsIDataStorage will throw/return an error if given keys or values of
+ *   excess length.
+ *   Take care when storing data containing bytes that may be 0. When read
+ *   from disk, all trailing 0 bytes from keys and values are stripped.
+ */
+[scriptable, uuid(fcbb5ec4-7134-4069-91c6-9378eff51e03)]
+interface nsIDataStorage : nsISupports {
+  /**
+   * Data that is Persistent is saved on disk. Data that is Private is not
+   * saved. Private is meant to only be set and accessed from private contexts.
+   * It will be cleared upon observing the event "last-pb-context-exited".
+   */
+  cenum DataType : 8 {
+    Persistent,
+    Private,
+  };
+
+  // Given a key and a type of data, returns a value. Returns
+  // NS_ERROR_NOT_AVAILABLE if the key is not present for that type of data.
+  // This operation may block the current thread until the background task
+  // reading the backing file from disk has completed.
+  ACString get(in ACString key, in nsIDataStorage_DataType type);
+
+  // Give a key, value, and type of data, adds an entry as appropriate.
+  // Updates existing entries.
+  // This operation may block the current thread until the background task
+  // reading the backing file from disk has completed.
+  void put(in ACString key, in ACString value, in nsIDataStorage_DataType type);
+
+  // Given a key and type of data, removes an entry if present.
+  // This operation may block the current thread until the background task
+  // reading the backing file from disk has completed.
+  void remove(in ACString key, in nsIDataStorage_DataType type);
+
+  // Removes all entries of all types of data.
+  // This operation may block the current thread until the background task
+  // reading the backing file from disk has completed.
+  void clear();
+
+  // Returns true if this data storage is ready to be used. To avoid blocking
+  // when calling other nsIDataStorage functions, callers may wish to first
+  // ensure this function returns true.
+  bool isReady();
+
+  // Read all of the data items.
+  // This operation may block the current thread until the background task
+  // reading the backing file from disk has completed.
+  Array<nsIDataStorageItem> getAll();
+};
+
+[scriptable, uuid(4501f984-0e3a-4199-a67e-7753649e93f1)]
+interface nsIDataStorageItem : nsISupports {
+  readonly attribute ACString key;
+  readonly attribute ACString value;
+  readonly attribute nsIDataStorage_DataType type;
+};