new repo

[bytom/vapor.git] / vendor / github.com / btcsuite / btcd / database / interface.go

// Copyright (c) 2015-2016 The btcsuite developers
// Use of this source code is governed by an ISC
// license that can be found in the LICENSE file.

// Parts of this interface were inspired heavily by the excellent boltdb project
// at https://github.com/boltdb/bolt by Ben B. Johnson.

package database

import (
        "github.com/btcsuite/btcd/chaincfg/chainhash"
        "github.com/btcsuite/btcutil"
)

// Cursor represents a cursor over key/value pairs and nested buckets of a
// bucket.
//
// Note that open cursors are not tracked on bucket changes and any
// modifications to the bucket, with the exception of Cursor.Delete, invalidates
// the cursor.  After invalidation, the cursor must be repositioned, or the keys
// and values returned may be unpredictable.
type Cursor interface {
        // Bucket returns the bucket the cursor was created for.
        Bucket() Bucket

        // Delete removes the current key/value pair the cursor is at without
        // invalidating the cursor.
        //
        // The interface contract guarantees at least the following errors will
        // be returned (other implementation-specific errors are possible):
        //   - ErrIncompatibleValue if attempted when the cursor points to a
        //     nested bucket
        //   - ErrTxNotWritable if attempted against a read-only transaction
        //   - ErrTxClosed if the transaction has already been closed
        Delete() error

        // First positions the cursor at the first key/value pair and returns
        // whether or not the pair exists.
        First() bool

        // Last positions the cursor at the last key/value pair and returns
        // whether or not the pair exists.
        Last() bool

        // Next moves the cursor one key/value pair forward and returns whether
        // or not the pair exists.
        Next() bool

        // Prev moves the cursor one key/value pair backward and returns whether
        // or not the pair exists.
        Prev() bool

        // Seek positions the cursor at the first key/value pair that is greater
        // than or equal to the passed seek key.  Returns whether or not the
        // pair exists.
        Seek(seek []byte) bool

        // Key returns the current key the cursor is pointing to.
        Key() []byte

        // Value returns the current value the cursor is pointing to.  This will
        // be nil for nested buckets.
        Value() []byte
}

