clientpool

Documentation

Overview

Package clientpool manages a set of SSH connections, each with their own session pool, partitioned by custom IDs (a good candidate might be serialized SSH configs). Uses a leaky bucket, where connections are aged out after they have no open sessions for a time.

Example:

p := New()
defer p.Close()

// set addr and  clientConfig, then

sftpCli, cleanup, err := sesspool.AsSFTPClient(p.ClaimSession(ctx, WithDialArgs("tcp", addr, clientConfig)))
if err != nil {
    log.Fatalf("Error claiming sftp session: %v", err)
}
defer cleanup()

// Use the sftpCli to do stuff with the session.

When a connection has no open sessions for a configurable amount of time, a reaper clears it out of the pool, making room for new configurations to take its place if needed.

Index

• Constants
• Variables
• func DialArgsID(net, addr string, conf *ssh.ClientConfig) string
• type ClaimOption
  • func WithClientFactory(f NewSSHClientFunc) ClaimOption
  • func WithDialArgs(net, addr string, conf *ssh.ClientConfig) ClaimOption
  • func WithID(id string) ClaimOption
  • func WithSessPoolOption(opts ...sesspool.Option) ClaimOption
• type ClientPool
  • func New(opts ...Option) *ClientPool
  • func (p *ClientPool) ClaimSession(ctx context.Context, opts ...ClaimOption) (*Session, error)
  • func (p *ClientPool) Close() error
  • func (p *ClientPool) Exhausted() bool
  • func (p *ClientPool) HasID(id string) bool
  • func (p *ClientPool) NumSessionsForID(id string) int
  • func (p *ClientPool) PoolStats() map[string]int
  • func (p *ClientPool) TryClaimSession(ctx context.Context, opts ...ClaimOption) (*Session, error)
• type NewSSHClientFunc
• type Option
  • func WithExpireAfter(d time.Duration) Option
  • func WithPoolSize(max int) Option
• type Session
  • func (s *Session) InvalidateClient() error

Constants

const (
	DefaultExpireAfter = 5 * time.Minute
)

Variables

var (
	PoolExhausted = errors.New("client pool exhausted")
)

Functions

func DialArgsID

func DialArgsID(net, addr string, conf *ssh.ClientConfig) string

DialArgsID computes an ID from arguments that would be passed to ssh.Dial. The ID is relatively sure to be unique, so is used to identify different SSH connections in the pool.

If you are specifying your own ID when creating an SSH client from scratch, this can be useful to provide an ID with it.

Types

type ClaimOption

type ClaimOption func(*claimOptions)

ClaimOption changes how claims are done.

func WithClientFactory

func WithClientFactory(f NewSSHClientFunc) ClaimOption

WithClientFactory specifies a function to call to create a new SSH client. Supports fully custom creation. Must specify an ID with this.

func WithDialArgs

func WithDialArgs(net, addr string, conf *ssh.ClientConfig) ClaimOption

WithDialArgs specifies dial arguments to use for creating a new connection when claiming. If no ID is also given using WithClientID, the ID is inferred from the dial arguments.

func WithID

func WithID(id string) ClaimOption

WithID specifies a client ID to use when claiming. If none is given, it is inferred from dial arguments.

func WithSessPoolOption

func WithSessPoolOption(opts ...sesspool.Option) ClaimOption

WithSessPoolOptions specifies session pool options to use during claims.

type ClientPool

type ClientPool struct {
	sync.Mutex
	// contains filtered or unexported fields
}

ClientPool is a set of client session pools, partitioned by ID (such as serialized SSH configuration), and using the leaky bucket algorithm to age out unused connections.

func New

func New(opts ...Option) *ClientPool

New creates a new ClientPool with the given options.

func (*ClientPool) ClaimSession

func (p *ClientPool) ClaimSession(ctx context.Context, opts ...ClaimOption) (*Session, error)

ClaimSession blocks until the context expires or a session is obtained from the given ID in the pool. Will block until an appropriate connection is available, or until a session is available on a connection.

func (*ClientPool) Close

func (p *ClientPool) Close() error

Close closes all connections in the pool (all session pools) and cleans up.

func (*ClientPool) Exhausted

func (p *ClientPool) Exhausted() bool

Exhausted tells us whether there are slots for new IDs to be added into the pool.

func (*ClientPool) HasID

func (p *ClientPool) HasID(id string) bool

HasID indicates whether the pool has the given ID in it (an open connection).

func (*ClientPool) NumSessionsForID

func (p *ClientPool) NumSessionsForID(id string) int

NumSessionsForID returns the number of sessions in the session pool for this client ID.

func (*ClientPool) PoolStats

func (p *ClientPool) PoolStats() map[string]int

PoolStats returns a map of all client IDs to the number of sessions in each pool.

func (*ClientPool) TryClaimSession

func (p *ClientPool) TryClaimSession(ctx context.Context, opts ...ClaimOption) (*Session, error)

TryClaimSession attempts, without blocking, to claim a session from the given ID in the pool. Returns PoolExhausted error (from errors.Cause) if there are no available resources.

type NewSSHClientFunc

type NewSSHClientFunc func(ctx context.Context) (*ssh.Client, error)

NewSSHClientFunc returns a new ssh client.

type Option

type Option func(*ClientPool)

Option sets client pool characteristics

func WithExpireAfter

func WithExpireAfter(d time.Duration) Option

WithExpireAfter sets the expiration time of a connection in the pool. If a connection is available past this amount of time, it is reaped.

func WithPoolSize

func WithPoolSize(max int) Option

WithPoolSize sets the pool size to something other than the default.

type Session

type Session struct {
	sesspool.Session
	// contains filtered or unexported fields
}

Session is a wrapper around sesspool.Session that knows which client pool it came from, allowing it to be used to invalidate an entire connection and remove it from the pool if a session returns a connection error.

func (*Session) InvalidateClient

func (s *Session) InvalidateClient() error

InvalidateClient closes the session, its underlying pool, and the connection, removing it from the client pool associated with this session. Useful when a session returns an error that is really an underlying connection error, and no sessions on that connection can work anymore..