Documentation ¶
Index ¶
- Constants
- Variables
- func ExceededMaxTypeDefinitionsLimitError(limit int) error
- func InvalidWriteInputError(tk *openfgapb.TupleKey, operation openfgapb.TupleOperation) error
- type AssertionsBackend
- type AuthorizationModelBackend
- type AuthorizationModelReadBackend
- type ChangelogBackend
- type ContextTracerWrapper
- func (c *ContextTracerWrapper) Close()
- func (c *ContextTracerWrapper) Read(ctx context.Context, store string, tupleKey *openfgapb.TupleKey) (TupleIterator, error)
- func (c *ContextTracerWrapper) ReadPage(ctx context.Context, store string, tupleKey *openfgapb.TupleKey, ...) ([]*openfgapb.Tuple, []byte, error)
- func (c *ContextTracerWrapper) ReadStartingWithUser(ctx context.Context, store string, opts ReadStartingWithUserFilter) (TupleIterator, error)
- func (c *ContextTracerWrapper) ReadUserTuple(ctx context.Context, store string, tupleKey *openfgapb.TupleKey) (*openfgapb.Tuple, error)
- func (c *ContextTracerWrapper) ReadUsersetTuples(ctx context.Context, store string, filter ReadUsersetTuplesFilter) (TupleIterator, error)
- type Deletes
- type Iterator
- type ObjectIterator
- func NewObjectIteratorFromTupleKeyIterator(iter TupleKeyIterator) ObjectIterator
- func NewStaticObjectIterator(objects []*openfgapb.Object) ObjectIterator
- func NewTupleKeyObjectIterator(tupleKeys []*openfgapb.TupleKey) ObjectIterator
- func NewUniqueObjectIterator(iter1, iter2 ObjectIterator) ObjectIterator
- type OpenFGADatastore
- type PaginationOptions
- type ReadStartingWithUserFilter
- type ReadUsersetTuplesFilter
- type RelationshipTupleReader
- type RelationshipTupleWriter
- type StoresBackend
- type TupleBackend
- type TupleIterator
- type TupleKeyFilterFunc
- type TupleKeyIterator
- type TypeDefinitionReadBackend
- type TypeDefinitionWriteBackend
- type Writes
Examples ¶
Constants ¶
const ( DefaultMaxTuplesPerWrite = 100 DefaultMaxTypesPerAuthorizationModel = 100 DefaultPageSize = 50 )
Variables ¶
var ( ErrCollision = errors.New("item already exists") ErrInvalidContinuationToken = errors.New("invalid continuation token") ErrInvalidWriteInput = errors.New("invalid write input") ErrNotFound = errors.New("not found") ErrTransactionalWriteFailed = errors.New("transactional write failed due to bad input") ErrMismatchObjectType = errors.New("mismatched types in request and continuation token") ErrExceededWriteBatchLimit = errors.New("number of operations exceeded write batch limit") ErrCancelled = errors.New("request has been cancelled") )
since these errors are allocated at init time, it is better to leave them as normal errors instead of errors that have stack encoded.
var ErrIteratorDone = errors.New("iterator done")
Functions ¶
func InvalidWriteInputError ¶
func InvalidWriteInputError(tk *openfgapb.TupleKey, operation openfgapb.TupleOperation) error
Types ¶
type AssertionsBackend ¶
type AuthorizationModelBackend ¶
type AuthorizationModelBackend interface { AuthorizationModelReadBackend TypeDefinitionReadBackend TypeDefinitionWriteBackend }
AuthorizationModelBackend provides an R/W interface for managing type definition.
type AuthorizationModelReadBackend ¶
type AuthorizationModelReadBackend interface { // ReadAuthorizationModel Read the store type definition corresponding to `id`. ReadAuthorizationModel(ctx context.Context, store string, id string) (*openfgapb.AuthorizationModel, error) // ReadAuthorizationModels Read all type definitions ids for the supplied store. ReadAuthorizationModels(ctx context.Context, store string, options PaginationOptions) ([]*openfgapb.AuthorizationModel, []byte, error) FindLatestAuthorizationModelID(ctx context.Context, store string) (string, error) }
AuthorizationModelReadBackend Provides a Read interface for managing type definitions.
type ChangelogBackend ¶
type ChangelogBackend interface { // ReadChanges returns the writes and deletes that have occurred for tuples of a given object type within a store. // The horizonOffset should be specified using a unit no more granular than a millisecond and should be interpreted // as a millisecond duration. ReadChanges(ctx context.Context, store, objectType string, paginationOptions PaginationOptions, horizonOffset time.Duration) ([]*openfgapb.TupleChange, []byte, error) }
type ContextTracerWrapper ¶
type ContextTracerWrapper struct {
OpenFGADatastore
}
ContextTracerWrapper is a wrapper around a datastore that passes a new context to the underlying datastore methods. It must be the first wrapper around the datastore if traces are to work properly.
func NewContextWrapper ¶
func NewContextWrapper(inner OpenFGADatastore) *ContextTracerWrapper
func (*ContextTracerWrapper) Close ¶
func (c *ContextTracerWrapper) Close()
func (*ContextTracerWrapper) Read ¶
func (c *ContextTracerWrapper) Read(ctx context.Context, store string, tupleKey *openfgapb.TupleKey) (TupleIterator, error)
func (*ContextTracerWrapper) ReadStartingWithUser ¶
func (c *ContextTracerWrapper) ReadStartingWithUser(ctx context.Context, store string, opts ReadStartingWithUserFilter) (TupleIterator, error)
func (*ContextTracerWrapper) ReadUserTuple ¶
func (*ContextTracerWrapper) ReadUsersetTuples ¶
func (c *ContextTracerWrapper) ReadUsersetTuples(ctx context.Context, store string, filter ReadUsersetTuplesFilter) (TupleIterator, error)
type Iterator ¶
type Iterator[T any] interface { // Next will return the next available item. Next() (T, error) // Stop terminates iteration over the underlying iterator. Stop() }
func NewCombinedIterator ¶
NewCombinedIterator takes generic iterators of a given type T and combines them into a single iterator that yields all the values from all iterators. Duplicates can be returned.
type ObjectIterator ¶
ObjectIterator is an iterator for Objects (type + id). It is closed by explicitly calling Stop() or by calling Next() until it returns an ErrIteratorDone error.
func NewObjectIteratorFromTupleKeyIterator ¶
func NewObjectIteratorFromTupleKeyIterator(iter TupleKeyIterator) ObjectIterator
NewObjectIteratorFromTupleKeyIterator takes a TupleKeyIterator and yields all the objects from it as a ObjectIterator.
func NewStaticObjectIterator ¶
func NewStaticObjectIterator(objects []*openfgapb.Object) ObjectIterator
NewStaticObjectIterator returns an ObjectIterator that iterates over the provided slice of objects.
func NewTupleKeyObjectIterator ¶
func NewTupleKeyObjectIterator(tupleKeys []*openfgapb.TupleKey) ObjectIterator
NewTupleKeyObjectIterator returns an ObjectIterator that iterates over the objects contained in the provided list of TupleKeys.
func NewUniqueObjectIterator ¶
func NewUniqueObjectIterator(iter1, iter2 ObjectIterator) ObjectIterator
NewUniqueObjectIterator returns an ObjectIterator that iterates over two ObjectIterators and yields only distinct objects with the duplicates removed.
iter1 should generally be provided by a constrained iterator (e.g. contextual tuples) and iter2 should be provided by a storage iterator that already guarantees uniqueness.
Example ¶
contextualTuples := []*openfgapb.TupleKey{ tuple.NewTupleKey("document:doc1", "viewer", "jon"), tuple.NewTupleKey("document:doc1", "viewer", "elbuo"), } iter1 := NewTupleKeyObjectIterator(contextualTuples) // this would generally be a database call iter2 := NewStaticObjectIterator([]*openfgapb.Object{ { Type: "document", Id: "doc1", }, { Type: "document", Id: "doc2", }, }) // pass the contextual tuples iterator (iter1) first since it's more // constrained than the other iterator (iter2). In practice iter2 will // be coming from a database that should guarantee uniqueness over the // objects yielded. iter := NewUniqueObjectIterator(iter1, iter2) defer iter.Stop() var objects []string for { obj, err := iter.Next() if err != nil { if err == ErrIteratorDone { break } // handle the error in some way panic(err) } objects = append(objects, tuple.ObjectKey(obj)) } fmt.Println(objects)
Output: [document:doc1 document:doc2]
type OpenFGADatastore ¶
type OpenFGADatastore interface { TupleBackend AuthorizationModelBackend StoresBackend AssertionsBackend ChangelogBackend // IsReady reports whether the datastore is ready to accept traffic. IsReady(ctx context.Context) (bool, error) // Close closes the datastore and cleans up any residual resources. Close() }
type PaginationOptions ¶
func NewPaginationOptions ¶
func NewPaginationOptions(ps int32, contToken string) PaginationOptions
type ReadStartingWithUserFilter ¶
type ReadStartingWithUserFilter struct { ObjectType string Relation string UserFilter []*openfgapb.ObjectRelation }
ReadStartingWithUserFilter specifies the filter options that will be used to constrain the ReadStartingWithUser query.
type ReadUsersetTuplesFilter ¶ added in v0.4.0
type ReadUsersetTuplesFilter struct { Object string // required Relation string // required AllowedUserTypeRestrictions []*openfgapb.RelationReference // optional }
type RelationshipTupleReader ¶
type RelationshipTupleReader interface { // Read the set of tuples associated with `store` and `TupleKey`, which may be nil or partially filled. If nil, // Read will return an iterator over all the `Tuple`s in the given store. If the `TupleKey` is partially filled, // it will return an iterator over those `Tuple`s which match the `TupleKey`. Note that at least one of `Object` // or `User` (or both), must be specified in this case. // // The caller must be careful to close the TupleIterator, either by consuming the entire iterator or by closing it. // There is NO guarantee on the order returned on the iterator. Read(context.Context, string, *openfgapb.TupleKey) (TupleIterator, error) // ReadPage is similar to Read, but with PaginationOptions. Instead of returning a TupleIterator, ReadPage // returns a page of tuples and a possibly non-empty continuation token. ReadPage( ctx context.Context, store string, tk *openfgapb.TupleKey, opts PaginationOptions, ) ([]*openfgapb.Tuple, []byte, error) // ReadUserTuple tries to return one tuple that matches the provided key exactly. ReadUserTuple( ctx context.Context, store string, tk *openfgapb.TupleKey, ) (*openfgapb.Tuple, error) // ReadUsersetTuples returns all userset tuples for a specified object and relation. // For example, given the following relationship tuples: // document:doc1, viewer, user:* // document:doc1, viewer, group:eng#member // and the filter // object=document:1, relation=viewer, allowedTypesForUser=[group#member] // this method would return the tuple (document:doc1, viewer, group:eng#member) // If allowedTypesForUser is empty, both tuples would be returned. ReadUsersetTuples( ctx context.Context, store string, filter ReadUsersetTuplesFilter, ) (TupleIterator, error) // ReadStartingWithUser performs a reverse read of relationship tuples starting at one or // more user(s) or userset(s) and filtered by object type and relation. // // For example, given the following relationship tuples: // document:doc1, viewer, user:jon // document:doc2, viewer, group:eng#member // document:doc3, editor, user:jon // // ReverseReadTuples for ['user:jon', 'group:eng#member'] filtered by 'document#viewer' would // return ['document:doc1#viewer@user:jon', 'document:doc2#viewer@group:eng#member']. ReadStartingWithUser( ctx context.Context, store string, filter ReadStartingWithUserFilter, ) (TupleIterator, error) // ListObjectsByType returns all the objects of a specific type. // You can assume that the type has already been validated. // The result can't have duplicate elements. ListObjectsByType( ctx context.Context, store string, objectType string, ) (ObjectIterator, error) }
func NewCombinedTupleReader ¶ added in v0.4.3
func NewCombinedTupleReader(ds RelationshipTupleReader, contextualTuples []*openfgapb.TupleKey) RelationshipTupleReader
NewCombinedTupleReader returns a TupleReader that reads from a persistent datastore and from the contextual tuples specified in the request
type RelationshipTupleWriter ¶
type RelationshipTupleWriter interface { // Write updates data in the tuple backend, performing all delete operations in // `deletes` before adding new values in `writes`, returning the time of the transaction, or an error. // It is expected that // - there is at most 10 deletes/writes // - no duplicate item in delete/write list Write(ctx context.Context, store string, d Deletes, w Writes) error // MaxTuplesPerWrite returns the maximum number of items allowed in a single write transaction MaxTuplesPerWrite() int }
type StoresBackend ¶
type StoresBackend interface { CreateStore(ctx context.Context, store *openfgapb.Store) (*openfgapb.Store, error) DeleteStore(ctx context.Context, id string) error GetStore(ctx context.Context, id string) (*openfgapb.Store, error) ListStores(ctx context.Context, paginationOptions PaginationOptions) ([]*openfgapb.Store, []byte, error) }
type TupleBackend ¶
type TupleBackend interface { RelationshipTupleReader RelationshipTupleWriter }
A TupleBackend provides an R/W interface for managing tuples.
type TupleIterator ¶
TupleIterator is an iterator for Tuples. It is closed by explicitly calling Stop() or by calling Next() until it returns an ErrIteratorDone error.
func NewStaticTupleIterator ¶
func NewStaticTupleIterator(tuples []*openfgapb.Tuple) TupleIterator
NewStaticTupleIterator returns a TupleIterator that iterates over the provided slice.
type TupleKeyFilterFunc ¶
TupleKeyFilterFunc is a filter function that is used to filter out tuples from a TupleKey iterator that don't meet some criteria. Implementations should return true if the tuple should be returned and false if it should be filtered out.
type TupleKeyIterator ¶
TupleKeyIterator is an iterator for TupleKeys. It is closed by explicitly calling Stop() or by calling Next() until it returns an ErrIteratorDone error.
func NewFilteredTupleKeyIterator ¶
func NewFilteredTupleKeyIterator(iter TupleKeyIterator, filter TupleKeyFilterFunc) TupleKeyIterator
NewFilteredTupleKeyIterator returns an iterator that filters out all tuples that don't meet the conditions of the provided TupleFilterFunc.
Example ¶
tuples := []*openfgapb.TupleKey{ tuple.NewTupleKey("document:doc1", "viewer", "user:jon"), tuple.NewTupleKey("document:doc1", "editor", "user:elbuo"), } iter := NewFilteredTupleKeyIterator( NewStaticTupleKeyIterator(tuples), func(tk *openfgapb.TupleKey) bool { return tk.GetRelation() == "editor" }, ) defer iter.Stop() var filtered []string for { tuple, err := iter.Next() if err != nil { if err == ErrIteratorDone { break } // handle the error in some way panic(err) } filtered = append(filtered, fmt.Sprintf("%s#%s@%s", tuple.GetObject(), tuple.GetRelation(), tuple.GetUser())) } fmt.Println(filtered)
Output: [document:doc1#editor@user:elbuo]
func NewStaticTupleKeyIterator ¶
func NewStaticTupleKeyIterator(tupleKeys []*openfgapb.TupleKey) TupleKeyIterator
NewStaticTupleKeyIterator returns a TupleKeyIterator that iterates over the provided slice.
func NewTupleKeyIteratorFromTupleIterator ¶
func NewTupleKeyIteratorFromTupleIterator(iter TupleIterator) TupleKeyIterator
NewTupleKeyIteratorFromTupleIterator takes a TupleIterator and yields all of the TupleKeys from it as a TupleKeyIterator.
type TypeDefinitionReadBackend ¶
type TypeDefinitionReadBackend interface { // ReadTypeDefinition Read the store authorization model corresponding to `id` + `objectType`. ReadTypeDefinition(ctx context.Context, store, id string, objectType string) (*openfgapb.TypeDefinition, error) }
TypeDefinitionReadBackend Provides a Read interface for managing type definitions.
type TypeDefinitionWriteBackend ¶
type TypeDefinitionWriteBackend interface { // MaxTypesPerAuthorizationModel returns the maximum number of items allowed for type definitions MaxTypesPerAuthorizationModel() int // WriteAuthorizationModel writes an authorization model for the given store. // It is expected that the number of type definitions is less than or equal to 24 WriteAuthorizationModel(ctx context.Context, store string, model *openfgapb.AuthorizationModel) error }
TypeDefinitionWriteBackend Provides a write interface for managing typed definition.