README
¶
GRPC Extensions
Extensions to the grpc-go library, for making GRPC more useful and/or easier to use.
Documentation
¶
Overview ¶
Package grpcext contains useful extensions to GRPC.
At the moment, the contents focus on interceptors and on metadata.
GRPC allows applications to register up to one interceptor for unary RPCs and up to one interceptor for streaming RPCs. But it does not provide any way to unify the two -- when you need an interceptor that handles both unary and streaming RPCs. Also, it only allows for exactly one interceptor, not multiple. So this package has some new things to address that:
- This package contains adapters so that stream interceptors can be used to intercept unary RPCs. This allows an interceptor to be written once and used in all contexts. Note that the other direction (adapting a unary interceptor for a streaming RPC) is not really possible.
- This package includes generally useful functions for combining interceptors. So if you have multiple unary interceptors or multiple stream interceptors, these functions allow you to combine them into one, so that you can configure the GRPC client or server with it.
GRPC's metadata API (metadata.MD) is narrow. You have to query metadata via map usage. It fails to provide helper methods that will normalize keys (which are always lower-case) or that will conveniently handle the most common cases for extracting a single value when multiple are present. This package provides its own grpcext.MD type. Since its underlying map type is the same, it can be assigned from a metadata.MD with a simple type conversion, e.g.:
var md metadata.MD = metadata.Pairs("key1", "value1", "key2", "value2")
var extmd grpext.MD = grpcext.MD(md)
Index ¶
- func CombineStreamClientInterceptors(interceptors ...grpc.StreamClientInterceptor) grpc.StreamClientInterceptor
- func CombineStreamServerInterceptors(interceptors ...grpc.StreamServerInterceptor) grpc.StreamServerInterceptor
- func CombineUnaryClientInterceptors(interceptors ...grpc.UnaryClientInterceptor) grpc.UnaryClientInterceptor
- func CombineUnaryServerInterceptors(interceptors ...grpc.UnaryServerInterceptor) grpc.UnaryServerInterceptor
- func StreamClientInterceptorToUnary(interceptor grpc.StreamClientInterceptor) grpc.UnaryClientInterceptor
- func StreamServerInterceptorToUnary(interceptor grpc.StreamServerInterceptor) grpc.UnaryServerInterceptor
- func WithClientInterceptorsAsUnary(interceptors ...interface{}) grpc.DialOption
- func WithServerInterceptorsAsUnary(interceptors ...interface{}) grpc.ServerOption
- func WithStreamClientInterceptors(interceptors ...grpc.StreamClientInterceptor) grpc.DialOption
- func WithStreamServerInterceptors(interceptors ...grpc.StreamServerInterceptor) grpc.ServerOption
- func WithUnaryClientInterceptors(interceptors ...grpc.UnaryClientInterceptor) grpc.DialOption
- func WithUnaryServerInterceptors(interceptors ...grpc.UnaryServerInterceptor) grpc.ServerOption
- type MD
- func (md MD) Add(key, value string)
- func (md MD) Clone() MD
- func (md MD) Combine(other MD) MD
- func (md MD) Get(key string) string
- func (md MD) GetAll(key string) []string
- func (md MD) GetFirst(key string) string
- func (md MD) Merge(other MD)
- func (md MD) Remove(key string) bool
- func (md MD) RemoveValue(key, val string) bool
- func (md MD) Set(key, value string)
- func (md MD) With(key, value string) MD
- func (md MD) WithReplacement(key, value string) MD
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func CombineStreamClientInterceptors ¶
func CombineStreamClientInterceptors(interceptors ...grpc.StreamClientInterceptor) grpc.StreamClientInterceptor
CombineStreamClientInterceptors combines the given interceptors, in order, and returns a single resulting interceptor. The first interceptor given will be the first one invoked. It is passed a streamer that will actually invoke the next interceptor in the slice, and so on. The final interceptor given will be passed the original streamer.
func CombineStreamServerInterceptors ¶
func CombineStreamServerInterceptors(interceptors ...grpc.StreamServerInterceptor) grpc.StreamServerInterceptor
CombineStreamServerInterceptors combines the given interceptors, in order, and returns a single resulting interceptor. The first interceptor given will be the first one invoked. It is passed a handler that will actually invoke the next interceptor in the slice, and so on. The final interceptor given will be passed the original handler.
func CombineUnaryClientInterceptors ¶
func CombineUnaryClientInterceptors(interceptors ...grpc.UnaryClientInterceptor) grpc.UnaryClientInterceptor
CombineUnaryClientInterceptors combines the given interceptors, in order, and returns a single resulting interceptor. The first interceptor given will be the first one invoked. It is passed an invoker that will actually call the next interceptor in the slice, and so on. The final interceptor given will be passed the original invoker.
func CombineUnaryServerInterceptors ¶
func CombineUnaryServerInterceptors(interceptors ...grpc.UnaryServerInterceptor) grpc.UnaryServerInterceptor
CombineUnaryServerInterceptors combines the given interceptors, in order, and returns a single resulting interceptor. The first interceptor given will be the first one invoked. It is passed a handler that will actually invoke the next interceptor in the slice, and so on. The final interceptor given will be passed the original handler.
func StreamClientInterceptorToUnary ¶
func StreamClientInterceptorToUnary(interceptor grpc.StreamClientInterceptor) grpc.UnaryClientInterceptor
StreamClientInterceptorToUnary converts a GRPC stream interceptor into an equivalent unary interceptor. This lets you re-use stream interceptors for all kinds of RPCs.
func StreamServerInterceptorToUnary ¶
func StreamServerInterceptorToUnary(interceptor grpc.StreamServerInterceptor) grpc.UnaryServerInterceptor
StreamServerInterceptorToUnary converts a GRPC stream interceptor into an equivalent unary interceptor. This lets you re-use stream interceptors for all kinds of RPCs.
It is recommended to instead implement the ServerInterceptor interface (in this package), instead of either of the GRPC interceptor interfaces. While slightly less powerful, they are simpler to implement and are more easily adapted to both kinds of GRPC calls (so the result will be a more efficient unary interceptor than what this function returns).
func WithClientInterceptorsAsUnary ¶
func WithClientInterceptorsAsUnary(interceptors ...interface{}) grpc.DialOption
WithClientInterceptorsAsUnary returns a client DialOption, for configuring a GRPC client that uses the given interceptors with unary RPC methods. The given interceptors can be either unary or stream interceptors. Stream interceptors will be adapted to unary RPCs via StreamClientInterceptorToUnary.
func WithServerInterceptorsAsUnary ¶
func WithServerInterceptorsAsUnary(interceptors ...interface{}) grpc.ServerOption
WithServerInterceptorsAsUnary returns a ServerOption, for configuring a GRPC server that uses the given interceptors with unary RPC methods. The given interceptors can be either unary or stream interceptors. Stream interceptors will be adapted to unary RPCs via StreamServerInterceptorToUnary.
func WithStreamClientInterceptors ¶
func WithStreamClientInterceptors(interceptors ...grpc.StreamClientInterceptor) grpc.DialOption
WithStreamClientInterceptors returns a client DialOption, for configuring a GRPC client that uses the given interceptors with streaming RPC methods.
func WithStreamServerInterceptors ¶
func WithStreamServerInterceptors(interceptors ...grpc.StreamServerInterceptor) grpc.ServerOption
WithServerInterceptorsStream returns a ServerOption, for configuring a GRPC server that uses the given interceptors with streaming RPC methods.
func WithUnaryClientInterceptors ¶
func WithUnaryClientInterceptors(interceptors ...grpc.UnaryClientInterceptor) grpc.DialOption
WithUnaryClientInterceptors returns a client DialOption, for configuring a GRPC client that uses the given interceptors with unary RPC methods.
func WithUnaryServerInterceptors ¶
func WithUnaryServerInterceptors(interceptors ...grpc.UnaryServerInterceptor) grpc.ServerOption
WithUnaryServerInterceptors returns a ServerOption, for configuring a GRPC server that uses the given interceptors with unary RPC methods.
Types ¶
type MD ¶
MD represents metadata that can be accompanied with a GRPC request (as headers) or with a response (as headers or trailers). It can be type-converted from the GRPC's metadata.MD type, and provides a much fuller API.
func Create ¶
Create creates an MD with the given key + value pairs. The arguments must be even in number and alternating order of key then value, key then value, etc.
func New ¶
New creates an MD from the given map of metadata. The given map has a single value per key. But if the given map contains multiple entries for the same metadata key (e.g. vary only in case), the values will be merged with those associated with lesser keys (e.g. collate earlier based on case) coming before values associated with greater keys.
func NewMulti ¶
NewMulti creates an MD from the given map of metadata. The map may have multiple values per key. If the given map contains multiple entries for the same metadata key (e.g. vary only in case), the values will be merged with those associated with lesser keys (e.g. collate earlier based on case) coming before values associated with greater keys.
func (MD) Add ¶
Add updates the current metadata to include the given key and value. If values already exist for the given key, the given value will be appended to them. This is just like With except that it modifies the current metadata, in place, instead of returning a new object
func (MD) Clone ¶
Clone returns a new copy of this metadata. The returned metadata will be a deep copy that shares no storage with this object.
func (MD) Combine ¶
Combine returns the result of combining this metadata with the given set of metadata. Neither of the given metadata objects are modified: a new metadata object is returned. If both objects contain a given key, the values for that key are combined with this metadata object's values appearing before the given metadata object's values.
func (MD) Get ¶
Get returns the value associated with the given key. If there are multiple values then only the last value is returned. If there are no values associated with the given key then the empty string is returned.
func (MD) GetFirst ¶
GetFirst returns the first value associated with the given key. If there are no values associated with the given key then the empty string is returned.
func (MD) Merge ¶
Merge adds the given metadata to this object. If the given object contains keys that already exist in this metadata, its values are appended to existing values. This is just like Combine except that it modifies the current metadata, in place, instead of returning a new object.
func (MD) Remove ¶
Remove deletes the given key from this metadata, returning true if it was present and removed or false if the key did not exist.
func (MD) RemoveValue ¶
RemoveValue deletes the given value from the list of values for the given key from this metadata. It returns true if the given key and value were found and removed, or false if either the key or value were not found.
func (MD) Set ¶
Set updates the current metadata to include the given key and value. If values already exist for the given key, they will be replaced with the given single value. This is just like WithReplacement except that it modifies the current metadata, in place, instead of returning a new object.
func (MD) With ¶
With returns the contents of the current metadata, but with the given key and value added to it. If the given key already exists in this metadata, the returned metadata will include them, with the given value appended to them.
func (MD) WithReplacement ¶
WithReplacement returns the contents of the current metadata, but with the given key and value set. If the given key already exists in this metadata, the returned metadata will have only the given replacement value, ignoring any existing values.
Source Files