grpcutil

README

grpcutil

grpcutil implements various utilities to simplify common gRPC APIs.

Documentation

Overview

Package grpcutil implements various utilities to simplify common gRPC APIs.

Index

• Constants
• Variables
• func NewAuthlessReflectionInterceptor(srv reflection.GRPCServer) reflection.GRPCServer
• func NoopUnaryInterceptor(ctx context.Context, req interface{}, _ *grpc.UnaryServerInfo, ...) (resp interface{}, err error)
• func RequireStatus(t *testing.T, expected codes.Code, err error)
• func SplitMethodName(fullMethodName string) (string, string)
• func WithBearerToken(token string) grpc.DialOption
• func WithCustomCertBytes(v verification, certsContents ...[]byte) (grpc.DialOption, error)
• func WithCustomCerts(v verification, certPaths ...string) (grpc.DialOption, error)
• func WithInsecureBearerToken(token string) grpc.DialOption
• func WithSystemCerts(v verification) (grpc.DialOption, error)
• func WrapMethods(svcDesc grpc.ServiceDesc, interceptors ...grpc.UnaryServerInterceptor) (wrapped *grpc.ServiceDesc)
• func WrapStreams(svcDesc grpc.ServiceDesc, interceptors ...grpc.StreamServerInterceptor) (wrapped *grpc.ServiceDesc)
• type AuthlessHealthServer
  • func NewAuthlessHealthServer() *AuthlessHealthServer
  • func (s *AuthlessHealthServer) SetServicesHealthy(svcDesc ...*grpc.ServiceDesc)
• type IgnoreAuthMixin
  • func (m IgnoreAuthMixin) AuthFuncOverride(ctx context.Context, _ string) (context.Context, error)

Examples

• WithBearerToken
• WithInsecureBearerToken
• WithSystemCerts

Constants

const (
	// SkipVerifyCA is a constant that improves the readability of functions
	// with the insecureSkipVerify parameter.
	SkipVerifyCA verification = iota

	// VerifyCA is a constant that improves the readability of functions
	// with the insecureSkipVerify parameter.
	VerifyCA
)

Variables

var DefaultUnaryMiddleware = []grpc.UnaryServerInterceptor{grpcvalidate.UnaryServerInterceptor()}

DefaultUnaryMiddleware is a recommended set of middleware that should each gracefully no-op if the middleware is not applicable.

Functions

func NewAuthlessReflectionInterceptor

func NewAuthlessReflectionInterceptor(srv reflection.GRPCServer) reflection.GRPCServer

NewAuthlessReflectionInterceptor creates a proxy GRPCServer which automatically converts ServerReflectionServer instances to ones that skip grpc auth middleware.

change: reflection.Register(srv) to: reflection.Register(grpcutil.NewAuthlessReflectionInterceptor(srv))

func NoopUnaryInterceptor

func NoopUnaryInterceptor(ctx context.Context, req interface{}, _ *grpc.UnaryServerInfo, handler grpc.UnaryHandler) (resp interface{}, err error)

NoopUnaryInterceptor is a gRPC middleware that does not do anything.

func RequireStatus

func RequireStatus(t *testing.T, expected codes.Code, err error)

RequireStatus asserts that an error is a gRPC error and returns the expected status code.

func SplitMethodName

func SplitMethodName(fullMethodName string) (string, string)

SplitMethodName is used to split service name and method name from the method string passed into Interceptors.

This function is vendored from: https://github.com/grpc-ecosystem/go-grpc-prometheus/blob/82c243799c991a7d5859215fba44a81834a52a71/util.go#L31-L37

Copyright 2016 Michal Witkowski. All Rights Reserved. Apache 2.0 Licensed

func WithBearerToken

func WithBearerToken(token string) grpc.DialOption

WithBearerToken returns a grpc.DialOption that adds a standard HTTP Bearer token to all requests sent from a client.

Example

package main

import (
	"log"

	"google.golang.org/grpc"

	"github.com/authzed/grpcutil"
)

