db

package
v1.1.5 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Mar 2, 2022 License: MIT Imports: 40 Imported by: 30

README

DB

DB is a json-document database backed by Threads V2.

This document describes its public API, and its internal design/architecture. Internal understanding isn't necessary to use DB, but will help understand how things are wired. Creating a DB under the default configuration will automatically build everything required to work.

Currently, a DB is backed by a single Thread. In the future, this can change making the DB map different Collections to different Threads, or any other combination.

Usage

ToDo: Describe public API here.

Internal Design

In this section, there is a high-level overview of internal DB design.

Diagram

The following diagram try to express all components and their relationships and communications:

Design

The above diagram depicts the different components inside a DB. Also, it travels through their relationships caused by a transaction commit. The inverse path, caused by a new event detected in other peer log in the thread, is somewhat similar but in the other direction.

Arrows aren't always synchronous calls, but also channel notifications and other mediums in order to inverse dependency between components. Arrows are conceptual communications.

Collections

Collections are part of DB public-api. Main responsibility: store instances of a user-defined schema.

Collections are json-schemas that describe instance types of the DB. They provide the public API for creating, deleting, updating, and querying instances within this collection. They also provide read/write transactions which have serializable isolation within the DB scope.

Indexes

Collections support indexes for faster queries on schema-defined fields. When registering a new schema (and defining a Collection), a caller may supply a list of field paths to index on. This creates an Index, which can be used to speed up queries at the expense of additional storage and compute on instance creation and updates. For dbs with a small number of instances, it may not be worth the added overhead, so as always avoid optimizing your queries until you need it!

Insertion with indexes costs approximately twice as much as without (depending on the complexity and frequency of a given index), whereas updates are only slightly more costly (almost identical in most cases). Depending on the underlying data distribution, queries can be greater than an order of magnitude faster. This depends on many factors, including the size of the db (i.e., number of instances), the uniqueness of the indexed field, and the complexity of the query. For example, in our benchmark tests using a relatively simple Collection and a relatively small db size (i.e., ~5000 instances), the query speedup for a simple OR-based equality test is ~10x. See db/bench_test.go for details or to run the benchmarks yourself.

EventCodec

This is an internal component not available in the public API. Main responsibility: Transform and apply and encode/decode transaction actions.

EventCodec is an abstraction used to:

  • Transform actions made in a txn, to an array of db.Event that will be dispatcher to be reduced.
  • Encode actions made in a txn to a format.Node which will serve as the next building block for the appended Record in the local peer log.
  • The reverse of last point, when receiving external actions to allow to be dispatched.

For example, if within a collection WriteTxn(), a new instance is created and other was updated, these two action will be sent to the EventCodec to transform them in Events. These Event have a byte payload with the encoded transformation. Currently, the only implementation of EventCodec is a jsonpatcher, which transforms these actions in json-merge/patches, and store them as payloads in events.

These events are also aggregated in a returned format.Node, which is the compatible/analogous information to be used by net.Net to add in the peer own log in the thread associated with the DB. Likewise, EventCodec also do the inverse transformation. Given a format.Node, it transforms its byte payload into actions that will be reduced in the db.

The EventCodec abstraction allows an extensibility point. If instead of a json-patcher we want to encode instance changes as full instance snapshots (i.e: instead of generating the json-patch, let generate the full instance data), we could provide another implementation of the EventCodec to use in the DB.

Similarly, more advanced encodings of JSON-Document changes can be implemented as EventCodec such as JSON-Documents-Delta-CRDTs, or a hybrid json-patch with logical clocks.

Dispatcher

This is an internal component not available in the public API. Main responsibility: Source of truth regarding known db.Events for the DB. Will notify registered parties to let them know about new ones.

Every Event generated in the DB is sent to a Dispatcher when write transactions are committed. The dispatcher is responsible for broadcasting these events to all registered Reducers. A reducer is a party which is interested in knowing about DB events. Currently, the only reducer is the DB itself.

For example, if a particular instance is updated in a Collection, these corresponding actions will be encoded as Event by the EventCodec as mentioned in the last section. These Events will be dispatched to the Dispatcher, which will:

  • Store the new event in durable storage. If the txn made multiple changes, this is done transactionally.
  • Broadcast them to all registered Reducers (which currently is only DB). Reducers will apply those changes for their own interests.

The implications of this design imply that real DB state changes can only happen when the Dispatcher broadcast new db.Events. A Reducer can't distinguish between Events generated locally or externally. External events are the results of net.Net sending new events to the Dispatcher, which means that new Events where detected in other peer logs of the same Thread.

