database

Documentation

Index

• func CompareChannels(expected *protoed.Channel, got *protoed.Channel, t *testing.T)
• func Initialize(access Access, path string) (err error)
• type Access
• type Descriptor
  • func DecodeDescriptor(data []byte) Descriptor
  • func (d Descriptor) Encode() []byte
• type Env
  • func NewEnv(access Access, path string) (e *Env, err error)
  • func (e *Env) Close() error
  • func (e *Env) Update(fn func(txn *Txn) error) error
  • func (e *Env) View(fn func(txn *Txn) error) error
• type Timestamp
  • func DecodeTimestamp(data []byte) Timestamp
  • func TimestampFromTime(tm time.Time) Timestamp
  • func (t Timestamp) Encode() []byte
  • func (t Timestamp) ToTime() time.Time
• type Txn
  • func (t *Txn) ChannelPage(page uint, perPage uint) (channels []*protoed.Channel, err error)
  • func (t *Txn) CountChannels() (count uint64, err error)
  • func (t *Txn) CountTimestamps() (count uint64, err error)
  • func (t *Txn) GetChannel(descriptor string) (channel *protoed.Channel, err error)
  • func (t *Txn) GetTimestamp(descriptor string) (Timestamp *Timestamp, err error)
  • func (t *Txn) PutChannel(channel *protoed.Channel) (err error)
  • func (t *Txn) PutTimestamp(descriptor Descriptor, Timestamp *Timestamp) (err error)
  • func (t *Txn) RemoveChannel(descriptor string) (err error)

Functions

func CompareChannels

func CompareChannels(
	expected *protoed.Channel,
	got *protoed.Channel,
	t *testing.T)

CompareChannels runs a deep comparison between two proto Channel messages, raising errors upon differences.

func Initialize

func Initialize(access Access, path string) (err error)

Initialize initializes the database environment in the given directory. Initialize creates the expected database and should be called only once during the deployment.

Types

type Access

type Access int

Access enumerates different access rights for transactions on the database.

const (
	// ControlAccess defines the access rights for the Control server.
	ControlAccess Access = 0
	// RelayAccess defines the access rights for the Relay server.
	RelayAccess Access = 1
)

type Descriptor

type Descriptor string

Descriptor is a key at which data is stored in the database.

func DecodeDescriptor

func DecodeDescriptor(data []byte) Descriptor

DecodeDescriptor decodes an array of bytes to a descriptor.

func (Descriptor) Encode

func (d Descriptor) Encode() []byte

Encode encodes the descriptor to an array of bytes.

type Env

type Env struct {
	Path string

	Access Access
	// contains filtered or unexported fields
}

Env represents a database of channels.

func NewEnv

func NewEnv(access Access, path string) (e *Env, err error)

NewEnv creates a new database environment object. The database directory is assumed to be already initialized.

func (*Env) Close

func (e *Env) Close() error

Close closes the database.

func (*Env) Update

func (e *Env) Update(fn func(txn *Txn) error) error

Update executes a read-write transaction.

func (*Env) View

func (e *Env) View(fn func(txn *Txn) error) error

View executes a read-only transaction.

type Timestamp

type Timestamp uint64

Timestamp is a timestamp expressed as milliseconds from epoch in UTC.

func DecodeTimestamp

func DecodeTimestamp(data []byte) Timestamp

DecodeTimestamp decodes the array of bytes to a timestamp.

func TimestampFromTime

func TimestampFromTime(tm time.Time) Timestamp

TimestampFromTime converts a time.Time to the corresponding timestamp in nanoseconds.

func (Timestamp) Encode

func (t Timestamp) Encode() []byte

Encode encodes the timestamp to an array of bytes.

func (Timestamp) ToTime

func (t Timestamp) ToTime() time.Time

ToTime converts the timestamp to the corresponding time.Time object.

type Txn

type Txn struct {
	// contains filtered or unexported fields
}

Txn represents a transaction over the entries of the database.

func (*Txn) ChannelPage

func (t *Txn) ChannelPage(page uint,
	perPage uint) (channels []*protoed.Channel, err error)

ChannelPage returns the requested `page` of the database entries.

Given the entire database as a list of channels, the elements starting from index `page*perPage` are inserted in the list sequentially until either the list contains `perPage` elements, or there are no more database entries.

If the database has less than `page*perPage` elements, an empty list is returned. ChannelPage requires: * t.access == ControlAccess

ChannelPage ensures: * err != nil || len(channels) <= int(perPage) * err != nil || !dbc.InTest || !(t.mustCountCh() <= uint64((page-1)*perPage) || len(channels) == 0) * err != nil || !dbc.InTest || !(t.mustCountCh() > uint64((page-1)*perPage) || len(channels) > 0) * err != nil || !dbc.InTest || !(t.mustCountCh() >= uint64(page*perPage) || len(channels) == int(perPage))

