db

package
v0.6.2 Latest Latest
Warning

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

 Go to latest Published: Feb 24, 2024 License: MIT Imports: 7 Imported by: 0

Documentation

Overview

Package db implements a uniform mechanism for interacting with entities and groups on top of a generic key/value store which is used for persistent data.

Index

Constants

This section is empty.

Variables

View Source 
var (
	// ErrUnknownEntity is returned for requests to load an entity
	// that does not exist.
	ErrUnknownEntity = errors.New("the specified entity does not exist")

	// ErrUnknownGroup is returned for requests to load a group
	// that does not exist.
	ErrUnknownGroup = errors.New("the specified group does not exist")

	// ErrUnknownDatabase is returned for an attempt to create a
	// new database that hasn't been registered.
	ErrUnknownDatabase = errors.New("the specified database does not exist")

	// ErrInternalError is used for all other errors that occur
	// within a database implementation.
	ErrInternalError = errors.New("the database has encountered an internal error")

	// ErrBadSearch is returned when a search request cannot be
	// filled for some reason.
	ErrBadSearch = errors.New("the provided SearchRequest is invalid")

	// ErrNoValue is returned when no value exists for a given key.
	ErrNoValue = errors.New("no value exists")
)

Functions

func RegisterKV added in v0.4.0 

func RegisterKV(name string, factory KVFactory)

RegisterKV registers a KV factory which can be called later.

func SetParentLogger added in v0.3.4 

func SetParentLogger(l hclog.Logger)

SetParentLogger sets the parent logger for this instance.

Types

type Callback added in v0.0.12 

type Callback func(Event)

Callback is a function type registered by an external customer that is interested in some change that might happen in the storage system. These are returned with a DBEvent populated of whether or not the event pertained to an entity or a group, and the relavant primary key.

type DB 

type DB struct {
	*Index
	// contains filtered or unexported fields
}

A DB is a collection of methods satisfying tree.DB, and which read and write data to a KVStore

func New 

func New(backend string) (*DB, error)

New returns a db struct.

func (*DB) Capabilities added in v0.4.0 

func (db *DB) Capabilities() []KVCapability

Capabilities returns a slice of capabilities the backing store supports. This allows higher level abstractions to decide if they want to return errors in certain circumstances, such as this instance not being writeable.

func (*DB) DeleteEntity 

func (db *DB) DeleteEntity(ctx context.Context, ID string) error

DeleteEntity tries to delete an entity that already exists.

func (*DB) DeleteGroup 

func (db *DB) DeleteGroup(ctx context.Context, ID string) error

DeleteGroup tries to delete an group that already exists.

func (*DB) DiscoverEntityIDs 

func (db *DB) DiscoverEntityIDs(ctx context.Context) ([]string, error)

DiscoverEntityIDs searches the keyspace for all entity IDs. All returned strings are loadable entities.

func (*DB) DiscoverGroupNames 

func (db *DB) DiscoverGroupNames(ctx context.Context) ([]string, error)

DiscoverGroupNames searches the keyspace for all group names. All returned strings are loadable groups.

func (*DB) EventUpdateAll added in v0.5.0 

func (db *DB) EventUpdateAll() error

EventUpdateAll fires an event for all entities and all groups with the type set to "Update". This is used to allow the async components that are event driven to pre-load on a server startup and begin monitoring changes after the load completes.

func (*DB) FireEvent added in v0.4.0 

func (db *DB) FireEvent(e Event)

FireEvent fires an event to all callbacks.

func (*DB) LoadEntity 

func (db *DB) LoadEntity(ctx context.Context, ID string) (*types.Entity, error)

LoadEntity retrieves a single entity from the kv store.

func (*DB) LoadGroup 

func (db *DB) LoadGroup(ctx context.Context, ID string) (*types.Group, error)

LoadGroup retrieves a single group from the kv store.

func (*DB) NextEntityNumber added in v0.0.12 

func (db *DB) NextEntityNumber(ctx context.Context) (int32, error)

NextEntityNumber computes and returns the next unnassigned number in the entity space.

func (*DB) NextGroupNumber added in v0.0.12 

func (db *DB) NextGroupNumber(ctx context.Context) (int32, error)

NextGroupNumber computes the next available group number and returns it.

func (*DB) RegisterCallback added in v0.4.0 

func (db *DB) RegisterCallback(name string, c Callback)

RegisterCallback takes a callback name and handle and registers them for later calling.

func (*DB) SaveEntity 

func (db *DB) SaveEntity(ctx context.Context, e *types.Entity) error

SaveEntity writes an entity to the kv store.

func (*DB) SaveGroup 

func (db *DB) SaveGroup(ctx context.Context, g *types.Group) error

SaveGroup writes an group to the kv store.

func (*DB) SearchEntities added in v0.0.12 

func (db *DB) SearchEntities(ctx context.Context, r SearchRequest) ([]*types.Entity, error)

SearchEntities performs a search of all entities using the given query and then batch loads the result.

