api

Documentation

Index

• Constants
• Variables
• func DefaultGrpcDialOptions(hostport string, s UsesAuthorizer, additionalOpts ...grpc.DialOption) (opts []grpc.DialOption)
• func ListAllPaginated[ResponseType PaginatedResponse, RequestType PaginatedRequest, ResultType any](req RequestType, ...) (results []ResultType, err error)
• func Validate(req IncomingRequest) (err error)
• type Authorizer
  • func NewOAuthAuthorizerFromClientCredentials(config *clientcredentials.Config) Authorizer
  • func NewOAuthAuthorizerFromConfig(config *oauth2.Config, token *oauth2.Token) Authorizer
• type CloudServiceRequest
• type IncomingRequest
• type InitFuncOf
• type PageToken
  • func DecodePageToken(b64token string) (t *PageToken, err error)
  • func (*PageToken) Descriptor() ([]byte, []int)
  • func (t *PageToken) Encode() (b64token string, err error)
  • func (x *PageToken) GetSize() int32
  • func (x *PageToken) GetStart() int64
  • func (*PageToken) ProtoMessage()
  • func (x *PageToken) ProtoReflect() protoreflect.Message
  • func (x *PageToken) Reset()
  • func (x *PageToken) String() string
• type PaginatedRequest
• type PaginatedResponse
• type PayloadRequest
• type RPCConnection
  • func NewRPCConnection[T any](target string, newClientFunc func(cc grpc.ClientConnInterface) T, ...) *RPCConnection[T]
  • func (conn *RPCConnection[T]) Authorizer() Authorizer
  • func (conn *RPCConnection[T]) ForceReconnect()
  • func (conn *RPCConnection[T]) Invoke(ctx context.Context, method string, args interface{}, reply interface{}, ...) (err error)
  • func (conn *RPCConnection[T]) NewStream(ctx context.Context, desc *grpc.StreamDesc, method string, ...) (stream grpc.ClientStream, err error)
  • func (conn *RPCConnection[T]) SetAuthorizer(auth Authorizer)
• type StreamChannelOf
  • func (c *StreamChannelOf[StreamType, MsgType]) Send(msg MsgType)
• type StreamsOf
  • func NewStreamsOf[StreamType grpc.ClientStream, MsgType proto.Message](opts ...StreamsOfOption[StreamType, MsgType]) (s *StreamsOf[StreamType, MsgType])
  • func (s *StreamsOf[StreamType, MsgType]) CloseAll()
  • func (s *StreamsOf[StreamType, MsgType]) GetStream(target string, component string, init InitFuncOf[StreamType], ...) (c *StreamChannelOf[StreamType, MsgType], err error)
• type StreamsOfOption
  • func WithLogger[StreamType grpc.ClientStream, MsgType proto.Message](log *logrus.Entry) StreamsOfOption[StreamType, MsgType]
• type UsesAuthorizer

Constants

const IDField = "id"

IDField is the name of the ID field used in protobuf messages

const PageTokenField = "page_token"

PageTokenField is the protobuf field that contains our page token.

Variables

var (
	ErrInvalidColumnName = errors.New("column name is invalid")
	ErrEmptyRequest      = errors.New("empty request")
	ErrInvalidRequest    = errors.New("invalid request")
)

var (
	ErrMissingInitFunc = errors.New("missing stream initializer function")
)

var File_api_page_token_proto protoreflect.FileDescriptor

Functions

func DefaultGrpcDialOptions

func DefaultGrpcDialOptions(hostport string, s UsesAuthorizer, additionalOpts ...grpc.DialOption) (opts []grpc.DialOption)

DefaultGrpcDialOptions returns a set of sensible default list of grpc.DialOption values. It includes transport credentials and configures per-RPC credentials using an authorizer, if one is configured.

func ListAllPaginated

func ListAllPaginated[ResponseType PaginatedResponse, RequestType PaginatedRequest, ResultType any](
	req RequestType, list func(context.Context, RequestType, ...grpc.CallOption) (ResponseType, error),
	getter func(res ResponseType) []ResultType) (results []ResultType, err error)

ListAllPaginated invokes a List gRPC function that supports pagination, fetches all pages using individual calls and finally combines all results of all pages into a single slice. It executes the function specified in list using the req of RequestType. Afterwards, the function getter is executed to transform the response of the list calls into the results slice.

func Validate

func Validate(req IncomingRequest) (err error)

Validate validates an incoming request according to different criteria:

• If the request is nil, api.ErrEmptyRequest is returned
• The request is validated according to the generated validation method
• Lastly, if the request is a api.PaginatedRequest, an additional check is performed to ensure only valid columns are listed

