datastore

package
v1.28.0-rc1 Latest Latest
Warning

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

 Go to latest Published: Nov 27, 2023 License: Apache-2.0 Imports: 14 Imported by: 1

Documentation

Index

Constants

View Source 
const Ellipsis = "..."

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

View Source 
const FilterMaximumIDCount uint16 = 100

FilterMaximumIDCount is the maximum number of resource IDs or subject IDs that can be sent into a filter.

Variables

View Source 
var (
	ErrClosedIterator        = errors.New("unable to iterate: iterator closed")
	ErrCursorsWithoutSorting = errors.New("cursors are disabled on unsorted results")
	ErrCursorEmpty           = errors.New("cursors are only available after the first result")
)
View Source 
var Engines []string

Functions

func DefinitionsOf added in v1.16.2 

func DefinitionsOf[T SchemaDefinition](revisionedDefinitions []RevisionedDefinition[T]) []T

DefinitionsOf returns just the schema definitions found in the list of revisioned definitions.

func EngineOptions 

func EngineOptions() string

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

func NewCaveatNameNotFoundErr added in v1.13.0 

func NewCaveatNameNotFoundErr(name string) error

NewCaveatNameNotFoundErr constructs a new caveat name not found error.

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 NewWatchDisabledErr added in v1.16.0 

func NewWatchDisabledErr(reason string) error

NewWatchDisabledErr constructs a new watch is disabled error.

func NewWatchDisconnectedErr 

func NewWatchDisconnectedErr() error

NewWatchDisconnectedErr constructs a new watch was disconnected error.

func SortedEngineIDs 

func SortedEngineIDs() []string

SortedEngineIDs returns the full set of engine IDs, sorted.

Types

type BulkWriteRelationshipSource added in v1.22.0 

type BulkWriteRelationshipSource interface {
	// Returns a pointer to a relation tuple if one is available, or nil if
	// there are no more or there was an error.
	//
	// Note: sources may re-use the same memory address for every tuple, data
	// may change on every call to next even if the pointer has not changed.
	Next(ctx context.Context) (*core.RelationTuple, error)
}

BulkWriteRelationshipSource is an interface for transferring relationships to a backing datastore with a zero-copy methodology.

type CaveatReader added in v1.13.0 

type CaveatReader interface {
	// ReadCaveatByName returns a caveat with the provided name.
	// It returns an instance of ErrCaveatNotFound if not found.
	ReadCaveatByName(ctx context.Context, name string) (caveat *core.CaveatDefinition, lastWritten Revision, err error)

	// ListAllCaveats returns all caveats stored in the system.
	ListAllCaveats(ctx context.Context) ([]RevisionedCaveat, error)

	// LookupCaveatsWithNames finds all caveats with the matching names.
	LookupCaveatsWithNames(ctx context.Context, names []string) ([]RevisionedCaveat, error)
}

CaveatReader offers read operations for caveats

type CaveatStorer added in v1.13.0 

type CaveatStorer interface {
	CaveatReader

	// WriteCaveats stores the provided caveats, and returns the assigned IDs
	// Each element of the returning slice corresponds by possition to the input slice
	WriteCaveats(context.Context, []*core.CaveatDefinition) error

	// DeleteCaveats deletes the provided caveats by name
	DeleteCaveats(ctx context.Context, names []string) error
}

CaveatStorer offers both read and write operations for Caveats

type Datastore 

