var (
// MinSupportedMongoDBVersion is the version string for the lowest MongoDB version supported by the driver.
MinSupportedMongoDBVersion = "3.6"
// SupportedWireVersions is the range of wire versions supported by the driver.
SupportedWireVersions = description.NewVersionRange(6, 21)
)
var (
// BGReadTimeout is the maximum amount of the to wait when trying to read
// the server reply on a connection after an operation timed out. The
// default is 1 second.
//
// Deprecated: BGReadTimeout is intended for internal use only and may be
// removed or modified at any time.
BGReadTimeout = 1 * time.Second
// BGReadCallback is a callback for monitoring the behavior of the
// background-read-on-timeout connection preserving mechanism.
//
// Deprecated: BGReadCallback is intended for internal use only and may be
// removed or modified at any time.
BGReadCallback func(addr string, start, read time.Time, errs []error, connClosed bool)
)
var (
// ErrServerClosed occurs when an attempt to Get a connection is made after
// the server has been closed.
ErrServerClosed = errors.New("server is closed")
// ErrServerConnected occurs when at attempt to Connect is made after a server
// has already been connected.
ErrServerConnected = errors.New("server is connected")
)
ErrConnectionClosed is returned from an attempt to use an already closed connection.
var ErrConnectionClosed = ConnectionError{ConnectionID: "<closed>", /* contains filtered or unexported fields */}
ErrPoolClosed is returned when attempting to check out a connection from a closed pool.
var ErrPoolClosed = PoolError("attempted to check out a connection from closed connection pool")
ErrPoolNotPaused is returned when attempting to mark a connection pool "ready" that is not currently "paused".
var ErrPoolNotPaused = PoolError("only a paused pool can be marked ready")
ErrServerSelectionTimeout is returned from server selection when the server selection process took longer than allowed by the timeout.
var ErrServerSelectionTimeout = errors.New("server selection timeout")
ErrSubscribeAfterClosed is returned when a user attempts to subscribe to a closed Server or Topology.
var ErrSubscribeAfterClosed = errors.New("cannot subscribe after closeConnection")
ErrTopologyClosed is returned when a user attempts to call a method on a closed Topology.
var ErrTopologyClosed = errors.New("topology is closed")
ErrTopologyConnected is returned whena user attempts to Connect to an already connected Topology.
var ErrTopologyConnected = errors.New("topology is connected or connecting")
ErrWrongPool is return when a connection is returned to a pool it doesn't belong to.
var ErrWrongPool = PoolError("connection does not belong to this pool")
func ConvertToDriverAPIOptions(s *options.ServerAPIOptions) *driver.ServerAPIOptions
ConvertToDriverAPIOptions converts a options.ServerAPIOptions instance to a driver.ServerAPIOptions.
func ServerAPIFromServerOptions(opts []ServerOption) *driver.ServerAPIOptions
ServerAPIFromServerOptions will return the server API options if they have been functionally set on the ServerOption slice.
Config is used to construct a topology.
type Config struct {
Mode MonitorMode
ReplicaSetName string
SeedList []string
ServerOpts []ServerOption
URI string
ServerSelectionTimeout time.Duration
ServerMonitor *event.ServerMonitor
SRVMaxHosts int
SRVServiceName string
LoadBalanced bool
// contains filtered or unexported fields
}
func NewConfig(co *options.ClientOptions, clock *session.ClusterClock) (*Config, error)
NewConfig will translate data from client options into a topology config for building non-default deployments. Server and topology options are not honored if a custom deployment is used.
Connection implements the driver.Connection interface to allow reading and writing wire messages and the driver.Expirable interface to allow expiring. It wraps an underlying topology.connection to make it more goroutine-safe and nil-safe.
type Connection struct {
// contains filtered or unexported fields
}
func (c *Connection) Address() address.Address
Address returns the address of this connection.
func (c *Connection) Alive() bool
Alive returns if the connection is still alive.
func (c *Connection) Close() error
Close returns this connection to the connection pool. This method may not closeConnection the underlying socket.
func (c *Connection) CompressWireMessage(src, dst []byte) ([]byte, error)
CompressWireMessage handles compressing the provided wire message using the underlying connection's compressor. The dst parameter will be overwritten with the new wire message. If there is no compressor set on the underlying connection, then no compression will be performed.
func (c *Connection) Description() description.Server
Description returns the server description of the server this connection is connected to.
func (c *Connection) DriverConnectionID() uint64
DriverConnectionID returns the driver connection ID. TODO(GODRIVER-2824): change return type to int64.
func (c *Connection) Expire() error
Expire closes this connection and will closeConnection the underlying socket.
func (c *Connection) ID() string
ID returns the ID of this connection.
func (c *Connection) LocalAddress() address.Address
LocalAddress returns the local address of the connection
func (c *Connection) PinToCursor() error
PinToCursor updates this connection to reflect that it is pinned to a cursor.
func (c *Connection) PinToTransaction() error
PinToTransaction updates this connection to reflect that it is pinned to a transaction.
func (c *Connection) ReadWireMessage(ctx context.Context) ([]byte, error)
ReadWireMessage handles reading a wire message from the underlying connection. The dst parameter will be overwritten with the new wire message.
func (c *Connection) ServerConnectionID() *int64
ServerConnectionID returns the server connection ID of this connection.
func (c *Connection) Stale() bool
Stale returns if the connection is stale.
func (c *Connection) UnpinFromCursor() error
UnpinFromCursor updates this connection to reflect that it is no longer pinned to a cursor.
func (c *Connection) UnpinFromTransaction() error
UnpinFromTransaction updates this connection to reflect that it is no longer pinned to a transaction.
func (c *Connection) WriteWireMessage(ctx context.Context, wm []byte) error
WriteWireMessage handles writing a wire message to the underlying connection.
ConnectionError represents a connection error.
type ConnectionError struct {
ConnectionID string
Wrapped error
// contains filtered or unexported fields
}
func (e ConnectionError) Error() string
Error implements the error interface.
func (e ConnectionError) Unwrap() error
Unwrap returns the underlying error.
ConnectionOption is used to configure a connection.
type ConnectionOption func(*connectionConfig)
func WithCompressors(fn func([]string) []string) ConnectionOption
WithCompressors sets the compressors that can be used for communication.
func WithConnectTimeout(fn func(time.Duration) time.Duration) ConnectionOption
WithConnectTimeout configures the maximum amount of time a dial will wait for a Connect to complete. The default is 30 seconds.
func WithConnectionLoadBalanced(fn func(bool) bool) ConnectionOption
WithConnectionLoadBalanced specifies whether or not the connection is to a server behind a load balancer.
func WithDialer(fn func(Dialer) Dialer) ConnectionOption
WithDialer configures the Dialer to use when making a new connection to MongoDB.
func WithDisableOCSPEndpointCheck(fn func(bool) bool) ConnectionOption
WithDisableOCSPEndpointCheck specifies whether or the driver should perform non-stapled OCSP verification. If set to true, the driver will only check stapled responses and will continue the connection without reaching out to OCSP responders.
func WithHTTPClient(fn func(*http.Client) *http.Client) ConnectionOption
WithHTTPClient configures the HTTP client for a connection.
func WithHandshaker(fn func(Handshaker) Handshaker) ConnectionOption
WithHandshaker configures the Handshaker that wll be used to initialize newly dialed connections.
func WithIdleTimeout(fn func(time.Duration) time.Duration) ConnectionOption
WithIdleTimeout configures the maximum idle time to allow for a connection.
func WithMonitor(fn func(*event.CommandMonitor) *event.CommandMonitor) ConnectionOption
WithMonitor configures a event for command monitoring.
func WithOCSPCache(fn func(ocsp.Cache) ocsp.Cache) ConnectionOption
WithOCSPCache specifies a cache to use for OCSP verification.
func WithReadTimeout(fn func(time.Duration) time.Duration) ConnectionOption
WithReadTimeout configures the maximum read time for a connection.
func WithTLSConfig(fn func(*tls.Config) *tls.Config) ConnectionOption
WithTLSConfig configures the TLS options for a connection.
func WithWriteTimeout(fn func(time.Duration) time.Duration) ConnectionOption
WithWriteTimeout configures the maximum write time for a connection.
func WithZlibLevel(fn func(*int) *int) ConnectionOption
WithZlibLevel sets the zLib compression level.
func WithZstdLevel(fn func(*int) *int) ConnectionOption
WithZstdLevel sets the zstd compression level.
Dialer is used to make network connections.
type Dialer interface {
DialContext(ctx context.Context, network, address string) (net.Conn, error)
}
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.
var DefaultDialer Dialer = &net.Dialer{}
DialerFunc is a type implemented by functions that can be used as a Dialer.
type DialerFunc func(ctx context.Context, network, address string) (net.Conn, error)
func (df DialerFunc) DialContext(ctx context.Context, network, address string) (net.Conn, error)
DialContext implements the Dialer interface.
Handshaker is the interface implemented by types that can perform a MongoDB handshake over a provided driver.Connection. This is used during connection initialization. Implementations must be goroutine safe.
type Handshaker = driver.Handshaker
MonitorMode represents the way in which a server is monitored.
type MonitorMode uint8
These constants are the available monitoring modes.
const (
AutomaticMode MonitorMode = iota
SingleMode
)
PoolError is an error returned from a Pool method.
type PoolError string
func (pe PoolError) Error() string
SelectedServer represents a specific server that was selected during server selection. It contains the kind of the topology it was selected from.
type SelectedServer struct {
*Server
Kind description.TopologyKind
}
func (ss *SelectedServer) Description() description.SelectedServer
Description returns a description of the server as of the last heartbeat.
Server is a single server within a topology.
type Server struct {
// contains filtered or unexported fields
}
func ConnectServer(
addr address.Address,
updateCallback updateTopologyCallback,
topologyID primitive.ObjectID,
opts ...ServerOption,
) (*Server, error)
ConnectServer creates a new Server and then initializes it using the Connect method.
func NewServer(addr address.Address, topologyID primitive.ObjectID, opts ...ServerOption) *Server
NewServer creates a new server. The mongodb server at the address will be monitored on an internal monitoring goroutine.
func (s *Server) Connect(updateCallback updateTopologyCallback) error
Connect initializes the Server by starting background monitoring goroutines. This method must be called before a Server can be used.
func (s *Server) Connection(ctx context.Context) (driver.Connection, error)
Connection gets a connection to the server.
func (s *Server) Description() description.Server
Description returns a description of the server as of the last heartbeat.
func (s *Server) Disconnect(ctx context.Context) error
Disconnect closes sockets to the server referenced by this Server. Subscriptions to this Server will be closed. Disconnect will shutdown any monitoring goroutines, closeConnection the idle connection pool, and will wait until all the in use connections have been returned to the connection pool and are closed before returning. If the context expires via cancellation, deadline, or timeout before the in use connections have been returned, the in use connections will be closed, resulting in the failure of any in flight read or write operations. If this method returns with no errors, all connections associated with this Server have been closed.
func (s *Server) OperationCount() int64
OperationCount returns the current number of in-progress operations for this server.
func (s *Server) ProcessError(err error, conn driver.Connection) driver.ProcessErrorResult
ProcessError handles SDAM error handling and implements driver.ErrorProcessor.
func (s *Server) ProcessHandshakeError(err error, startingGenerationNumber uint64, serviceID *primitive.ObjectID)
ProcessHandshakeError implements SDAM error handling for errors that occur before a connection finishes handshaking.
func (s *Server) RTTMonitor() driver.RTTMonitor
RTTMonitor returns this server's round-trip-time monitor.
func (s *Server) RequestImmediateCheck()
RequestImmediateCheck will cause the server to send a heartbeat immediately instead of waiting for the heartbeat timeout.
func (s *Server) SelectedDescription() description.SelectedServer
SelectedDescription returns a description.SelectedServer with a Kind of Single. This can be used when performing tasks like monitoring a batch of servers and you want to run one off commands against those servers.
func (s *Server) String() string
String implements the Stringer interface.
func (s *Server) Subscribe() (*ServerSubscription, error)
Subscribe returns a ServerSubscription which has a channel on which all updated server descriptions will be sent. The channel will have a buffer size of one, and will be pre-populated with the current description.
ServerOption configures a server.
type ServerOption func(*serverConfig)
func WithClock(fn func(clock *session.ClusterClock) *session.ClusterClock) ServerOption
WithClock configures the ClusterClock for the server to use.
func WithCompressionOptions(fn func(...string) []string) ServerOption
WithCompressionOptions configures the server's compressors.
func WithConnectionOptions(fn func(...ConnectionOption) []ConnectionOption) ServerOption
WithConnectionOptions configures the server's connections.
func WithConnectionPoolMaintainInterval(fn func(time.Duration) time.Duration) ServerOption
WithConnectionPoolMaintainInterval configures the interval that the background connection pool maintenance goroutine runs.
func WithConnectionPoolMaxIdleTime(fn func(time.Duration) time.Duration) ServerOption
WithConnectionPoolMaxIdleTime configures the maximum time that a connection can remain idle in the connection pool before being removed. If connectionPoolMaxIdleTime is 0, then no idle time is set and connections will not be removed because of their age
func WithConnectionPoolMonitor(fn func(*event.PoolMonitor) *event.PoolMonitor) ServerOption
WithConnectionPoolMonitor configures the monitor for all connection pool actions
func WithHeartbeatInterval(fn func(time.Duration) time.Duration) ServerOption
WithHeartbeatInterval configures a server's heartbeat interval.
func WithHeartbeatTimeout(fn func(time.Duration) time.Duration) ServerOption
WithHeartbeatTimeout configures how long to wait for a heartbeat socket to connection.
func WithMaxConnecting(fn func(uint64) uint64) ServerOption
WithMaxConnecting configures the maximum number of connections a connection pool may establish simultaneously. If maxConnecting is 0, the default value of 2 is used.
func WithMaxConnections(fn func(uint64) uint64) ServerOption
WithMaxConnections configures the maximum number of connections to allow for a given server. If max is 0, then maximum connection pool size is not limited.
func WithMinConnections(fn func(uint64) uint64) ServerOption
WithMinConnections configures the minimum number of connections to allow for a given server. If min is 0, then there is no lower limit to the number of connections.
func WithRegistry(fn func(*bsoncodec.Registry) *bsoncodec.Registry) ServerOption
WithRegistry configures the registry for the server to use when creating cursors.
func WithServerAPI(fn func(serverAPI *driver.ServerAPIOptions) *driver.ServerAPIOptions) ServerOption
WithServerAPI configures the server API options for the server to use.
func WithServerAppName(fn func(string) string) ServerOption
WithServerAppName configures the server's application name.
func WithServerLoadBalanced(fn func(bool) bool) ServerOption
WithServerLoadBalanced specifies whether or not the server is behind a load balancer.
func WithServerMonitor(fn func(*event.ServerMonitor) *event.ServerMonitor) ServerOption
WithServerMonitor configures the monitor for all SDAM events for a server
ServerSelectionError represents a Server Selection error.
type ServerSelectionError struct {
Desc description.Topology
Wrapped error
}
func (e ServerSelectionError) Error() string
Error implements the error interface.
func (e ServerSelectionError) Unwrap() error
Unwrap returns the underlying error.
ServerSubscription represents a subscription to the description.Server updates for a specific server.
type ServerSubscription struct {
C <-chan description.Server
// contains filtered or unexported fields
}
func (ss *ServerSubscription) Unsubscribe() error
Unsubscribe unsubscribes this ServerSubscription from updates and closes the subscription channel.
Topology represents a MongoDB deployment.
type Topology struct {
// contains filtered or unexported fields
}
func New(cfg *Config) (*Topology, error)
New creates a new topology. A "nil" config is interpreted as the default configuration.
func (t *Topology) Connect() error
Connect initializes a Topology and starts the monitoring process. This function must be called to properly monitor the topology.
func (t *Topology) Description() description.Topology
Description returns a description of the topology.
func (t *Topology) Disconnect(ctx context.Context) error
Disconnect closes the topology. It stops the monitoring thread and closes all open subscriptions.
func (t *Topology) FindServer(selected description.Server) (*SelectedServer, error)
FindServer will attempt to find a server that fits the given server description. This method will return nil, nil if a matching server could not be found.
func (t *Topology) Kind() description.TopologyKind
Kind returns the topology kind of this Topology.
func (t *Topology) RequestImmediateCheck()
RequestImmediateCheck will send heartbeats to all the servers in the topology right away, instead of waiting for the heartbeat timeout.
func (t *Topology) SelectServer(ctx context.Context, ss description.ServerSelector) (driver.Server, error)
SelectServer selects a server with given a selector. SelectServer complies with the server selection spec, and will time out after serverSelectionTimeout or when the parent context is done.
func (t *Topology) String() string
String implements the Stringer interface
func (t *Topology) Subscribe() (*driver.Subscription, error)
Subscribe returns a Subscription on which all updated description.Topologys will be sent. The channel of the subscription will have a buffer size of one, and will be pre-populated with the current description.Topology. Subscribe implements the driver.Subscriber interface.
func (t *Topology) Unsubscribe(sub *driver.Subscription) error
Unsubscribe unsubscribes the given subscription from the topology and closes the subscription channel. Unsubscribe implements the driver.Subscriber interface.
WaitQueueTimeoutError represents a timeout when requesting a connection from the pool
type WaitQueueTimeoutError struct {
Wrapped error
// contains filtered or unexported fields
}
func (w WaitQueueTimeoutError) Error() string
Error implements the error interface.
func (w WaitQueueTimeoutError) Unwrap() error
Unwrap returns the underlying error.