chromium/components/services/storage/public/mojom/session_storage_control.mojom

// Copyright 2020 The Chromium Authors
// Use of this source code is governed by a BSD-style license that can be
// found in the LICENSE file.

module storage.mojom;

import "third_party/blink/public/mojom/dom_storage/storage_area.mojom";
import "third_party/blink/public/mojom/dom_storage/session_storage_namespace.mojom";
import "third_party/blink/public/mojom/storage_key/storage_key.mojom";

// Used to describe entries present in a partition's Session Storage. See
// `SessionStorageControl.GetUsage()` below.
struct SessionStorageUsageInfo {
  // The `storage_key` for this Session Storage entry.
  blink.mojom.StorageKey storage_key;

  // The namespace ID for this Session Storage entry.
  string namespace_id;
};

// Allows the browser to specify service expectations regarding a new namespace
// produced via `SessionStorageControl.CloneNamespace()` defined below.
enum SessionStorageCloneType {
  // The source namespace is not currently in use or is being cloned by some
  // non-renderer action (e.g. a browser duplicating a tab through browser UI)
  // where strict ordering against mutations is irrelevant.
  kImmediate,

  // The service should expect a `Clone()` call on a
  // blink.mojom.SessionStorageNamespace corresponding to the source namespace
  // before proceeding to clone any data, because the source namespace is
  // currently in use by a client and the client will send its own `Clone()`
  // message, ordered against its own in-flight Session Storage mutations.
  kWaitForCloneOnNamespace,
};

// Controls the state of Session Storage within a partition. This is a
// privileged interface and must not be brokered to untrusted clients.
//
// Currently this is consumed and implemented in the browser process, but the
// implementation will eventually live in the storage service which may run
// out-of-process.
interface SessionStorageControl {
  // Binds a control interface for the given namespace. Returns `true` if
  // `namespace_id` matched a valid namespace name and `false` otherwise.
  BindNamespace(string namespace_id,
                pending_receiver<blink.mojom.SessionStorageNamespace> receiver)
      => (bool success);

  // Binds a blink.mojom.StorageArea receiver for the `storage_key` in the
  // given namespace. Returns `true` if `namespace_id` matched a valid
  // namespace name and `false` otherwise.
  //
  // Note that the browser calling this method should have already validated
  // that the source of `receiver` (i.e. some specific renderer process) is
  // allowed to access storage for `storage_key`.
  BindStorageArea(blink.mojom.StorageKey storage_key,
                  string namespace_id,
                  pending_receiver<blink.mojom.StorageArea> receiver)
      => (bool success);

  // Retrieves some basic usage information about the Session Storage state.
  GetUsage() => (array<SessionStorageUsageInfo> info);

  // Deletes storage for the given `storage_key` in the given namespace.
  // Responds when the deletion is complete.
  DeleteStorage(blink.mojom.StorageKey storage_key, string namespace_id) => ();

  // Ensures that no traces of deleted Session Storage data are left in the
  // backing storage. Responds when the cleanup is complete.
  CleanUpStorage() => ();

  // Scans Session Storage for entries pertaining to unused namespaces and
  // removes them from the backing storage. Response when done.
  ScavengeUnusedNamespaces() => ();

  // Tells the service to immediately commit any pending operations to disk.
  Flush();

  // Purges any in-memory caches to free up as much memory as possible. The
  // next access to a StorageArea will reload data from the backing database.
  PurgeMemory();

  // Creates a new namespace which can later be manipulated by other requests
  // on this interface.
  CreateNamespace(string namespace_id);

  // Clones a namespace from `namespace_id_to_clone` to `clone_namespace_id`.
  // See documentation on SessionStorageCloneType for the meaning of
  // `clone_type`.
  CloneNamespace(string namespace_id_to_clone,
                 string clone_namespace_id,
                 SessionStorageCloneType clone_type);

  // Called when a session is ending and will not need to be restored later.
  // This results in a purge of all data for the namespace from memory. If
  // `should_persist` is true, the namespace's data is left in the database;
  // otherwise it is permanently deleted.
  DeleteNamespace(string namespace_id, bool should_persist);
};