proxy

Documentation

Overview

Package proxy implements client and server code for proxying an unsecure connection over SSL.

Index

• Constants
• Variables
• func Dial(instance string) (net.Conn, error)
• func DialContext(ctx context.Context, instance string) (net.Conn, error)
• func Init(auth *http.Client, connset *ConnSet, dialer Dialer)
• func InitClient(c Client)
• func InitDefault(ctx context.Context) error
• func InitWithClient(c *Client)
• func NewConnSrc(instance string, l net.Listener) <-chan Conn
• func ParseInstanceConnectionName(instance string) (string, string, string, []string, error)
• type CertSource
• type Client
  • func (c *Client) AvailableConn() bool
  • func (c *Client) Dial(instance string) (net.Conn, error)
  • func (c *Client) DialContext(ctx context.Context, instance string) (net.Conn, error)
  • func (c *Client) GetInstances() []string
  • func (c *Client) InstanceVersion(instance string) (string, error)
  • func (c *Client) InstanceVersionContext(ctx context.Context, instance string) (string, error)
  • func (c *Client) InvalidInstances() []*InvalidError
  • func (c *Client) Run(connSrc <-chan Conn)
  • func (c *Client) RunContext(ctx context.Context, connSrc <-chan Conn)
  • func (c *Client) Shutdown(termTimeout time.Duration) error
• type Conn
• type ConnSet
  • func NewConnSet() *ConnSet
  • func (c *ConnSet) Add(id string, conn net.Conn)
  • func (c *ConnSet) Close() error
  • func (c *ConnSet) Conns(ids ...string) []net.Conn
  • func (c *ConnSet) IDs() []string
  • func (c *ConnSet) Remove(id string, conn net.Conn) error
  • func (c *ConnSet) String() string
• type Dialer
• type InvalidError
  • func (e *InvalidError) Error() string

Constants

const (
	// DefaultRefreshCfgThrottle is the time a refresh attempt must wait since
	// the last attempt.
	DefaultRefreshCfgThrottle = time.Minute
	// IAMLoginRefreshThrottle is the time a refresh attempt must wait since the
	// last attempt when using IAM login.
	IAMLoginRefreshThrottle = 30 * time.Second

	// DefaultRefreshCfgBuffer is the minimum amount of time for which a
	// certificate must be valid to ensure the next refresh attempt has adequate
	// time to complete.
	DefaultRefreshCfgBuffer = 5 * time.Minute
	// IAMLoginRefreshCfgBuffer is the minimum amount of time for which a
	// certificate holding an Access Token must be valid. Because some token
	// sources (e.g., ouath2.ComputeTokenSource) are refreshed with only ~60
	// seconds before expiration, this value must be smaller than the
	// DefaultRefreshCfgBuffer.
	IAMLoginRefreshCfgBuffer = 55 * time.Second
)

const DefaultPort = 3307

The port that CloudSQL expects the client to connect to.

const SQLScope = "https://www.googleapis.com/auth/sqlservice.admin"

SQLScope is the Google Cloud Platform scope required for executing API calls to Cloud SQL.

Variables

var ErrUnexpectedFailure = errors.New("ErrUnexpectedFailure")

ErrUnexpectedFailure indicates the internal refresh operation failed unexpectedly.

Functions

func Dial

func Dial(instance string) (net.Conn, error)

Dial does the same as DialContext but using context.Background() as the context.

func DialContext

func DialContext(ctx context.Context, instance string) (net.Conn, error)

Dial returns a net.Conn connected to the Cloud SQL Instance specified. The format of 'instance' is "project-name:region:instance-name".

If one of the Init functions hasn't been called yet, InitDefault is called.

This is a network-level function; consider looking in the dialers subdirectory for more convenience functions related to actually logging into your database.

func Init

func Init(auth *http.Client, connset *ConnSet, dialer Dialer)

Init must be called before Dial is called. This is a more flexible version of InitDefault, but allows you to set more fields.

The http.Client is used to authenticate API requests. The connset parameter is optional. If the dialer is nil, net.Conn is used. Use InitWithClient to with a filled client if you want to provide a Context-Aware dialer

func InitClient

func InitClient(c Client)

Deprecated: Use InitWithClient instead.

func InitDefault

func InitDefault(ctx context.Context) error

InitDefault attempts to initialize the Dial function using application default credentials.

func InitWithClient

func InitWithClient(c *Client)

InitWithClient specifies the Client directly.

func NewConnSrc

func NewConnSrc(instance string, l net.Listener) <-chan Conn

NewConnSrc returns a chan which can be used to receive connections on the passed Listener. All requests sent to the returned chan will have the instance name provided here. The chan will be closed if the Listener returns an error.

func ParseInstanceConnectionName

func ParseInstanceConnectionName(instance string) (string, string, string, []string, error)

ParseInstanceConnectionName verifies that instances are in the expected format and include the necessary components.

Types

type CertSource

type CertSource interface {
	// Local returns a certificate that can be used to authenticate with the
	// provided instance.
	Local(instance string) (tls.Certificate, error)
	// Remote returns the instance's CA certificate, address, and name.
	Remote(instance string) (cert *x509.Certificate, addr, name, version string, err error)
}

