sesspool

Documentation

Overview

Package sesspool provides a "pool" of ssh sessions. You can try to claim one from the pool, closing it when done. The pool has a configurable maximum size.

Each session, when released, is actually closed, and a new claim creates a new session over the provided connection.

Example:

	// Create an ssh.Client however you want, then...
 pool := New(ctx, sshClient, WithMaxSessions(10))
 sess, err := pool.Claim(ctx)
 if err != nil {
   log.Fatalf("Error claiming: %v", err)
 }
 defer sess.Close()

 sftpCli, err := sess.SFTPClient()
 if err != nil {
   log.Fatalf("Error getting sftp client: %v", err)
 }
 defer sftpCli.Close()

 // Use the sftpCli over the session until done.

Index

• Variables
• func AsSFTPClient(s SFTPClientCloser, err error) (*sftp.Client, func() error, error)
• type Option
  • func WithMaxSessions(max int) Option
• type Pool
  • func New(client *ssh.Client, opts ...Option) *Pool
  • func (p *Pool) Claim(ctx context.Context) (*Session, error)
  • func (p *Pool) Close() error
  • func (p *Pool) Exhausted() bool
  • func (p *Pool) TryClaim(ctx context.Context) (*Session, error)
  • func (p *Pool) Used() int
• type SFTPClientCloser
• type Session
  • func (s *Session) Close() (err error)
  • func (s *Session) SFTPClient(opts ...sftp.ClientOption) (*sftp.Client, error)

Variables

var (
	// PoolExhausted is returned when the pool is "empty", meaning no more
	// session can be claimed.
	PoolExhausted = errors.New("session pool exhausted")

	// SessionNotFound is returned when attempting to close a session not in the pool.
	SessionNotFound = errors.New("not found")
)

Functions

func AsSFTPClient

func AsSFTPClient(s SFTPClientCloser, err error) (*sftp.Client, func() error, error)

AsSFTPClient can wrap a Claim method to produce an SFTP client.

Example:

cli, cleanup, err := AsSFTPClient(pool.Claim(ctx))
if err != nil {
  // handle err
}
defer cleanup()
// use cli

Types

type Option

type Option func(*Pool)

Option is used to modify how pools are created.

func WithMaxSessions

func WithMaxSessions(max int) Option

WithMaxSessions sets the maximum allowed simultaneous sessions for a connection.

type Pool

type Pool struct {
	sync.Mutex

	SSHClient *ssh.Client
	// contains filtered or unexported fields
}

Pool provides convenient ways to create new sessions within an existing SSH connection.

func New

func New(client *ssh.Client, opts ...Option) *Pool

New creates a new Pool given an already-created ssh client. It does not take ownership of the client: callers should clean it up on their own when finished.

func (*Pool) Claim

func (p *Pool) Claim(ctx context.Context) (*Session, error)

Claim blocks on the pool until a session can be claimed. Returns immediately for unlimited pools.

func (*Pool) Close

func (p *Pool) Close() error

Close cleans up the sessions in this pool (but does not clean up the underlying connection). This should always be called when finished.

func (*Pool) Exhausted

func (p *Pool) Exhausted() bool

Exhausted indicates whether this pool is exhausted (not free for claims).

func (*Pool) TryClaim

func (p *Pool) TryClaim(ctx context.Context) (*Session, error)

TryClaim creates a Session (if it can) and passes it back. The caller should close the Session when finished, to return it to the pool. The underlying session is closed at that time.

Does not block if the pool is empty, rather returns a PoolExhausted error.

func (*Pool) Used

func (p *Pool) Used() int

Used indicates how many things are busy from the pool.

type SFTPClientCloser

type SFTPClientCloser interface {
	SFTPClient(opts ...sftp.ClientOption) (*sftp.Client, error)
	Close() error
}

SFTPClientCloser is the type required by AsSFTPClient, allowing it to accept a session from here or elsewhere so long as it can be used to create an SFTPClient and can be closed. The clientpool module's Session type satisfies this, as does the Session type found here.

type Session

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

Session is an abstraction around ssh.Session that is pool-aware. When finished, callers should invoke Close on it to return it to the pool.

func (*Session) Close

func (s *Session) Close() (err error)

Close returns this session to the pool and closes the underlying session.

func (*Session) SFTPClient

func (s *Session) SFTPClient(opts ...sftp.ClientOption) (*sftp.Client, error)

SFTPClient returns an sftp.Client for this session. Be sure to close it when finished.