Datastore

This is an internal component not available in the public API. Main responsibility: Delivering durable persistence for data.

Datastore is the underlying persistence of Collection instances and Dispatcher raw Event information. In both cases, their interface is a datastore.TxnDatastore to have txn guarantees.

Local Event Bus

This is an internal component not available in the public API. Main responsibility: Deliver format.Node encoded information of changes done in local committed transactions. Currently, only to SingleThreadAdapter is listening to this bus.

DB Listener

This is part of the public-api. Main responsibility: Notify external actors that the DB changed its state, with details about the change: in which collection, what action (Create, Save, Delete), and wich InstanceID.

Listeners are useful for clients that want to be notified about changes in the DB. Recall that DB state can change by external events, such as receiving external changes from other peers sharing the DB.

The client can configure which kind of events wants to be notified. Can add any number of criterias; if more than one criteria is used they will be interpreted as OR conditions. A criteria contains the following information:

  • Which collection to listen changes
  • What action is done (Create, Save, Delete)
  • Which InstanceID

Any of the above three attributes can be set empty. For example, we can listen to all changes of all instances in a collection if only the first attribute is set and the other two are left empty/default.

DBThreadAdapter (SingleThreadAdapter, unique implementation)

This is an internal component not available in the public API. Main responsibility: Responsible to be the two-way communication between DB and Threads.

Every time a new local format.Node is generated in the DB due to a write transaction commit, the DBThreadAdapter will notify net.Net that a new Record should be added to the local peer log.

Similarly, when net.Net detects new Records in other peer logs, it will dispatch them to SingleThreadAdapter. Then, it will transform it into a DB Events that will be dispatched to Dispatcher and ultimately will be reduced to impact DB state.

As said initially, currently, the DB is only mapped to a single Thread. But is possible to decide a different map, where a DB might be backed by more than one thread or any other schema. This is the component that should be taking this decisions.

net.Net

This component is part of the public-api so that it can be accessed. Main responsibility: Is the DB interface with Threads layer.

net.Net is the bidirectional communication interface to the underlying Thread backing the DB. It only interacts with DBThreadAdapter

Documentation

Overview

Package db provides a DB which manage collections

Index

Constants

View Source 
const (
	// Eq is "equals"
	Eq = Operation(eq)
	// Ne is "not equal to"
	Ne = Operation(ne)
	// Gt is "greater than"
	Gt = Operation(gt)
	// Lt is "less than"
	Lt = Operation(lt)
	// Ge is "greater than or equal to"
	Ge = Operation(ge)
	// Le is "less than or equal to"
	Le = Operation(le)
)

Variables

View Source 
var (
	// ErrInvalidCollectionSchemaPath indicates path does not resolve to a schema type.
	ErrInvalidCollectionSchemaPath = errors.New("collection schema does not contain path")
	// ErrCollectionNotFound indicates that the specified collection doesn't exist in the db.
	ErrCollectionNotFound = errors.New("collection not found")
	// ErrCollectionAlreadyRegistered indicates a collection with the given name is already registered.
	ErrCollectionAlreadyRegistered = errors.New("collection already registered")
	// ErrInstanceNotFound indicates that the specified instance doesn't exist in the collection.
	ErrInstanceNotFound = errors.New("instance not found")
	// ErrReadonlyTx indicates that no write operations can be done since
	// the current transaction is readonly.
	ErrReadonlyTx = errors.New("read only transaction")
	// ErrInvalidSchemaInstance indicates the current operation is from an
	// instance that doesn't satisfy the collection schema.
	ErrInvalidSchemaInstance = errors.New("instance doesn't correspond to schema")
)
View Source 
var (

	// ErrThreadReadKeyRequired indicates the provided thread key does not contain a read key.
	ErrThreadReadKeyRequired = errors.New("thread read key is required")
	// ErrInvalidName indicates the provided name isn't valid for a Collection.
	ErrInvalidName = errors.New("name may only contain alphanumeric characters or non-consecutive hyphens, " +
		"and cannot begin or end with a hyphen")
	// ErrInvalidCollectionSchema indicates the provided schema isn't valid for a Collection.
	ErrInvalidCollectionSchema = errors.New("the collection schema _id property must be a string")
	// ErrCannotIndexIDField indicates a custom index was specified on the ID field.
	ErrCannotIndexIDField = errors.New("cannot create custom index on " + idFieldName)
)
View Source 
var (
	// ErrUniqueExists indicates an insert resulted in a unique constraint violation.
	ErrUniqueExists = errors.New("unique constraint violation")
	// ErrNotIndexable indicates an index path does not resolve to a value.
	ErrNotIndexable = errors.New("value not indexable")
	// ErrCantCreateUniqueIndex indicates a unique index can't be created because multiple instances share a value at path.
	ErrCantCreateUniqueIndex = errors.New("can't create unique index (duplicate instances exist)")
	// ErrIndexNotFound indicates a requested index was not found.
	ErrIndexNotFound = errors.New("index not found")
)
View Source 
var (
	// ErrDBNotFound indicates that the specified db doesn't exist in the manager.
	ErrDBNotFound = errors.New("db not found")
	// ErrDBExists indicates that the specified db alrady exists in the manager.
	ErrDBExists = errors.New("db already exists")

	// MaxLoadConcurrency is the max number of dbs that will be concurrently loaded when the manager starts.
	MaxLoadConcurrency = 100
)
View Source 
var (
	// ErrInvalidSortingField is returned when a query sorts a result by a
	// non-existent field in the collection schema.
	ErrInvalidSortingField = errors.New("sorting field doesn't correspond to instance type")
)

