connection

Documentation

Overview

Package connection contains the types for building and pooling connections that can speak the MongoDB Wire Protocol. Since this low level library is meant to be used in the context of either a driver or a server there are some extra identifiers on a connection so one can keep track of what a connection is. This package purposefully hides the underlying network and abstracts the writing to and reading from a connection to wireops.Op's. This package also provides types for listening for and accepting Connections, as well as some types for handling connections and proxying connections to another server.

Index

• Variables
• type Addr
  • func (Addr) Canonicalize() Addr
  • func (Addr) Network() string
  • func (Addr) String() string
• type Connection
  • func New(ctx context.Context, address addr.Addr, opts ...Option) (Connection, *description.Server, error)
• type Dialer
• type DialerFunc
  • func (df DialerFunc) DialContext(ctx context.Context, network, address string) (net.Conn, error)
• type Error
  • func (e Error) Error() string
• type Handler
• type Handshaker
• type HandshakerFunc
  • func (hf HandshakerFunc) Handshake(ctx context.Context, address addr.Addr, rw wiremessage.ReadWriter) (description.Server, error)
• type Listener
  • func Listen(network, address string) (Listener, error)
• type NetworkError
  • func (ne NetworkError) Error() string
• type Option
  • func WithAppName(fn func(string) string) Option
  • func WithConnectTimeout(fn func(time.Duration) time.Duration) Option
  • func WithDialer(fn func(Dialer) Dialer) Option
  • func WithHandshaker(fn func(Handshaker) Handshaker) Option
  • func WithIdleTimeout(fn func(time.Duration) time.Duration) Option
  • func WithLifeTimeout(fn func(time.Duration) time.Duration) Option
  • func WithReadTimeout(fn func(time.Duration) time.Duration) Option
  • func WithTLSConfig(fn func(*TLSConfig) *TLSConfig) Option
  • func WithWriteTimeout(fn func(time.Duration) time.Duration) Option
• type Pool
  • func NewPool(address addr.Addr, size, capacity uint64, opts ...Option) (Pool, error)
• type PoolError
  • func (pe PoolError) Error() string
• type Proxy
  • func (*Proxy) HandleConnection(Connection)
• type Server
  • func (*Server) ListenAndServe() error
  • func (*Server) Serve(Listener) error
  • func (*Server) Shutdown(context.Context) error
• type TLSConfig
  • func NewTLSConfig() *TLSConfig
  • func (c *TLSConfig) AddCACertFromFile(file string) error
  • func (c *TLSConfig) AddClientCertFromFile(clientFile string) (string, error)
  • func (c *TLSConfig) Clone() *TLSConfig
  • func (c *TLSConfig) SetClientCertDecryptPassword(f func() string)
  • func (c *TLSConfig) SetInsecure(allow bool)

Variables

var ErrConnectionClosed = Error{ConnectionID: "<closed>", /* contains filtered or unexported fields */}

ErrConnectionClosed is returned from an attempt to use an already closed connection.

var ErrPoolClosed = PoolError("pool is closed")

ErrPoolClosed is returned from an attempt to use a closed pool.

var ErrPoolConnected = PoolError("pool is connected")

ErrPoolConnected is returned from an attempt to connect an already connected pool

var ErrPoolDisconnected = PoolError("pool is disconnected or disconnecting")

ErrPoolDisconnected is returned from an attempt to disconnect an already disconnected or disconnecting pool.

var ErrSizeLargerThanCapacity = PoolError("size is larger than capacity")

ErrSizeLargerThanCapacity is returned from an attempt to create a pool with a size larger than the capacity.

Types

type Addr

type Addr string

Addr is a network address. It can be either an IP address or a DNS name.

func (Addr) Canonicalize

func (Addr) Canonicalize() Addr

Canonicalize creates a canonicalized address.

func (Addr) Network

func (Addr) Network() string

Network is the network protcol for this address. In most cases this will be "tcp" or "unix".

func (Addr) String

func (Addr) String() string

String is the canonical version of this address, e.g. localhost:27017, 1.2.3.4:27017, example.com:27017

type Connection

type Connection interface {
	WriteWireMessage(context.Context, wiremessage.WireMessage) error
	ReadWireMessage(context.Context) (wiremessage.WireMessage, error)
	Close() error
	Expired() bool
	Alive() bool
	ID() string
}

Connection is used to read and write wire protocol messages to a network.