func (*Txn) CountChannels

func (t *Txn) CountChannels() (count uint64, err error)

CountChannels returns the number of channels in the database.

CountChannels requires: * t.access == ControlAccess || t.access == RelayAccess

CountChannels ensures: * !dbc.InTest || err != nil || t.mustCountTs() <= count

func (*Txn) CountTimestamps

func (t *Txn) CountTimestamps() (count uint64, err error)

CountTimestamps returns the number of timestamps in the database.

CountTimestamps requires: * t.access == ControlAccess || t.access == RelayAccess

func (*Txn) GetChannel

func (t *Txn) GetChannel(descriptor string) (channel *protoed.Channel,
	err error)

GetChannel returns the channel associated with the descriptor in the database, if it exists; nil otherwise.

GetChannel requires: * t.access == ControlAccess || t.access == RelayAccess

GetChannel ensures: * err == nil || channel == nil || channel.Descriptor_ == descriptor * count positive if result: !dbc.InTest || !(err == nil && channel != nil) || t.mustCountCh() > 0 * empty response for empty database: !dbc.InTest || !(err == nil && t.mustCountCh() == 0) || channel == nil

func (*Txn) GetTimestamp

func (t *Txn) GetTimestamp(descriptor string) (Timestamp *Timestamp, err error)

GetTimestamp returns the Timestamp associated with the descriptor in the database, if it exists; nil otherwise.

GetTimestamp requires: * t.access == ControlAccess || t.access == RelayAccess

GetTimestamp ensures: * err == nil || Timestamp == nil || *Timestamp > 0 * !dbc.InTest || !(err == nil && Timestamp != nil) || t.mustCountTs() > 0 * empty response for empty database: !dbc.InTest || !(err == nil && t.mustCountTs() == 0) || Timestamp == nil

func (*Txn) PutChannel

func (t *Txn) PutChannel(channel *protoed.Channel) (err error)

PutChannel inserts a channel in the database, keyed on its descriptor.

PutChannel requires: * t.access == ControlAccess * channel != nil

PutChannel preamble:

var oldHas bool
oldCount := uint64(0)
if dbc.InTest {
	oldCount = t.mustCountCh()
	oldHas = t.mustGetCh(channel.Descriptor_) != nil
}

PutChannel ensures: * !dbc.InTest || err != nil || t.mustGetCh(channel.Descriptor_) != nil * !dbc.InTest || err != nil || oldHas || t.mustCountCh() == oldCount+1 * !dbc.InTest || err != nil || !oldHas || t.mustCountCh() == oldCount * !dbc.InTest || err != nil || t.mustGetCh(channel.Descriptor_) == nil || t.mustGetCh(channel.Descriptor_).MinPeriod == channel.MinPeriod || t.mustGetTs(channel.Descriptor_) == nil

func (*Txn) PutTimestamp

func (t *Txn) PutTimestamp(descriptor Descriptor,
	Timestamp *Timestamp) (err error)

PutTimestamp inserts a Timestamp in the database, keyed on its descriptor.

PutTimestamp requires: * !dbc.InTest || t.access == RelayAccess * Timestamp != nil * *Timestamp > 0

PutTimestamp preamble:

var oldHas bool
oldCount := uint64(0)
if dbc.InTest {
	oldCount = t.mustCountTs()
	oldHas = t.mustGetTs(string(descriptor)) != nil
}

PutTimestamp ensures: * !dbc.InTest || err != nil || t.mustGetTs(string(descriptor)) != nil * !dbc.InTest || err != nil || oldHas || t.mustCountTs() == oldCount+1 * !dbc.InTest || err != nil || !oldHas || t.mustCountTs() == oldCount

func (*Txn) RemoveChannel

func (t *Txn) RemoveChannel(descriptor string) (err error)

RemoveChannel removes a channel from the database.

RemoveChannel requires: * t.access == ControlAccess

RemoveChannel preamble:

var oldHasCh, oldHasTs bool
oldCountCh := uint64(0)
oldCountTs := uint64(0)
if dbc.InTest {
	oldCountTs = t.mustCountTs()
	oldCountCh = t.mustCountCh()
	oldHasCh = t.mustGetCh(descriptor) != nil
	oldHasTs = t.mustGetTs(descriptor) != nil
}

RemoveChannel ensures: * !dbc.InTest || err != nil || t.mustGetCh(descriptor) == nil && t.mustGetTs(descriptor) == nil * !dbc.InTest || err != nil || !oldHasCh || t.mustCountCh() == oldCountCh-1 * !dbc.InTest || err != nil || oldHasCh || t.mustCountCh() == oldCountCh * !dbc.InTest || err != nil || !oldHasTs || t.mustCountTs() == oldCountTs-1 * !dbc.InTest || err != nil || oldHasTs || t.mustCountTs() == oldCountTs