// Bucket represents a collection of key/value pairs.
type Bucket interface {
        // Bucket retrieves a nested bucket with the given key.  Returns nil if
        // the bucket does not exist.
        Bucket(key []byte) Bucket

        // CreateBucket creates and returns a new nested bucket with the given
        // key.
        //
        // The interface contract guarantees at least the following errors will
        // be returned (other implementation-specific errors are possible):
        //   - ErrBucketExists if the bucket already exists
        //   - ErrBucketNameRequired if the key is empty
        //   - ErrIncompatibleValue if the key is otherwise invalid for the
        //     particular implementation
        //   - ErrTxNotWritable if attempted against a read-only transaction
        //   - ErrTxClosed if the transaction has already been closed
        CreateBucket(key []byte) (Bucket, error)

        // CreateBucketIfNotExists creates and returns a new nested bucket with
        // the given key if it does not already exist.
        //
        // The interface contract guarantees at least the following errors will
        // be returned (other implementation-specific errors are possible):
        //   - ErrBucketNameRequired if the key is empty
        //   - ErrIncompatibleValue if the key is otherwise invalid for the
        //     particular implementation
        //   - ErrTxNotWritable if attempted against a read-only transaction
        //   - ErrTxClosed if the transaction has already been closed
        CreateBucketIfNotExists(key []byte) (Bucket, error)

        // DeleteBucket removes a nested bucket with the given key.  This also
        // includes removing all nested buckets and keys under the bucket being
        // deleted.
        //
        // The interface contract guarantees at least the following errors will
        // be returned (other implementation-specific errors are possible):
        //   - ErrBucketNotFound if the specified bucket does not exist
        //   - ErrTxNotWritable if attempted against a read-only transaction
        //   - ErrTxClosed if the transaction has already been closed
        DeleteBucket(key []byte) error

        // ForEach invokes the passed function with every key/value pair in the
        // bucket.  This does not include nested buckets or the key/value pairs
        // within those nested buckets.
        //
        // WARNING: It is not safe to mutate data while iterating with this
        // method.  Doing so may cause the underlying cursor to be invalidated
        // and return unexpected keys and/or values.
        //
        // The interface contract guarantees at least the following errors will
        // be returned (other implementation-specific errors are possible):
        //   - ErrTxClosed if the transaction has already been closed
        //
        // NOTE: The slices returned by this function are only valid during a
        // transaction.  Attempting to access them after a transaction has ended
        // results in undefined behavior.  Additionally, the slices must NOT
        // be modified by the caller.  These constraints prevent additional data
        // copies and allows support for memory-mapped database implementations.
        ForEach(func(k, v []byte) error) error

        // ForEachBucket invokes the passed function with the key of every
        // nested bucket in the current bucket.  This does not include any
        // nested buckets within those nested buckets.
        //
        // WARNING: It is not safe to mutate data while iterating with this
        // method.  Doing so may cause the underlying cursor to be invalidated
        // and return unexpected keys and/or values.
        //
        // The interface contract guarantees at least the following errors will
        // be returned (other implementation-specific errors are possible):
        //   - ErrTxClosed if the transaction has already been closed
        //
        // NOTE: The keys returned by this function are only valid during a
        // transaction.  Attempting to access them after a transaction has ended
        // results in undefined behavior.  This constraint prevents additional
        // data copies and allows support for memory-mapped database
        // implementations.
        ForEachBucket(func(k []byte) error) error

        // Cursor returns a new cursor, allowing for iteration over the bucket's
        // key/value pairs and nested buckets in forward or backward order.
        //
        // You must seek to a position using the First, Last, or Seek functions
        // before calling the Next, Prev, Key, or Value functions.  Failure to
        // do so will result in the same return values as an exhausted cursor,
        // which is false for the Prev and Next functions and nil for Key and
        // Value functions.
        Cursor() Cursor

        // Writable returns whether or not the bucket is writable.
        Writable() bool

        // Put saves the specified key/value pair to the bucket.  Keys that do
        // not already exist are added and keys that already exist are
        // overwritten.
        //
        // The interface contract guarantees at least the following errors will
        // be returned (other implementation-specific errors are possible):
        //   - ErrKeyRequired if the key is empty
        //   - ErrIncompatibleValue if the key is the same as an existing bucket
        //   - ErrTxNotWritable if attempted against a read-only transaction
        //   - ErrTxClosed if the transaction has already been closed
        //
        // NOTE: The slices passed to this function must NOT be modified by the
        // caller.  This constraint prevents the requirement for additional data
        // copies and allows support for memory-mapped database implementations.
        Put(key, value []byte) error

        // Get returns the value for the given key.  Returns nil if the key does
        // not exist in this bucket.  An empty slice is returned for keys that
        // exist but have no value assigned.
        //
        // NOTE: The value returned by this function is only valid during a
        // transaction.  Attempting to access it after a transaction has ended
        // results in undefined behavior.  Additionally, the value must NOT
        // be modified by the caller.  These constraints prevent additional data
        // copies and allows support for memory-mapped database implementations.
        Get(key []byte) []byte

        // Delete removes the specified key from the bucket.  Deleting a key
        // that does not exist does not return an error.
        //
        // The interface contract guarantees at least the following errors will
        // be returned (other implementation-specific errors are possible):
        //   - ErrKeyRequired if the key is empty
        //   - ErrIncompatibleValue if the key is the same as an existing bucket
        //   - ErrTxNotWritable if attempted against a read-only transaction
        //   - ErrTxClosed if the transaction has already been closed
        Delete(key []byte) error
}

// BlockRegion specifies a particular region of a block identified by the
// specified hash, given an offset and length.
type BlockRegion struct {
        Hash   *chainhash.Hash
        Offset uint32
        Len    uint32
}