Functions

func DefaultDecode 

func DefaultDecode(data []byte, value interface{}) error

DefaultDecode is the default decoding func from badgerhold (Gob).

func DefaultEncode 

func DefaultEncode(value interface{}) ([]byte, error)

DefaultEncode is the default encoding func from badgerhold (Gob).

func NewSimpleTx 

func NewSimpleTx(store ds.Datastore) dse.TxnExt

Types

type Action 

type Action struct {
	Collection string
	Type       ActionType
	ID         core.InstanceID
}

type ActionType 

type ActionType int
const (
	ActionCreate ActionType = iota + 1
	ActionSave
	ActionDelete
)

type Collection 

type Collection struct {
	sync.Mutex
	// contains filtered or unexported fields
}

Collection is a group of instances sharing a schema. Collections are like RDBMS tables. They can only exist in a single database.

func (*Collection) Create 

func (c *Collection) Create(v []byte, opts ...TxnOption) (id core.InstanceID, err error)

Create creates an instance in the collection.

func (*Collection) CreateMany added in v0.1.13 

func (c *Collection) CreateMany(vs [][]byte, opts ...TxnOption) (ids []core.InstanceID, err error)

CreateMany creates multiple instances in the collection.

func (*Collection) Delete 

func (c *Collection) Delete(id core.InstanceID, opts ...TxnOption) error

Delete deletes an instance by its ID. It doesn't fail if the ID doesn't exist.

func (*Collection) DeleteMany added in v0.1.13 

func (c *Collection) DeleteMany(ids []core.InstanceID, opts ...TxnOption) error

DeleteMany deletes multiple instances by ID. It doesn't fail if one of the IDs don't exist.

func (*Collection) Find 

func (c *Collection) Find(q *Query, opts ...TxnOption) (instances [][]byte, err error)

Find executes a Query and returns the result.

func (*Collection) FindByID 

func (c *Collection) FindByID(id core.InstanceID, opts ...TxnOption) (instance []byte, err error)

FindByID finds an instance by its ID. If doesn't exists returns ErrInstanceNotFound.

func (*Collection) GetIndexes added in v0.1.19 

func (c *Collection) GetIndexes() []Index

GetIndexes returns the current indexes.

func (*Collection) GetName added in v0.1.22 

func (c *Collection) GetName() string

GetName returns the collection name.

func (*Collection) GetReadFilter added in v1.0.0 

func (c *Collection) GetReadFilter() []byte

GetReadFilter returns the current collection read filter.

func (*Collection) GetSchema added in v0.1.22 

func (c *Collection) GetSchema() []byte

GetSchema returns the current collection schema.

func (*Collection) GetWriteValidator added in v1.0.0 

func (c *Collection) GetWriteValidator() []byte

GetWriteValidator returns the current collection write validator.

func (*Collection) Has 

func (c *Collection) Has(id core.InstanceID, opts ...TxnOption) (exists bool, err error)

Has returns true if ID exists in the collection, false otherwise.

func (*Collection) HasMany added in v0.1.13 

func (c *Collection) HasMany(ids []core.InstanceID, opts ...TxnOption) (exists bool, err error)

HasMany returns true if all IDs exist in the collection, false otherwise.

