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) ListObjectsByType(ctx context.Context, store string, objectType string) (ObjectIterator, error)
- 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 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 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. This is so that if the context gets cancelled (e.g by the client), the underlying database connection isn't closed. So, we let outstanding queries run their course even if the context gets cancelled to avoid database connection churning.
ContextTracerWrapper 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) ListObjectsByType ¶ added in v1.1.0
func (c *ContextTracerWrapper) ListObjectsByType(ctx context.Context, store string, objectType string) (ObjectIterator, error)
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. // The tuples returned are ordered by ULID. 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. // There is NO guarantee on the order returned on the iterator. 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']. // There is NO guarantee on the order returned on the iterator. 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. // There is NO guarantee on the order returned on the iterator. 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 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.