topology

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
  • func (ss *SelectedServer) Description() description.SelectedServer
• type Server
  • func ConnectServer(ctx context.Context, addr address.Address, topo func(description.Server), ...) (*Server, error)
  • func NewServer(addr address.Address, topo func(description.Server), opts ...ServerOption) (*Server, 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) ProcessWriteConcernError(err *result.WriteConcernError)
  • func (s *Server) RequestImmediateCheck()
  • func (s *Server) SelectedDescription() description.SelectedServer
  • func (s *Server) String() string
  • 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
  • func (ss *ServerSubscription) Unsubscribe() error
• type Subscription
  • func (s *Subscription) Unsubscribe() error
• type Topology
  • func New(opts ...Option) (*Topology, error)
  • 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) String() string
  • func (t *Topology) Subscribe() (*Subscription, error)
  • func (t *Topology) SupportsSessions() bool

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.

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

func WithReplicaSetName(fn func(string) string) Option

WithReplicaSetName configures the topology's default replica set name.

func WithSeedList

func WithSeedList(fn func(...string) []string) Option

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.

func WithServerSelectionTimeout

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

WithServerSelectionTimeout configures a topology's server selection timeout. A server selection timeout of 0 means there is no timeout for server selection.

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 topology 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, topo func(description.Server), opts ...ServerOption) (*Server, error)

ConnectServer creates a new Server and then initializes it using the Connect method.

func NewServer

func NewServer(addr address.Address, topo func(description.Server), 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) Connect

func (s *Server) Connect(ctx context.Context) error

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

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, 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

func (s *Server) Drain() error

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) ProcessWriteConcernError

func (s *Server) ProcessWriteConcernError(err *result.WriteConcernError)

ProcessWriteConcernError checks if a WriteConcernError is an isNotMaster or isRecovering error, and if so updates the server accordingly.

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) String

func (s *Server) String() string

String implements the Stringer interface.

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

func WithClock(fn func(clock *session.ClusterClock) *session.ClusterClock) ServerOption

WithClock configures the ClusterClock for the server to use.

func WithCompressionOptions

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

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

type Topology struct {
	SessionPool *session.Pool
	// contains filtered or unexported fields
}

Topology represents a MongoDB deployment.

func New

func New(opts ...Option) (*Topology, error)

New creates a new topology.

func (*Topology) Connect

func (t *Topology) Connect(ctx context.Context) error

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

func (t *Topology) Disconnect(ctx context.Context) error

Disconnect closes the topology. It stops the monitoring thread and closes all open subscriptions.

func (*Topology) FindServer

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) String

func (t *Topology) String() string

String implements the Stringer interface

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

func (t *Topology) SupportsSessions() bool

SupportsSessions returns true if the topology supports sessions.