CertSource is how a Client obtains various certificates required for operation.

type Client

type Client struct {
	// ConnectionsCounter is used to enforce the optional maxConnections limit
	ConnectionsCounter uint64

	// MaxConnections is the maximum number of connections to establish
	// before refusing new connections. 0 means no limit.
	MaxConnections uint64

	// Port designates which remote port should be used when connecting to
	// instances. This value is defined by the server-side code, but for now it
	// should always be 3307.
	Port int
	// Required; specifies how certificates are obtained.
	Certs CertSource
	// Optionally tracks connections through this client. If nil, connections
	// are not tracked and will not be closed before method Run exits.
	Conns *ConnSet
	// ContextDialer should return a new connection to the provided address.
	// It is called on each new connection to an instance.
	// If left nil, Dialer will be tried first, and if that one is nil too then net.Dial will be used.
	ContextDialer func(ctx context.Context, net, addr string) (net.Conn, error)
	// Dialer should return a new connection to the provided address. It will be used only if ContextDialer is nil.
	Dialer func(net, addr string) (net.Conn, error)

	// RefreshCfgThrottle is the amount of time to wait between configuration
	// refreshes. If not set, it defaults to 1 minute.
	//
	// This is to prevent quota exhaustion in the case of client-side
	// malfunction.
	RefreshCfgThrottle time.Duration

	// RefreshCertBuffer is the amount of time before the configuration expires
	// to attempt to refresh it. If not set, it defaults to 5 minutes. When IAM
	// Login is enabled, this value should be set to IAMLoginRefreshCfgBuffer.
	RefreshCfgBuffer time.Duration
	// contains filtered or unexported fields
}

Client is a type to handle connecting to a Server. All fields are required unless otherwise specified.

func (*Client) AvailableConn

func (c *Client) AvailableConn() bool

AvailableConn returns false if MaxConnections has been reached, true otherwise. When MaxConnections is 0, there is no limit.

func (*Client) Dial

func (c *Client) Dial(instance string) (net.Conn, error)

Dial does the same as DialContext but using context.Background() as the context.

func (*Client) DialContext

func (c *Client) DialContext(ctx context.Context, instance string) (net.Conn, error)

DialContext uses the configuration stored in the client to connect to an instance. If this func returns a nil error the connection is correctly authenticated to connect to the instance.

func (*Client) GetInstances

func (c *Client) GetInstances() []string

GetInstances iterates through the client cache, returning a list of previously dialed instances.

func (*Client) InstanceVersion

func (c *Client) InstanceVersion(instance string) (string, error)

InstanceVersion uses client cache to return instance version string.

Deprecated: Use Client.InstanceVersionContext instead.

func (*Client) InstanceVersionContext

func (c *Client) InstanceVersionContext(ctx context.Context, instance string) (string, error)

InstanceVersionContext uses client cache to return instance version string.

func (*Client) InvalidInstances

func (c *Client) InvalidInstances() []*InvalidError

InvalidInstances reports whether the existing connections have valid configuration.

func (*Client) Run

func (c *Client) Run(connSrc <-chan Conn)

Run causes the client to start waiting for new connections to connSrc and proxy them to the destination instance. It blocks until connSrc is closed.

func (*Client) RunContext

func (c *Client) RunContext(ctx context.Context, connSrc <-chan Conn)

RunContext is like Run with an additional context.Context argument.

func (*Client) Shutdown

func (c *Client) Shutdown(termTimeout time.Duration) error

Shutdown waits up to a given amount of time for all active connections to close. Returns an error if there are still active connections after waiting for the whole length of the timeout.

type Conn

type Conn struct {
	Instance string
	Conn     net.Conn
}

Conn represents a connection from a client to a specific instance.

type ConnSet

type ConnSet struct {
	sync.RWMutex
	// contains filtered or unexported fields
}

A ConnSet tracks net.Conns associated with a provided ID. A nil ConnSet will be a no-op for all methods called on it.

func NewConnSet

func NewConnSet() *ConnSet

NewConnSet initializes a new ConnSet and returns it.

func (*ConnSet) Add

func (c *ConnSet) Add(id string, conn net.Conn)

Add saves the provided conn and associates it with the given string identifier.

func (*ConnSet) Close

func (c *ConnSet) Close() error

Close closes every net.Conn contained in the set.

func (*ConnSet) Conns

func (c *ConnSet) Conns(ids ...string) []net.Conn

Conns returns all active connections associated with the provided ids.

func (*ConnSet) IDs

func (c *ConnSet) IDs() []string

IDs returns a slice of all identifiers which still have active connections.

func (*ConnSet) Remove

func (c *ConnSet) Remove(id string, conn net.Conn) error

Remove undoes an Add operation to have the set forget about a conn. Do not Remove an id/conn pair more than it has been Added.

func (*ConnSet) String

func (c *ConnSet) String() string

String returns a debug string for the ConnSet.

type Dialer

type Dialer func(net, addr string) (net.Conn, error)

Dialer is a convenience type to model the standard 'Dial' function.

type InvalidError

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

InvalidError is an error from an instance connection that is invalid because its recent refresh attempt has failed, its TLS config is invalid, etc.

func (*InvalidError) Error

func (e *InvalidError) Error() string