// Tx represents a database transaction.  It can either by read-only or
// read-write.  The transaction provides a metadata bucket against which all
// read and writes occur.
//
// As would be expected with a transaction, no changes will be saved to the
// database until it has been committed.  The transaction will only provide a
// view of the database at the time it was created.  Transactions should not be
// long running operations.
type Tx interface {
        // Metadata returns the top-most bucket for all metadata storage.
        Metadata() Bucket

        // StoreBlock stores the provided block into the database.  There are no
        // checks to ensure the block connects to a previous block, contains
        // double spends, or any additional functionality such as transaction
        // indexing.  It simply stores the block in the database.
        //
        // The interface contract guarantees at least the following errors will
        // be returned (other implementation-specific errors are possible):
        //   - ErrBlockExists when the block hash already exists
        //   - ErrTxNotWritable if attempted against a read-only transaction
        //   - ErrTxClosed if the transaction has already been closed
        //
        // Other errors are possible depending on the implementation.
        StoreBlock(block *btcutil.Block) error

        // HasBlock returns whether or not a block with the given hash exists
        // in the database.
        //
        // The interface contract guarantees at least the following errors will
        // be returned (other implementation-specific errors are possible):
        //   - ErrTxClosed if the transaction has already been closed
        //
        // Other errors are possible depending on the implementation.
        HasBlock(hash *chainhash.Hash) (bool, error)

        // HasBlocks returns whether or not the blocks with the provided hashes
        // exist in the database.
        //
        // The interface contract guarantees at least the following errors will
        // be returned (other implementation-specific errors are possible):
        //   - ErrTxClosed if the transaction has already been closed
        //
        // Other errors are possible depending on the implementation.
        HasBlocks(hashes []chainhash.Hash) ([]bool, error)

        // FetchBlockHeader returns the raw serialized bytes for the block
        // header identified by the given hash.  The raw bytes are in the format
        // returned by Serialize on a wire.BlockHeader.
        //
        // It is highly recommended to use this function (or FetchBlockHeaders)
        // to obtain block headers over the FetchBlockRegion(s) functions since
        // it provides the backend drivers the freedom to perform very specific
        // optimizations which can result in significant speed advantages when
        // working with headers.
        //
        // The interface contract guarantees at least the following errors will
        // be returned (other implementation-specific errors are possible):
        //   - ErrBlockNotFound if the requested block hash does not exist
        //   - ErrTxClosed if the transaction has already been closed
        //   - ErrCorruption if the database has somehow become corrupted
        //
        // NOTE: The data returned by this function is only valid during a
        // database transaction.  Attempting to access it after a transaction
        // has ended results in undefined behavior.  This constraint prevents
        // additional data copies and allows support for memory-mapped database
        // implementations.
        FetchBlockHeader(hash *chainhash.Hash) ([]byte, error)

        // FetchBlockHeaders returns the raw serialized bytes for the block
        // headers identified by the given hashes.  The raw bytes are in the
        // format returned by Serialize on a wire.BlockHeader.
        //
        // It is highly recommended to use this function (or FetchBlockHeader)
        // to obtain block headers over the FetchBlockRegion(s) functions since
        // it provides the backend drivers the freedom to perform very specific
        // optimizations which can result in significant speed advantages when
        // working with headers.
        //
        // Furthermore, depending on the specific implementation, this function
        // can be more efficient for bulk loading multiple block headers than
        // loading them one-by-one with FetchBlockHeader.
        //
        // The interface contract guarantees at least the following errors will
        // be returned (other implementation-specific errors are possible):
        //   - ErrBlockNotFound if any of the request block hashes do not exist
        //   - ErrTxClosed if the transaction has already been closed
        //   - ErrCorruption if the database has somehow become corrupted
        //
        // NOTE: The data returned by this function is only valid during a
        // database transaction.  Attempting to access it after a transaction
        // has ended results in undefined behavior.  This constraint prevents
        // additional data copies and allows support for memory-mapped database
        // implementations.
        FetchBlockHeaders(hashes []chainhash.Hash) ([][]byte, error)

        // FetchBlock returns the raw serialized bytes for the block identified
        // by the given hash.  The raw bytes are in the format returned by
        // Serialize on a wire.MsgBlock.
        //
        // The interface contract guarantees at least the following errors will
        // be returned (other implementation-specific errors are possible):
        //   - ErrBlockNotFound if the requested block hash does not exist
        //   - ErrTxClosed if the transaction has already been closed
        //   - ErrCorruption if the database has somehow become corrupted
        //
        // NOTE: The data returned by this function is only valid during a
        // database transaction.  Attempting to access it after a transaction
        // has ended results in undefined behavior.  This constraint prevents
        // additional data copies and allows support for memory-mapped database
        // implementations.
        FetchBlock(hash *chainhash.Hash) ([]byte, error)

        // FetchBlocks returns the raw serialized bytes for the blocks
        // identified by the given hashes.  The raw bytes are in the format
        // returned by Serialize on a wire.MsgBlock.
        //
        // The interface contract guarantees at least the following errors will
        // be returned (other implementation-specific errors are possible):
        //   - ErrBlockNotFound if the any of the requested block hashes do not
        //     exist
        //   - ErrTxClosed if the transaction has already been closed
        //   - ErrCorruption if the database has somehow become corrupted
        //
        // NOTE: The data returned by this function is only valid during a
        // database transaction.  Attempting to access it after a transaction
        // has ended results in undefined behavior.  This constraint prevents
        // additional data copies and allows support for memory-mapped database
        // implementations.
        FetchBlocks(hashes []chainhash.Hash) ([][]byte, error)

        // FetchBlockRegion returns the raw serialized bytes for the given
        // block region.
        //
        // For example, it is possible to directly extract Bitcoin transactions
        // and/or scripts from a block with this function.  Depending on the
        // backend implementation, this can provide significant savings by
        // avoiding the need to load entire blocks.
        //
        // The raw bytes are in the format returned by Serialize on a
        // wire.MsgBlock and the Offset field in the provided BlockRegion is
        // zero-based and relative to the start of the block (byte 0).
        //
        // The interface contract guarantees at least the following errors will
        // be returned (other implementation-specific errors are possible):
        //   - ErrBlockNotFound if the requested block hash does not exist
        //   - ErrBlockRegionInvalid if the region exceeds the bounds of the
        //     associated block
        //   - ErrTxClosed if the transaction has already been closed
        //   - ErrCorruption if the database has somehow become corrupted
        //
        // NOTE: The data returned by this function is only valid during a
        // database transaction.  Attempting to access it after a transaction
        // has ended results in undefined behavior.  This constraint prevents
        // additional data copies and allows support for memory-mapped database
        // implementations.
        FetchBlockRegion(region *BlockRegion) ([]byte, error)

        // FetchBlockRegions returns the raw serialized bytes for the given
        // block regions.
        //
        // For example, it is possible to directly extract Bitcoin transactions
        // and/or scripts from various blocks with this function.  Depending on
        // the backend implementation, this can provide significant savings by
        // avoiding the need to load entire blocks.
        //
        // The raw bytes are in the format returned by Serialize on a
        // wire.MsgBlock and the Offset fields in the provided BlockRegions are
        // zero-based and relative to the start of the block (byte 0).
        //
        // The interface contract guarantees at least the following errors will
        // be returned (other implementation-specific errors are possible):
        //   - ErrBlockNotFound if any of the requested block hashed do not
        //     exist
        //   - ErrBlockRegionInvalid if one or more region exceed the bounds of
        //     the associated block
        //   - ErrTxClosed if the transaction has already been closed
        //   - ErrCorruption if the database has somehow become corrupted
        //
        // NOTE: The data returned by this function is only valid during a
        // database transaction.  Attempting to access it after a transaction
        // has ended results in undefined behavior.  This constraint prevents
        // additional data copies and allows support for memory-mapped database
        // implementations.
        FetchBlockRegions(regions []BlockRegion) ([][]byte, error)

        // ******************************************************************
        // Methods related to both atomic metadata storage and block storage.
        // ******************************************************************

        // Commit commits all changes that have been made to the metadata or
        // block storage.  Depending on the backend implementation this could be
        // to a cache that is periodically synced to persistent storage or
        // directly to persistent storage.  In any case, all transactions which
        // are started after the commit finishes will include all changes made
        // by this transaction.  Calling this function on a managed transaction
        // will result in a panic.
        Commit() error

        // Rollback undoes all changes that have been made to the metadata or
        // block storage.  Calling this function on a managed transaction will
        // result in a panic.
        Rollback() error
}

