datastore

Documentation

Index

• Constants
• Variables
• func BuildFinalizerFunction() func(iter *sliceRelationshipIterator)
• func EngineOptions() string
• func NewInvalidRevisionErr(revision Revision, reason InvalidRevisionReason) error
• func NewNamespaceNotFoundErr(nsName string) error
• func NewReadonlyErr() error
• func NewWatchCanceledErr() error
• func NewWatchDisconnectedErr() error
• func SeparateContextWithTracing(ctx context.Context) context.Context
• func SortedEngineIDs() []string
• type Datastore
• type ErrInvalidRevision
  • func (eri ErrInvalidRevision) InvalidRevision() Revision
  • func (eri ErrInvalidRevision) MarshalZerologObject(e *zerolog.Event)
  • func (eri ErrInvalidRevision) Reason() InvalidRevisionReason
• type ErrNamespaceNotFound
  • func (enf ErrNamespaceNotFound) MarshalZerologObject(e *zerolog.Event)
  • func (enf ErrNamespaceNotFound) NotFoundNamespaceName() string
• type ErrReadOnly
• type ErrWatchCanceled
• type ErrWatchDisconnected
• type InvalidRevisionReason
• type ObjectTypeStat
  • func ComputeObjectTypeStats(objTypes []*core.NamespaceDefinition) []ObjectTypeStat
• type ReadWriteTransaction
• type Reader
• type RelationshipIterator
  • func NewSliceRelationshipIterator(tuples []*core.RelationTuple) RelationshipIterator
• type Revision
• type RevisionChanges
• type Stats
• type TxUserFunc

Constants

const Ellipsis = "..."

Ellipsis is a special relation that is assumed to be valid on the right hand side of a tuple.

Variables

var Engines = []string{}

Functions

func BuildFinalizerFunction

func BuildFinalizerFunction() func(iter *sliceRelationshipIterator)

BuildFinalizerFunction creates a function which can be used as a finalizer to make sure that tuples are getting closed before they are garbage collected.

func EngineOptions

func EngineOptions() string

EngineOptions returns the full set of engine IDs, sorted and quoted into a string.

func NewInvalidRevisionErr

func NewInvalidRevisionErr(revision Revision, reason InvalidRevisionReason) error

NewInvalidRevisionErr constructs a new invalid revision error.

func NewNamespaceNotFoundErr

func NewNamespaceNotFoundErr(nsName string) error

NewNamespaceNotFoundErr constructs a new namespace not found error.

func NewReadonlyErr

func NewReadonlyErr() error

NewReadonlyErr constructs an error for when a request has failed because the datastore has been configured to be read-only.

func NewWatchCanceledErr

func NewWatchCanceledErr() error

NewWatchCanceledErr constructs a new watch was canceled error.

func NewWatchDisconnectedErr

func NewWatchDisconnectedErr() error

NewWatchDisconnectedErr constructs a new watch was disconnected error.

func SeparateContextWithTracing

func SeparateContextWithTracing(ctx context.Context) context.Context

SeparateContextWithTracing is a utility method which allows for severing the context between grpc and the datastore to prevent context cancellation from killing database connections that should otherwise go back to the connection pool.

func SortedEngineIDs

func SortedEngineIDs() []string

SortedEngineIDs returns the full set of engine IDs, sorted.

Types

type Datastore

type Datastore interface {
	// SnapshotRead creates a read-only handle that reads the datastore at the specified revision.
	// Any errors establishing the reader will be returned by subsequent calls.
	SnapshotReader(Revision) Reader

	// ReadWriteTx tarts a read/write transaction, which will be committed if no error is
	// returned and rolled back if an error is returned.
	ReadWriteTx(context.Context, TxUserFunc) (Revision, error)

	// OptimizedRevision gets a revision that will likely already be replicated
	// and will likely be shared amongst many queries.
	OptimizedRevision(ctx context.Context) (Revision, error)

	// HeadRevision gets a revision that is guaranteed to be at least as fresh as
	// right now.
	HeadRevision(ctx context.Context) (Revision, error)

	// CheckRevision checks the specified revision to make sure it's valid and
	// hasn't been garbage collected.
	CheckRevision(ctx context.Context, revision Revision) error

	// Watch notifies the caller about all changes to tuples.
	//
	// All events following afterRevision will be sent to the caller.
	Watch(ctx context.Context, afterRevision Revision) (<-chan *RevisionChanges, <-chan error)

	// IsReady returns whether the datastore is ready to accept data. Datastores that require
	// database schema creation will return false until the migrations have been run to create
	// the necessary tables.
	IsReady(ctx context.Context) (bool, error)

	// Statistics returns relevant values about the data contained in this cluster.
	Statistics(ctx context.Context) (Stats, error)

	// Close closes the data store.
	Close() error
}

Datastore represents tuple access for a single namespace.

type ErrInvalidRevision

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

ErrInvalidRevision occurs when a revision specified to a call was invalid.

func (ErrInvalidRevision) InvalidRevision

func (eri ErrInvalidRevision) InvalidRevision() Revision

InvalidRevision is the revision that failed.

func (ErrInvalidRevision) MarshalZerologObject

func (eri ErrInvalidRevision) MarshalZerologObject(e *zerolog.Event)

MarshalZerologObject implements zerolog object marshalling.

func (ErrInvalidRevision) Reason

