connection

package
v1.0.0-rc2 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Mar 7, 2019 License: Apache-2.0 Imports: 26 Imported by: 0

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

Constants

This section is empty.

Variables

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

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

View Source 
var ErrPoolClosed = PoolError("pool is closed")

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

View Source 
var ErrPoolConnected = PoolError("pool is connected")

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

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

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

View Source 
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.

Functions

This section is empty.

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, addr address.Address, 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, address.Address, 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, address.Address, 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, addr address.Address, 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 occurred 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 WithCompressors 

func WithCompressors(fn func([]string) []string) Option

WithCompressors sets the compressors that can be used for communication.

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 WithMonitor 

func WithMonitor(fn func(*event.CommandMonitor) *event.CommandMonitor) Option

WithMonitor configures a event for command monitoring.

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.

func WithZlibLevel added in v1.0.0 

func WithZlibLevel(fn func(*int) *int) Option

WithZlibLevel sets the zLib compression level.

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(addr address.Address, 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.

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.