datastore

type BulkWriteRelationshipSource interface {
	// Next 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) (*tuple.Relationship, error)
}

type CaveatFilterOption int

type CaveatNameFilter struct {
	// Option is the filter option to use for the caveat name.
	Option CaveatFilterOption

	// CaveatName is the name of the caveat to filter by. Must be specified if option is
	// CaveatFilterOptionHasCaveat.
	CaveatName string
}

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

type CaveatReader interface {
	// ReadCaveatByName returns a caveat with the provided name.
	// It returns an instance of CaveatNotFoundError 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)
}

type CaveatStorer interface {
	CaveatReader

	// WriteCaveats stores the provided caveats, and returns the assigned IDs
	// Each element of the returning slice corresponds by position 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 CounterAlreadyRegisteredError struct {
	// contains filtered or unexported fields
}

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

type CounterReader interface {
	// CountRelationships returns the count of relationships that match the provided counter. If the counter is not
	// registered, returns an error.
	CountRelationships(ctx context.Context, name string) (int, error)

	// LookupCounters returns all registered counters.
	LookupCounters(ctx context.Context) ([]RelationshipCounter, error)
}

type CounterRegisterer interface {
	// RegisterCounter registers a count with the provided filter. If the counter already exists,
	// returns an error.
	RegisterCounter(ctx context.Context, name string, filter *core.RelationshipFilter) error

	// UnregisterCounter unregisters a counter. If the counter did not exist, returns an error.
	UnregisterCounter(ctx context.Context, name string) error

	// StoreCounterValue stores a count for the counter with the given name, at the given revision.
	// If the counter does not exist, returns an error.
	StoreCounterValue(ctx context.Context, name string, value int, computedAtRevision Revision) error
}

type CredentialsProvider interface {
	// Name returns the name of the provider
	Name() string
	// IsCleartextToken returns true if the token returned represents a token (rather than a password) that must be sent in cleartext to the datastore, or false otherwise.
	// This may be used to configure the datastore options to avoid sending a hash of the token instead of its value.
	// Note that it is always recommended that communication channel be encrypted.
	IsCleartextToken() bool
	// Get returns the username and password to use when connecting to the underlying datastore
	Get(ctx context.Context, dbEndpoint string, dbUser string) (string, string, error)
}

type Datastore interface {
	ReadOnlyDatastore

	// ReadWriteTx starts 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)
}

type DeleteNamespacesRelationshipsOption int

type EmissionStrategy int

type ErrNotFound interface {
	IsNotFoundError() bool
}

type ExpirationFilterOption int

type Explainable interface {
	// BuildExplainQuery builds an EXPLAIN statement for the given SQL and arguments.
	BuildExplainQuery(sql string, args []any) (string, []any, error)

	// ParseExplain parses the output of an EXPLAIN statement.
	ParseExplain(explain string) (ParsedExplain, error)

	// PreExplainStatements returns any statements that should be run before the EXPLAIN statement.
	PreExplainStatements() []string
}

type Feature struct {
	Status FeatureStatus
	Reason string
}

type FeatureStatus int

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

	// ContinuousCheckpointing is enabled if the underlying datastore supports continuous checkpointing
	// via the Watch API. If not supported, clients of the Watch API may expect checkpoints only when
	// new transactions are committed.
	ContinuousCheckpointing Feature

	// WatchEmitsImmediately indicates if the datastore supports the EmitImmediatelyStrategy EmissionStrategy.
	// If not supported, clients of the Watch API will receive an error when calling Watch API with
	// EmitImmediatelyStrategy option.
	WatchEmitsImmediately Feature

	// IntegrityData is enabled if the underlying datastore supports retrieving and storing
	// integrity information.
	IntegrityData Feature
}

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

type InvalidRevisionReason int

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

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

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 ParsedExplain struct {
	// IndexesUsed is the list of indexes used in the query.
	IndexesUsed []string
}

