shdb

package module
v1.0.1 Latest Latest
Warning

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

 Go to latest Published: Mar 22, 2023 License: Apache-2.0 Imports: 16 Imported by: 0

README

Shdb

A simple database for protobuf based objects

Installing

$ go get github.com/shenrytech/shdb

Example

package main

func main() {
	Init(path.Join(os.TempDir(), "example_query.db"))
	Register(&TObject{
		Metadata: &Metadata{Type: TObj[:]},
		MyField:  "The flying duck is flying low"})

	count := 100
	pageSize := 10

	list := []*TObject{}
	for k := 0; k < count; k++ {
		tObj := MustNew[*TObject](TObj)
		tObj.MyInt = uint64(k)
		list = append(list, tObj)
	}
	if err := Put(list...); err != nil {
		panic(err)
	}

	defer func() {
		Close()
		os.Remove(path.Join(os.TempDir(), "example_query.db"))
	}()

	var (
		nextPageToken string = ""
		partList      []*TObject
		err           error
	)
	ctx := context.Background()

	selectorFn := func(obj *TObject) (bool, error) {
		return strings.Contains(obj.MyField, "flying"), nil
	}
	collected := []*TObject{}
	for {
		partList, nextPageToken, err = Query(ctx, 
            TObj, selectorFn, int32(count/pageSize), nextPageToken)
		if err != nil {
			panic(err)
		}
		collected = append(collected, partList...)
		if nextPageToken == "" {
			break
		}
	}
	for idx, obj := range collected {
		log.Printf("%d: [%v]\n", idx, obj)
	}
}

License

Shdb is released under the Apache 2.0 license. See LICENSE.txt

Documentation

Index

Examples

Constants

View Source 
const (
	InvalidWatchEvent = 0
	EventCreated      = 1
	EventUpdated      = 2
	EventDeleted      = 3
)

Events reflecting life-cycle changes to an object

Variables

View Source 
var (
	ErrNotAnObject      = errors.New("not an object type")
	ErrInvalidType      = errors.New("invalid type")
	ErrNotFound         = errors.New("not found")
	ErrSessionInvalid   = errors.New("session invalid")
	ErrContextCancelled = errors.New("context cancelled")
)
View Source 
var File_shdb_proto protoreflect.FileDescriptor

Functions

func Close 

func Close() error

Close the backing database

func Create 

func Create[T IObject](typeKey TypeKey) (T, error)

Create just creates the memory for an IObject without initializing the Metadata

func Delete 

func Delete[T IObject](tid TypeId) (T, error)

Delete an object from the database based on the type and id. The old value is returned

func Get 

func Get[T IObject](tid TypeId) (T, error)

Get an object from the database based on the type and id of the object.

func GetAll 

func GetAll[T IObject](typeKey TypeKey) ([]T, error)

GetAll returns all objects in database of a specific type

func GetFirst 

func GetFirst[T IObject](typeKey TypeKey, selector func(obj T) bool) (T, error)

GetOne returns one of the objects in the database with the specified type that matches the selector function. The selector should return true for a match and false otherwise when presented with an object.

func GetRef added in v1.0.1 

func GetRef[T IObject](ref *ObjRef) (T, error)

GetRef returns an object from the database based on an ObjRef

func Init 

func Init(dbFile string)

Init initializes the backing database.

func List 

func List[T IObject](ctx context.Context, typ TypeKey, pageSize int32, pageToken string) (result []T, nextPageToken string, err error)

List all objects pertaining to a specific type. For arguments and paging see `Query` method.

func MustNew 

func MustNew[T IObject](typeKey TypeKey) T

MustNew is like `New` but panics if there is an error

func New 

func New[T IObject](typeKey TypeKey) (obj T, err error)

New creates a new IObject based on the type key and initializes the Metadata fields.

func Put 

func Put[T IObject](val ...T) error

Put creates objects in the database. If the object already existed it will be overwritten.

func Query 

func Query[T IObject](ctx context.Context, typ TypeKey, selectFn func(obj T) (bool, error), pageSize int32, pageToken string) (result []T, nextPageToken string, err error)

Query returns all objects of a specific type matching a selector function. Paging of the results is implemented using a pageSize and a token. If there are more results available after pageSize items have been returned a non-empty nextPageToken is returned that can be used to retrieve a new page of results. If nextPageToken is the empty string, no more results are available.

Example 
Init(path.Join(os.TempDir(), "example_query.db"))
Register(&TObject{
	Metadata: &Metadata{Type: TObj[:]},
	MyField:  "The flying duck is flying low"})

count := 100
pageSize := 10

