grpctransport

Documentation

Overview

Package grpctransport provides functionality for managing gRPC client connections to Google Cloud services.

Index

• type ClientCertProvider
• type GRPCClientConnPool
  • func Dial(ctx context.Context, secure bool, opts *Options) (GRPCClientConnPool, error)
• type InternalOptions
• type Options

Types

type ClientCertProvider

type ClientCertProvider = func(*tls.CertificateRequestInfo) (*tls.Certificate, error)

ClientCertProvider is a function that returns a TLS client certificate to be used when opening TLS connections. It follows the same semantics as crypto/tls.Config.GetClientCertificate.

type GRPCClientConnPool

type GRPCClientConnPool interface {
	// Connection returns a [google.golang.org/grpc.ClientConn] from the pool.
	//
	// ClientConn aren't returned to the pool and should not be closed directly.
	Connection() *grpc.ClientConn

	// Len returns the number of connections in the pool. It will always return
	// the same value.
	Len() int

	// Close closes every ClientConn in the pool. The error returned by Close
	// may be a single error or multiple errors.
	Close() error

	grpc.ClientConnInterface
	// contains filtered or unexported methods
}

GRPCClientConnPool is an interface that satisfies google.golang.org/grpc.ClientConnInterface and has some utility functions that are needed for connection lifecycle when using in a client library. It may be a pool or a single connection. This interface is not intended to, and can't be, implemented by others.

func Dial

func Dial(ctx context.Context, secure bool, opts *Options) (GRPCClientConnPool, error)

Dial returns a GRPCClientConnPool that can be used to communicate with a Google cloud service, configured with the provided Options. It automatically appends Authorization metadata to all outgoing requests.

type InternalOptions

type InternalOptions struct {
	// EnableNonDefaultSAForDirectPath overrides the default requirement for
	// using the default service account for DirectPath.
	EnableNonDefaultSAForDirectPath bool
	// EnableDirectPath overrides the default attempt to use DirectPath.
	EnableDirectPath bool
	// EnableDirectPathXds overrides the default DirectPath type. It is only
	// valid when DirectPath is enabled.
	EnableDirectPathXds bool
	// EnableJWTWithScope specifies if scope can be used with self-signed JWT.
	EnableJWTWithScope bool
	// DefaultAudience specifies a default audience to be used as the audience
	// field ("aud") for the JWT token authentication.
	DefaultAudience string
	// DefaultEndpointTemplate combined with UniverseDomain specifies
	// the default endpoint.
	DefaultEndpointTemplate string
	// DefaultMTLSEndpoint specifies the default mTLS endpoint.
	DefaultMTLSEndpoint string
	// DefaultScopes specifies the default OAuth2 scopes to be used for a
	// service.
	DefaultScopes []string
	// SkipValidation bypasses validation on Options. It should only be used
	// internally for clients that needs more control over their transport.
	SkipValidation bool
}

InternalOptions are only meant to be set by generated client code. These are not meant to be set directly by consumers of this package. Configuration in this type is considered EXPERIMENTAL and may be removed at any time in the future without warning.

type Options

type Options struct {
	// DisableTelemetry disables default telemetry (OpenTelemetry). An example
	// reason to do so would be to bind custom telemetry that overrides the
	// defaults.
	DisableTelemetry bool
	// DisableAuthentication specifies that no authentication should be used. It
	// is suitable only for testing and for accessing public resources, like
	// public Google Cloud Storage buckets.
	DisableAuthentication bool
	// Endpoint overrides the default endpoint to be used for a service.
	Endpoint string
	// Metadata is extra gRPC metadata that will be appended to every outgoing
	// request.
	Metadata map[string]string
	// GRPCDialOpts are dial options that will be passed to `grpc.Dial` when
	// establishing a`grpc.Conn“
	GRPCDialOpts []grpc.DialOption
	// PoolSize is specifies how many connections to balance between when making
	// requests. If unset or less than 1, the value defaults to 1.
	PoolSize int
	// Credentials used to add Authorization metadata to all requests. If set
	// DetectOpts are ignored.
	Credentials *auth.Credentials
	// ClientCertProvider is a function that returns a TLS client certificate to
	// be used when opening TLS connections. It follows the same semantics as
	// crypto/tls.Config.GetClientCertificate.
	ClientCertProvider ClientCertProvider
	// DetectOpts configures settings for detect Application Default
	// Credentials.
	DetectOpts *credentials.DetectOptions
	// UniverseDomain is the default service domain for a given Cloud universe.
	// The default value is "googleapis.com". This is the universe domain
	// configured for the client, which will be compared to the universe domain
	// that is separately configured for the credentials.
	UniverseDomain string
	// APIKey specifies an API key to be used as the basis for authentication.
	// If set DetectOpts are ignored.
	APIKey string
	// Logger is used for debug logging. If provided, logging will be enabled
	// at the loggers configured level. By default logging is disabled unless
	// enabled by setting GOOGLE_SDK_GO_LOGGING_LEVEL in which case a default
	// logger will be used. Optional.
	Logger *slog.Logger

	// InternalOptions are NOT meant to be set directly by consumers of this
	// package, they should only be set by generated client code.
	InternalOptions *InternalOptions
}

Options used to configure a GRPCClientConnPool from Dial.