selector

Documentation

Overview

Package selector

`selector` a generic server-side selector middleware for gRPC.

# Server Side Selector Middleware It allows to set check rules to allowlist or blocklist middleware such as Auth interceptors to toggle behavior on or off based on the request path.

Please see examples for simple examples of use.

Example (Login)

package main

import (
	"context"

	"github.com/grpc-ecosystem/go-grpc-middleware/v2/interceptors"
	"github.com/grpc-ecosystem/go-grpc-middleware/v2/interceptors/auth"
	"github.com/grpc-ecosystem/go-grpc-middleware/v2/interceptors/logging"
	"github.com/grpc-ecosystem/go-grpc-middleware/v2/interceptors/selector"
	"google.golang.org/grpc"
	"google.golang.org/grpc/codes"
	"google.golang.org/grpc/status"
)

var tokenInfoKey struct{}

func parseToken(token string) (struct{}, error) {
	return struct{}{}, nil
}

func userClaimFromToken(struct{}) string {
	return "foobar"
}

// exampleAuthFunc is used by a middleware to authenticate requests
func exampleAuthFunc(ctx context.Context) (context.Context, error) {
	token, err := auth.AuthFromMD(ctx, "bearer")
	if err != nil {
		return nil, err
	}

	tokenInfo, err := parseToken(token)
	if err != nil {
		return nil, status.Errorf(codes.Unauthenticated, "invalid auth token: %v", err)
	}

	ctx = logging.InjectFields(ctx, logging.Fields{"auth.sub", userClaimFromToken(tokenInfo)})

	return context.WithValue(ctx, tokenInfoKey, tokenInfo), nil
}

func loginSkip(_ context.Context, c interceptors.CallMeta) bool {
	return c.FullMethod() != "/auth.v1.AuthService/Login"
}

func main() {
	_ = grpc.NewServer(
		grpc.ChainUnaryInterceptor(
			selector.UnaryServerInterceptor(auth.UnaryServerInterceptor(exampleAuthFunc), selector.MatchFunc(loginSkip)),
		),
		grpc.ChainStreamInterceptor(
			selector.StreamServerInterceptor(auth.StreamServerInterceptor(exampleAuthFunc), selector.MatchFunc(loginSkip)),
		),
	)
}

Example (Ratelimit)

package main

import (
	"context"

	"github.com/grpc-ecosystem/go-grpc-middleware/v2/interceptors"
	"github.com/grpc-ecosystem/go-grpc-middleware/v2/interceptors/ratelimit"
	"github.com/grpc-ecosystem/go-grpc-middleware/v2/interceptors/selector"
	"google.golang.org/grpc"
)

// alwaysPassLimiter is an example limiter which implements Limiter interface.
// It does not limit any request because Limit function always returns false.
type alwaysPassLimiter struct{}

func (*alwaysPassLimiter) Limit(_ context.Context) error {
	return nil
}

func healthSkip(_ context.Context, c interceptors.CallMeta) bool {
	return c.FullMethod() != "/ping.v1.PingService/Health"
}

func main() {
	limiter := &alwaysPassLimiter{}
	_ = grpc.NewServer(
		grpc.ChainUnaryInterceptor(
			selector.UnaryServerInterceptor(ratelimit.UnaryServerInterceptor(limiter), selector.MatchFunc(healthSkip)),
		),
		grpc.ChainStreamInterceptor(
			selector.StreamServerInterceptor(ratelimit.StreamServerInterceptor(limiter), selector.MatchFunc(healthSkip)),
		),
	)
}

Index

• func StreamClientInterceptor(i grpc.StreamClientInterceptor, matcher Matcher) grpc.StreamClientInterceptor
• func StreamServerInterceptor(i grpc.StreamServerInterceptor, matcher Matcher) grpc.StreamServerInterceptor
• func UnaryClientInterceptor(i grpc.UnaryClientInterceptor, matcher Matcher) grpc.UnaryClientInterceptor
• func UnaryServerInterceptor(i grpc.UnaryServerInterceptor, matcher Matcher) grpc.UnaryServerInterceptor
• type Matcher
  • func MatchFunc(f func(ctx context.Context, callMeta interceptors.CallMeta) bool) Matcher

Examples

• Package (Login)
• Package (Ratelimit)

Functions

func StreamClientInterceptor

func StreamClientInterceptor(i grpc.StreamClientInterceptor, matcher Matcher) grpc.StreamClientInterceptor

StreamClientInterceptor returns a new stream client interceptor that will decide whether to call the interceptor based on the return argument from the Matcher. TODO(bwplotka): Write unit test.

func StreamServerInterceptor

func StreamServerInterceptor(i grpc.StreamServerInterceptor, matcher Matcher) grpc.StreamServerInterceptor

StreamServerInterceptor returns a new stream server interceptor that will decide whether to call the interceptor based on the return argument from the Matcher.

func UnaryClientInterceptor

func UnaryClientInterceptor(i grpc.UnaryClientInterceptor, matcher Matcher) grpc.UnaryClientInterceptor

UnaryClientInterceptor returns a new unary client interceptor that will decide whether to call the interceptor based on the return argument from the Matcher. TODO(bwplotka): Write unit test.

func UnaryServerInterceptor

func UnaryServerInterceptor(i grpc.UnaryServerInterceptor, matcher Matcher) grpc.UnaryServerInterceptor

UnaryServerInterceptor returns a new unary server interceptor that will decide whether to call the interceptor based on the return argument from the Matcher.

Types

type Matcher

type Matcher interface {
	// Match returns true, if given context and gRPC call metadata like type, service and method are matching.
	Match(ctx context.Context, callMeta interceptors.CallMeta) bool
}

Matcher allows matching.

func MatchFunc

func MatchFunc(f func(ctx context.Context, callMeta interceptors.CallMeta) bool) Matcher

MatchFunc return Matcher from closure.