func main() {
	withSystemCerts, err := grpcutil.WithSystemCerts(grpcutil.VerifyCA)
	if err != nil {
		log.Fatal(err)
	}

	_, err = grpc.Dial(
		"grpc.authzed.com:443",
		withSystemCerts,
		grpcutil.WithBearerToken("t_your_token_here_1234567deadbeef"),
	)
	if err != nil {
		log.Fatal(err)
	}
}

func WithCustomCertBytes

func WithCustomCertBytes(v verification, certsContents ...[]byte) (grpc.DialOption, error)

WithCustomCertBytes returns a grpc.DialOption for requiring TLS that is authenticated using a certificate authority chain provided in bytes.

func WithCustomCerts

func WithCustomCerts(v verification, certPaths ...string) (grpc.DialOption, error)

WithCustomCerts returns a grpc.DialOption for requiring TLS that is authenticated using a certificate authority chain provided as a path on disk.

If the path is a directory, all files are loaded.

func WithInsecureBearerToken

func WithInsecureBearerToken(token string) grpc.DialOption

WithInsecureBearerToken returns a grpc.DialOption that adds a standard HTTP Bearer token to all requests sent from an insecure client.

Must be used in conjunction with `insecure.NewCredentials()`.

Example

package main

import (
	"log"

	"google.golang.org/grpc"
	"google.golang.org/grpc/credentials/insecure"

	"github.com/authzed/grpcutil"
)

func main() {
	_, err := grpc.Dial(
		"grpc.authzed.com:443",
		grpc.WithTransportCredentials(insecure.NewCredentials()),
		grpcutil.WithInsecureBearerToken("t_your_token_here_1234567deadbeef"),
	)
	if err != nil {
		log.Fatal(err)
	}
}

func WithSystemCerts

func WithSystemCerts(v verification) (grpc.DialOption, error)

WithSystemCerts returns a grpc.DialOption that uses the system-provided certificate authority chain to verify the connection.

If one cannot be found, this falls back to using a vendored version of Mozilla's collection of root certificate authorities.

Example

package main

import (
	"log"

	"google.golang.org/grpc"

	"github.com/authzed/grpcutil"
)

func main() {
	withSysCerts, err := grpcutil.WithSystemCerts(grpcutil.VerifyCA)
	if err != nil {
		log.Fatal(err)
	}

	_, err = grpc.Dial("grpc.authzed.com:443", withSysCerts)
	if err != nil {
		log.Fatal(err)
	}
}

func WrapMethods

func WrapMethods(svcDesc grpc.ServiceDesc, interceptors ...grpc.UnaryServerInterceptor) (wrapped *grpc.ServiceDesc)

WrapMethods wraps all non-streaming endpoints with the given list of interceptors. It returns a copy of the ServiceDesc with the new wrapped methods.

func WrapStreams

func WrapStreams(svcDesc grpc.ServiceDesc, interceptors ...grpc.StreamServerInterceptor) (wrapped *grpc.ServiceDesc)

WrapStreams wraps all streaming endpoints with the given list of interceptors. It returns a copy of the ServiceDesc with the new wrapped methods.

Types

type AuthlessHealthServer

type AuthlessHealthServer struct {
	*health.Server
	IgnoreAuthMixin
}

AuthlessHealthServer implements a gRPC health endpoint that will ignore any auth requirements set by github.com/grpc-ecosystem/go-grpc-middleware/auth.

func NewAuthlessHealthServer

func NewAuthlessHealthServer() *AuthlessHealthServer

NewAuthlessHealthServer returns a new gRPC health server that ignores auth middleware.

func (*AuthlessHealthServer) SetServicesHealthy

func (s *AuthlessHealthServer) SetServicesHealthy(svcDesc ...*grpc.ServiceDesc)

SetServicesHealthy sets the service to SERVING

type IgnoreAuthMixin

type IgnoreAuthMixin struct{}

IgnoreAuthMixin is a struct that can be embedded to make a gRPC handler ignore any auth requirements set by the gRPC community auth middleware.

func (IgnoreAuthMixin) AuthFuncOverride

func (m IgnoreAuthMixin) AuthFuncOverride(ctx context.Context, _ string) (context.Context, error)

AuthFuncOverride implements the grpc_auth.ServiceAuthFuncOverride by performing a no-op.