func (*Collection) ModifiedSince added in v1.0.1 

func (c *Collection) ModifiedSince(time int64, opts ...TxnOption) (ids []core.InstanceID, err error)

ModifiedSince returns a list of all instances that have been modified (and/or touched) since `time`.

func (*Collection) ReadTxn 

func (c *Collection) ReadTxn(f func(txn *Txn) error, opts ...TxnOption) error

ReadTxn creates an explicit readonly transaction. Any operation that tries to mutate an instance of the collection will ErrReadonlyTx. Provides serializable isolation gurantees.

func (*Collection) Save 

func (c *Collection) Save(v []byte, opts ...TxnOption) error

Save saves changes of an instance in the collection.

func (*Collection) SaveMany added in v0.1.13 

func (c *Collection) SaveMany(vs [][]byte, opts ...TxnOption) error

SaveMany saves changes of multiple instances in the collection.

func (*Collection) Verify added in v1.0.0 

func (c *Collection) Verify(v []byte, opts ...TxnOption) error

Verify verifies changes of an instance in the collection.

func (*Collection) VerifyMany added in v1.0.0 

func (c *Collection) VerifyMany(vs [][]byte, opts ...TxnOption) error

VerifyMany verifies changes of multiple instances in the collection.

func (*Collection) WriteTxn 

func (c *Collection) WriteTxn(f func(txn *Txn) error, opts ...TxnOption) error

WriteTxn creates an explicit write transaction. Provides serializable isolation gurantees.

type CollectionConfig 

type CollectionConfig struct {
	// Name is the name of the collection.
	// Must only contain alphanumeric characters or non-consecutive hyphens, and cannot begin or end with a hyphen.
	Name string
	// Schema is JSON Schema used for instance validation.
	Schema *jsonschema.Schema
	// Indexes is a list of index configurations, which define how instances are indexed.
	Indexes []Index
	// An optional JavaScript (ECMAScript 5.1) function that is used to validate instances on write.
	// The function receives three arguments:
	//   - writer: The multibase-encoded public key identity of the writer.
	//   - event: An object describing the update event (see core.Event).
	//   - instance: The current instance as a JavaScript object before the update event is applied.
	// A "falsy" return value indicates a failed validation (https://developer.mozilla.org/en-US/docs/Glossary/Falsy).
	// Note: Only the function body should be defined here.
	WriteValidator string
	// An optional JavaScript (ECMAScript 5.1) function that is used to filter instances on read.
	// The function receives two arguments:
	//   - reader: The multibase-encoded public key identity of the reader.
	//   - instance: The current instance as a JavaScript object.
	// The function must return a JavaScript object.
	// Most implementation will modify and return the current instance.
	// Note: Only the function body should be defined here.
	ReadFilter string
}

CollectionConfig describes a new Collection.

type Comparer 

type Comparer interface {
	Compare(other interface{}) (int, error)
}

Comparer compares a type against the encoded value in the db. The result should be 0 if current==other, -1 if current < other, and +1 if current > other. If a field in a struct doesn't specify a comparer, then the default comparison is used (convert to string and compare) this interface is already handled for standard Go Types as well as more complex ones such as those in time and big an error is returned if the type cannot be compared The concrete type will always be passedin, not a pointer

type Criterion 

type Criterion struct {
	FieldPath string
	Operation Operation
	Value     Value
	// contains filtered or unexported fields
}

Criterion represents a restriction on a field.

func Where 

func Where(field string) *Criterion

Where starts to create a query condition for a field.

func (*Criterion) Eq 

func (c *Criterion) Eq(value interface{}) *Query

Eq is an equality operator against a field.

func (*Criterion) Ge 

func (c *Criterion) Ge(value interface{}) *Query

Ge is a greater or equal operator against a field.

func (*Criterion) Gt 

func (c *Criterion) Gt(value interface{}) *Query

Gt is a greater operator against a field.

func (*Criterion) Le 

func (c *Criterion) Le(value interface{}) *Query

Le is a less or equal operator against a field.

func (*Criterion) Lt 

func (c *Criterion) Lt(value interface{}) *Query

Lt is a less operation against a field.

func (*Criterion) Ne 

func (c *Criterion) Ne(value interface{}) *Query

Ne is a not equal operator against a field.

func (*Criterion) Validate added in v0.1.15 

func (c *Criterion) Validate() error

Validate validates a single query criterion.

type DB 

type DB struct {
	io.Closer
	// contains filtered or unexported fields
}

