grpc

Documentation

Overview

Package grpchelpers includes helpers to set up grpc connections.

Index

• func Dial(ctx context.Context, conf Config) (*grpc.ClientConn, error)
• func ProxyProofTarget(host string) string
• func ServiceConfig(serviceName string) string
• type Config

Functions

func Dial

func Dial(ctx context.Context, conf Config) (*grpc.ClientConn, error)

Dial wraps up a standard set of dial behaviours that most grpc clients will want to use. Using this will default to some grpc calls retrying if the name resolver does not provide a service config.

func ProxyProofTarget

func ProxyProofTarget(host string) string

ProxyProofTarget takes the host and if there is no proxy in place in the environment at all or if there is a proxy, but we should still use it for the given url, the returned host will include the dns:// prefix.

Note if this is used to avoid traffic going via a proxy then DNS based load balancing is disabled.

A Note On Proxies.

NO_PROXY domain names can't be honored with dns scheme because of https://github.com/grpc/grpc-go/issues/3401

The following doc... https://github.com/grpc/grpc/blob/master/doc/naming.md suggests that if no scheme prefix is used then the dns is used automatically, but this is a bit misleading.

The dns scheme does a lookup for any SRV and multiple A records amongst other things, to set up a list of servers. At this point the server addresses are all in the form ip:port. The thing is - nothing is actually connected at this point, connections are made lazily. Using the dns scheme supports client side per request load balancing.

If the dns scheme is not used then in fact go grpc uses a 'passthrough' scheme, which defers name resolution to the standard (dns) resolver at connection (dial) time passing through the server name, resolving to one IP. This obviously does not support client side per call balancing.

The detection of a proxy only happens during dialing, and it is the proxy environment variables that indicate whether a proxy should be used.

In the 'passthrough' case because we have the full domain during dialing the client can compare this with the list of domains in the NO_PROXY list. However, in the full dns scheme case we only have a list of IPs which don't match anything in the NO_PROXY list - so they are duly proxied. host should be the host part not including scheme, or have the dns scheme in which case the authority should not be present

func ServiceConfig

func ServiceConfig(serviceName string) string

ServiceConfig returns a JSON-encoded service config. Takes a service name as defined in the service's .proto file (e.g. "package.ServiceName").

Types

type Config

type Config struct {
	// Host is the grpc host URL typically in this form: "dns:///service.domain.:80" if load balancing is desired
	// otherwise the raw host should be provided without the dns:/// prefix.
	// If the dns:// load balancing scheme is indicated - authority is not accepted and should be empty
	Host string
	// ServiceName should be as it is defined in the service's .proto file
	// (e.g. "package.ServiceName").
	ServiceName string
	// Timeout is the maximum duration we allow any call to take. Note if this timeout is
	// hit then the default retries will not happen, it is up to the caller to decide on retry behaviour.
	Timeout time.Duration
}