sshx

Documentation

Overview

Package sshx is the single SSH connection path used by the rest of kay. It dials with public-key auth, verifies host keys with trust-on-first-use, and exposes one-shot command execution and an interactive shell.

Index

• Variables
• type Client
  • func Dial(opts DialOptions) (*Client, error)
  • func (c *Client) Close() error
  • func (c *Client) Ping() error
  • func (c *Client) Run(cmd string) (string, error)
  • func (c *Client) Shell() error
• type ConnState
  • func (s ConnState) String() string
• type DialOptions
• type Managed
  • func (m *Managed) Client() *Client
  • func (m *Managed) Close()
  • func (m *Managed) Err() error
  • func (m *Managed) Run(cmd string) (string, error)
  • func (m *Managed) State() ConnState
• type Pool
  • func NewPool(maxDials int) *Pool
  • func (p *Pool) Add(dial func() (*Client, error)) *Managed
  • func (p *Pool) Close()

Variables

var ErrNotReady = errors.New("ssh connection not ready")

ErrNotReady is returned by Managed.Run when the underlying connection is not currently established (it is connecting, backing off, or reconnecting).

var ErrPoolClosed = errors.New("ssh pool closed")

ErrPoolClosed is returned when an operation is attempted after Close.

Types

type Client

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

Client wraps an *ssh.Client with the helpers kay needs.

func Dial

func Dial(opts DialOptions) (*Client, error)

Dial establishes an authenticated connection.

func (*Client) Close

func (c *Client) Close() error

Close terminates the connection and stops the keepalive goroutine. It is safe to call more than once. The done channel is never reassigned after Dial, so the keepalive goroutine reads it without racing Close.

func (*Client) Ping

func (c *Client) Ping() error

Ping sends an OpenSSH keepalive global request and reports whether the peer answered. It is deadline-guarded: a black-hole peer that never replies can't wedge the caller (golang/go#21478), so it is safe to call from a health probe.

func (*Client) Run

func (c *Client) Run(cmd string) (string, error)

Run executes a single command and returns its combined stdout+stderr output. This is the only place commands are executed, so metrics and `exec` share it.

func (*Client) Shell

func (c *Client) Shell() error

Shell opens an interactive PTY-backed shell wired to the local terminal.

type ConnState

type ConnState int

ConnState is the lifecycle state of a Managed connection.

const (
	// StateConnecting is the initial state before the first dial resolves.
	StateConnecting ConnState = iota
	// StateReady means a live connection is established and usable.
	StateReady
	// StateBroken means the last attempt failed; a reconnect is scheduled.
	StateBroken
)

func (ConnState) String

func (s ConnState) String() string

String renders the state for logs and status lines.

type DialOptions

type DialOptions struct {
	Addr           string // host:port
	User           string
	Signer         ssh.Signer
	Password       string // optional; enables password auth (e.g. assisted install)
	KnownHostsPath string
	Insecure       bool // skip host key verification (dangerous)
	Timeout        time.Duration
}

DialOptions configures a connection.

type Managed

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

Managed is a self-healing connection to one host: it keeps a single live connection, reconnecting with exponential backoff and jitter after a failure, and hands the live connection to callers. All command execution reuses the same transport, so only the first dial pays the handshake cost.

func (*Managed) Client

func (m *Managed) Client() *Client

Client returns the live *Client for direct reuse (e.g. drilling into a host's dashboard without a second handshake), or nil when not currently ready.

func (*Managed) Close

func (m *Managed) Close()

Close stops maintaining the connection and tears down the live transport.

func (*Managed) Err

func (m *Managed) Err() error

Err returns the error from the last failed attempt, or nil.

func (*Managed) Run

func (m *Managed) Run(cmd string) (string, error)

Run executes a command on the live connection, reusing the transport. It returns ErrNotReady immediately (without blocking) when no connection is currently established, so a caller polling many hosts never stalls on one that is down. A transport-level failure schedules a reconnect.

func (*Managed) State

func (m *Managed) State() ConnState

State returns the current lifecycle state.

type Pool

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

Pool owns a set of Managed connections and the dial concurrency limit shared across them. Capping concurrent dials keeps a cold start of many hosts from tripping a server's sshd MaxStartups throttle or exhausting local sockets.

func NewPool

func NewPool(maxDials int) *Pool

NewPool returns a pool that permits at most maxDials concurrent dials across all its connections. A non-positive maxDials defaults to 16.

func (*Pool) Add

func (p *Pool) Add(dial func() (*Client, error)) *Managed

Add registers a host and starts maintaining a connection to it in the background, returning immediately. dial is called whenever a (re)connection is needed. The returned Managed is usable at once (Run reports ErrNotReady until the first dial succeeds).

func (*Pool) Close

func (p *Pool) Close()

Close tears down every Managed connection. It is safe to call once; further Add calls return an already-closed Managed.