DB is the aggregate-root of events and state. External/remote events are dispatched to the DB, and are internally processed to impact collection states. Likewise, local changes in collections registered produce events dispatched externally.

func NewDB 

func NewDB(
	ctx context.Context,
	store kt.TxnDatastoreExtended,
	network app.Net,
	id thread.ID,
	opts ...NewOption,
) (*DB, error)

NewDB creates a new DB, which will *own* ds and dispatcher for internal use. Saying it differently, ds and dispatcher shouldn't be used externally.

func NewDBFromAddr 

func NewDBFromAddr(
	ctx context.Context,
	store kt.TxnDatastoreExtended,
	network app.Net,
	addr ma.Multiaddr,
	key thread.Key,
	opts ...NewOption,
) (*DB, error)

NewDBFromAddr creates a new DB from a thread hosted by another peer at address, which will *own* ds and dispatcher for internal use. Saying it differently, ds and dispatcher shouldn't be used externally.

func (*DB) Close 

func (d *DB) Close() error

func (*DB) DeleteCollection added in v0.1.19 

func (d *DB) DeleteCollection(name string, opts ...Option) error

DeleteCollection deletes collection by name and drops all indexes.

func (*DB) GetCollection 

func (d *DB) GetCollection(name string, opts ...Option) *Collection

GetCollection returns a collection by name.

func (*DB) GetDBInfo added in v0.1.13 

func (d *DB) GetDBInfo(opts ...Option) (info Info, err error)

GetDBInfo returns the addresses and key that can be used to join the DB thread.

func (*DB) HandleNetRecord added in v0.1.13 

func (d *DB) HandleNetRecord(ctx context.Context, rec net.ThreadRecord, key thread.Key) error

func (*DB) ListCollections added in v0.1.22 

func (d *DB) ListCollections(opts ...Option) []*Collection

ListCollections returns all collections.

func (*DB) Listen 

func (d *DB) Listen(los ...ListenOption) (Listener, error)

Listen returns a Listener which notifies about actions applying the defined filters. The DB *won't* wait for slow receivers, so if the channel is full, the action will be dropped.

func (*DB) NewCollection 

func (d *DB) NewCollection(config CollectionConfig, opts ...Option) (*Collection, error)

NewCollection creates a new db collection with config.

func (*DB) Reduce 

func (d *DB) Reduce(events []core.Event) error

func (*DB) UpdateCollection added in v0.1.19 

func (d *DB) UpdateCollection(config CollectionConfig, opts ...Option) (*Collection, error)

UpdateCollection updates an existing db collection with a new config. Indexes to new paths will be created. Indexes to removed paths will be dropped.

func (*DB) ValidateNetRecordBody added in v1.0.0 

func (d *DB) ValidateNetRecordBody(_ context.Context, body format.Node, identity thread.PubKey) error

type DecodeFunc 

type DecodeFunc func(data []byte, value interface{}) error

DecodeFunc is a function for decoding a value from bytes.

type EncodeFunc 

type EncodeFunc func(value interface{}) ([]byte, error)

EncodeFunc is a function for encoding a value into bytes.

type Index 

type Index struct {
	// Path to the field to index in dot syntax, e.g., "name.last" or "age".
	Path string `json:"path"`
	// Unique indicates that only one instance should exist per field value.
	Unique bool `json:"unique,omitempty"`
}

Index defines an index.

type Info added in v1.0.0 

type Info struct {
	Name  string
	Addrs []ma.Multiaddr
	Key   thread.Key
}

Info wraps info about a db.

type ListenActionType 

type ListenActionType int
const (
	ListenAll ListenActionType = iota
	ListenCreate
	ListenSave
	ListenDelete
)

type ListenOption 

type ListenOption struct {
	Type       ListenActionType
	Collection string
	ID         core.InstanceID
}

type Listener 

type Listener interface {
	Channel() <-chan Action
	Close()
}

type ManagedOption added in v0.1.19 

type ManagedOption func(*ManagedOptions)

ManagedOption specifies a managed db option.

func WithManagedToken added in v0.1.19 

func WithManagedToken(t thread.Token) ManagedOption

WithManagedToken provides authorization for interacting with a managed db.

type ManagedOptions added in v0.1.19 

type ManagedOptions struct {
	Token thread.Token
}

ManagedOptions defines options for interacting with a managed db.

type Manager 

type Manager struct {
	io.Closer
	// contains filtered or unexported fields
}

func NewManager 

