grpcgcp

Documentation

Overview

Package grpcgcp provides grpc supports for Google Cloud APIs. For now it provides connection management with affinity support.

Note: "channel" is analagous to "connection" in our context.

Usage:

1. First, initialize the api configuration. There are two ways:

1a. Create a json file defining the configuration and use `ParseAPIConfig()`
	to convert the json file to ApiConfig object.

	// Create some_api_config.json
	{
		"channelPool": {
			"maxSize": 10,
			"maxConcurrentStreamsLowWatermark": 1
		},
		"method": [
			{
				"name": [ "/some.api.v1/Method1" ],
				"affinity": {
					"command": "BIND",
					"affinityKey": "key1"
				}
			},
			{
				"name": [ "/some.api.v1/Method2" ],
				"affinity": {
					"command": "BOUND",
					"affinityKey": "key2"
				}
			},
			{
				"name": [ "/some.api.v1/Method3" ],
				"affinity": {
					"command": "UNBIND",
					"affinityKey": "key3"
				}
			}
		]
	}

	// Then convert json file to apiConfig object:

	apiConfig, err := grpcgcp.ParseAPIConfig("some_api_config.json")

1b. Create apiConfig directly.

	// import (
	// 	configpb "github.com/GoogleCloudPlatform/grpc-gcp-go/grpcgcp/grpc_gcp"
	// )

	apiConfig := &configpb.ApiConfig{
	ChannelPool: &configpb.ChannelPoolConfig{
		MaxSize:                          10,
		MaxConcurrentStreamsLowWatermark: 1,
	},
	Method: []*configpb.MethodConfig{
		&configpb.MethodConfig{
			Name: []string{"/some.api.v1/Method1"},
			Affinity: &configpb.AffinityConfig{
				Command:     configpb.AffinityConfig_BIND,
				AffinityKey: "key1",
			},
		},
		&configpb.MethodConfig{
			Name: []string{"/some.api.v1/Method2"},
			Affinity: &configpb.AffinityConfig{
				Command:     configpb.AffinityConfig_BOUND,
				AffinityKey: "key2",
			},
		},
		&configpb.MethodConfig{
			Name: []string{"/some.api.v1/Method3"},
			Affinity: &configpb.AffinityConfig{
				Command:     configpb.AffinityConfig_UNBIND,
				AffinityKey: "key3",
			},
		},
	},

2. Initialize GCPInterceptor.

gcpInt := grpcgcp.NewGCPInterceptor(apiConfig)

3. Make ClientConn with specific DialOptions to enable grpc_gcp load balancer.

conn, err := grpc.Dial(
	target,
	// Register and specify the grpc-gcp load balancer.
	grpc.WithBalancerName("grpc_gcp"),
	grpc.WithUnaryInterceptor(gcpInt.GCPUnaryClientInterceptor),
	grpc.WithStreamInterceptor(gcpInt.GCPStreamClientInterceptor),
)

Index

• Constants
• func ParseAPIConfig(path string) (*pb.ApiConfig, error)
• type GCPInterceptor
  • func NewGCPInterceptor(config *pb.ApiConfig) *GCPInterceptor
  • func (gcpInt *GCPInterceptor) GCPStreamClientInterceptor(ctx context.Context, desc *grpc.StreamDesc, cc *grpc.ClientConn, method string, ...) (grpc.ClientStream, error)
  • func (gcpInt *GCPInterceptor) GCPUnaryClientInterceptor(ctx context.Context, method string, req interface{}, reply interface{}, ...) error

Constants

const (
	// Name is the name of grpc_gcp balancer.
	Name = "grpc_gcp"
)

Functions

func ParseAPIConfig

func ParseAPIConfig(path string) (*pb.ApiConfig, error)

ParseAPIConfig parses a json config file into ApiConfig proto message.

Types

type GCPInterceptor

type GCPInterceptor struct {
	// contains filtered or unexported fields
}

GCPInterceptor provides functions for intercepting client requests in order to support GCP specific features

func NewGCPInterceptor

func NewGCPInterceptor(config *pb.ApiConfig) *GCPInterceptor

NewGCPInterceptor creates a new GCPInterceptor with a given ApiConfig

func (*GCPInterceptor) GCPStreamClientInterceptor

func (gcpInt *GCPInterceptor) GCPStreamClientInterceptor(
	ctx context.Context,
	desc *grpc.StreamDesc,
	cc *grpc.ClientConn,
	method string,
	streamer grpc.Streamer,
	opts ...grpc.CallOption,
) (grpc.ClientStream, error)

GCPStreamClientInterceptor intercepts the execution of a client streaming RPC and injects necessary information to be used by the picker.

func (*GCPInterceptor) GCPUnaryClientInterceptor

func (gcpInt *GCPInterceptor) GCPUnaryClientInterceptor(
	ctx context.Context,
	method string,
	req interface{},
	reply interface{},
	cc *grpc.ClientConn,
	invoker grpc.UnaryInvoker,
	opts ...grpc.CallOption,
) error

GCPUnaryClientInterceptor intercepts the execution of a unary RPC and injects necessary information to be used by the picker.