list := []*TObject{}
for k := 0; k < count; k++ {
	tObj := MustNew[*TObject](TObj)
	tObj.MyInt = uint64(k)
	list = append(list, tObj)
}
if err := Put(list...); err != nil {
	panic(err)
}

defer func() {
	Close()
	os.Remove(path.Join(os.TempDir(), "example_query.db"))
}()

var (
	nextPageToken string = ""
	partList      []*TObject
	err           error
)
ctx := context.Background()

selectorFn := func(obj *TObject) (bool, error) {
	return strings.Contains(obj.MyField, "flying"), nil
}
collected := []*TObject{}
for {
	partList, nextPageToken, err = Query(ctx, TObj, selectorFn, int32(count/pageSize), nextPageToken)
	if err != nil {
		panic(err)
	}
	collected = append(collected, partList...)
	if nextPageToken == "" {
		break
	}
}
for idx, obj := range collected {
	log.Printf("%d: [%v]\n", idx, obj)
}

Output:

func Register 

func Register[T IObject](tmpl T)

Register an IObject and it's type in the type table

func RemoveWatcher 

func RemoveWatcher(watcherId string) error

RemoveWatcher closes the eventCh for the watcher and removes the watcher.

func SearchProto 

func SearchProto(m proto.Message, query func(s string) bool) (hits []string, err error)

SearchProto searches within the fields of the proto message forthe string provided. The result will contain a number of hits in the form - /[fieldName|@idx]/... Examples:

  • / - The object contained only one item and it matched
  • /myField - {"myField": <match>}
  • /field1/field2/@3 {"field1": {"field2": [1,2,<match>]}}

func Unmarshal 

func Unmarshal[T IObject](kv KeyVal) (T, error)

Unmarshal returns the IObject from a KeyVal binary representation

func UnmarshalMany 

func UnmarshalMany[T IObject](kvs []KeyVal) ([]T, error)

UnmarshalMany unmarshals a list of KeyVal binary representations

func UnwatchType 

func UnwatchType(watcherId string, typeKeys ...TypeKey) error

UnwatchType removes a list of TypeKeys from a watcher

func UnwatchTypeId 

func UnwatchTypeId(watcherId string, tids ...TypeId) error

UnwatchTypeId removes a list of TypeIds from a watcher

func Update 

func Update[T IObject](tid TypeId, updater func(obj T) (T, error)) (t T, err error)

Update an object in the database by using an updater function. The updated object is returned.

func WatchType 

func WatchType(watcherId string, eventCh chan *EventInfo, typeKeys ...TypeKey) (string, error)

WatchType creates or updates a watcher by adding watches to new TypeKeys If the provided watcherId is the empty string, a new watcher is created and the eventCh must be specified. If watcherId is non-empty, then the eventCh can be set to nil The watcherId is returned.

func WatchTypeId 

func WatchTypeId(watcherId string, eventCh chan *EventInfo, tids ...TypeId) (string, error)

WatchType creates or updates a watcher by adding watches to new TypeIds If the provided watcherId is the empty string, a new watcher is created and the eventCh must be specified. If watcherId is non-empty, then the eventCh can be set to nil The watcherId is returned.

Types

type EventInfo 

type EventInfo struct {
	Kind     int
	Tid      TypeId
	Object   IObject
	Previous IObject
}

EventInfo contains the information about a specific life cycle event

type IObject 

type IObject interface {
	proto.Message
	GetMetadata() *Metadata
}

IObject is the interface for all objects in the dataabase. They all should stem from a protobuf message that looks like this: 

	message TObject {
  		shdb.Metadata metadata = 1;
  		string my_field = 2;
  		uint64 my_int = 3;
	}

type KeyVal 

type KeyVal struct {
	TypeId
	Value []byte
}

KeyVal is the binary representation of an IObject as it is stored in the database

func GetAllKV 

func GetAllKV(typeKey TypeKey) ([]KeyVal, error)

GetAllKV returns all KeyVals of the database.

func Marshal 

func Marshal[T IObject](objs ...T) (ret []KeyVal, err error)

Marshal returns a list of KeyVal binary representation representing a list of IObjects

type Metadata 

type Metadata struct {
	Type        []byte                 `protobuf:"bytes,1,opt,name=type,proto3" json:"type,omitempty"`
	Uuid        []byte                 `protobuf:"bytes,2,opt,name=uuid,proto3" json:"uuid,omitempty"`
	Labels      []string               `protobuf:"bytes,3,rep,name=labels,proto3" json:"labels,omitempty"`
	Description string                 `protobuf:"bytes,4,opt,name=description,proto3" json:"description,omitempty"`
	CreatedAt   *timestamppb.Timestamp `protobuf:"bytes,5,opt,name=created_at,json=createdAt,proto3" json:"created_at,omitempty"`
	UpdatedAt   *timestamppb.Timestamp `protobuf:"bytes,6,opt,name=updated_at,json=updatedAt,proto3" json:"updated_at,omitempty"`
	// contains filtered or unexported fields
}

