datastore

type CaveatReader interface {
	// ReadCaveatByName returns a caveat with the provided name
	ReadCaveatByName(ctx context.Context, name string) (*core.CaveatDefinition, Revision, error)

	// ListCaveats returns all caveats stored in the system. If caveatNames are provided
	// the result will be filtered to the provided caveat names
	ListCaveats(ctx context.Context, caveatNamesForFiltering ...string) ([]*core.CaveatDefinition, error)
}

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
}

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

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

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

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

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

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

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

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

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

type Feature struct {
	Enabled bool
	Reason  string
}

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

type InvalidRevisionReason int

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
}

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
}

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,
		subjectFilter SubjectsFilter,
		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)

	// LookupNamespaces finds all namespaces with the matching names.
	LookupNamespaces(ctx context.Context, nsNames []string) ([]*core.NamespaceDefinition, error)
}

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

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

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

	// OptionalSubjectsFilter is the filter to use for subjects of the relationship. If nil, all subjects are allowed.
	OptionalSubjectsFilter *SubjectsFilter

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

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
}

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

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
}

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
}

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
}

type TxUserFunc func(ReadWriteTransaction) error