ssh

Documentation

Overview

Package ssh provides a minimal SSH/SFTP client for wrtbox.

The Executor interface is the seam used by internal/apply, internal/diff and internal/rollback. Tests substitute a fake; production wiring uses the Client implementation in client.go.

Index

• type Client
  • func Dial(ctx context.Context, opts DialOptions) (*Client, error)
  • func (c *Client) Close() error
  • func (c *Client) Download(ctx context.Context, path string) ([]byte, error)
  • func (c *Client) MkdirAll(ctx context.Context, path string, mode fs.FileMode) error
  • func (c *Client) Run(ctx context.Context, command string) ([]byte, []byte, error)
  • func (c *Client) Upload(ctx context.Context, path string, data []byte, mode fs.FileMode) error
• type DialOptions
• type Executor

Types

type Client

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

Client is the production Executor backed by golang.org/x/crypto/ssh and github.com/pkg/sftp. It multiplexes exec sessions and one long-lived sftp subsystem over a single TCP connection.

func Dial

func Dial(ctx context.Context, opts DialOptions) (*Client, error)

Dial opens a connection using opts. The caller owns the returned Client and must call Close.

func (*Client) Close

func (c *Client) Close() error

Close implements Executor. Idempotent.

func (*Client) Download

func (c *Client) Download(ctx context.Context, path string) ([]byte, error)

Download implements Executor.

func (*Client) MkdirAll

func (c *Client) MkdirAll(ctx context.Context, path string, mode fs.FileMode) error

MkdirAll implements Executor.

func (*Client) Run

func (c *Client) Run(ctx context.Context, command string) ([]byte, []byte, error)

Run implements Executor.

func (*Client) Upload

func (c *Client) Upload(ctx context.Context, path string, data []byte, mode fs.FileMode) error

Upload implements Executor with a tmp-then-rename on the remote so a half-written file never shadows the target.

type DialOptions

type DialOptions struct {
	Host           string // host or IP (no user@ prefix)
	Port           int    // default 22
	User           string // default "root"
	KeyPath        string // absolute path to private key
	Passphrase     []byte // optional — empty means unencrypted key
	KnownHostsPath string // absolute path; default ~/.ssh/known_hosts
	// AcceptNewHostKey is explicit opt-in for TOFU: a host that is not
	// yet in known_hosts will be accepted (and appended). An EXISTING
	// mismatched host key is always fatal regardless of this flag.
	AcceptNewHostKey bool
	// ConnectTimeout bounds TCP + SSH handshake. Zero means 15s.
	ConnectTimeout time.Duration
}

DialOptions controls how Client connects. Fields follow the resolved values from hosts.yaml + ~/.ssh/config lookup done in internal/hosts; DialOptions itself does no resolution.

type Executor

type Executor interface {
	// Run executes a shell command on the remote and returns its
	// combined stdout and stderr along with the exit error (if any).
	// Implementations MUST respect ctx cancellation.
	Run(ctx context.Context, cmd string) (stdout, stderr []byte, err error)

	// Upload writes data to path, creating parent directories as
	// needed and setting the POSIX mode. Atomic write (tmp + rename)
	// is the caller's concern — the pipeline stages uploads into a
	// separate directory and swaps at the end.
	Upload(ctx context.Context, path string, data []byte, mode fs.FileMode) error

	// Download reads and returns the contents of path.
	Download(ctx context.Context, path string) ([]byte, error)

	// MkdirAll behaves like os.MkdirAll but on the remote.
	MkdirAll(ctx context.Context, path string, mode fs.FileMode) error

	// Close releases all resources (session, sftp subsystem,
	// underlying TCP). Safe to call multiple times.
	Close() error
}

Executor is the narrow surface the higher-level apply/diff/rollback pipelines need. Any implementation must be safe for sequential use by one goroutine (the pipelines never go parallel over a single connection).