func (*Metadata) Descriptor deprecated 

func (*Metadata) Descriptor() ([]byte, []int)

Deprecated: Use Metadata.ProtoReflect.Descriptor instead.

func (*Metadata) Fill added in v1.0.1 

func (m *Metadata) Fill() error

Fill the metadata with fields that are missing

func (*Metadata) GetCreatedAt 

func (x *Metadata) GetCreatedAt() *timestamppb.Timestamp

func (*Metadata) GetDescription 

func (x *Metadata) GetDescription() string

func (*Metadata) GetLabels 

func (x *Metadata) GetLabels() []string

func (*Metadata) GetType 

func (x *Metadata) GetType() []byte

func (*Metadata) GetUpdatedAt 

func (x *Metadata) GetUpdatedAt() *timestamppb.Timestamp

func (*Metadata) GetUuid 

func (x *Metadata) GetUuid() []byte

func (*Metadata) GetUuidAsString added in v1.0.1 

func (m *Metadata) GetUuidAsString() (string, error)

GetUuidAsString returns the UUID as a string

func (*Metadata) GetUuidAsUUID added in v1.0.1 

func (m *Metadata) GetUuidAsUUID() (uuid.UUID, error)

GetUuidAsUUID returns the UUID as a uuid.UUID

func (*Metadata) ProtoMessage 

func (*Metadata) ProtoMessage()

func (*Metadata) ProtoReflect 

func (x *Metadata) ProtoReflect() protoreflect.Message

func (*Metadata) Ref added in v1.0.1 

func (m *Metadata) Ref() *ObjRef

Return the Metadata as an *ObjRef

func (*Metadata) Reset 

func (x *Metadata) Reset()

func (*Metadata) String 

func (x *Metadata) String() string

func (*Metadata) TypeId 

func (m *Metadata) TypeId() TypeId

TypeId returns the TypeId representation of the type and Id

type ObjRef added in v1.0.1 

type ObjRef struct {
	Type []byte `protobuf:"bytes,1,opt,name=type,proto3" json:"type,omitempty"`
	Uuid []byte `protobuf:"bytes,2,opt,name=uuid,proto3" json:"uuid,omitempty"`
	// contains filtered or unexported fields
}

func UnmarshalObjRef added in v1.0.1 

func UnmarshalObjRef(data []byte) (*ObjRef, error)

UnmarshalObjRef a byte slice into ObjRef

func (*ObjRef) Descriptor deprecated added in v1.0.1 

func (*ObjRef) Descriptor() ([]byte, []int)

Deprecated: Use ObjRef.ProtoReflect.Descriptor instead.

func (*ObjRef) GetType added in v1.0.1 

func (x *ObjRef) GetType() []byte

func (*ObjRef) GetUuid added in v1.0.1 

func (x *ObjRef) GetUuid() []byte

func (*ObjRef) Marshal added in v1.0.1 

func (r *ObjRef) Marshal() []byte

Marshal an ObjRef to a byte slice

func (*ObjRef) ProtoMessage added in v1.0.1 

func (*ObjRef) ProtoMessage()

func (*ObjRef) ProtoReflect added in v1.0.1 

func (x *ObjRef) ProtoReflect() protoreflect.Message

func (*ObjRef) Reset added in v1.0.1 

func (x *ObjRef) Reset()

func (*ObjRef) String added in v1.0.1 

func (x *ObjRef) String() string

func (*ObjRef) TypeId added in v1.0.1 

func (r *ObjRef) TypeId() *TypeId

TypeId returns the ObjRef as a *TypeId

type SearchHit 

type SearchHit struct {
	Metadata *Metadata `protobuf:"bytes,1,opt,name=metadata,proto3" json:"metadata,omitempty"`
	Hits     []string  `protobuf:"bytes,2,rep,name=hits,proto3" json:"hits,omitempty"`
	// contains filtered or unexported fields
}

func (*SearchHit) Descriptor deprecated 

func (*SearchHit) Descriptor() ([]byte, []int)

Deprecated: Use SearchHit.ProtoReflect.Descriptor instead.

func (*SearchHit) GetHits 

func (x *SearchHit) GetHits() []string

func (*SearchHit) GetMetadata 

func (x *SearchHit) GetMetadata() *Metadata

func (*SearchHit) ProtoMessage 

func (*SearchHit) ProtoMessage()

func (*SearchHit) ProtoReflect 

func (x *SearchHit) ProtoReflect() protoreflect.Message

