goa: goa.design/goa/grpc/middleware Index | Files | Directories

package middleware

import "goa.design/goa/grpc/middleware"

Package middleware contains gRPC server and client interceptors that wraps unary and streaming RPCs to provide additional functionality.

This package contains the following middlewares:

* Logging server middleware for unary and streaming endpoints.
* Request ID server middleware for unary and streaming endpoints.
* Stream Canceler server middleware for canceling streaming requests.
* Tracing middleware for unary and streaming server and client.
* AWS X-Ray middleware for producing X-Ray segments for unary and streaming
  client and server.

Example to use the server middleware:

srv := grpc.NewServer(middleware.UnaryRequestID())

Example to use the client middleware:

conn, err := grpc.Dial(host,
    grpc.WithUnaryInterceptor(middleware.UnaryClientTrace()),
    grpc.WithStreamInterceptor(middleware.StreamClientTrace()),
)

Index

Package Files

canceler.go doc.go helpers.go log.go requestid.go trace.go

Constants

const (
    // TraceIDMetadataKey is the default name of the gRPC request metadata
    // key containing the current TraceID if any.
    TraceIDMetadataKey = "trace-id"

    // ParentSpanIDMetadataKey is the default name of the gRPC request metadata
    // key containing the parent span ID if any.
    ParentSpanIDMetadataKey = "parent-span-id"

    // SpanIDMetadataKey is the default name of the gRPC request metadata
    // containing the span ID if any.
    SpanIDMetadataKey = "span-id"
)
const (
    // RequestIDMetadataKey is the key containing the request ID in the gRPC
    // metadata.
    RequestIDMetadataKey = "x-request-id"
)

func MaxSamplingRate Uses

func MaxSamplingRate(r int) middleware.TraceOption

MaxSamplingRate is a wrapper for the top-level MaxSamplingRate.

func MetadataValue Uses

func MetadataValue(md metadata.MD, key string) string

MetadataValue returns the first value for the given metadata key if key exists, else returns an empty string.

func SampleSize Uses

func SampleSize(s int) middleware.TraceOption

SampleSize is a wrapper for the top-level SampleSize.

func SamplingPercent Uses

func SamplingPercent(p int) middleware.TraceOption

SamplingPercent is a wrapper for the top-level SamplingPercent.

func SpanIDFunc Uses

func SpanIDFunc(f middleware.IDFunc) middleware.TraceOption

SpanIDFunc is a wrapper for the top-level SpanIDFunc.

func StreamCanceler Uses

func StreamCanceler(ctx context.Context) grpc.StreamServerInterceptor

StreamCanceler provides a middleware that can be used to gracefully stop streaming requests. To stop streaming requests, simply pass in a context with cancellation and cancel the context. When the context given to the StreamCanceler is canceled, it does the following:

1. Stops accepting further streaming requests and returns the code
   Unavailable with message "server is stopping".
2. Cancels the context of all streaming requests. Your request handler
   should obey to the cancelation of request context.

Example:

var (
    ctxCancel  context.Context
    cancelFunc context.CancelFunc
)
ctxCancel, cancelFunc = context.WithCancel(parentCtx)
streamInterceptor := StreamCanceler(ctxCancel)
// Use the interceptor in your server and when you need to shutdown
// your server, simply cancel the context given to the StreamCanceler interceptor.
cancelFunc()

