datastore

Documentation

Index

• Constants
• func BuildFinalizerFunction() func(iter *sliceTupleIterator)
• func NewInvalidRevisionErr(revision Revision, reason InvalidRevisionReason) error
• func NewNamespaceNotFoundErr(nsName string) error
• func NewPreconditionFailedErr(precondition *v1.Precondition) error
• func NewReadonlyErr() error
• func NewWatchCanceledErr() error
• func NewWatchDisconnectedErr() error
• func SeparateContextWithTracing(ctx context.Context) context.Context
• 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 ErrPreconditionFailed
  • func (epf ErrPreconditionFailed) MarshalZerologObject(e *zerolog.Event)
• type ErrReadOnly
• type ErrWatchCanceled
• type ErrWatchDisconnected
• type GraphDatastore
• type InvalidRevisionReason
• type Revision
• type RevisionChanges
• type TupleIterator
  • func NewSliceTupleIterator(tuples []*v0.RelationTuple) TupleIterator

Constants

const Ellipsis = "..."

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

Functions

func BuildFinalizerFunction

func BuildFinalizerFunction() func(iter *sliceTupleIterator)

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 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 NewPreconditionFailedErr

func NewPreconditionFailedErr(precondition *v1.Precondition) error

NewPreconditionFailedErr constructs a new precondition failed 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.

Types

type Datastore

type Datastore interface {
	GraphDatastore

	// WriteTuples takes a list of existing tuples that must exist, and a list of
	// tuple mutations and applies it to the datastore for the specified
	// namespace.
	WriteTuples(ctx context.Context, preconditions []*v1.Precondition, mutations []*v1.RelationshipUpdate) (Revision, error)

	// DeleteRelationships deletes all Relationships that match the provided
	// filter if all preconditions are met.
	DeleteRelationships(ctx context.Context, preconditions []*v1.Precondition, filter *v1.RelationshipFilter) (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)

	// 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)

	// WriteNamespace takes a proto namespace definition and persists it,
	// returning the version of the namespace that was created.
	WriteNamespace(ctx context.Context, newConfig *v0.NamespaceDefinition) (Revision, error)

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

	// DeleteNamespace deletes a namespace and any associated tuples.
	DeleteNamespace(ctx context.Context, nsName string) (Revision, error)

	// ListNamespaces lists all namespaces defined.
	ListNamespaces(ctx context.Context, revision Revision) ([]*v0.NamespaceDefinition, 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)

	// 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 ErrPreconditionFailed

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

ErrPreconditionFailed occurs when the precondition to a write tuple call does not match.

func (ErrPreconditionFailed) MarshalZerologObject

func (epf ErrPreconditionFailed) MarshalZerologObject(e *zerolog.Event)

MarshalZerologObject implements zerolog object marshalling.

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 GraphDatastore

type GraphDatastore interface {
	// QueryTuples reads relationships starting from the resource side.
	QueryTuples(
		ctx context.Context,
		filter *v1.RelationshipFilter,
		revision Revision,
		options ...options.QueryOptionsOption,
	) (TupleIterator, error)

	// ReverseQueryRelationships reads relationships starting from the subject.
	ReverseQueryTuples(
		ctx context.Context,
		subjectFilter *v1.SubjectFilter,
		revision Revision,
		options ...options.ReverseQueryOptionsOption,
	) (TupleIterator, 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
}

GraphDatastore is a subset of the datastore interface that is passed to graph resolvers.

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 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  []*v0.RelationTupleUpdate
}

RevisionChanges represents the changes in a single transaction.

type TupleIterator

type TupleIterator interface {
	// Next returns the next tuple in the result set.
	Next() *v0.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()
}

TupleIterator is an iterator over matched tuples.

func NewSliceTupleIterator

func NewSliceTupleIterator(tuples []*v0.RelationTuple) TupleIterator

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