Documentation
¶
Overview ¶
Package topology contains types that handles the discovery, monitoring, and selection of servers. This package is designed to expose enough inner workings of service discovery and monitoring to allow low level applications to have fine grained control, while hiding most of the detailed implementation of the algorithms.
Index ¶
- Variables
- type MonitorMode
- type Option
- func WithConnString(fn func(connstring.ConnString) connstring.ConnString) Option
- func WithMode(fn func(MonitorMode) MonitorMode) Option
- func WithReplicaSetName(fn func(string) string) Option
- func WithSeedList(fn func(...string) []string) Option
- func WithServerOptions(fn func(...ServerOption) []ServerOption) Option
- func WithServerSelectionTimeout(fn func(time.Duration) time.Duration) Option
- type SelectedServer
- type Server
- func (s *Server) BuildCursor(result bson.Raw, clientSession *session.Client, clock *session.ClusterClock, ...) (command.Cursor, error)
- func (s *Server) Connect(ctx context.Context) error
- func (s *Server) Connection(ctx context.Context) (connection.Connection, error)
- func (s *Server) Description() description.Server
- func (s *Server) Disconnect(ctx context.Context) error
- func (s *Server) Drain() error
- func (s *Server) RequestImmediateCheck()
- func (s *Server) SelectedDescription() description.SelectedServer
- func (s *Server) Subscribe() (*ServerSubscription, error)
- type ServerOption
- func WithClock(fn func(clock *session.ClusterClock) *session.ClusterClock) ServerOption
- func WithCompressionOptions(fn func(...string) []string) ServerOption
- func WithConnectionOptions(fn func(...connection.Option) []connection.Option) ServerOption
- func WithHeartbeatInterval(fn func(time.Duration) time.Duration) ServerOption
- func WithHeartbeatTimeout(fn func(time.Duration) time.Duration) ServerOption
- func WithMaxConnections(fn func(uint16) uint16) ServerOption
- func WithMaxIdleConnections(fn func(uint16) uint16) ServerOption
- func WithRegistry(fn func(*bsoncodec.Registry) *bsoncodec.Registry) ServerOption
- type ServerSubscription
- type Subscription
- type Topology
- func (t *Topology) Connect(ctx context.Context) error
- func (t *Topology) Description() description.Topology
- func (t *Topology) Disconnect(ctx context.Context) error
- func (t *Topology) FindServer(selected description.Server) (*SelectedServer, error)
- func (t *Topology) RequestImmediateCheck()
- func (t *Topology) SelectServer(ctx context.Context, ss description.ServerSelector) (*SelectedServer, error)
- func (t *Topology) Subscribe() (*Subscription, error)
- func (t *Topology) SupportsSessions() bool
Constants ¶
This section is empty.
Variables ¶
var ErrServerClosed = errors.New("server is closed")
ErrServerClosed occurs when an attempt to get a connection is made after the server has been closed.
var ErrServerConnected = errors.New("server is connected")
ErrServerConnected occurs when at attempt to connect is made after a server has already been connected.
var ErrServerSelectionTimeout = errors.New("server selection timeout")
ErrServerSelectionTimeout is returned from server selection when the server selection process took longer than allowed by the timeout.
var ErrSubscribeAfterClosed = errors.New("cannot subscribe after close")
ErrSubscribeAfterClosed is returned when a user attempts to subscribe to a closed Server or Topology.
var ErrTopologyClosed = errors.New("topology is closed")
ErrTopologyClosed is returned when a user attempts to call a method on a closed Topology.
var ErrTopologyConnected = errors.New("topology is connected or connecting")
ErrTopologyConnected is returned whena user attempts to connect to an already connected Topology.
Functions ¶
This section is empty.
Types ¶
type MonitorMode ¶
type MonitorMode uint8
MonitorMode represents the way in which a server is monitored.
const ( AutomaticMode MonitorMode = iota SingleMode )
These constants are the available monitoring modes.
type Option ¶
type Option func(*config) error
Option is a configuration option for a topology.
func WithConnString ¶
func WithConnString(fn func(connstring.ConnString) connstring.ConnString) Option
WithConnString configures the topology using the connection string.
func WithMode ¶
func WithMode(fn func(MonitorMode) MonitorMode) Option
WithMode configures the topology's monitor mode.
func WithReplicaSetName ¶
WithReplicaSetName configures the topology's default replica set name.
func WithSeedList ¶
WithSeedList configures a topology's seed list.
func WithServerOptions ¶
func WithServerOptions(fn func(...ServerOption) []ServerOption) Option
WithServerOptions configures a topology's server options for when a new server needs to be created.
type SelectedServer ¶
type SelectedServer struct {
*Server
Kind description.TopologyKind
}
SelectedServer represents a specific server that was selected during server selection. It contains the kind of the typology it was selected from.
func (*SelectedServer) Description ¶
func (ss *SelectedServer) Description() description.SelectedServer
Description returns a description of the server as of the last heartbeat.
type Server ¶
type Server struct {
// contains filtered or unexported fields
}
Server is a single server within a topology.
func ConnectServer ¶
func ConnectServer(ctx context.Context, addr address.Address, opts ...ServerOption) (*Server, error)
ConnectServer creates a new Server and then initializes it using the Connect method.
func NewServer ¶
func NewServer(addr address.Address, opts ...ServerOption) (*Server, error)
NewServer creates a new server. The mongodb server at the address will be monitored on an internal monitoring goroutine.
func (*Server) BuildCursor ¶
func (s *Server) BuildCursor(result bson.Raw, clientSession *session.Client, clock *session.ClusterClock, opts ...bsonx.Elem) (command.Cursor, error)
BuildCursor implements the command.CursorBuilder interface for the Server type.
func (*Server) Connect ¶
Connect initialzies the Server by starting background monitoring goroutines. This method must be called before a Server can be used.
func (*Server) Connection ¶
func (s *Server) Connection(ctx context.Context) (connection.Connection, error)
Connection gets a connection to the server.
func (*Server) Description ¶
func (s *Server) Description() description.Server
Description returns a description of the server as of the last heartbeat.
func (*Server) Disconnect ¶
Disconnect closes sockets to the server referenced by this Server. Subscriptions to this Server will be closed. Disconnect will shutdown any monitoring goroutines, close 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 (*Server) Drain ¶
Drain will drain the connection pool of this server. This is mainly here so the pool for the server doesn't need to be directly exposed and so that when an error is returned from reading or writing, a client can drain the pool for this server. This is exposed here so we don't have to wrap the Connection type and sniff responses for errors that would cause the pool to be drained, which can in turn centralize the logic for handling errors in the Client type.
func (*Server) RequestImmediateCheck ¶
func (s *Server) RequestImmediateCheck()
RequestImmediateCheck will cause the server to send a heartbeat immediately instead of waiting for the heartbeat timeout.
func (*Server) SelectedDescription ¶
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 (*Server) Subscribe ¶
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.
type ServerOption ¶
type ServerOption func(*serverConfig) error
ServerOption configures a server.
func WithClock ¶ added in v0.0.10
func WithClock(fn func(clock *session.ClusterClock) *session.ClusterClock) ServerOption
WithClock configures the ClusterClock for the server to use.
func WithCompressionOptions ¶ added in v0.0.8
func WithCompressionOptions(fn func(...string) []string) ServerOption
WithCompressionOptions configures the server's compressors.
func WithConnectionOptions ¶
func WithConnectionOptions(fn func(...connection.Option) []connection.Option) ServerOption
WithConnectionOptions configures the server's connections.
func WithHeartbeatInterval ¶
func WithHeartbeatInterval(fn func(time.Duration) time.Duration) ServerOption
WithHeartbeatInterval configures a server's heartbeat interval.
func WithHeartbeatTimeout ¶
func WithHeartbeatTimeout(fn func(time.Duration) time.Duration) ServerOption
WithHeartbeatTimeout configures how long to wait for a heartbeat socket to connection.
func WithMaxConnections ¶
func WithMaxConnections(fn func(uint16) uint16) ServerOption
WithMaxConnections configures the maximum number of connections to allow for a given server. If max is 0, then there is no upper limit to the number of connections.
func WithMaxIdleConnections ¶
func WithMaxIdleConnections(fn func(uint16) uint16) ServerOption
WithMaxIdleConnections configures the maximum number of idle connections allowed for the server.
func WithRegistry ¶ added in v0.0.15
func WithRegistry(fn func(*bsoncodec.Registry) *bsoncodec.Registry) ServerOption
WithRegistry configures the registry for the server to use when creating cursors.
type ServerSubscription ¶
type ServerSubscription struct {
C <-chan description.Server
// contains filtered or unexported fields
}
ServerSubscription represents a subscription to the description.Server updates for a specific server.
func (*ServerSubscription) Unsubscribe ¶
func (ss *ServerSubscription) Unsubscribe() error
Unsubscribe unsubscribes this ServerSubscription from updates and closes the subscription channel.
type Subscription ¶
type Subscription struct {
C <-chan description.Topology
// contains filtered or unexported fields
}
Subscription is a subscription to updates to the description of the Topology that created this Subscription.
func (*Subscription) Unsubscribe ¶
func (s *Subscription) Unsubscribe() error
Unsubscribe unsubscribes this Subscription from updates and closes the subscription channel.
type Topology ¶
Topology represents a MongoDB deployment.
func (*Topology) Connect ¶
Connect initializes a Topology and starts the monitoring process. This function must be called to properly monitor the topology.
func (*Topology) Description ¶
func (t *Topology) Description() description.Topology
Description returns a description of the topology.
func (*Topology) Disconnect ¶
Disconnect closes the topology. It stops the monitoring thread and closes all open subscriptions.
func (*Topology) FindServer ¶ added in v0.0.10
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 (*Topology) RequestImmediateCheck ¶
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 (*Topology) SelectServer ¶
func (t *Topology) SelectServer(ctx context.Context, ss description.ServerSelector) (*SelectedServer, error)
SelectServer selects a server given a selector.SelectServer complies with the server selection spec, and will time out after severSelectionTimeout or when the parent context is done.
func (*Topology) Subscribe ¶
func (t *Topology) Subscribe() (*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.
func (*Topology) SupportsSessions ¶ added in v0.0.10
SupportsSessions returns true if the topology supports sessions.
Source Files