func (eri ErrInvalidRevision) Reason() InvalidRevisionReason

Reason is the reason the revision failed.

type ErrNamespaceNotFound

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

ErrNamespaceNotFound occurs when a namespace was not found.

func (ErrNamespaceNotFound) MarshalZerologObject

func (enf ErrNamespaceNotFound) MarshalZerologObject(e *zerolog.Event)

MarshalZerologObject implements zerolog object marshalling.

func (ErrNamespaceNotFound) NotFoundNamespaceName

func (enf ErrNamespaceNotFound) NotFoundNamespaceName() string

NotFoundNamespaceName is the name of the namespace not found.

type ErrReadOnly

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

ErrReadOnly is returned when the operation cannot be completed because the datastore is in read-only mode.

type ErrWatchCanceled

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

ErrWatchCanceled occurs when a watch was canceled by the caller

type ErrWatchDisconnected

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

ErrWatchDisconnected occurs when a watch has fallen too far behind and was forcibly disconnected as a result.

type InvalidRevisionReason

type InvalidRevisionReason int

InvalidRevisionReason is the reason the revision could not be used.

const (
	// RevisionStale is the reason returned when a revision is outside the window of
	// validity by being too old.
	RevisionStale InvalidRevisionReason = iota

	// RevisionInFuture is the reason returned when a revision is outside the window of
	// validity by being too new.
	RevisionInFuture

	// CouldNotDetermineRevision is the reason returned when a revision for a
	// request could not be determined.
	CouldNotDetermineRevision
)

type ObjectTypeStat

type ObjectTypeStat struct {
	// NumRelations is the number of relations defined in a single object type.
	NumRelations uint32

	// NumPermissions is the number of permissions defined in a single object type.
	NumPermissions uint32
}

ObjectTypeStat represents statistics for a single object type (namespace).

func ComputeObjectTypeStats

func ComputeObjectTypeStats(objTypes []*core.NamespaceDefinition) []ObjectTypeStat

ComputeObjectTypeStats creates a list of object type stats from an input list of parsed object types.

type ReadWriteTransaction

type ReadWriteTransaction interface {
	Reader

	// WriteRelationships takes a list of tuple mutations and applies them to the datastore.
	WriteRelationships(mutations []*v1.RelationshipUpdate) error

	// DeleteRelationships deletes all Relationships that match the provided filter.
	DeleteRelationships(filter *v1.RelationshipFilter) error

	// WriteNamespaces takes proto namespace definitions and persists them.
	WriteNamespaces(newConfigs ...*core.NamespaceDefinition) error

	// DeleteNamespace deletes a namespace and any associated tuples.
	DeleteNamespace(nsName string) error
}

type Reader

type Reader interface {
	// QueryRelationships reads relationships, starting from the resource side.
	QueryRelationships(
		ctx context.Context,
		filter *v1.RelationshipFilter,
		options ...options.QueryOptionsOption,
	) (RelationshipIterator, error)

	// ReverseQueryRelationships reads relationships, starting from the subject.
	ReverseQueryRelationships(
		ctx context.Context,
		subjectFilter *v1.SubjectFilter,
		options ...options.ReverseQueryOptionsOption,
	) (RelationshipIterator, error)

	// ReadNamespace reads a namespace definition and the revision at which it was created or
	// last written. It returns an instance of ErrNamespaceNotFound if not found.
	ReadNamespace(ctx context.Context, nsName string) (ns *core.NamespaceDefinition, lastWritten Revision, err error)

	// ListNamespaces lists all namespaces defined.
	ListNamespaces(ctx context.Context) ([]*core.NamespaceDefinition, error)
}

type RelationshipIterator

type RelationshipIterator interface {
	// Next returns the next tuple in the result set.
	Next() *core.RelationTuple

	// After receiving a nil response, the caller must check for an error.
	Err() error

	// Close cancels the query and closes any open connections.
	Close()
}

RelationshipIterator is an iterator over matched tuples.

func NewSliceRelationshipIterator

func NewSliceRelationshipIterator(tuples []*core.RelationTuple) RelationshipIterator

NewSliceRelationshipIterator creates a datastore.TupleIterator instance from a materialized slice of tuples.

type Revision

type Revision = decimal.Decimal

Revision is a type alias to make changing the revision type a little bit easier if we need to do it in the future. Implementations should code directly against decimal.Decimal when creating or parsing.

var NoRevision Revision

NoRevision is a zero type for the revision that will make changing the revision type in the future a bit easier if necessary. Implementations should use any time they want to signal an empty/error revision.

type RevisionChanges

type RevisionChanges struct {
	Revision Revision
	Changes  []*core.RelationTupleUpdate
}

RevisionChanges represents the changes in a single transaction.

type Stats

type Stats struct {
	// UniqueID is a unique string for a single datastore.
	UniqueID string

	// EstimatedRelationshipCount is a best-guess estimate of the number of relationships
	// in the datstore. Computing it should use a lightweight method such as reading
	// table statistics.
	EstimatedRelationshipCount uint64

	// ObjectTypeStatistics returns a slice element for each object type (namespace)
	// stored in the datastore.
	ObjectTypeStatistics []ObjectTypeStat
}

Stats represents statistics for the entire datastore.

type TxUserFunc

type TxUserFunc func(context.Context, ReadWriteTransaction) error

TxUserFunc is a type for the function that users supply when they invoke a read-write transaction.