func (*DB) SearchGroups added in v0.0.12 

func (db *DB) SearchGroups(ctx context.Context, r SearchRequest) ([]*types.Group, error)

SearchGroups performs a search of all groups using the given query and then batch loads the result.

func (*DB) Shutdown added in v0.4.0 

func (db *DB) Shutdown()

Shutdown is called to disconnect the KV store from any other systems and flush any buffers before shutting down the server.

type Event added in v0.0.12 

type Event struct {
	Type EventType
	PK   string
}

Event is a type of message that can be fed to callbacks describing the event and the key of the thing that happened.

func (*Event) IsEmpty added in v0.3.0 

func (e *Event) IsEmpty() bool

IsEmpty is used to test for an empty event being returned.

type EventType added in v0.3.0 

type EventType int

An EventType is used to specify what kind of event has happened and is constrained for consumption in downstream select cases. As these IDs are entirely internal and are maintained within a compiled version, iota is used here to make it easier to patch this list in the future. 

const (
	EventEntityCreate EventType = iota
	EventEntityUpdate
	EventEntityDestroy

	EventGroupCreate
	EventGroupUpdate
	EventGroupDestroy
)

The callbacks defined below are used to signal what events are handled by the Event subsystem.

type Index added in v0.4.0 

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

Index holds the methods to search entities and groups with blevesearch. This is meant to be embedded into a db implementation to transparently give it the search functions.

func NewIndex added in v0.4.0 

func NewIndex(l hclog.Logger) *Index

NewIndex returns a new SearchIndex with the mappings configured and ready to use. Mappings are statically defined for simplicity, and in general new mappings shouldn't be added without a very good reason.

func (*Index) ConfigureCallback added in v0.4.0 

func (s *Index) ConfigureCallback(el loadEntityFunc, gl loadGroupFunc)

ConfigureCallback is used to set the references to the loaders which are later used by the callback to fetch entities and groups for indexing.

func (*Index) DeleteEntity added in v0.4.0 

func (s *Index) DeleteEntity(e *pb.Entity) error

DeleteEntity removes an entity from the index

func (*Index) DeleteGroup added in v0.4.0 

func (s *Index) DeleteGroup(g *pb.Group) error

DeleteGroup removes a group from the index.

func (*Index) IndexCallback added in v0.4.0 

func (s *Index) IndexCallback(e Event)

IndexCallback is meant to be plugged into the event system and is subsequently capable of maintaining the index based on events being fired during save and as files change on disk.

func (*Index) IndexEntity added in v0.4.0 

func (s *Index) IndexEntity(e *pb.Entity) error

IndexEntity adds or updates an entity in the index.

func (*Index) IndexGroup added in v0.4.0 

func (s *Index) IndexGroup(g *pb.Group) error

IndexGroup adds or updates a group in the index.

func (*Index) SearchEntities added in v0.4.0 

func (s *Index) SearchEntities(r SearchRequest) ([]string, error)

SearchEntities searches the index for entities matching the qualities specified in the request.

func (*Index) SearchGroups added in v0.4.0 

func (s *Index) SearchGroups(r SearchRequest) ([]string, error)

SearchGroups searches the index for groups matching the qualities specified in the request.

type KVCapability added in v0.4.0 

type KVCapability int

A KVCapability is a specific property that a KV Store might have. It allows stores to express things like supporting HA access. 

const (
	// KVMutable signifies that the key/value store is able to
	// accept mutable queries.  Note that sending a mutation to a
	// KV that does not advertise this capability does not
	// necessarily mean that the KV isn't mutable, only that it
	// would prefer you not.
	KVMutable KVCapability = iota
)

type KVFactory added in v0.4.0 

type KVFactory func(hclog.Logger) (KVStore, error)

KVFactory returns a KVStore, and is a registeryable function during init to be called later.

type KVStore added in v0.4.0 

type KVStore interface {
	Put(context.Context, string, []byte) error
	Get(context.Context, string) ([]byte, error)
	Del(context.Context, string) error

	Keys(context.Context, string) ([]string, error)
	Close() error

	Capabilities() []KVCapability
	SetEventFunc(func(Event))
}

A KVStore is the backing mechanism that deals with persisting data to somewhere that won't lose it. This can be the disk, a remote blob store, the desk of a particularly trusted employee, etc.

func NewKV added in v0.5.0 

func NewKV(name string, l hclog.Logger) (KVStore, error)

NewKV returns a KV. This is exported to enable usage in nsutil, but should generally not be imported by external consumers.

type SearchRequest added in v0.0.12 

type SearchRequest struct {
	Expression string
}

SearchRequest is an expression that can be interpreted by the default util search system, or translated by a storage layer to provide a more optimized searching experience.

Source Files

View all Source files

Directories

Path Synopsis
Package filesystem implements a key/value store on top of a generic filesystem.
 Package filesystem implements a key/value store on top of a generic filesystem.
Package memory implements a fully in-memory key/value store for the database to use.
 Package memory implements a fully in-memory key/value store for the database to use.

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.