type ReadOnlyDatastore interface {
	// MetricsID returns an identifier for the datastore for use in metrics.
	// This identifier is typically the hostname of the datastore (where applicable)
	// and may not be unique; callers should not rely on uniqueness.
	MetricsID() (string, error)

	// UniqueID returns a unique identifier for the datastore. This identifier
	// must be stable across restarts of the datastore if the datastore is
	// persistent.
	UniqueID(context.Context) (string, error)

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

	// 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 changes to the datastore, based on the specified options.
	//
	// All events following afterRevision will be sent to the caller. Changes made *in* afterRevision will not be included.
	//
	// When the changes channel is closed, callers MUST discard any changes received (they will be the zero value).
	//
	// Errors returned will fall into a few classes:
	// - WatchDisconnectedError - the watch has fallen too far behind and has been disconnected.
	// - WatchCanceledError     - the watch was canceled by the caller.
	// - WatchDisabledError     - the watch is disabled by being unsupported by the datastore.
	// - WatchRetryableError    - the watch is retryable, and the caller may retry after some backoff time.
	// - InvalidRevisionError   - the revision specified has passed the datastore's watch history window and
	//                            the watch cannot be retried.
	// - Other errors 			- the watch should not be retried due to a fatal error.
	Watch(ctx context.Context, afterRevision Revision, options WatchOptions) (<-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. Can make calls to the database, so should
	// only be used when a connection is allowed.
	Features(ctx context.Context) (*Features, error)

	// OfflineFeatures returns an object representing what features this
	// datastore supports code-wise, without making any calls to the database.
	OfflineFeatures() (*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 ReadOnlyError struct {
	// contains filtered or unexported fields
}

type ReadWriteTransaction interface {
	Reader
	CaveatStorer
	CounterRegisterer

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

	// DeleteRelationships deletes relationships that match the provided filter, with
	// the optional limit. Returns the number of deleted relationships. If a limit
	// is provided and reached, the method will return true as the second return value.
	// Otherwise, the boolean can be ignored.
	DeleteRelationships(ctx context.Context, filter *v1.RelationshipFilter,
		options ...options.DeleteOptionsOption,
	) (uint64, bool, error)

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

	// DeleteNamespaces deletes namespaces.
	DeleteNamespaces(ctx context.Context, nsNames []string, delOption DeleteNamespacesRelationshipsOption) 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 interface {
	CaveatReader
	CounterReader

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

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
}

type RelationshipCounter struct {
	// Name is the name of the counter.
	Name string

	// Filter is the filter that the count represents.
	Filter *core.RelationshipFilter

	// Count is the count of relationships that match the filter.
	Count int

	// ComputedAtRevision is the revision at which the count was last computed. If NoRevision,
	// the count has never been computed.
	ComputedAtRevision Revision
}

type RelationshipIterator iter.Seq2[tuple.Relationship, error]

type RelationshipQueryOperation int

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

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

	// OptionalResourceIDPrefix is the prefix to use for resource IDs. If empty, any prefix is allowed.
	// Cannot be used with OptionalResourceIds.
	OptionalResourceIDPrefix 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

	// OptionalCaveatNameFilter is the filter to use for caveated relationships, filtering by a specific caveat name.
	// By default, no caveat filtered is done (one direction or the other).
	OptionalCaveatNameFilter CaveatNameFilter

	// OptionalExpirationOption is the filter to use for relationships with or without an expiration.
	OptionalExpirationOption ExpirationFilterOption
}

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

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
}

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
}

type Revision interface {
	fmt.Stringer

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

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

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

	// ByteSortable returns true if the string representation of the Revision is byte sortable, false otherwise.
	ByteSortable() bool
}

type RevisionChanges struct {
	Revision Revision

	// RelationshipChanges are any relationships that were changed at this revision.
	RelationshipChanges []tuple.RelationshipUpdate

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

	// Metadatas is the list of metadata associated with the revision, if any.
	Metadatas []*structpb.Struct
}

type RevisionedCaveat = RevisionedDefinition[*core.CaveatDefinition]

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
}

type RevisionedNamespace = RevisionedDefinition[*core.NamespaceDefinition]

type SQLDatastore interface {
	Datastore
	Explainable
}

type SchemaDefinition interface {
	GetName() string
	SizeVT() int
}

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
}

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 StrictReadDatastore interface {
	Datastore

	// IsStrictReadModeEnabled returns whether the datastore is in strict read mode.
	IsStrictReadModeEnabled() bool
}

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
}

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

type TxUserFunc func(context.Context, ReadWriteTransaction) error

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

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

type WatchContent int

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

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

type WatchOptions struct {
	// Content is the content to watch.
	Content WatchContent

	// CheckpointInterval is the interval to use for checkpointing in the watch.
	// If given the zero value, the datastore's default will be used. If smaller
	// than the datastore's minimum, the minimum will be used.
	CheckpointInterval time.Duration

	// WatchBufferLength is the length of the buffer for the watch channel. If
	// given the zero value, the datastore's default will be used.
	WatchBufferLength uint16

	// WatchBufferWriteTimeout is the timeout for writing to the watch channel.
	// If given the zero value, the datastore's default will be used.
	WatchBufferWriteTimeout time.Duration

	// WatchConnectTimeout is the timeout for connecting to the watch channel.
	// If given the zero value, the datastore's default will be used.
	// May not be supported by the datastore.
	WatchConnectTimeout time.Duration

	// MaximumBufferedChangesByteSize is the maximum byte size of the buffered changes struct.
	// If unspecified, no maximum will be enforced. If the maximum is reached before
	// the changes can be sent, the watch will be closed with an error.
	MaximumBufferedChangesByteSize uint64

	// EmissionStrategy defines when are changes streamed to the client. If unspecified, changes will be buffered until
	// they can be checkpointed, which is the default behavior.
	EmissionStrategy EmissionStrategy
}

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