func New

func New(ctx context.Context, address addr.Addr, opts ...Option) (Connection, *description.Server, error)

New opens a connection to a given Addr.

The server description returned is nil if there was no handshaker provided.

type Dialer

type Dialer interface {
	DialContext(ctx context.Context, network, address string) (net.Conn, error)
}

Dialer is used to make network connections.

var DefaultDialer Dialer = &net.Dialer{}

DefaultDialer is the Dialer implementation that is used by this package. Changing this will also change the Dialer used for this package. This should only be changed why all of the connections being made need to use a different Dialer. Most of the time, using a WithDialer option is more appropriate than changing this variable.

type DialerFunc

type DialerFunc func(ctx context.Context, network, address string) (net.Conn, error)

DialerFunc is a type implemented by functions that can be used as a Dialer.

func (DialerFunc) DialContext

func (df DialerFunc) DialContext(ctx context.Context, network, address string) (net.Conn, error)

DialContext implements the Dialer interface.

type Error

type Error struct {
	ConnectionID string
	Wrapped      error
	// contains filtered or unexported fields
}

Error represents a connection error.

func (Error) Error

func (e Error) Error() string

Error implements the error interface.

type Handler

type Handler interface {
	HandleConnection(Connection)
}

Handler handles an individual Connection. Returning signals that the Connection is no longer needed and can be closed.

type Handshaker

type Handshaker interface {
	Handshake(context.Context, addr.Addr, wiremessage.ReadWriter) (description.Server, error)
}

Handshaker is the interface implemented by types that can perform a MongoDB handshake over a provided ReadWriter. This is used during connection initialization.

type HandshakerFunc

type HandshakerFunc func(context.Context, addr.Addr, wiremessage.ReadWriter) (description.Server, error)

HandshakerFunc is an adapter to allow the use of ordinary functions as connection handshakers.

func (HandshakerFunc) Handshake

func (hf HandshakerFunc) Handshake(ctx context.Context, address addr.Addr, rw wiremessage.ReadWriter) (description.Server, error)

Handshake implements the Handshaker interface.

type Listener

type Listener interface {
	// Accept waits for and returns the next Connection to the listener.
	Accept() (Connection, error)

	// Close closes the listener.
	Close() error

	// Addr returns the listener's network address.
	Addr() Addr
}

Listener is a generic mongodb network protocol listener. It can return connections that speak the mongodb wire protocol.

Multiple goroutines may invoke methods on a Listener simultaneously.

TODO(GODRIVER-270): Implement this.

func Listen

func Listen(network, address string) (Listener, error)

Listen creates a new listener on the provided network and address.

type NetworkError

type NetworkError struct {
	ConnectionID string
	Wrapped      error
}

NetworkError represents an error that ocurred while reading from or writing to a network socket.

func (NetworkError) Error

func (ne NetworkError) Error() string

type Option

type Option func(*config) error

Option is used to configure a connection.

func WithAppName

func WithAppName(fn func(string) string) Option

WithAppName sets the application name which gets sent to MongoDB when it first connects.

func WithConnectTimeout

func WithConnectTimeout(fn func(time.Duration) time.Duration) Option

WithConnectTimeout configures the maximum amount of time a dial will wait for a connect to complete. The default is 30 seconds.

func WithDialer

func WithDialer(fn func(Dialer) Dialer) Option

WithDialer configures the Dialer to use when making a new connection to MongoDB.

func WithHandshaker

func WithHandshaker(fn func(Handshaker) Handshaker) Option

WithHandshaker configures the Handshaker that wll be used to initialize newly dialed connections.

func WithIdleTimeout

func WithIdleTimeout(fn func(time.Duration) time.Duration) Option

WithIdleTimeout configures the maximum idle time to allow for a connection.

func WithLifeTimeout

func WithLifeTimeout(fn func(time.Duration) time.Duration) Option

WithLifeTimeout configures the maximum life of a connection.

func WithReadTimeout

func WithReadTimeout(fn func(time.Duration) time.Duration) Option

WithReadTimeout configures the maximum read time for a connection.

func WithTLSConfig

func WithTLSConfig(fn func(*TLSConfig) *TLSConfig) Option

WithTLSConfig configures the TLS options for a connection.

func WithWriteTimeout

func WithWriteTimeout(fn func(time.Duration) time.Duration) Option