Note: This function already returns a gRPC error, so the error can be returned directly without any wrapping in a request function.

Types

type Authorizer

type Authorizer interface {
	credentials.PerRPCCredentials
	oauth2.TokenSource
}

Authorizer represents an interface which provides a token used for authenticating a client in server-client communication. More specifically, this interfaces requires credentials.PerRPCCredentials, which enables this to be used by a gRPC client to communicate with a gRPC server that requires per-RPC credentials.

func NewOAuthAuthorizerFromClientCredentials

func NewOAuthAuthorizerFromClientCredentials(config *clientcredentials.Config) Authorizer

NewOAuthAuthorizerFromClientCredentials creates a new authorizer based on an OAuth 2.0 client credentials.

func NewOAuthAuthorizerFromConfig

func NewOAuthAuthorizerFromConfig(config *oauth2.Config, token *oauth2.Token) Authorizer

NewOAuthAuthorizerFromConfig creates a new authorizer based on an OAuth 2.0 config.

type CloudServiceRequest

type CloudServiceRequest = api.CloudServiceRequest

CloudServiceRequest represents any kind of RPC request, that contains a reference to a cloud service.

Note: GetCloudServiceId() is already implemented by the generated protobuf code for the following messages because they directly have a cloud_service id field:

• orchestrator.RemoveControlFromScopeRequest
• orchestrator.ListControlsInScopeRequest
• orchestrator.GetCloudServiceRequest
• orchestrator.RemoveCloudServiceRequest
• orchestrator.UpdateMetricConfigurationRequest
• orchestrator.GetMetricConfigurationRequest
• orchestrator.ListMetricConfigurationRequest
• orchestrator.MetricChangeEvent
• orchestrator.TargetOfEvaluation
• orchestrator.RemoveTargetOfEvaluationRequest
• orchestrator.GetTargetOfEvaluationRequest
• orchestrator.ListTargetsOfEvaluationRequest
• orchestrator.Certificate

All other requests, especially in cases where the cloud service ID is embedded in a sub-field need to explicitly implement this interface in order. This interface is for example used by authorization checks.

type IncomingRequest

type IncomingRequest interface {
	proto.Message
}

type InitFuncOf

type InitFuncOf[StreamType grpc.ClientStream] func(target string, additionalOpts ...grpc.DialOption) (stream StreamType, err error)

InitFuncOf describes a function with type parameters that creates any kind of stream towards a gRPC server specified in target and returns the stream or an error. Additional gRPC dial options can be specified in additionalOpts.

type PageToken

type PageToken struct {
	Start int64 `protobuf:"varint,1,opt,name=start,proto3" json:"start,omitempty"`
	Size  int32 `protobuf:"varint,2,opt,name=size,proto3" json:"size,omitempty"`
	// contains filtered or unexported fields
}

func DecodePageToken

func DecodePageToken(b64token string) (t *PageToken, err error)

DecodePageToken decodes a PageToken out of a base 64 URL encoded string.

func (*PageToken) Descriptor

func (*PageToken) Descriptor() ([]byte, []int)

Deprecated: Use PageToken.ProtoReflect.Descriptor instead.

func (*PageToken) Encode

func (t *PageToken) Encode() (b64token string, err error)

Encode encodes this page token into a base64 URL encoded string.

func (*PageToken) GetSize

func (x *PageToken) GetSize() int32

func (*PageToken) GetStart

func (x *PageToken) GetStart() int64

func (*PageToken) ProtoMessage

func (*PageToken) ProtoMessage()

func (*PageToken) ProtoReflect

func (x *PageToken) ProtoReflect() protoreflect.Message

func (*PageToken) Reset

func (x *PageToken) Reset()

func (*PageToken) String

func (x *PageToken) String() string

type PaginatedRequest

type PaginatedRequest interface {
	GetPageToken() string
	GetPageSize() int32
	GetOrderBy() string // For ordering
	GetAsc() bool       // For ordering
	proto.Message
}

PaginatedRequest contains the typical parameters for a paginated request, usually a request for a List gRPC call.

type PaginatedResponse

type PaginatedResponse interface {
	GetNextPageToken() string
}

PaginatedResponse contains the typical parameters for a paginated response, usually a response for a List gRPC call.

type PayloadRequest

type PayloadRequest = api.PayloadRequest

PayloadRequest describes any kind of requests that carries a certain payload. This is for example a Create/Update request carrying an embedded message, which should be updated or created.

type RPCConnection

type RPCConnection[T any] struct {
	// Target contains the target used in grpc.Dial. Ideally, this should not be changed after the first client call.
	Target string

	// Opts contain options used in grpc.Dial. Ideally, this should not be changed after the first client call.
	Opts []grpc.DialOption

	// Client contains a gRPC client that is used to issue the actual RPCs.
	Client T
	// contains filtered or unexported fields
}