func NewManager(store kt.TxnDatastoreExtended, network app.Net, opts ...NewOption) (*Manager, error)

NewManager hydrates and starts dbs from prefixes.

func (*Manager) Close 

func (m *Manager) Close() error

Close all dbs.

func (*Manager) DeleteDB added in v0.1.13 

func (m *Manager) DeleteDB(ctx context.Context, id thread.ID, opts ...ManagedOption) error

DeleteDB deletes a db by id.

func (*Manager) GetDB 

func (m *Manager) GetDB(ctx context.Context, id thread.ID, opts ...ManagedOption) (*DB, error)

GetDB returns a db by id.

func (*Manager) GetToken added in v0.1.13 

func (m *Manager) GetToken(ctx context.Context, identity thread.Identity) (thread.Token, error)

GetToken provides access to thread network tokens.

func (*Manager) ListDBs added in v0.1.19 

func (m *Manager) ListDBs(ctx context.Context, opts ...ManagedOption) (map[thread.ID]*DB, error)

ListDBs returns a list of all dbs.

func (*Manager) Net 

func (m *Manager) Net() net.Net

Net returns the manager's thread network.

func (*Manager) NewDB 

func (m *Manager) NewDB(ctx context.Context, id thread.ID, opts ...NewManagedOption) (*DB, error)

NewDB creates a new db and prefixes its datastore with base key.

func (*Manager) NewDBFromAddr 

func (m *Manager) NewDBFromAddr(
	ctx context.Context,
	addr ma.Multiaddr,
	key thread.Key,
	opts ...NewManagedOption,
) (*DB, error)

NewDBFromAddr creates a new db from address and prefixes its datastore with base key. Unlike NewDB, this method takes a list of collections added to the original db that should also be added to this host.

type MarshaledResult 

type MarshaledResult struct {
	query.Result
	MarshaledValue map[string]interface{}
}

type MatchFunc 

type MatchFunc func(value interface{}) (bool, error)

MatchFunc is a function used to test an arbitrary matching value in a query

type NewManagedOption added in v0.1.19 

type NewManagedOption func(*NewManagedOptions)

NewManagedOption specifies a new managed db option.

func WithNewManagedBackfillBlock added in v0.1.22 

func WithNewManagedBackfillBlock(block bool) NewManagedOption

WithNewBackfillBlock makes the caller of NewDBFromAddr block until the underlying thread is completely backfilled. Without this, NewDBFromAddr returns immediately and thread backfilling happens in the background.

func WithNewManagedCollections added in v0.1.19 

func WithNewManagedCollections(cs ...CollectionConfig) NewManagedOption

WithNewManagedCollections is used to specify collections that will be created in a managed db.

func WithNewManagedKey added in v1.0.2 

func WithNewManagedKey(key thread.Key) NewManagedOption

WithNewManagedKey provides control over thread keys to use with a managed db.

func WithNewManagedLogKey added in v1.0.0 

func WithNewManagedLogKey(key crypto.Key) NewManagedOption

WithNewManagedLogKey is the public or private key used to write log records. If this is just a public key, the service itself won't be able to create records. In other words, all records must be pre-created and added with AddRecord. If no log key is provided, one will be created internally.

func WithNewManagedName added in v0.1.19 

func WithNewManagedName(name string) NewManagedOption

WithNewManagedName assigns a name to a new managed db.

func WithNewManagedToken added in v0.1.19 

func WithNewManagedToken(t thread.Token) NewManagedOption

WithNewManagedToken provides authorization for creating a new managed db.

type NewManagedOptions added in v0.1.19 

type NewManagedOptions struct {
	Name        string
	Key         thread.Key
	LogKey      crypto.Key
	Token       thread.Token
	Collections []CollectionConfig
	Block       bool
}

NewManagedOptions defines options for creating a new managed db.

type NewOption added in v0.1.19 

type NewOption func(*NewOptions)

NewOption specifies a new db option.

func WithNewBackfillBlock added in v0.1.22 

func WithNewBackfillBlock(block bool) NewOption

WithNewBackfillBlock makes the caller of NewDBFromAddr block until the underlying thread is completely backfilled. Without this, NewDBFromAddr returns immediately and thread backfilling happens in the background.

func WithNewCollections added in v0.1.19 

func WithNewCollections(cs ...CollectionConfig) NewOption

WithNewCollections is used to specify collections that will be created.

func WithNewDebug added in v0.1.19 

func WithNewDebug(enable bool) NewOption

WithNewDebug indicate to output debug information.