WithWriteTimeout configures the maximum write time for a connection.

type Pool

type Pool interface {
	// Get must return a nil *description.Server if the returned connection is
	// not a newly dialed connection.
	Get(context.Context) (Connection, *description.Server, error)
	// Connect handles the initialization of a Pool and allow Connections to be
	// retrieved and pooled. Implementations must return an error if Connect is
	// called more than once before calling Disconnect.
	Connect(context.Context) error
	// Disconnect closest connections managed by this Pool. Implementations must
	// either wait until all of the connections in use have been returned and
	// closed or the context expires before returning. If the context expires
	// via cancellation, deadline, timeout, or some other manner, implementations
	// must close the in use connections. If this method returns with no errors,
	// all connections managed by this pool must be closed. Calling Disconnect
	// multiple times after a single Connect call must result in an error.
	Disconnect(context.Context) error
	Drain() error
}

Pool is used to pool Connections to a server.

func NewPool

func NewPool(address addr.Addr, size, capacity uint64, opts ...Option) (Pool, error)

NewPool creates a new pool that will hold size number of idle connections and will create a max of capacity connections. It will use the provided options.

type PoolError

type PoolError string

PoolError is an error returned from a Pool method.

func (PoolError) Error

func (pe PoolError) Error() string

type Proxy

type Proxy struct {
	Processor wiremessage.Transformer
	Pool      Pool
}

Proxy implements a MongoDB proxy. It will use the given pool to connect to a MongoDB server and proxy the traffic between connections it is given and the server. It will pass each of the wireops it reads from the handled connection to a Processor. If an error is returned from the processor, the wireop will not be forwarded onto the server. If there is not an error the returned message will be passed onto the server. If both the return message and the error are nil, the original wiremessage will be passed onto the server.

TODO(GODRIVER-268): Implement this.

func (*Proxy) HandleConnection

func (*Proxy) HandleConnection(Connection)

HandleConnection implements the Handler interface.

type Server

type Server struct {
	Addr    Addr
	Handler Handler
}

Server is used to handle incoming Connections. It handles the boilerplate of accepting a Connection and cleaning it up after running a Handler. This also makes it easier to build higher level processors, like proxies, by handling the life cycle of the underlying connection.

TODO(GODRIVER-269): Implement this.

func (*Server) ListenAndServe

func (*Server) ListenAndServe() error

ListenAndServe listens on the network address srv.Addr and calls Serve to handle requests on incoming connections. If srv.Addr is blank, "localhost:27017" is used.

func (*Server) Serve

func (*Server) Serve(Listener) error

Serve accepts incoming connections on the Listener l, creating a new service goroutine for each. The service goroutines call srv.Handler and do not processing beforehand. When srv.Handler returns, the connection is closed.

func (*Server) Shutdown

func (*Server) Shutdown(context.Context) error

Shutdown gracefully shuts down the server by closing the active listeners. Shutdown does not handle or wait for all open connections to close and return before returning.

type TLSConfig

type TLSConfig struct {
	*tls.Config
	// contains filtered or unexported fields
}

TLSConfig contains options for configuring a TLS connection to the server.

func NewTLSConfig

func NewTLSConfig() *TLSConfig

NewTLSConfig creates a new TLSConfig.

func (*TLSConfig) AddCACertFromFile

func (c *TLSConfig) AddCACertFromFile(file string) error

AddCACertFromFile adds a root CA certificate to the configuration given a path to the containing file.

func (*TLSConfig) AddClientCertFromFile

func (c *TLSConfig) AddClientCertFromFile(clientFile string) (string, error)

AddClientCertFromFile adds a client certificate to the configuration given a path to the containing file and returns the certificate's subject name.

func (*TLSConfig) Clone

func (c *TLSConfig) Clone() *TLSConfig

Clone returns a shallow clone of c. It is safe to clone a Config that is being used concurrently by a TLS client or server.

func (*TLSConfig) SetClientCertDecryptPassword

func (c *TLSConfig) SetClientCertDecryptPassword(f func() string)

SetClientCertDecryptPassword sets a function to retrieve the decryption password necessary to read a certificate. This is a function instead of a string to provide greater flexibility when deciding how to retrieve and store the password.

func (*TLSConfig) SetInsecure

func (c *TLSConfig) SetInsecure(allow bool)

SetInsecure sets whether the client should verify the server's certificate chain and hostnames.