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

module blink.mojom;

// Gives information about changes to a StorageArea.
//
// NOTE: When used for Local Storage, all of the events defined here may be
// received by an observer. Session Storage observers will ONLY ever observe
// |AllDeleted()| messages, and only in response to browser-initiated storage
// removal. This is because every Session Storage area is effectively owned by
// a single client and there is no need to incur IPC overhead by repeating the
// client's changes back to itself.
interface StorageAreaObserver {
  // Notifies the observer that a key's value was changed. If |old_value| is
  // null, the key was newly added and had no previous value stored.
  KeyChanged(array<uint8> key, array<uint8> new_value, array<uint8>? old_value,
             string source);

  // Notifies the observer that a requested key change failed. This is generally
  // only of interest to the client corresponding to |source| which attempted to
  // change the key (e.g. to roll back a cache update).
  KeyChangeFailed(array<uint8> key, string source);

  // Notifies the observer that a key was deleted. |old_value| may be null if
  // the deleted key didn't have an entry prior to this call.
  KeyDeleted(array<uint8> key, array<uint8>? old_value, string source);

  // Notifies the observer that all keys were deleted. |was_nonempty| indicates
  // whether the StorageArea had at least one key-value stored at when the
  // corresponding |DeleteAll()| call was received.
  AllDeleted(bool was_nonempty, string source);

  // Tells the client if it should send the old values for the key on |Put()|
  // and |Delete()| calls for sending notifications. Clients should assume they
  // need to send these values unless this method is called with |false| at some
  // point.
  ShouldSendOldValueOnMutations(bool value);
};

struct KeyValue {
  array<uint8> key;
  array<uint8> value;
};

// The mojo interface representing the connection to a single Local Storage or
// Session Storage storage area. Every area represents an isolated key-value
// store.
interface StorageArea {
  // The quota for each storage area.
  // This value is enforced in renderer processes and the browser process.
  const uint32 kPerStorageAreaQuota = 10485760; // 10 MiB

  // In the browser process we allow some overage to
  // accommodate concurrent writes from different renderers
  // that were allowed because the limit imposed in the renderer
  // wasn't exceeded.
  const uint32 kPerStorageAreaOverQuotaAllowance = 102400; // 100 KiB

  // Adds an observer to monitor changes to the StorageArea. Note that no
  // guarantees can be made about exactly when this observer will start
  // observing events. For example, a |Put()| immediately before or after this
  // |AddObserver()| call may or may not result in a corresponding
  // |KeyChanged()| event on the observer.
  //
  // In order to properly synchronize observed events against known storage
  // state, callers must use |GetAll()| or |DeleteAll()| and pass an observer
  // to those methods.
  AddObserver(pending_remote<StorageAreaObserver> observer);

  // Set the database entry for |key| to |value|.
  // Takes an optional |client_old_value| (see ShouldSendOldValueOnMutations()):
  // 1. If the client is notified to not send old value on mutations
  //    |client_old_value| is unused and can be nullopt.
  // 2. If the client is notified to send old values or not notified at all,
  //    |client_old_value| must be filled in with old value of the |key|, or
  //    nullopt if |key| was not present in database. This value is used to send
  //    notifications to StorageArea(s).
  // Returns |true| on success or |false| on failure.
  //
  // Note that a successful reply should not be treated as an indication that
  // the value stored at |key| is |value|: it is possible for the reply to be
  // received after some other client has already modified the key again.
  // Clients interested in maintaining a consistent local cache of the stored
  // contents should rely only on sequential StorageAreaObserver events from
  // an observer bound via |GetAll()| or |DeleteAll()|.
  Put(array<uint8> key, array<uint8> value, array<uint8>? client_old_value,
      string source)
      => (bool success);

  // Remove the database entry (if any) for |key|.
  // Takes an optional |client_old_value| (see ShouldSendOldValueOnMutations()):
  // 1. If the client is notified to not send old value on mutations,
  //    |client_old_value| is unused and can be nullopt.
  // 2. If the client is notified to send old values or not notified at all,
  //    |client_old_value| must be filled in with old value of the |key|, or
  //    nullopt if |key| was not present in database. This value is used to send
  //    notifications to StorageAreaObserver(s).
  //
  // TODO(https://crbug.com/1000959): Remove the |success| reply argument. This
  // call always succeeds.
  //
  // Note that a successful reply should not be treated as an indication that
  // the value for |key| is still empty: it is possible for the reply to be
  // received after some other client has already added the key again. Clients
  // interested in maintaining a consistent local cache of the stored contents
  // should rely only on sequential StorageAreaObserver events from an observer
  // bound via |GetAll()| or |DeleteAll()|.
  Delete(array<uint8> key, array<uint8>? client_old_value, string source)
      => (bool success);

  // Removes all entries. If |new_observer| is non-null, it will be added to
  // the StorageArea's set of observers immediately BEFORE broadcasting the
  // corresponding |AllDeleted()| event, such that |new_observer|'s receiver
  // will always receive that |AllDeleted()| as its first observed event.
  //
  // TODO(https://crbug.com/1000959): Remove the |success| reply argument. This
  // call always succeeds.
  DeleteAll(string source, pending_remote<StorageAreaObserver>? new_observer)
      => (bool success);

  // [DEPRECATED] Returns the value of the |key| only if values are
  // stored in the internal in-memory cache. Fails if the |key| does not exist
  // or if values are not required to be stored in the cache.
  // TODO(ssid): Remove this function, crbug.com/764127.
  Get(array<uint8> key) => (bool success, array<uint8> value);

  // Returns all key/value pairs and optionally adds a new StorageAreaObserver
  // which will observe all events on the StorageArea which occur after the
  // returned snapshot.
  [Sync]
  GetAll(pending_remote<StorageAreaObserver>? new_observer)
      => (array<KeyValue> data);
};