// DB provides a generic interface that is used to store bitcoin blocks and
// related metadata.  This interface is intended to be agnostic to the actual
// mechanism used for backend data storage.  The RegisterDriver function can be
// used to add a new backend data storage method.
//
// This interface is divided into two distinct categories of functionality.
//
// The first category is atomic metadata storage with bucket support.  This is
// accomplished through the use of database transactions.
//
// The second category is generic block storage.  This functionality is
// intentionally separate because the mechanism used for block storage may or
// may not be the same mechanism used for metadata storage.  For example, it is
// often more efficient to store the block data as flat files while the metadata
// is kept in a database.  However, this interface aims to be generic enough to
// support blocks in the database too, if needed by a particular backend.
type DB interface {
        // Type returns the database driver type the current database instance
        // was created with.
        Type() string

        // Begin starts a transaction which is either read-only or read-write
        // depending on the specified flag.  Multiple read-only transactions
        // can be started simultaneously while only a single read-write
        // transaction can be started at a time.  The call will block when
        // starting a read-write transaction when one is already open.
        //
        // NOTE: The transaction must be closed by calling Rollback or Commit on
        // it when it is no longer needed.  Failure to do so can result in
        // unclaimed memory and/or inablity to close the database due to locks
        // depending on the specific database implementation.
        Begin(writable bool) (Tx, error)

        // View invokes the passed function in the context of a managed
        // read-only transaction.  Any errors returned from the user-supplied
        // function are returned from this function.
        //
        // Calling Rollback or Commit on the transaction passed to the
        // user-supplied function will result in a panic.
        View(fn func(tx Tx) error) error

        // Update invokes the passed function in the context of a managed
        // read-write transaction.  Any errors returned from the user-supplied
        // function will cause the transaction to be rolled back and are
        // returned from this function.  Otherwise, the transaction is committed
        // when the user-supplied function returns a nil error.
        //
        // Calling Rollback or Commit on the transaction passed to the
        // user-supplied function will result in a panic.
        Update(fn func(tx Tx) error) error

        // Close cleanly shuts down the database and syncs all data.  It will
        // block until all database transactions have been finalized (rolled
        // back or committed).
        Close() error
}