func WithNewEventCodec added in v0.1.19 

func WithNewEventCodec(ec core.EventCodec) NewOption

WithNewEventCodec configure to use ec as the EventCodec for transforming actions in events, and viceversa.

func WithNewKey added in v1.0.2 

func WithNewKey(key thread.Key) NewOption

WithNewKey provides control over thread keys to use with a db.

func WithNewLogKey added in v1.0.0 

func WithNewLogKey(key crypto.Key) NewOption

WithNewLogKey is the public or private key used to write log records. If this is just a public key, the service itself won't be able to create records. In other words, all records must be pre-created and added with AddRecord. If no log key is provided, one will be created internally.

func WithNewName added in v0.1.19 

func WithNewName(name string) NewOption

WithNewName sets the db name.

func WithNewToken added in v0.1.19 

func WithNewToken(t thread.Token) NewOption

WithNewToken provides authorization for interacting with a db.

type NewOptions added in v0.1.19 

type NewOptions struct {
	Name        string
	Key         thread.Key
	LogKey      crypto.Key
	Collections []CollectionConfig
	Block       bool
	EventCodec  core.EventCodec
	Token       thread.Token
	Debug       bool
}

NewOptions defines options for creating a new db.

type Operation added in v0.1.13 

type Operation int

Operation models comparison operators.

type Option 

type Option func(*Options)

Option specifies a db option.

func WithToken added in v0.1.19 

func WithToken(t thread.Token) Option

WithToken provides authorization for interacting with a db.

type Options added in v0.1.19 

type Options struct {
	Token thread.Token
}

Options defines options for interacting with a db.

type Query 

type Query struct {
	Ands  []*Criterion
	Ors   []*Query
	Sort  Sort
	Seek  core.InstanceID
	Limit int
	Skip  int
	Index string
}

Query is a json-seriable query representation.

func OrderBy 

func OrderBy(field string) *Query

OrderBy specifies ascending order for the query results.

func OrderByDesc 

func OrderByDesc(field string) *Query

OrderByDesc specifies descending order for the query results.

func OrderByID added in v1.0.0 

func OrderByID() *Query

OrderByID specifies ascending ID order for the query results.

func OrderByIDDesc added in v1.0.0 

func OrderByIDDesc() *Query

OrderByIDDesc specifies descending ID order for the query results.

func (*Query) And 

func (q *Query) And(field string) *Criterion

And concatenates a new condition in an existing field.

func (*Query) LimitTo added in v1.0.0 

func (q *Query) LimitTo(limit int) *Query

LimitTo sets the maximum number of results.

func (*Query) Or 

func (q *Query) Or(orQuery *Query) *Query

Or concatenates a new condition that is sufficient for an instance to satisfy, independant of the current Query. Has left-associativity as: (a And b) Or c

func (*Query) OrderBy 

func (q *Query) OrderBy(field string) *Query

OrderBy specifies ascending order for the query results. On multiple calls, only the last one is considered.

func (*Query) OrderByDesc 

func (q *Query) OrderByDesc(field string) *Query

OrderByDesc specifies descending order for the query results. On multiple calls, only the last one is considered.

func (*Query) OrderByID added in v1.0.0 

func (q *Query) OrderByID() *Query

OrderByID specifies ascending ID order for the query results. On multiple calls, only the last one is considered.

func (*Query) OrderByIDDesc added in v1.0.0 

func (q *Query) OrderByIDDesc() *Query

OrderByIDDesc specifies descending ID order for the query results. On multiple calls, only the last one is considered.

func (*Query) SeekID added in v1.0.0 

func (q *Query) SeekID(id core.InstanceID) *Query

SeekID seeks to the given ID before returning query results.

func (*Query) SkipNum added in v1.0.0 

func (q *Query) SkipNum(num int) *Query

SkipNum skips the given number of results.

func (*Query) UseIndex added in v0.1.13 

func (q *Query) UseIndex(path string) *Query

UseIndex specifies the index to use when running this query.

func (*Query) Validate added in v0.1.15 

func (q *Query) Validate() error

Validate validates en entire query.

type Reducer 

type Reducer interface {
	Reduce(events []core.Event) error
}

Reducer applies an event to an existing state.

type SimpleTx 

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

SimpleTx implements the transaction interface for datastores who do not have any sort of underlying transactional support.

func (*SimpleTx) Commit 

func (bt *SimpleTx) Commit() error

func (*SimpleTx) Delete 