// In your application code, look for context cancellation and respond with proper code.
for {
    select {
    case <-ctx.Done():
        return status.Error(codes.Canceled, "canceled")
...

func StreamClientTrace Uses

func StreamClientTrace() grpc.StreamClientInterceptor

StreamClientTrace sets the outgoing stream request metadata with the trace information found in the context so that the downstream service may properly retrieve the parent span ID and trace ID.

Example:

conn, err := grpc.Dial(url, grpc.WithStreamInterceptor(StreamClientTrace()))

func StreamRequestID Uses

func StreamRequestID(options ...middleware.RequestIDOption) grpc.StreamServerInterceptor

StreamRequestID returns a middleware for streaming gRPC requests which initializes the stream metadata with a unique value under the RequestIDMetadata key. Optionally, it uses the incoming "x-request-id" request metadata key, if present, with or without a length limit to use as request ID. The default behavior is to always generate a new ID.

examples of use:

grpc.NewServer(grpc.UnaryInterceptor(middleware.StreamRequestID()))

// enable options for using "x-request-id" metadata key with length limit.
grpc.NewServer(grpc.UnaryInterceptor(middleware.StreamRequestID(
  middleware.UseXRequestIDMetadataOption(true),
  middleware.XRequestMetadataLimitOption(128))))

func StreamServerLog Uses

func StreamServerLog(l middleware.Logger) grpc.StreamServerInterceptor

StreamServerLog returns a middleware that logs incoming streaming gRPC requests and responses. The middleware uses the request ID set by the RequestID middleware or creates a short unique request ID if missing for each incoming request and logs it with the request and corresponding response details.

func StreamServerTrace Uses

func StreamServerTrace(opts ...middleware.TraceOption) grpc.StreamServerInterceptor

StreamServerTrace returns a server trace middleware that initializes the trace information in the streaming gRPC request context.

Example:

grpc.NewServer(grpc.StreamInterceptor(middleware.StreamServerTrace()))

// enable options
grpc.NewServer(grpc.StreamInterceptor(middleware.StreamServerTrace(
  middleware.TraceIDFunc(myTraceIDFunc),
  middleware.SpanIDFunc(mySpanIDFunc),
  middleware.MaxSamplingRate(50)))

func TraceIDFunc Uses

func TraceIDFunc(f middleware.IDFunc) middleware.TraceOption

TraceIDFunc is a wrapper for the top-level TraceIDFunc.

func UnaryClientTrace Uses

func UnaryClientTrace() grpc.UnaryClientInterceptor

UnaryClientTrace sets the outgoing unary request metadata with the trace information found in the context so that the downstream service may properly retrieve the parent span ID and trace ID.

Example:

conn, err := grpc.Dial(url, grpc.WithUnaryInterceptor(UnaryClientTrace()))

func UnaryRequestID Uses

func UnaryRequestID(options ...middleware.RequestIDOption) grpc.UnaryServerInterceptor

UnaryRequestID returns a middleware for unary gRPC requests which initializes the request metadata with a unique value under the RequestIDMetadata key. Optionally, it uses the incoming "x-request-id" request metadata key, if present, with or without a length limit to use as request ID. The default behavior is to always generate a new ID.

examples of use:

grpc.NewServer(grpc.UnaryInterceptor(middleware.UnaryRequestID()))

// enable options for using "x-request-id" metadata key with length limit.
grpc.NewServer(grpc.UnaryInterceptor(middleware.UnaryRequestID(
  middleware.UseXRequestIDMetadataOption(true),
  middleware.XRequestMetadataLimitOption(128))))

func UnaryServerLog Uses

func UnaryServerLog(l middleware.Logger) grpc.UnaryServerInterceptor

UnaryServerLog returns a middleware that logs incoming gRPC requests and outgoing responses. The middleware uses the request ID set by the RequestID middleware or creates a short unique request ID if missing for each incoming request and logs it with the request and corresponding response details.

The middleware logs the incoming requests gRPC method. It also logs the response gRPC status code, message length (in bytes), and timing information.

func UnaryServerTrace Uses

func UnaryServerTrace(opts ...middleware.TraceOption) grpc.UnaryServerInterceptor

UnaryServerTrace returns a server trace middleware that initializes the trace informartion in the unary gRPC request context.

Example:

grpc.NewServer(grpc.UnaryInterceptor(middleware.UnaryServerTrace()))

// enable options
grpc.NewServer(grpc.UnaryInterceptor(middleware.UnaryServerTrace(
  middleware.TraceIDFunc(myTraceIDFunc),
  middleware.SpanIDFunc(mySpanIDFunc),
  middleware.SamplingPercent(100)))

func UseXRequestIDMetadataOption Uses

func UseXRequestIDMetadataOption(f bool) middleware.RequestIDOption

UseXRequestIDMetadataOption enables/disables using "x-request-id" metadata.

func XRequestMetadataLimitOption Uses

func XRequestMetadataLimitOption(limit int) middleware.RequestIDOption

XRequestMetadataLimitOption sets the option for limiting "x-request-id" metadata length.

type WrappedServerStream Uses

type WrappedServerStream struct {
    grpc.ServerStream
    // contains filtered or unexported fields
}

WrappedServerStream overrides the Context() method of the grpc.ServerStream interface.

func NewWrappedServerStream Uses

func NewWrappedServerStream(ctx context.Context, ss grpc.ServerStream) *WrappedServerStream

NewWrappedServerStream returns a new wrapped grpc ServerStream.

func (*WrappedServerStream) Context Uses

func (w *WrappedServerStream) Context() context.Context

Context returns the context for the server stream.

Directories

PathSynopsis
xrayPackage xray contains unary and streaming server and client interceptors that create AWS X-Ray segments from the gRPC requests and responses and send the segments to an AWS X-ray daemon.

Package middleware imports 13 packages (graph) and is imported by 3 packages. Updated 2019-07-15. Refresh now. Tools for package owners.