// Copyright 2016 The Chromium Authors
// 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);
// This is called when a task that wrote to the storage area has finished,
// suggesting to the backing store that now might be a good time to commit
// pending modifications to disk.
Checkpoint();
};
Codebase Browser
chromium