func (*SearchHit) Reset 

func (x *SearchHit) Reset()

func (*SearchHit) String 

func (x *SearchHit) String() string

type SearchResult 

type SearchResult struct {
	Hits []*SearchHit `protobuf:"bytes,1,rep,name=hits,proto3" json:"hits,omitempty"`
	// contains filtered or unexported fields
}
func Search(ctx context.Context,
	typ TypeKey,
	selector func(string) bool,
	pageSize int32,
	pageToken string) (result *SearchResult, nextPageToken string, err error)

Search searches the values of the fields of objects pertaining to a type by calling a selector function for each field in all objects. For paging functionality see `Query` method.

func (*SearchResult) Descriptor deprecated 

func (*SearchResult) Descriptor() ([]byte, []int)

Deprecated: Use SearchResult.ProtoReflect.Descriptor instead.

func (*SearchResult) GetHits 

func (x *SearchResult) GetHits() []*SearchHit

func (*SearchResult) ProtoMessage 

func (*SearchResult) ProtoMessage()

func (*SearchResult) ProtoReflect 

func (x *SearchResult) ProtoReflect() protoreflect.Message

func (*SearchResult) Reset 

func (x *SearchResult) Reset()

func (*SearchResult) String 

func (x *SearchResult) String() string

type TObject 

type TObject struct {
	Metadata *Metadata `protobuf:"bytes,1,opt,name=metadata,proto3" json:"metadata,omitempty"`
	MyField  string    `protobuf:"bytes,2,opt,name=my_field,json=myField,proto3" json:"my_field,omitempty"`
	MyInt    uint64    `protobuf:"varint,3,opt,name=my_int,json=myInt,proto3" json:"my_int,omitempty"`
	// contains filtered or unexported fields
}

func (*TObject) Descriptor deprecated 

func (*TObject) Descriptor() ([]byte, []int)

Deprecated: Use TObject.ProtoReflect.Descriptor instead.

func (*TObject) GetMetadata 

func (x *TObject) GetMetadata() *Metadata

func (*TObject) GetMyField 

func (x *TObject) GetMyField() string

func (*TObject) GetMyInt 

func (x *TObject) GetMyInt() uint64

func (*TObject) ProtoMessage 

func (*TObject) ProtoMessage()

func (*TObject) ProtoReflect 

func (x *TObject) ProtoReflect() protoreflect.Message

func (*TObject) Reset 

func (x *TObject) Reset()

func (*TObject) String 

func (x *TObject) String() string

type TypeId 

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

TypeId is the key in the key-value database that is used to store IObjects. It has a memory layout like: 

[b0 .. b3]		TypeKey
[b4 .. b20]		Binary representation of an UUID

func GetTypeId 

func GetTypeId(obj IObject) *TypeId

GetTypeId returns the TypeID from the Metadata of an IObject

func MarshalTypeId 

func MarshalTypeId(key []byte) *TypeId

MarshalTypeId creates a TypeId from a []byte slice

func NewTypeId 

func NewTypeId(typeKey TypeKey, id []byte) *TypeId

NewTypeId creates a new TypeId based on TypeKey and UUID (Byte version)

func TypeIdFromString 

func TypeIdFromString(str string) (*TypeId, error)

TypeIdFromString returns a TypeId from an URL-encoded string

func (*TypeId) Equal 

func (k *TypeId) Equal(other *TypeId) bool

Equal compares two TypeIds and return true if they are equal

func (*TypeId) Key 

func (k *TypeId) Key() []byte

Key returns the TypeId as a []byte slice

func (*TypeId) SetType 

func (k *TypeId) SetType(keyType TypeKey)

SetType sets the type of a TypeId

func (*TypeId) SetUuid 

func (k *TypeId) SetUuid(id uuid.UUID)

SetUuid sets thte id (as uuid.UUID) of a TypeId

func (*TypeId) SetUuidBytes 

func (k *TypeId) SetUuidBytes(id []byte)

SetUuidBytes sets the Id (as bytes) of a TypeId

func (*TypeId) String 

func (k *TypeId) String() string

String returns the URL-encoded string of the TypeId

func (TypeId) TypeKey 

func (k TypeId) TypeKey() TypeKey

TypeKey returns the TypeKey of a TypeId

func (TypeId) Uuid 

func (k TypeId) Uuid() uuid.UUID

Uuid returns the uuid.UUID of the id of a TypeID

func (TypeId) UuidBytes 

func (k TypeId) UuidBytes() []byte

UuidBytes returns the byte version of the id of a TypeId

type TypeKey 

type TypeKey = [4]byte

TypeKey is the four bytes that identifies the type of an object

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.