type Datastore interface {
	// SnapshotReader 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, ...options.RWTOptionsOption) (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

	// RevisionFromString will parse the revision text and return the specific type of Revision
	// used by the specific datastore implementation.
	RevisionFromString(serialized string) (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)

	// ReadyState returns a state indicating whether the datastore is ready to accept data.
	// Datastores that require database schema creation will return not-ready until the migrations
	// have been run to create the necessary tables.
	ReadyState(ctx context.Context) (ReadyState, error)

	// Features returns an object representing what features this
	// datastore can support.
	Features(ctx context.Context) (*Features, 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 ErrCaveatNameNotFound added in v1.13.0 

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

ErrCaveatNameNotFound is the error returned when a caveat is not found by its name

func (ErrCaveatNameNotFound) CaveatName added in v1.13.0 

func (err ErrCaveatNameNotFound) CaveatName() string

CaveatName returns the name of the caveat that couldn't be found

func (ErrCaveatNameNotFound) DetailsMetadata added in v1.14.0 

func (err ErrCaveatNameNotFound) DetailsMetadata() map[string]string

DetailsMetadata returns the metadata for details for this error.

func (ErrCaveatNameNotFound) IsNotFoundError added in v1.16.2 

func (err ErrCaveatNameNotFound) IsNotFoundError() bool

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 (err ErrInvalidRevision) InvalidRevision() Revision

InvalidRevision is the revision that failed.

func (ErrInvalidRevision) MarshalZerologObject 

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

MarshalZerologObject implements zerolog object marshalling.

func (ErrInvalidRevision) Reason 

func (err 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) DetailsMetadata added in v1.14.0 

func (err ErrNamespaceNotFound) DetailsMetadata() map[string]string

DetailsMetadata returns the metadata for details for this error.

func (ErrNamespaceNotFound) IsNotFoundError added in v1.16.2 

func (err ErrNamespaceNotFound) IsNotFoundError() bool

func (ErrNamespaceNotFound) MarshalZerologObject 

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

MarshalZerologObject implements zerolog object marshalling.

func (ErrNamespaceNotFound) NotFoundNamespaceName 

func (err ErrNamespaceNotFound) NotFoundNamespaceName() string

NotFoundNamespaceName is the name of the namespace not found.

type ErrNotFound added in v1.16.2 

type ErrNotFound interface {
	IsNotFoundError() bool
}

ErrNotFound is a shared interface for not found errors.

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 ErrWatchDisabled added in v1.16.0 

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

ErrWatchDisabled occurs when watch is disabled by being unsupported by the datastore.

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 Feature added in v1.11.0 

type Feature struct {
	Enabled bool
	Reason  string
}

Feature represents a capability that a datastore can support, plus an optional message explaining the feature is available (or not).

type Features added in v1.11.0 

type Features struct {
	// Watch is enabled if the underlying datastore can support the Watch api.
	Watch Feature
}

Features holds values that represent what features a database can support.

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

	// 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 []RevisionedNamespace) []ObjectTypeStat

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

type ReadWriteTransaction 

type ReadWriteTransaction interface {
	Reader
	CaveatStorer

	// WriteRelationships takes a list of tuple mutations and applies them to the datastore.
	WriteRelationships(ctx context.Context, mutations []*core.RelationTupleUpdate) error

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

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

	// DeleteNamespaces deletes namespaces including associated relationships.
	DeleteNamespaces(ctx context.Context, nsNames ...string) error

	// BulkLoad takes a relationship source iterator, and writes all of the
	// relationships to the backing datastore in an optimized fashion. This
	// method can and will omit checks and otherwise cut corners in the
	// interest of performance, and should not be relied upon for OLTP-style
	// workloads.
	BulkLoad(ctx context.Context, iter BulkWriteRelationshipSource) (uint64, error)
}

type Reader 

type Reader interface {
	CaveatReader

	// QueryRelationships reads relationships, starting from the resource side.
	QueryRelationships(
		ctx context.Context,
		filter RelationshipsFilter,
		options ...options.QueryOptionsOption,
	) (RelationshipIterator, error)

	// ReverseQueryRelationships reads relationships, starting from the subject.
	ReverseQueryRelationships(
		ctx context.Context,
		subjectsFilter SubjectsFilter,
		options ...options.ReverseQueryOptionsOption,
	) (RelationshipIterator, error)

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

	// ListAllNamespaces lists all namespaces defined.
	ListAllNamespaces(ctx context.Context) ([]RevisionedNamespace, error)

	// LookupNamespacesWithNames finds all namespaces with the matching names.
	LookupNamespacesWithNames(ctx context.Context, nsNames []string) ([]RevisionedNamespace, error)
}

Reader is an interface for reading relationships from the datastore.

type ReadyState added in v1.18.1 

type ReadyState struct {
	// Message is a human-readable status message for the current state.
	Message string

	// IsReady indicates whether the datastore is ready.
	IsReady bool
}

ReadyState represents the ready state of the datastore.

type RelationshipIterator 

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

	// Cursor returns a cursor that can be used to resume reading of relationships
	// from the last relationship returned. Only applies if a sort ordering was
	// requested.
	Cursor() (options.Cursor, error)

	// Err 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.

type RelationshipQueryOperation added in v1.16.0 

type RelationshipQueryOperation int
const (
	RelationshipQueryNone RelationshipQueryOperation = 0
	RelationshipQueryOr   RelationshipQueryOperation = 1
	RelationshipQueryAnd  RelationshipQueryOperation = 2
)

type RelationshipsFilter added in v1.12.0 

type RelationshipsFilter struct {
	// ResourceType is the namespace/type for the resources to be found.
	ResourceType string

	// OptionalResourceIds are the IDs of the resources to find. If nil empty, any resource ID will be allowed.
	OptionalResourceIds []string

	// OptionalResourceRelation is the relation of the resource to find. If empty, any relation is allowed.
	OptionalResourceRelation string

	// OptionalSubjectsSelectors is the selectors to use for subjects of the relationship. If nil, all subjects are allowed.
	// If specified, relationships matching *any* selector will be returned.
	OptionalSubjectsSelectors []SubjectsSelector

	// OptionalCaveatName is the filter to use for caveated relationships, filtering by a specific caveat name.
	// If nil, all caveated and non-caveated relationships are allowed
	OptionalCaveatName string
}

RelationshipsFilter is a filter for relationships.

func RelationshipsFilterFromPublicFilter added in v1.12.0 

func RelationshipsFilterFromPublicFilter(filter *v1.RelationshipFilter) RelationshipsFilter

RelationshipsFilterFromPublicFilter constructs a datastore RelationshipsFilter from an API-defined RelationshipFilter.

type RelationshipsQueryTree added in v1.16.0 

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

func NewRelationshipQueryTree added in v1.16.0 

func NewRelationshipQueryTree(filter RelationshipsFilter) RelationshipsQueryTree

type RepairOperation added in v1.28.0 

type RepairOperation struct {
	// Name is the command-line name for the repair operation.
	Name string

	// Description is the human-readable description for the repair operation.
	Description string
}

RepairOperation represents a single kind of repair operation that can be run in a repairable datastore.

type RepairableDatastore added in v1.28.0 

type RepairableDatastore interface {
	Datastore

	// Repair runs the repair operation on the datastore.
	Repair(ctx context.Context, operationName string, outputProgress bool) error

	// RepairOperations returns the available repair operations for the datastore.
	RepairOperations() []RepairOperation
}

RepairableDatastore is an optional extension to the datastore interface that, when implemented, provides the ability for callers to repair the datastore's data in some fashion.

type Revision 

type Revision interface {
	fmt.Stringer
	encoding.BinaryMarshaler

	// Equal returns whether the revisions should be considered equal.
	Equal(Revision) bool

	// Equal returns whether the receiver is provably greater than the right hand side.
	GreaterThan(Revision) bool

	// Equal returns whether the receiver is provably less than the right hand side.
	LessThan(Revision) bool
}

Revision is an interface for a comparable revision type that can be different for each datastore implementation. 

var NoRevision Revision = nilRevision{}

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 RevisionedCaveat added in v1.16.2 

type RevisionedCaveat = RevisionedDefinition[*core.CaveatDefinition]

RevisionedCaveat is a revisioned version of a caveat definition.

type RevisionedDefinition added in v1.16.2 

type RevisionedDefinition[T SchemaDefinition] struct {
	// Definition is the namespace or caveat definition.
	Definition T

	// LastWrittenRevision is the revision at which the namespace or caveat was last updated.
	LastWrittenRevision Revision
}

RevisionedDefinition holds a schema definition and its last updated revision.

func (RevisionedDefinition[T]) GetLastWrittenRevision added in v1.25.0 

func (rd RevisionedDefinition[T]) GetLastWrittenRevision() Revision

type RevisionedNamespace added in v1.16.2 

type RevisionedNamespace = RevisionedDefinition[*core.NamespaceDefinition]

RevisionedNamespace is a revisioned version of a namespace definition.

type SchemaDefinition added in v1.16.2 

type SchemaDefinition interface {
	GetName() string
}

SchemaDefinition represents a namespace or caveat definition under a schema.

type SchemaState added in v1.25.0 

type SchemaState struct {
	// Revision is the timestamp at which this state was created.
	Revision Revision

	// ChangedDefinitions are any definitions that were added or changed at this revision.
	ChangedDefinitions []SchemaDefinition

	// DeletedNamespaces are any namespaces that were deleted.
	DeletedNamespaces []string

	// DeletedCaveats are any caveats that were deleted.
	DeletedCaveats []string

	// IsCheckpoint, if true, indicates that the datastore has reported all changes
	// up until and including the Revision and that no additional schema updates can
	// have occurred before this point.
	IsCheckpoint bool
}

SchemaState is the state of the schema at a point in time.

func (*SchemaState) MarshalZerologObject added in v1.25.0 

func (ss *SchemaState) MarshalZerologObject(e *zerolog.Event)

type SchemaWatchableDatastore added in v1.25.0 

type SchemaWatchableDatastore interface {
	Datastore

	// WatchSchema notifies the caller about all changes to schema, as well as when time has moved forward
	// without any changes.
	//
	// All events following afterRevision will be sent to the caller.
	//
	// If the SchemaState received is a checkpoint, then *no additional changes to schema* can have occurred
	// before that revision timestamp.
	WatchSchema(ctx context.Context, afterRevision Revision) (<-chan *SchemaState, <-chan error)
}

SchemaWatchableDatastore is an optional extension to the datastore interface that, when implemented, provides the ability for callers to watch the datastore for schema (namespace and caveat) changes.

type StartableDatastore added in v1.25.0 

type StartableDatastore interface {
	Datastore

	// Start starts any background operations on the datastore. The context provided, if canceled, will
	// also cancel the background operation(s) on the datastore.
	Start(ctx context.Context) error
}

StartableDatastore is an optional extension to the datastore interface that, when implemented, provides the ability for callers to start background operations on the datastore.

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 datastore. 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 SubjectRelationFilter added in v1.11.0 

type SubjectRelationFilter struct {
	// NonEllipsisRelation is the relation of the subject type to find. If empty,
	// IncludeEllipsisRelation must be true.
	NonEllipsisRelation string

	// IncludeEllipsisRelation, if true, indicates that the ellipsis relation
	// should be included as an option.
	IncludeEllipsisRelation bool

	// OnlyNonEllipsisRelations, if true, indicates that only non-ellipsis relations
	// should be included.
	OnlyNonEllipsisRelations bool
}

SubjectRelationFilter is the filter to use for relation(s) of subjects being queried.

func (SubjectRelationFilter) IsEmpty added in v1.11.0 

func (sf SubjectRelationFilter) IsEmpty() bool

IsEmpty returns true if the subject relation filter is empty.

func (SubjectRelationFilter) WithEllipsisRelation added in v1.11.0 

func (sf SubjectRelationFilter) WithEllipsisRelation() SubjectRelationFilter

WithEllipsisRelation indicates that the subject filter should include the ellipsis relation as an option for the subjects' relation.

func (SubjectRelationFilter) WithNonEllipsisRelation added in v1.11.0 

func (sf SubjectRelationFilter) WithNonEllipsisRelation(relation string) SubjectRelationFilter

WithNonEllipsisRelation indicates that the specified non-ellipsis relation should be included as an option for the subjects' relation.

func (SubjectRelationFilter) WithOnlyNonEllipsisRelations added in v1.16.0 

func (sf SubjectRelationFilter) WithOnlyNonEllipsisRelations() SubjectRelationFilter

WithOnlyNonEllipsisRelations indicates that only non-ellipsis relations should be included.

func (SubjectRelationFilter) WithRelation added in v1.16.0 

func (sf SubjectRelationFilter) WithRelation(relation string) SubjectRelationFilter

WithRelation indicates that the specified relation should be included as an option for the subjects' relation.

type SubjectsFilter added in v1.11.0 

type SubjectsFilter struct {
	// SubjectType is the namespace/type for the subjects to be found.
	SubjectType string

	// OptionalSubjectIds are the IDs of the subjects to find. If nil or empty, any subject ID will be allowed.
	OptionalSubjectIds []string

	// RelationFilter is the filter to use for the relation(s) of the subjects. If neither field
	// is set, any relation is allowed.
	RelationFilter SubjectRelationFilter
}

SubjectsFilter is a filter for subjects.

func (SubjectsFilter) AsSelector added in v1.16.0 

func (sf SubjectsFilter) AsSelector() SubjectsSelector

type SubjectsSelector added in v1.16.0 

type SubjectsSelector struct {
	// OptionalSubjectType is the namespace/type for the subjects to be found, if any.
	OptionalSubjectType string

	// OptionalSubjectIds are the IDs of the subjects to find. If nil or empty, any subject ID will be allowed.
	OptionalSubjectIds []string

	// RelationFilter is the filter to use for the relation(s) of the subjects. If neither field
	// is set, any relation is allowed.
	RelationFilter SubjectRelationFilter
}

SubjectsSelector is a selector for subjects.

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.

type UnwrappableDatastore added in v1.16.0 

type UnwrappableDatastore interface {
	// Unwrap returns the wrapped datastore.
	Unwrap() Datastore
}

UnwrappableDatastore represents a datastore that can be unwrapped into the underlying datastore.

Source Files

View all Source files

Directories

Path Synopsis
Code generated by github.com/ecordell/optgen.
 Code generated by github.com/ecordell/optgen.

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.