database

README

database

![ISC License] (http://img.shields.io/badge/license-ISC-blue.svg)

Package database provides a database interface for CRUD operations on Bitmessage objects. It's derived from and based on btcsuite/btcd/database by Conformal.

Please note that this package is intended to enable bmd to support different database backends and is not something that a client can directly access as only one entity can have the database open at a time (for most database backends), and that entity will be bmd.

Documentation

[] (http://godoc.org/github.com/monetas/bmd/database)

Full go doc style documentation for the project can be viewed online without installing this package by using the GoDoc site here.

You can also view the documentation locally once the package is installed with the godoc tool by running godoc -http=":6060" and pointing your browser to http://localhost:6060/pkg/github.com/monetas/bmd/database

Installation

$ go get github.com/monetas/bmd/database

Examples

Nothing yet.

TODO

• Increase test coverage to 100%
• Implement and test FetchIdentityByAddress and related operations on pubkeys.

License

Package database is licensed under the copyfree ISC License.

Documentation

Overview

Package database provides a database interface for handling Bitmessage objects.

Basic Design

The basic design of this package is to store objects to be propagated separate from the objects that need to persist (pubkeys). The objects to be propagated are periodically deleted as they expire. It uses counters instead of timestamps to keep track of the order that objects were received in. High level operations such as FetchIdentityByAddress are also provided for convenience.

Usage

At the highest level, the use of this packages just requires that you import it, setup a database, insert some data into it, and optionally, query the data back.

Index

• Constants
• Variables
• func AddDBDriver(instance DriverDB)
• func CheckPubKey(pubkey cipher.PubKey) (id *identity.Public, err error)
• func DisableLog()
• func GetLog() btclog.Logger
• func SetLogWriter(w io.Writer, level string) error
• func SupportedDBs() []string
• func UseLogger(logger btclog.Logger)
• type Db
  • func OpenDB(dbtype string, args ...interface{}) (pbdb Db, err error)
• type DriverDB
• type ObjectWithCounter

Constants

const ExpiredCacheTime = -time.Hour * 3

ExpiredCacheTime is how long we store expired objects, just in case.

Variables

var (
	ErrDbClosed          = errors.New("database is closed")
	ErrDuplicateObject   = errors.New("duplicate insert attempted")
	ErrDbDoesNotExist    = errors.New("non-existent database")
	ErrDbUnknownType     = errors.New("non-existent database type")
	ErrExpired           = errors.New("object is expired.")
	ErrNotImplemented    = errors.New("method has not yet been implemented")
	ErrNonexistentObject = errors.New("object doesn't exist in database")
)

Errors that the various database functions may return.

Functions

func AddDBDriver

func AddDBDriver(instance DriverDB)

AddDBDriver adds a back end database driver to available interfaces.

func CheckPubKey

func CheckPubKey(pubkey cipher.PubKey) (id *identity.Public, err error)

CheckPubKey is used to check

func DisableLog

func DisableLog()

DisableLog disables all library log output. Logging output is disabled by default until either UseLogger or SetLogWriter are called.

func GetLog

func GetLog() btclog.Logger

GetLog returns the currently active logger.

func SetLogWriter

func SetLogWriter(w io.Writer, level string) error

SetLogWriter uses a specified io.Writer to output package logging info. This allows a caller to direct package logging output without needing a dependency on seelog. If the caller is also using btclog, UseLogger should be used instead.

func SupportedDBs

func SupportedDBs() []string

SupportedDBs returns a slice of strings that represent the database drivers that have been registered and are therefore supported.

func UseLogger

func UseLogger(logger btclog.Logger)

UseLogger uses a specified Logger to output package logging info. This should be used in preference to SetLogWriter if the caller is also using btclog.

Types

type Db

type Db interface {
	// Close cleanly shuts down the database and syncs all data.
	Close() error

	// ExistsObject returns whether or not an object with the given inventory
	// hash exists in the database.
	ExistsObject(*wire.ShaHash) (bool, error)

	// FetchObjectByHash returns an object from the database as a wire.MsgObject.
	FetchObjectByHash(*wire.ShaHash) (obj.Object, error)

	// FetchObjectByCounter returns the corresponding object based on the
	// counter. Note that each object type has a different counter, with unknown
	// objects being consolidated into one counter. Counters are meant for use
	// as a convenience method for fetching new data from database since last
	// check.
	FetchObjectByCounter(wire.ObjectType, uint64) (obj.Object, error)

	// FetchObjectsFromCounter returns a slice of `count' objects which have a
	// counter position starting from `counter'. It also returns the counter
	// value of the last object, which could be useful for more queries to the
	// function.
	FetchObjectsFromCounter(objType wire.ObjectType, counter uint64,
		count uint64) ([]ObjectWithCounter, uint64, error)

	// FetchIdentityByAddress returns identity.Public stored in the form
	// of a PubKey message in the pubkey database.
	FetchIdentityByAddress(*bmutil.Address) (*identity.Public, error)

	// FetchRandomInvHashes returns at most the specified number of
	// inventory hashes corresponding to random unexpired objects from
	// the database. It does not guarantee that the number of returned
	// inventory vectors would be `count'.
	FetchRandomInvHashes(count uint64) ([]*wire.InvVect, error)

	// GetCounter returns the highest value of counter that exists for objects
	// of the given type.
	GetCounter(wire.ObjectType) (uint64, error)

	// InsertObject inserts the given object into the database and returns the
	// counter position. If the object is a PubKey, it inserts it into a
	// separate place where it isn't touched by RemoveObject or
	// RemoveExpiredObjects and has to be removed using RemovePubKey.
	InsertObject(obj.Object) (uint64, error)

	// RemoveObject removes the object with the specified hash from the
	// database. Does not remove PubKeys.
	RemoveObject(*wire.ShaHash) error

	// RemoveObjectByCounter removes the object with the specified counter value
	// from the database.
	RemoveObjectByCounter(wire.ObjectType, uint64) error

	// RemoveExpiredObjects prunes all objects in the main circulation store
	// whose expiry time has passed (along with a margin of 3 hours). This does
	// not touch the pubkeys stored in the public key collection.
	RemoveExpiredObjects() ([]*wire.ShaHash, error)

	// RemoveEncryptedPubKey removes a v4 PubKey with the specified tag from the
	// encrypted PubKey store. Note that it doesn't touch the general object
	// store and won't remove the public key from there.
	RemoveEncryptedPubKey(*wire.ShaHash) error

	// RemovePublicIdentity removes the public identity corresponding the given
	// address from the database. This includes any v2/v3/previously used v4
	// identities. Note that it doesn't touch the general object store and won't
	// remove the public key object from there.
	RemovePublicIdentity(*bmutil.Address) error
}

Db defines a generic interface that is used to request and insert data into the database. This interface is intended to be agnostic to actual mechanism used for backend data storage. The AddDBDriver function can be used to add a new backend data storage method.

func OpenDB

func OpenDB(dbtype string, args ...interface{}) (pbdb Db, err error)

OpenDB opens a database, initializing it if necessary.

type DriverDB

type DriverDB struct {
	DbType string
	OpenDB func(args ...interface{}) (pbdb Db, err error)
}

DriverDB defines a structure for backend drivers to use when they registered themselves as a backend which implements the Db interface.

type ObjectWithCounter

type ObjectWithCounter struct {
	Counter uint64
	Object  obj.Object
}

ObjectWithCounter is a struct to couple an object message with its counter value. It's returned by FetchObjectsFromCounter.