storage

package
v0.3.2 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Jan 18, 2023 License: Apache-2.0 Imports: 7 Imported by: 0

Documentation

Index

Examples

Constants

View Source 
const (
	DefaultMaxTuplesPerWrite             = 100
	DefaultMaxTypesPerAuthorizationModel = 100
	DefaultPageSize                      = 50
)

Variables

View Source 
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.

View Source 
var ErrIteratorDone = errors.New("iterator done")

Functions

func ExceededMaxTypeDefinitionsLimitError 

func ExceededMaxTypeDefinitionsLimitError(limit int) error

func InvalidWriteInputError 

func InvalidWriteInputError(tk *openfgapb.TupleKey, operation openfgapb.TupleOperation) error

Types

type AssertionsBackend 

type AssertionsBackend interface {
	WriteAssertions(ctx context.Context, store, modelID string, assertions []*openfgapb.Assertion) error
	ReadAssertions(ctx context.Context, store, modelID string) ([]*openfgapb.Assertion, error)
}

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 Deletes 

type Deletes = []*openfgapb.TupleKey

type Iterator added in v0.2.1 

type Iterator[T any] interface {
	// Next will return the next available item. If the context is cancelled or times out, it should return ErrIteratorDone
	Next(ctx context.Context) (T, error)
	// Stop terminates iteration over the underlying iterator.
	Stop()
}

func NewCombinedIterator added in v0.2.1 

func NewCombinedIterator[T any](iter1, iter2 Iterator[T]) Iterator[T]

NewCombinedIterator takes two generic iterators of a given type T and combines them into a single iterator that yields all of the values from both iterators. If the two iterators yield the same value then duplicates will be returned.

type ObjectIterator added in v0.2.0 

type ObjectIterator = Iterator[*openfgapb.Object]

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 added in v0.3.0 

func NewObjectIteratorFromTupleKeyIterator(iter TupleKeyIterator) ObjectIterator

NewObjectIteratorFromTupleKeyIterator takes a TupleKeyIterator and yields all the objects from it as a ObjectIterator.

func NewStaticObjectIterator added in v0.2.1 

func NewStaticObjectIterator(objects []*openfgapb.Object) ObjectIterator

NewStaticObjectIterator returns an ObjectIterator that iterates over the provided slice of objects.

func NewTupleKeyObjectIterator added in v0.2.1 

func NewTupleKeyObjectIterator(tupleKeys []*openfgapb.TupleKey) ObjectIterator

NewTupleKeyObjectIterator returns an ObjectIterator that iterates over the objects contained in the provided list of TupleKeys.

func NewUniqueObjectIterator added in v0.2.1 

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(context.Background())
	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 

type PaginationOptions struct {
	PageSize int
	From     string
}

func NewPaginationOptions 

func NewPaginationOptions(ps int32, contToken string) PaginationOptions

type ReadStartingWithUserFilter added in v0.2.3 

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 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 {
	// 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.
	Read(context.Context, string, *openfgapb.TupleKey) (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)

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

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

	ReadUserTuple(
		ctx context.Context,
		store string,
		tk *openfgapb.TupleKey,
	) (*openfgapb.Tuple, error)

	ReadUsersetTuples(
		ctx context.Context,
		store string,
		tk *openfgapb.TupleKey,
	) (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)

	// MaxTuplesPerWrite returns the maximum number of items allowed in a single write transaction
	MaxTuplesPerWrite() int
}

A TupleBackend provides an R/W interface for managing tuples.

type TupleIterator 

type TupleIterator = Iterator[*openfgapb.Tuple]

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 added in v0.2.5 

func NewStaticTupleIterator(tuples []*openfgapb.Tuple) TupleIterator

NewStaticTupleIterator returns a TupleIterator that iterates over the provided slice.

type TupleKeyFilterFunc added in v0.3.0 

type TupleKeyFilterFunc func(tupleKey *openfgapb.TupleKey) bool

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 added in v0.2.1 

type TupleKeyIterator = Iterator[*openfgapb.TupleKey]

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 added in v0.3.0 

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(context.Background())
	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 added in v0.2.1 

func NewStaticTupleKeyIterator(tupleKeys []*openfgapb.TupleKey) TupleKeyIterator

NewStaticTupleKeyIterator returns a TupleKeyIterator that iterates over the provided slice.

func NewTupleKeyIteratorFromTupleIterator added in v0.2.1 

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.

type Writes 

type Writes = []*openfgapb.TupleKey

Source Files

View all Source files

Directories

Path Synopsis
Package mocks is a generated GoMock package.
 Package mocks is a generated GoMock package.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.