Documentation ¶
Overview ¶
Package server contains the endpoint handlers.
Index ¶
- type ExperimentalFeatureFlag
- type OpenFGAServiceV1Option
- func WithChangelogHorizonOffset(offset int) OpenFGAServiceV1Option
- func WithCheckQueryCacheEnabled(enabled bool) OpenFGAServiceV1Option
- func WithCheckQueryCacheLimit(limit uint32) OpenFGAServiceV1Option
- func WithCheckQueryCacheTTL(ttl time.Duration) OpenFGAServiceV1Option
- func WithDatastore(ds storage.OpenFGADatastore) OpenFGAServiceV1Option
- func WithDispatchThrottlingCheckResolverEnabled(enabled bool) OpenFGAServiceV1Option
- func WithDispatchThrottlingCheckResolverFrequency(frequency time.Duration) OpenFGAServiceV1Option
- func WithDispatchThrottlingCheckResolverMaxThreshold(maxThreshold uint32) OpenFGAServiceV1Option
- func WithDispatchThrottlingCheckResolverThreshold(defaultThreshold uint32) OpenFGAServiceV1Option
- func WithExperimentals(experimentals ...ExperimentalFeatureFlag) OpenFGAServiceV1Option
- func WithListObjectsDeadline(deadline time.Duration) OpenFGAServiceV1Option
- func WithListObjectsMaxResults(limit uint32) OpenFGAServiceV1Option
- func WithListUsersDeadline(deadline time.Duration) OpenFGAServiceV1Option
- func WithListUsersMaxResults(limit uint32) OpenFGAServiceV1Option
- func WithLogger(l logger.Logger) OpenFGAServiceV1Option
- func WithMaxAuthorizationModelSizeInBytes(size int) OpenFGAServiceV1Option
- func WithMaxConcurrentReadsForCheck(max uint32) OpenFGAServiceV1Option
- func WithMaxConcurrentReadsForListObjects(max uint32) OpenFGAServiceV1Option
- func WithMaxConcurrentReadsForListUsers(max uint32) OpenFGAServiceV1Option
- func WithRequestDurationByDispatchCountHistogramBuckets(buckets []uint) OpenFGAServiceV1Option
- func WithRequestDurationByQueryHistogramBuckets(buckets []uint) OpenFGAServiceV1Option
- func WithResolveNodeBreadthLimit(limit uint32) OpenFGAServiceV1Option
- func WithResolveNodeLimit(limit uint32) OpenFGAServiceV1Option
- func WithTokenEncoder(encoder encoder.Encoder) OpenFGAServiceV1Option
- func WithTransport(t gateway.Transport) OpenFGAServiceV1Option
- type Server
- func (s *Server) Check(ctx context.Context, req *openfgav1.CheckRequest) (*openfgav1.CheckResponse, error)
- func (s *Server) Close()
- func (s *Server) CreateStore(ctx context.Context, req *openfgav1.CreateStoreRequest) (*openfgav1.CreateStoreResponse, error)
- func (s *Server) DeleteStore(ctx context.Context, req *openfgav1.DeleteStoreRequest) (*openfgav1.DeleteStoreResponse, error)
- func (s *Server) Expand(ctx context.Context, req *openfgav1.ExpandRequest) (*openfgav1.ExpandResponse, error)
- func (s *Server) GetStore(ctx context.Context, req *openfgav1.GetStoreRequest) (*openfgav1.GetStoreResponse, error)
- func (s *Server) IsExperimentallyEnabled(flag ExperimentalFeatureFlag) bool
- func (s *Server) IsReady(ctx context.Context) (bool, error)
- func (s *Server) ListObjects(ctx context.Context, req *openfgav1.ListObjectsRequest) (*openfgav1.ListObjectsResponse, error)
- func (s *Server) ListStores(ctx context.Context, req *openfgav1.ListStoresRequest) (*openfgav1.ListStoresResponse, error)
- func (s *Server) ListUsers(ctx context.Context, req *openfgav1.ListUsersRequest) (*openfgav1.ListUsersResponse, error)
- func (s *Server) Read(ctx context.Context, req *openfgav1.ReadRequest) (*openfgav1.ReadResponse, error)
- func (s *Server) ReadAssertions(ctx context.Context, req *openfgav1.ReadAssertionsRequest) (*openfgav1.ReadAssertionsResponse, error)
- func (s *Server) ReadAuthorizationModel(ctx context.Context, req *openfgav1.ReadAuthorizationModelRequest) (*openfgav1.ReadAuthorizationModelResponse, error)
- func (s *Server) ReadAuthorizationModels(ctx context.Context, req *openfgav1.ReadAuthorizationModelsRequest) (*openfgav1.ReadAuthorizationModelsResponse, error)
- func (s *Server) ReadChanges(ctx context.Context, req *openfgav1.ReadChangesRequest) (*openfgav1.ReadChangesResponse, error)
- func (s *Server) StreamedListObjects(req *openfgav1.StreamedListObjectsRequest, ...) error
- func (s *Server) Write(ctx context.Context, req *openfgav1.WriteRequest) (*openfgav1.WriteResponse, error)
- func (s *Server) WriteAssertions(ctx context.Context, req *openfgav1.WriteAssertionsRequest) (*openfgav1.WriteAssertionsResponse, error)
- func (s *Server) WriteAuthorizationModel(ctx context.Context, req *openfgav1.WriteAuthorizationModelRequest) (*openfgav1.WriteAuthorizationModelResponse, error)
Examples ¶
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
This section is empty.
Types ¶
type ExperimentalFeatureFlag ¶
type ExperimentalFeatureFlag string
const ( AuthorizationModelIDHeader = "Openfga-Authorization-Model-Id" ExperimentalEnableListUsers ExperimentalFeatureFlag = "enable-list-users" )
type OpenFGAServiceV1Option ¶ added in v1.3.0
type OpenFGAServiceV1Option func(s *Server)
func WithChangelogHorizonOffset ¶ added in v1.3.0
func WithChangelogHorizonOffset(offset int) OpenFGAServiceV1Option
WithChangelogHorizonOffset sets an offset (in minutes) from the current time. Changes that occur after this offset will not be included in the response of ReadChanges API. If your datastore is eventually consistent or if you have a database with replication delay, we recommend setting this (e.g. 1 minute).
func WithCheckQueryCacheEnabled ¶ added in v1.3.1
func WithCheckQueryCacheEnabled(enabled bool) OpenFGAServiceV1Option
WithCheckQueryCacheEnabled enables caching of Check results for the Check and List objects APIs. This cache is shared for all requests. See also WithCheckQueryCacheLimit and WithCheckQueryCacheTTL.
func WithCheckQueryCacheLimit ¶ added in v1.3.1
func WithCheckQueryCacheLimit(limit uint32) OpenFGAServiceV1Option
WithCheckQueryCacheLimit sets the cache size limit (in items) Needs WithCheckQueryCacheEnabled set to true.
func WithCheckQueryCacheTTL ¶ added in v1.3.1
func WithCheckQueryCacheTTL(ttl time.Duration) OpenFGAServiceV1Option
WithCheckQueryCacheTTL sets the TTL of cached checks and list objects partial results Needs WithCheckQueryCacheEnabled set to true.
func WithDatastore ¶ added in v1.3.0
func WithDatastore(ds storage.OpenFGADatastore) OpenFGAServiceV1Option
WithDatastore passes a datastore to the Server. You must call storage.OpenFGADatastore.Close on it after you have stopped using it.
func WithDispatchThrottlingCheckResolverEnabled ¶ added in v1.5.1
func WithDispatchThrottlingCheckResolverEnabled(enabled bool) OpenFGAServiceV1Option
WithDispatchThrottlingCheckResolverEnabled sets whether dispatch throttling is enabled. Enabling this feature will prioritize dispatched requests requiring less than the configured dispatch threshold over requests whose dispatch count exceeds the configured threshold.
func WithDispatchThrottlingCheckResolverFrequency ¶ added in v1.5.1
func WithDispatchThrottlingCheckResolverFrequency(frequency time.Duration) OpenFGAServiceV1Option
WithDispatchThrottlingCheckResolverFrequency defines how frequent dispatch throttling will be evaluated. Frequency controls how frequently throttled dispatch requests are evaluated to determine whether it can be processed. This value should not be too small (i.e., in the ns ranges) as i) there are limitation in timer resolution and ii) very small value will result in a higher frequency of processing dispatches, which diminishes the value of the throttling.
func WithDispatchThrottlingCheckResolverMaxThreshold ¶ added in v1.5.4
func WithDispatchThrottlingCheckResolverMaxThreshold(maxThreshold uint32) OpenFGAServiceV1Option
WithDispatchThrottlingCheckResolverMaxThreshold define the maximum threshold values allowed It will ensure dispatchThrottlingMaxThreshold will never be smaller than threshold.
func WithDispatchThrottlingCheckResolverThreshold ¶ added in v1.5.1
func WithDispatchThrottlingCheckResolverThreshold(defaultThreshold uint32) OpenFGAServiceV1Option
WithDispatchThrottlingCheckResolverThreshold define the number of dispatches to be throttled. In addition, it will update dispatchThrottlingMaxThreshold if required.
func WithExperimentals ¶ added in v1.3.0
func WithExperimentals(experimentals ...ExperimentalFeatureFlag) OpenFGAServiceV1Option
func WithListObjectsDeadline ¶ added in v1.3.0
func WithListObjectsDeadline(deadline time.Duration) OpenFGAServiceV1Option
WithListObjectsDeadline affect the ListObjects API only. It sets the maximum amount of time that the server will spend gathering results.
func WithListObjectsMaxResults ¶ added in v1.3.0
func WithListObjectsMaxResults(limit uint32) OpenFGAServiceV1Option
WithListObjectsMaxResults affects the ListObjects API only. It sets the maximum number of results that this API will return.
func WithListUsersDeadline ¶ added in v1.5.4
func WithListUsersDeadline(deadline time.Duration) OpenFGAServiceV1Option
WithListUsersDeadline affect the ListUsers API only. It sets the maximum amount of time that the server will spend gathering results.
func WithListUsersMaxResults ¶ added in v1.5.4
func WithListUsersMaxResults(limit uint32) OpenFGAServiceV1Option
WithListUsersMaxResults affects the ListUsers API only. It sets the maximum number of results that this API will return. If it's zero, all results will be attempted to be returned.
func WithLogger ¶ added in v1.3.0
func WithLogger(l logger.Logger) OpenFGAServiceV1Option
func WithMaxAuthorizationModelSizeInBytes ¶ added in v1.3.3
func WithMaxAuthorizationModelSizeInBytes(size int) OpenFGAServiceV1Option
func WithMaxConcurrentReadsForCheck ¶ added in v1.3.0
func WithMaxConcurrentReadsForCheck(max uint32) OpenFGAServiceV1Option
WithMaxConcurrentReadsForCheck sets a limit on the number of datastore reads that can be in flight for a given Check call. This number should be set depending on the RPS expected for Check and ListObjects APIs, the number of OpenFGA replicas running, and the number of connections the datastore allows. E.g. If Datastore.MaxOpenConns = 100 and assuming that each Check call takes 1 second and no traffic to ListObjects API: - One OpenFGA replica and expected traffic of 100 RPS => set it to 1. - One OpenFGA replica and expected traffic of 1 RPS => set it to 100. - Two OpenFGA replicas and expected traffic of 1 RPS => set it to 50.
func WithMaxConcurrentReadsForListObjects ¶ added in v1.3.0
func WithMaxConcurrentReadsForListObjects(max uint32) OpenFGAServiceV1Option
WithMaxConcurrentReadsForListObjects sets a limit on the number of datastore reads that can be in flight for a given ListObjects call. This number should be set depending on the RPS expected for Check and ListObjects APIs, the number of OpenFGA replicas running, and the number of connections the datastore allows. E.g. If Datastore.MaxOpenConns = 100 and assuming that each ListObjects call takes 1 second and no traffic to Check API: - One OpenFGA replica and expected traffic of 100 RPS => set it to 1. - One OpenFGA replica and expected traffic of 1 RPS => set it to 100. - Two OpenFGA replicas and expected traffic of 1 RPS => set it to 50.
func WithMaxConcurrentReadsForListUsers ¶ added in v1.5.4
func WithMaxConcurrentReadsForListUsers(max uint32) OpenFGAServiceV1Option
WithMaxConcurrentReadsForListUsers sets a limit on the number of datastore reads that can be in flight for a given ListUsers call. This number should be set depending on the RPS expected for all query APIs, the number of OpenFGA replicas running, and the number of connections the datastore allows. E.g. If Datastore.MaxOpenConns = 100 and assuming that each ListUsers call takes 1 second and no traffic to other query APIs: - One OpenFGA replica and expected traffic of 100 RPS => set it to 1. - One OpenFGA replica and expected traffic of 1 RPS => set it to 100. - Two OpenFGA replicas and expected traffic of 1 RPS => set it to 50.
func WithRequestDurationByDispatchCountHistogramBuckets ¶ added in v1.5.1
func WithRequestDurationByDispatchCountHistogramBuckets(buckets []uint) OpenFGAServiceV1Option
WithRequestDurationByDispatchCountHistogramBuckets sets the buckets used in labelling the requestDurationByQueryAndDispatchHistogram.
func WithRequestDurationByQueryHistogramBuckets ¶ added in v1.3.1
func WithRequestDurationByQueryHistogramBuckets(buckets []uint) OpenFGAServiceV1Option
WithRequestDurationByQueryHistogramBuckets sets the buckets used in labelling the requestDurationByQueryAndDispatchHistogram.
func WithResolveNodeBreadthLimit ¶ added in v1.3.0
func WithResolveNodeBreadthLimit(limit uint32) OpenFGAServiceV1Option
WithResolveNodeBreadthLimit sets a limit on the number of goroutines that can be created when evaluating a subtree of a Check, ListObjects or ListUsers call. Thinking of a Check request as a tree of evaluations, this option controls, on a given level of the tree, the maximum number of nodes that can be evaluated concurrently (the breadth). If your authorization models are very complex (e.g. one relation is a union of many relations, or one relation is deeply nested), or if you have lots of users for (object, relation) pairs, you should set this option to be a low number (e.g. 1000).
func WithResolveNodeLimit ¶ added in v1.3.0
func WithResolveNodeLimit(limit uint32) OpenFGAServiceV1Option
WithResolveNodeLimit sets a limit on the number of recursive calls that one Check, ListObjects or ListUsers call will allow. Thinking of a request as a tree of evaluations, this option controls how many levels we will evaluate before throwing an error that the authorization model is too complex.
func WithTokenEncoder ¶ added in v1.3.0
func WithTokenEncoder(encoder encoder.Encoder) OpenFGAServiceV1Option
func WithTransport ¶ added in v1.3.0
func WithTransport(t gateway.Transport) OpenFGAServiceV1Option
WithTransport sets the connection transport.
type Server ¶
type Server struct { openfgav1.UnimplementedOpenFGAServiceServer // contains filtered or unexported fields }
A Server implements the OpenFGA service backend as both a GRPC and HTTP server.
func MustNewServerWithOpts ¶ added in v1.3.0
func MustNewServerWithOpts(opts ...OpenFGAServiceV1Option) *Server
MustNewServerWithOpts see NewServerWithOpts.
func NewServerWithOpts ¶ added in v1.3.0
func NewServerWithOpts(opts ...OpenFGAServiceV1Option) (*Server, error)
NewServerWithOpts returns a new server. You must call Close on it after you are done using it.
Example ¶
datastore := memory.New() // other supported datastores include Postgres and MySQL defer datastore.Close() openfga, err := NewServerWithOpts(WithDatastore(datastore), WithCheckQueryCacheEnabled(true), // more options available ) if err != nil { panic(err) } defer openfga.Close() // create store store, err := openfga.CreateStore(context.Background(), &openfgav1.CreateStoreRequest{Name: "demo"}) if err != nil { panic(err) } model := language.MustTransformDSLToProto(` model schema 1.1 type user type document relations define reader: [user]`) // write the model to the store authorizationModel, err := openfga.WriteAuthorizationModel(context.Background(), &openfgav1.WriteAuthorizationModelRequest{ StoreId: store.GetId(), TypeDefinitions: model.GetTypeDefinitions(), Conditions: model.GetConditions(), SchemaVersion: model.GetSchemaVersion(), }) if err != nil { panic(err) } // write tuples to the store _, err = openfga.Write(context.Background(), &openfgav1.WriteRequest{ StoreId: store.GetId(), Writes: &openfgav1.WriteRequestWrites{ TupleKeys: []*openfgav1.TupleKey{ {Object: "document:budget", Relation: "reader", User: "user:anne"}, }, }, Deletes: nil, }) if err != nil { panic(err) } // make an authorization check checkResponse, err := openfga.Check(context.Background(), &openfgav1.CheckRequest{ StoreId: store.GetId(), AuthorizationModelId: authorizationModel.GetAuthorizationModelId(), // optional, but recommended for speed TupleKey: &openfgav1.CheckRequestTupleKey{ User: "user:anne", Relation: "reader", Object: "document:budget", }, }) if err != nil { panic(err) } fmt.Println(checkResponse.GetAllowed())
Output: true
func (*Server) Check ¶
func (s *Server) Check(ctx context.Context, req *openfgav1.CheckRequest) (*openfgav1.CheckResponse, error)
func (*Server) Close ¶ added in v1.4.3
func (s *Server) Close()
Close releases the server resources.
func (*Server) CreateStore ¶
func (s *Server) CreateStore(ctx context.Context, req *openfgav1.CreateStoreRequest) (*openfgav1.CreateStoreResponse, error)
func (*Server) DeleteStore ¶
func (s *Server) DeleteStore(ctx context.Context, req *openfgav1.DeleteStoreRequest) (*openfgav1.DeleteStoreResponse, error)
func (*Server) Expand ¶
func (s *Server) Expand(ctx context.Context, req *openfgav1.ExpandRequest) (*openfgav1.ExpandResponse, error)
func (*Server) GetStore ¶
func (s *Server) GetStore(ctx context.Context, req *openfgav1.GetStoreRequest) (*openfgav1.GetStoreResponse, error)
func (*Server) IsExperimentallyEnabled ¶ added in v1.5.4
func (s *Server) IsExperimentallyEnabled(flag ExperimentalFeatureFlag) bool
func (*Server) IsReady ¶
IsReady reports whether the datastore is ready. Please see the implementation of [storage.OpenFGADatastore.IsReady] for your datastore.
func (*Server) ListObjects ¶
func (s *Server) ListObjects(ctx context.Context, req *openfgav1.ListObjectsRequest) (*openfgav1.ListObjectsResponse, error)
func (*Server) ListStores ¶
func (s *Server) ListStores(ctx context.Context, req *openfgav1.ListStoresRequest) (*openfgav1.ListStoresResponse, error)
func (*Server) ListUsers ¶ added in v1.5.4
func (s *Server) ListUsers( ctx context.Context, req *openfgav1.ListUsersRequest, ) (*openfgav1.ListUsersResponse, error)
ListUsers returns all subjects (users) of a specified terminal type that are relate via specific relation to a specific object.
func (*Server) Read ¶
func (s *Server) Read(ctx context.Context, req *openfgav1.ReadRequest) (*openfgav1.ReadResponse, error)
func (*Server) ReadAssertions ¶
func (s *Server) ReadAssertions(ctx context.Context, req *openfgav1.ReadAssertionsRequest) (*openfgav1.ReadAssertionsResponse, error)
func (*Server) ReadAuthorizationModel ¶
func (s *Server) ReadAuthorizationModel(ctx context.Context, req *openfgav1.ReadAuthorizationModelRequest) (*openfgav1.ReadAuthorizationModelResponse, error)
func (*Server) ReadAuthorizationModels ¶
func (s *Server) ReadAuthorizationModels(ctx context.Context, req *openfgav1.ReadAuthorizationModelsRequest) (*openfgav1.ReadAuthorizationModelsResponse, error)
func (*Server) ReadChanges ¶
func (s *Server) ReadChanges(ctx context.Context, req *openfgav1.ReadChangesRequest) (*openfgav1.ReadChangesResponse, error)
func (*Server) StreamedListObjects ¶
func (s *Server) StreamedListObjects(req *openfgav1.StreamedListObjectsRequest, srv openfgav1.OpenFGAService_StreamedListObjectsServer) error
func (*Server) Write ¶
func (s *Server) Write(ctx context.Context, req *openfgav1.WriteRequest) (*openfgav1.WriteResponse, error)
func (*Server) WriteAssertions ¶
func (s *Server) WriteAssertions(ctx context.Context, req *openfgav1.WriteAssertionsRequest) (*openfgav1.WriteAssertionsResponse, error)
func (*Server) WriteAuthorizationModel ¶
func (s *Server) WriteAuthorizationModel(ctx context.Context, req *openfgav1.WriteAuthorizationModelRequest) (*openfgav1.WriteAuthorizationModelResponse, error)
Directories ¶
Path | Synopsis |
---|---|
Package commands contains the code that handles each endpoint.
|
Package commands contains the code that handles each endpoint. |
reverseexpand
Package reverseexpand contains the code that handles the ReverseExpand API
|
Package reverseexpand contains the code that handles the ReverseExpand API |
Package errors contains custom error codes that are sent to clients.
|
Package errors contains custom error codes that are sent to clients. |
Package health contains the service that check the health of an OpenFGA server.
|
Package health contains the service that check the health of an OpenFGA server. |