Documentation
¶
Overview ¶
Package pep implements gRPC client for Policy Decision Point (PDP) server. PEP package (Policy Enforcement Point) wraps service part of golang gRPC protocol implementation. The protocol is defined by github.com/infobloxopen/themis/proto/service.proto. Its golang implementation can be found at github.com/infobloxopen/themis/pdp-service. PEP is able to work with single server as well as multiple servers balancing requests using round-robin approach.
Index ¶
- Constants
- Variables
- type Client
- type ConnectionStateNotificationCallback
- type OnCacheHitHandler
- type Option
- func WithAutoRequestSize(b bool) Option
- func WithCacheTTL(ttl time.Duration) Option
- func WithCacheTTLAndMaxSize(ttl time.Duration, size int) Option
- func WithConnectionStateNotification(callback ConnectionStateNotificationCallback) Option
- func WithConnectionTimeout(timeout time.Duration) Option
- func WithContext(ctx context.Context) Option
- func WithHotSpotBalancer(addresses ...string) Option
- func WithMaxRequestSize(size uint32) Option
- func WithNoRequestBufferPool() Option
- func WithOnCacheHitHandler(h OnCacheHitHandler) Option
- func WithRoundRobinBalancer(addresses ...string) Option
- func WithStreams(n int) Option
- func WithTracer(tracer ot.Tracer) Option
Constants ¶
const ( // StreamingConnectionEstablished stands for succesfully established connection. StreamingConnectionEstablished = iota // StreamingConnectionBroken is passed to notification callback when // connection appears broken during a validation call. StreamingConnectionBroken // StreamingConnectionConnecting marks a connection attempt. StreamingConnectionConnecting // StreamingConnectionFailure used when a connection attempt fails. // In the case err gets value of an error occured. StreamingConnectionFailure )
StreamingConnection* constants designate different states of connection to particular PDP on notification callback call.
Variables ¶
var ( // ErrorConnected occurs if method connect is called after connection has been established. ErrorConnected = errors.New("connection has been already established") // ErrorNotConnected indicates that there is no connection established to PDP server. ErrorNotConnected = errors.New("no connection") // ErrorHotSpotBalancerUnsupported returned by attempt to make unary connection with // "hot spot" balancer. ErrorHotSpotBalancerUnsupported = errors.New("\"hot spot\" balancer isn't supported by unary gRPC client") )
var ( // ErrorInvalidSource indicates that input value of validate method is not // a structure. ErrorInvalidSource = errors.New("given value is not a structure") // ErrorInvalidSlice indicates that input structure has slice field // (client can't marshal slices). ErrorInvalidSlice = errors.New("marshalling for the slice hasn't been implemented") // ErrorInvalidStruct indicates that input structure has struct field // (client can't marshal nested structures). ErrorInvalidStruct = errors.New("marshalling for the struct hasn't been implemented") // ErrorIntegerOverflow indicates that input structure contains integer // which doesn't fit to int64. ErrorIntegerOverflow = errors.New("integer overflow") )
var ( // ErrorInvalidDestination indicates that output value of validate method is // not a structure. ErrorInvalidDestination = errors.New("given value is not a pointer to structure") )
Functions ¶
This section is empty.
Types ¶
type Client ¶
type Client interface {
// Connect establishes connection to given PDP server. It ignores address
// parameter if balancer is provided.
Connect(addr string) error
// Close terminates previously established connection if any.
// Close should silently return if connection hasn't been established yet or
// if it has been already closed.
Close()
// Validate sends decision request to PDP server and fills out response.
Validate(in, out interface{}) error
}
Client defines abstract PDP service client interface.
Marshalling and unmarshalling ¶
Validate method accepts as "in" argument any structure and pointer to any structure as "out" argument. If "in" argument is Request structure from github.com/infobloxopen/themis/pdp-service package, Validate passes it as is to server. Similarly if "out" argument is pointer to Response structure from the protocol package, Validate just copy data from server's response to the structure.
If "in" argument is just a structure, Validate marshals it to list of PDP attributes. If no fields contains format string, Validate tries to convert all exported fields to attributes. Any bool field is converted to boolean attribute, string - to string attribute, net.IP - to address, net.IPNet or *net.IPNet to network. Fields of other types are silently ingnored.
Marshalling can be ajusted more precisely with help of `pdp` key in format string. When some fields of "in" structure have format string, only fields with "pdp" key are converted to attributes. The key supports two option separated by comma. First is desired attribute name. Second - attribute type. Allowed types are: boolean, string, address, network and domain. Validate can convert only bool structure field to boolean attribute, string to string attribute, net.IP to address attribute, net.IPNet or *net.IPNet to network attribute and string to domain attribute.
Validate is also able to unmarshal server's response to structure. It accepts pointer to the structure as "out" argument. If no fields of the structure has format string, Validate assigns effect to Effect field, reason to Reason field and obligation attributes to other fields according to their names and types. Effect field can be of bool type (and becomes true if effect is Permit or false otherwise), integer (it gets one of Response_* constants form pdp-service package) or string (gets Response_Effect_name value). Reason should be a string field. Obligation attributes are assigned to fields with corresponding names if types of fields allow assignment if there is no field with appropriate name and type response attribute silently dropped. The same as for marshaling `pdp` key can control unmarshaling.
type ConnectionStateNotificationCallback ¶
ConnectionStateNotificationCallback is a function type for connection state notifications.
type OnCacheHitHandler ¶
type OnCacheHitHandler interface {
Handle(req interface{}, resp interface{}, err error)
}
type Option ¶
type Option func(*options)
An Option sets such options as balancer, tracer and number of streams.
func WithAutoRequestSize ¶
WithAutoRequestSize returns an Option which makes client automatically allocate buffer for decision request. By default request size is limited by 10KB. When the option is set MaxRequestSize is still used to determine cache limit.
func WithCacheTTL ¶
WithCacheTTL returns an Option which adds cache with given TTL for cached requests. Cache size isn't limited in the case and can consume all available memory on machine.
func WithCacheTTLAndMaxSize ¶
WithCacheTTLAndMaxSize returns an Option which adds cache with given TTL and size limit for entire cache in MB. When the limit is reached then new requests override the oldest ones.
func WithConnectionStateNotification ¶
func WithConnectionStateNotification(callback ConnectionStateNotificationCallback) Option
WithConnectionStateNotification returns an Option which sets connection state notification callback. The callback is called before connection attempt with state StreamingConnectionConnecting, on successfull connect with state StreamingConnectionEstablished. If connection attempt fails the callback is called with state StreamingConnectionFailure and with error occured during the attempt. State StreamingConnectionBroken is used when during request validation connection to any PDP server appears not working.
func WithConnectionTimeout ¶
WithConnectionTimeout returns an Option which sets validation timeout for the case when no connection can be established. Negative value means no timeout. Zero - don't wait for connection, fail immediately.
func WithContext ¶
WithContext returns an Option which sets context for the client. If nil, defaults to context.Background().
func WithHotSpotBalancer ¶
WithHotSpotBalancer returns an Option which sets "hot spot" balancer with given set of servers (the balancer can be applied for gRPC streaming connection).
func WithMaxRequestSize ¶
WithMaxRequestSize returns an Option which limits request size in bytes to given value. Default 10KB. WithAutoRequestSize overrides the option but it still affects cache size.
func WithNoRequestBufferPool ¶
func WithNoRequestBufferPool() Option
WithNoRequestBufferPool returns an Option which makes client allocate new buffer for each request.
func WithOnCacheHitHandler ¶
func WithOnCacheHitHandler(h OnCacheHitHandler) Option
func WithRoundRobinBalancer ¶
WithRoundRobinBalancer returns an Option which sets round-robin balancer with given set of servers.
func WithStreams ¶
WithStreams returns an Option which sets number of gRPC streams to run in parallel.
func WithTracer ¶
WithTracer returns an Option which sets OpenTracing tracer.
Source Files