client

Documentation

Index

• Variables
• func Dial(rawAddress string, connOpts []grpc.DialOption) (*grpc.ClientConn, error)
• func DialContext(ctx context.Context, rawAddress string, connOpts []grpc.DialOption) (*grpc.ClientConn, error)
• func DialSidechannel(ctx context.Context, rawAddress string, sr *SidechannelRegistry, ...) (*grpc.ClientConn, error)
• func FailOnNonTempDialError() []grpc.DialOption
• func OpenServerSidechannel(ctx context.Context) (io.ReadWriteCloser, error)
• func ReceivePack(ctx context.Context, conn *grpc.ClientConn, stdin io.Reader, ...) (int32, error)
• func SidechannelServer(logger *logrus.Entry, creds credentials.TransportCredentials) grpc.ServerOption
• func TestSidechannelServer(logger *logrus.Entry, creds credentials.TransportCredentials, ...) []grpc.ServerOption
• func UploadArchive(ctx context.Context, conn *grpc.ClientConn, stdin io.Reader, ...) (int32, error)
• func UploadPack(ctx context.Context, conn *grpc.ClientConn, stdin io.Reader, ...) (int32, error)
• func UploadPackWithSidechannel(ctx context.Context, conn *grpc.ClientConn, reg *SidechannelRegistry, ...) (int32, error)
• func WithGitalyDNSResolver(opts *DNSResolverBuilderConfig) grpc.DialOption
• type DNSResolverBuilderConfig
  • func DefaultDNSResolverBuilderConfig() *DNSResolverBuilderConfig
• type Dialer
  • func HealthCheckDialer(base Dialer) Dialer
• type Pool
  • func NewPool(dialOptions ...grpc.DialOption) *Pool
  • func NewPoolWithOptions(poolOptions ...PoolOption) *Pool
  • func (p *Pool) Close() error
  • func (p *Pool) Dial(ctx context.Context, address, token string) (*grpc.ClientConn, error)
• type PoolOption
  • func WithDialOptions(dialOptions ...grpc.DialOption) PoolOption
  • func WithDialer(dialer Dialer) PoolOption
• type SidechannelConn
• type SidechannelRegistry
  • func NewSidechannelRegistry(logger *logrus.Entry) *SidechannelRegistry
  • func (sr *SidechannelRegistry) Register(ctx context.Context, callback func(SidechannelConn) error) (context.Context, *SidechannelWaiter)
• type SidechannelWaiter
  • func (w *SidechannelWaiter) Close() error

Variables

var DefaultDialOpts = []grpc.DialOption{}

DefaultDialOpts hold the default DialOptions for connection to Gitaly over UNIX-socket

Functions

func Dial

func Dial(rawAddress string, connOpts []grpc.DialOption) (*grpc.ClientConn, error)

Dial calls DialContext with the provided arguments and context.Background. Refer to DialContext's documentation for details.

func DialContext

func DialContext(ctx context.Context, rawAddress string, connOpts []grpc.DialOption) (*grpc.ClientConn, error)

DialContext dials the Gitaly at the given address with the provided options. Valid address formats are 'unix:<socket path>' for Unix sockets, 'tcp://<host:port>' for insecure TCP connections and 'tls://<host:port>' for TCP+TLS connections.

The returned ClientConns are configured with tracing and correlation id interceptors to ensure they are propagated correctly. They're also configured to send Keepalives with settings matching what Gitaly expects.

connOpts should not contain `grpc.WithInsecure` as DialContext determines whether it is needed or not from the scheme. `grpc.TransportCredentials` should not be provided either as those are handled internally as well.

func DialSidechannel

func DialSidechannel(ctx context.Context, rawAddress string, sr *SidechannelRegistry, connOpts []grpc.DialOption) (*grpc.ClientConn, error)

DialSidechannel configures the dialer to establish a Gitaly backchannel connection instead of a regular gRPC connection. It also injects sr as a sidechannel registry, so that Gitaly can establish sidechannels back to the client.

func FailOnNonTempDialError

func FailOnNonTempDialError() []grpc.DialOption

FailOnNonTempDialError helps to identify if remote listener is ready to accept new connections.

func OpenServerSidechannel

func OpenServerSidechannel(ctx context.Context) (io.ReadWriteCloser, error)

OpenServerSidechannel opens a sidechannel on the server side. This only works if the server was created using SidechannelServer().

func ReceivePack

func ReceivePack(ctx context.Context, conn *grpc.ClientConn, stdin io.Reader, stdout, stderr io.Writer, req *gitalypb.SSHReceivePackRequest) (int32, error)

ReceivePack proxies an SSH git-receive-pack (git push) session to Gitaly

func SidechannelServer

func SidechannelServer(logger *logrus.Entry, creds credentials.TransportCredentials) grpc.ServerOption

SidechannelServer adds sidechannel support to a gRPC server

func TestSidechannelServer

func TestSidechannelServer(
	logger *logrus.Entry,
	creds credentials.TransportCredentials,
	handler func(interface{}, grpc.ServerStream, io.ReadWriteCloser) error,
) []grpc.ServerOption