RPCConnection is a helper struct that wraps all necessary information for a gRPC connection, which is established using grpc.Dial. It features transparent goroutine-safe lazy initialization of the connection by overloading the underlying grpc.ClientConn. The connection is established automatically once the first client call is made. If an io.EOF error is received the connection is tried to be re-established on the next client call.

func NewRPCConnection

func NewRPCConnection[T any](target string, newClientFunc func(cc grpc.ClientConnInterface) T, opts ...grpc.DialOption) *RPCConnection[T]

NewRPCConnection creates a new RPCConnection to the target using the specified function that creates a new client.

func (*RPCConnection[T]) Authorizer

func (conn *RPCConnection[T]) Authorizer() Authorizer

Authorizer implements UsesAuthorizer

func (*RPCConnection[T]) ForceReconnect

func (conn *RPCConnection[T]) ForceReconnect()

ForceReconnect drops the established gRPC client conn and forces a re-connect at the next client call.

func (*RPCConnection[T]) Invoke

func (conn *RPCConnection[T]) Invoke(ctx context.Context, method string, args interface{}, reply interface{}, opts ...grpc.CallOption) (err error)

Invoke implements grpc.ClientConnInterface.

func (*RPCConnection[T]) NewStream

func (conn *RPCConnection[T]) NewStream(ctx context.Context, desc *grpc.StreamDesc, method string, opts ...grpc.CallOption) (stream grpc.ClientStream, err error)

NewStream implements grpc.ClientConnInterface.

func (*RPCConnection[T]) SetAuthorizer

func (conn *RPCConnection[T]) SetAuthorizer(auth Authorizer)

SetAuthorizer implements UsesAuthorizer

type StreamChannelOf

type StreamChannelOf[StreamType grpc.ClientStream, MsgType proto.Message] struct {
	// contains filtered or unexported fields
}

StreamChannelOf provides a channel around a connection to a grpc.ClientStream to send messages of type MsgType to that particular stream, using an internal go routine. This is necessary, because gRPC does not allow sending to a stream from multiple goroutines directly.

func (*StreamChannelOf[StreamType, MsgType]) Send

func (c *StreamChannelOf[StreamType, MsgType]) Send(msg MsgType)

Send sends the message into the stream via the channel. Since this uses the receive operator on the channel, this function may block until the message is received on the sendLoop of this StreamChannelOf or if the buffer of the channel is full.

type StreamsOf

type StreamsOf[StreamType grpc.ClientStream, MsgType proto.Message] struct {
	// contains filtered or unexported fields
}

StreamsOf handles stream channels to multiple gRPC servers, identified by a unique target (usually host and port). Since gRPC does only allow to send to a stream using one goroutine, each stream provides a go channel that can be used to send messages to the particular stream.

A stream for a given target can be retrieved with the GetStream function, which automatically initializes the stream if it does not exist.

func NewStreamsOf

func NewStreamsOf[StreamType grpc.ClientStream, MsgType proto.Message](opts ...StreamsOfOption[StreamType, MsgType]) (s *StreamsOf[StreamType, MsgType])

NewStreamsOf creates a new StreamsOf object and initializes all the necessary objects for it.

func (*StreamsOf[StreamType, MsgType]) CloseAll

func (s *StreamsOf[StreamType, MsgType]) CloseAll()

CloseAll closes all streams

func (*StreamsOf[StreamType, MsgType]) GetStream

func (s *StreamsOf[StreamType, MsgType]) GetStream(target string, component string, init InitFuncOf[StreamType], opts ...grpc.DialOption) (c *StreamChannelOf[StreamType, MsgType], err error)

GetStream tries to retrieve a stream for the given target and component. If no stream exists, it tries to create a new stream using the supplied init function. An error is returned if the initialization is not successful.

type StreamsOfOption

type StreamsOfOption[StreamType grpc.ClientStream, MsgType proto.Message] func(*StreamsOf[StreamType, MsgType])

StreamsOfOption is a functional option type to configure the StreamOf type.

func WithLogger

func WithLogger[StreamType grpc.ClientStream, MsgType proto.Message](log *logrus.Entry) StreamsOfOption[StreamType, MsgType]

WithLogger can be used to specify a dedicated logger entry which is used for logging. Otherwise, the default logging entry of logrus is used.

type UsesAuthorizer

type UsesAuthorizer interface {
	SetAuthorizer(auth Authorizer)
	Authorizer() Authorizer
}

UsesAuthorizer is an interface to denote that a struct is willing to accept and use an Authorizer