database

type Batch interface {
	Putter
	Deleter
	ValueSize() int // amount of data in the batch
	Write() error
	// Reset resets the batch for reuse
	Reset()
}

type BlockKey [BlockKeyLength]byte

type BlockRegion struct {
	Key    *BlockKey
	Offset uint32
	Len    uint32
}

type BlockType byte

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
}

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
}

type Database interface {
	Type() string

	Putter
	Deleter
	Queryer

	Transactor

	NewBatch() Batch
}

type Deleter interface {
	Delete(key []byte) error
}

type Error struct {
	ErrorCode   ErrorCode // Describes the kind of error
	Description string    // Human readable description of the issue
	Err         error     // Underlying error
}

type ErrorCode int

type Putter interface {
	Put(key []byte, value []byte) error
}

type Queryer interface {
	Get(key []byte) ([]byte, error)
	Has(key []byte) (bool, error)
}

type Transactor interface {
	Begin(writable bool) (Tx, error)
	View(fn func(tx Tx) error) error
	Update(fn func(tx Tx) error) error
	Close() error
}

type Tx interface {
	// 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 key 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(blockKey *BlockKey, blockBytes []byte) error

	// HasBlock returns whether or not a block with the given key 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(key *BlockKey) (bool, error)

	// HasBlocks returns whether or not the blocks with the provided keys
	// 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(keys []BlockKey) ([]bool, error)

	// FetchBlockHeader returns the raw serialized bytes for the block
	// header identified by the given key.  The raw bytes are in the format
	// returned by Serialize on a protos.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 key 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(key *BlockKey) ([]byte, error)

	// FetchBlockHeaders returns the raw serialized bytes for the block
	// headers identified by the given keys.  The raw bytes are in the
	// format returned by Serialize on a protos.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 keys 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(keys []BlockKey) ([][]byte, error)

	// FetchBlock returns the raw serialized bytes for the block identified
	// by the given key.  The raw bytes are in the format returned by
	// Serialize on a protos.MsgBlock.
	//
	// The interface contract guarantees at least the following errors will
	// be returned (other implementation-specific errors are possible):
	//   - ErrBlockNotFound if the requested block key 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(key *BlockKey) ([]byte, error)

	// FetchBlocks returns the raw serialized bytes for the blocks
	// identified by the given keys.  The raw bytes are in the format
	// returned by Serialize on a protos.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 keys 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(keys []BlockKey) ([][]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
	// protos.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 key 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
	// protos.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 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)

	// Metadata returns the top-most bucket for all metadata storage.
	Metadata() Bucket

	// 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
}