naiveproxy/components/services/leveldb/public/interfaces/leveldb.mojom

// Copyright 2015 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 leveldb.mojom;

import "components/services/filesystem/public/interfaces/directory.mojom";
import "mojo/public/mojom/base/memory_allocator_dump_cross_process_uid.mojom";
import "mojo/public/mojom/base/unguessable_token.mojom";

enum DatabaseError {
  OK,
  NOT_FOUND,
  CORRUPTION,
  NOT_SUPPORTED,
  INVALID_ARGUMENT,
  IO_ERROR
};

enum BatchOperationType {
  PUT_KEY,
  DELETE_KEY,
  DELETE_PREFIXED_KEY,
  // |key| is source prefixed key, |value| is destination prefixed key.
  COPY_PREFIXED_KEY
};

// TODO(dmurph): change to a union type for value population.
struct BatchedOperation {
  BatchOperationType type;
  array<uint8> key;
  // Populated for operations of types PUT_KEY and COPY_PREFIXED_KEY.
  array<uint8>? value;
};

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

enum SharedReadCache {
  Default,
  Web,
};

// Options which control the behavior of a database. (This struct corresponds
// with the struct in leveldb's options.h.)
//
// Note: This struct does not have default values. The values are set by a
// struct trait which copies values to/from a leveldb_env::Options instance.
struct OpenOptions {
  // TODO(erg): Find all comparators and copy them into the service.

  // If true, the database will be created if it is missing.
  bool create_if_missing;

  // If true, an error is raised if the database already exists.
  bool error_if_exists;

  // If true, the implementation will do aggressive checking of the
  // data it is processing and will stop early if it detects any
  // errors.
  bool paranoid_checks;

  // Amount of data to build up in memory (backed by an unsorted log
  // on disk) before converting to a sorted on-disk file.
  uint64 write_buffer_size;

  // Number of open files that can be used by the DB.
  int32 max_open_files;

  // The shared read cache to use.
  SharedReadCache shared_block_read_cache = SharedReadCache.Default;
};

// Service which hands out databases.
interface LevelDBService {
  // Open the database with the specified "name" in the specified "directory".
  // Fails if the database doesn't already exist.
  Open(filesystem.mojom.Directory directory,
       string dbname,
       mojo_base.mojom.MemoryAllocatorDumpCrossProcessUid? memory_dump_id,
       associated LevelDBDatabase& database) => (DatabaseError status);

  // Open the database with the specified "name" in the specified "directory".
  OpenWithOptions(OpenOptions options,
                  filesystem.mojom.Directory directory,
                  string dbname,
                  mojo_base.mojom.MemoryAllocatorDumpCrossProcessUid?
                  memory_dump_id,
                  associated LevelDBDatabase& database) => (DatabaseError status);

  // Opens a database stored purely in memory.
  // "tracking_name" will be used for memory-infra reporting to associate memory
  // use with its origin.
  OpenInMemory(mojo_base.mojom.MemoryAllocatorDumpCrossProcessUid?
               memory_dump_id, string tracking_name,
               associated LevelDBDatabase& database) => (DatabaseError status);

  // Destroys the contents of the specified database. Returns OK if the database
  // already didn't exist.
  Destroy(filesystem.mojom.Directory directory,
          string dbname) => (DatabaseError status);
};

// A leveldb database.
interface LevelDBDatabase {
  // Basic Interface -------------------------------------------------------

  // Sets the database entry for "key" to "value". Returns OK on success.
  Put(array<uint8> key, array<uint8> value) => (DatabaseError status);

  // Remove the database entry (if any) for "key".  Returns OK on
  // success, and a non-OK status on error.  It is not an error if "key"
  // did not exist in the database.
  Delete(array<uint8> key) => (DatabaseError status);

  DeletePrefixed(array<uint8> key_prefix) => (DatabaseError status);

  // Atomically performs all |operations|.
  // The DELETE_PREFIXED_KEY applies to all keys that exist before these
  // operations execute. If a 'put' operation precedes a delete prefix, then it
  // will only be deleted if it was a previously-populated key in the database.
  // The COPY_PREFIXED_KEY operations will always ignore all other changes in
  // the operations batch. It will not copy records that were inserted earlier
  // in the operations list.
  Write(array<BatchedOperation> operations) => (DatabaseError status);

  Get(array<uint8> key) => (DatabaseError status, array<uint8> value);

  GetPrefixed(array<uint8> key_prefix)
      => (DatabaseError status, array<KeyValue> data);

  // Copies all data from the source prefix to the destination prefix. Useful
  // for deep copies.
  CopyPrefixed(array<uint8> source_key_prefix,
               array<uint8> destination_key_prefix)
      => (DatabaseError status);

  // Snapshots -------------------------------------------------------------

  // Returns a handle to the current database state.
  GetSnapshot() => (mojo_base.mojom.UnguessableToken snapshot);

  // Releases a previously acquired snapshot.
  ReleaseSnapshot(mojo_base.mojom.UnguessableToken snapshot);

  // If |key| exists at the time |snapshot_id| was taken, return OK and the
  // value. Otherwise return NOT_FOUND.
  GetFromSnapshot(mojo_base.mojom.UnguessableToken snapshot,
                  array<uint8> key)
      => (DatabaseError status, array<uint8> value);

  // Iteartors -------------------------------------------------------------

  // Creates an iterator, either from the current view or from a snapshot.
  NewIterator() => (mojo_base.mojom.UnguessableToken iterator);
  NewIteratorFromSnapshot(mojo_base.mojom.UnguessableToken snapshot)
      => (mojo_base.mojom.UnguessableToken? iterator);

  ReleaseIterator(mojo_base.mojom.UnguessableToken iterator);

  // Positions the iterator at the first key, last key, or the first key after
  // |target|.
  [Sync]
  IteratorSeekToFirst(mojo_base.mojom.UnguessableToken iterator)
      => (bool valid, DatabaseError status, array<uint8>? key,
          array<uint8>? value);
  [Sync]
  IteratorSeekToLast(mojo_base.mojom.UnguessableToken iterator)
      => (bool valid, DatabaseError status, array<uint8>? key,
          array<uint8>? value);
  [Sync]
  IteratorSeek(mojo_base.mojom.UnguessableToken iterator, array<uint8> target)
      => (bool valid, DatabaseError status, array<uint8>? key,
          array<uint8>? value);

  // Moves forward or backwards in iterator space.
  [Sync]
  IteratorNext(mojo_base.mojom.UnguessableToken iterator)
      => (bool valid, DatabaseError status, array<uint8>? key,
          array<uint8>? value);
  [Sync]
  IteratorPrev(mojo_base.mojom.UnguessableToken iterator)
      => (bool valid, DatabaseError status, array<uint8>? key,
          array<uint8>? value);
};