func (bt *SimpleTx) Delete(key ds.Key) error

func (*SimpleTx) Discard 

func (bt *SimpleTx) Discard()

func (*SimpleTx) Get 

func (bt *SimpleTx) Get(k ds.Key) ([]byte, error)

func (*SimpleTx) GetSize 

func (bt *SimpleTx) GetSize(k ds.Key) (int, error)

func (*SimpleTx) Has 

func (bt *SimpleTx) Has(k ds.Key) (bool, error)

func (*SimpleTx) Put 

func (bt *SimpleTx) Put(key ds.Key, val []byte) error

func (*SimpleTx) Query 

func (bt *SimpleTx) Query(q query.Query) (query.Results, error)

func (*SimpleTx) QueryExtended added in v1.1.0 

func (bt *SimpleTx) QueryExtended(q dse.QueryExt) (query.Results, error)

type Sort added in v0.1.13 

type Sort struct {
	FieldPath string
	Desc      bool
}

Sort represents a sort order on a field.

type Txn 

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

Txn represents a read/write transaction in the db. It allows for serializable isolation level within the db.

func (*Txn) Commit 

func (t *Txn) Commit() error

Commit applies all changes done in the current transaction to the collection. This is a syncrhonous call so changes can be assumed to be applied on function return.

func (*Txn) Create 

func (t *Txn) Create(new ...[]byte) ([]core.InstanceID, error)

Create creates new instances in the collection If the ID value on the instance is nil or otherwise a null value (e.g., ""), and ID is generated and used to store the instance.

func (*Txn) Delete 

func (t *Txn) Delete(ids ...core.InstanceID) error

Delete deletes instances by ID when the current transaction commits.

func (*Txn) Discard 

func (t *Txn) Discard()

Discard discards all changes done in the current transaction.

func (*Txn) Find 

func (t *Txn) Find(q *Query) ([][]byte, error)

Find queries for instances by Query.

func (*Txn) FindByID 

func (t *Txn) FindByID(id core.InstanceID) ([]byte, error)

FindByID gets an instance by ID in the current txn scope.

func (*Txn) Has 

func (t *Txn) Has(ids ...core.InstanceID) (bool, error)

Has returns true if all IDs exists in the collection, false otherwise.

func (*Txn) ModifiedSince added in v1.1.0 

func (t *Txn) ModifiedSince(time int64) (ids []core.InstanceID, err error)

ModifiedSince returns a list of all instances that have been modified (and/or touched) since `time`. The _mod field tracks modified instances, but not those that have been deleted, so we need to query the dispatcher for all (unique) instances in this collection that have been modified at all since `time`.

func (*Txn) RefreshCollection added in v1.0.0 

func (t *Txn) RefreshCollection() error

RefreshCollection updates the transaction's collection reference from the master db map, which may have received updates while the transaction is open.

func (*Txn) Save 

func (t *Txn) Save(updated ...[]byte) error

Save saves an instance changes to be committed when the current transaction commits.

func (*Txn) Verify added in v1.0.0 

func (t *Txn) Verify(updated ...[]byte) error

Verify verifies updated instances but does not save them.

type TxnMapDatastore added in v1.1.0 

type TxnMapDatastore struct {
	*ds.MapDatastore
	// contains filtered or unexported fields
}

func NewTxMapDatastore 

func NewTxMapDatastore() *TxnMapDatastore

func (*TxnMapDatastore) NewTransaction added in v1.1.0 

func (d *TxnMapDatastore) NewTransaction(_ bool) (ds.Txn, error)

func (*TxnMapDatastore) NewTransactionExtended added in v1.1.0 

func (d *TxnMapDatastore) NewTransactionExtended(_ bool) (dse.TxnExt, error)

func (*TxnMapDatastore) QueryExtended added in v1.1.0 

func (d *TxnMapDatastore) QueryExtended(q dse.QueryExt) (query.Results, error)

type TxnOption added in v0.1.13 

type TxnOption func(*TxnOptions)

TxnOption specifies a transaction option.

func WithTxnToken added in v0.1.13 

func WithTxnToken(t thread.Token) TxnOption

WithTxnToken provides authorization for the transaction.

type TxnOptions added in v0.1.13 

type TxnOptions struct {
	Token thread.Token
}

TxnOptions defines options for a transaction.

type Value added in v0.1.13 

type Value struct {
	String *string
	Bool   *bool
	Float  *float64
}

Value models a single value in JSON.

Source Files

View all Source files

Directories

Path Synopsis

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.