TestSidechannelServer allows downstream consumers of this package to create mock sidechannel gRPC servers.

func UploadArchive

func UploadArchive(ctx context.Context, conn *grpc.ClientConn, stdin io.Reader, stdout, stderr io.Writer, req *gitalypb.SSHUploadArchiveRequest) (int32, error)

UploadArchive proxies an SSH git-upload-archive (git archive --remote) session to Gitaly

func UploadPack

func UploadPack(ctx context.Context, conn *grpc.ClientConn, stdin io.Reader, stdout, stderr io.Writer, req *gitalypb.SSHUploadPackRequest) (int32, error)

UploadPack proxies an SSH git-upload-pack (git fetch) session to Gitaly

func UploadPackWithSidechannel

func UploadPackWithSidechannel(
	ctx context.Context,
	conn *grpc.ClientConn,
	reg *SidechannelRegistry,
	stdin io.Reader,
	stdout, stderr io.Writer,
	req *gitalypb.SSHUploadPackWithSidechannelRequest,
) (int32, error)

UploadPackWithSidechannel proxies an SSH git-upload-pack (git fetch) session to Gitaly using a sidechannel for the raw data transfer.

func WithGitalyDNSResolver

func WithGitalyDNSResolver(opts *DNSResolverBuilderConfig) grpc.DialOption

WithGitalyDNSResolver defines a gRPC dial option for injecting Gitaly's custom DNS resolver. This resolver watches for the changes of target URL periodically and update the target subchannels accordingly.

Types

type DNSResolverBuilderConfig

type DNSResolverBuilderConfig dnsresolver.BuilderConfig

DNSResolverBuilderConfig exposes the DNS resolver builder option. It is used to build Gitaly custom DNS resolver.

func DefaultDNSResolverBuilderConfig

func DefaultDNSResolverBuilderConfig() *DNSResolverBuilderConfig

DefaultDNSResolverBuilderConfig returns the default options for building DNS resolver.

type Dialer

type Dialer func(ctx context.Context, address string, dialOptions []grpc.DialOption) (*grpc.ClientConn, error)

Dialer is used by the Pool to create a *grpc.ClientConn.

func HealthCheckDialer

func HealthCheckDialer(base Dialer) Dialer

HealthCheckDialer uses provided dialer as an actual dialer, but issues a health check request to the remote to verify the connection was set properly and could be used with no issues.

type Pool

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

Pool is a pool of GRPC connections. Connections created by it are safe for concurrent use.

func NewPool

func NewPool(dialOptions ...grpc.DialOption) *Pool

NewPool creates a new connection pool that's ready for use.

func NewPoolWithOptions

func NewPoolWithOptions(poolOptions ...PoolOption) *Pool

NewPoolWithOptions creates a new connection pool that's ready for use.

func (*Pool) Close

func (p *Pool) Close() error

Close closes all connections tracked by the connection pool.

func (*Pool) Dial

func (p *Pool) Dial(ctx context.Context, address, token string) (*grpc.ClientConn, error)

Dial creates a new client connection in case no connection to the given address exists already or returns an already established connection. The returned address must not be `Close()`d.

type PoolOption

type PoolOption func(*poolOptions)

func WithDialOptions

func WithDialOptions(dialOptions ...grpc.DialOption) PoolOption

WithDialOptions sets gRPC options to use for the gRPC Dial call.

func WithDialer

func WithDialer(dialer Dialer) PoolOption

WithDialer sets the dialer that is called for each new gRPC connection the pool establishes.

type SidechannelConn

type SidechannelConn interface {
	io.ReadWriter

	// CloseWrite tells the server we won't write any more data. We can still
	// read data from the server after CloseWrite(). A typical use case is in
	// an RPC where the byte stream has a request/response pattern: the
	// client then uses CloseWrite() to signal the end of the request body.
	// When the client calls CloseWrite(), the server receives EOF.
	CloseWrite() error
}

SidechannelConn allows a client to read and write bytes with less overhead than doing so via gRPC messages.

type SidechannelRegistry

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

SidechannelRegistry associates sidechannel callbacks with outbound gRPC calls.

func NewSidechannelRegistry

func NewSidechannelRegistry(logger *logrus.Entry) *SidechannelRegistry

NewSidechannelRegistry returns a new registry.

func (*SidechannelRegistry) Register

func (sr *SidechannelRegistry) Register(
	ctx context.Context,
	callback func(SidechannelConn) error,
) (context.Context, *SidechannelWaiter)

Register registers a callback. It adds metadata to ctx and returns the new context. The caller must use the new context for the gRPC call. Caller must Close() the returned SidechannelWaiter to prevent resource leaks.

type SidechannelWaiter

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

SidechannelWaiter represents a pending sidechannel and its callback.

func (*SidechannelWaiter) Close

func (w *SidechannelWaiter) Close() error

Close de-registers the sidechannel callback. If the callback is still running, Close blocks until it is done and returns the error return value of the callback. If the callback has not been called yet, Close returns an error immediately.