session

Documentation

Overview

Package session abstracts command execution against local or remote hosts.

Index

• type LocalSession
  • func NewLocal() *LocalSession
  • func NewLocalWithOpts(o Opts) *LocalSession
  • func (l *LocalSession) Close() error
  • func (l *LocalSession) FileExists(ctx context.Context, path string) (bool, error)
  • func (l *LocalSession) Host() string
  • func (l *LocalSession) ReadFile(ctx context.Context, path string) ([]byte, error)
  • func (l *LocalSession) Run(ctx context.Context, cmd string) (string, string, error)
  • func (l *LocalSession) RunSudo(ctx context.Context, cmd string) (string, string, error)
  • func (l *LocalSession) WriteFile(ctx context.Context, path string, content []byte, mode uint32) error
• type Opts
• type SSHSession
  • func NewSSH(host, user string) *SSHSession
  • func NewSSHDial(o Opts) (*SSHSession, error)
  • func (s *SSHSession) Close() error
  • func (s *SSHSession) Dial(o Opts) error
  • func (s *SSHSession) FileExists(ctx context.Context, path string) (bool, error)
  • func (s *SSHSession) Host() string
  • func (s *SSHSession) ReadFile(ctx context.Context, path string) ([]byte, error)
  • func (s *SSHSession) Run(ctx context.Context, cmd string) (string, string, error)
  • func (s *SSHSession) RunSudo(ctx context.Context, cmd string) (string, string, error)
  • func (s *SSHSession) WriteFile(ctx context.Context, path string, content []byte, mode uint32) error
• type Session

Types

type LocalSession

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

LocalSession executes commands against the local host via /bin/sh.

func NewLocal

func NewLocal() *LocalSession

NewLocal returns a local session bound to the current host.

func NewLocalWithOpts

func NewLocalWithOpts(o Opts) *LocalSession

NewLocalWithOpts honours Opts.Host + Opts.SudoPassword.

func (*LocalSession) Close

func (l *LocalSession) Close() error

Close is a no-op for local sessions.

func (*LocalSession) FileExists

func (l *LocalSession) FileExists(ctx context.Context, path string) (bool, error)

FileExists reports whether path exists.

func (*LocalSession) Host

func (l *LocalSession) Host() string

Host reports the session target.

func (*LocalSession) ReadFile

func (l *LocalSession) ReadFile(ctx context.Context, path string) ([]byte, error)

ReadFile reads path, falling back to sudo cat if permission denied.

func (*LocalSession) Run

func (l *LocalSession) Run(ctx context.Context, cmd string) (string, string, error)

Run executes cmd in /bin/sh -c. Captures stdout + stderr separately.

func (*LocalSession) RunSudo

func (l *LocalSession) RunSudo(ctx context.Context, cmd string) (string, string, error)

RunSudo wraps cmd with `sudo -n` for non-interactive root.

func (*LocalSession) WriteFile

func (l *LocalSession) WriteFile(ctx context.Context, path string, content []byte, mode uint32) error

WriteFile writes content to path with the given mode. Uses sudo via tee if the path is not writable by the current user.

type Opts

type Opts struct {
	Host               string        // hostname or "localhost"
	User               string        // SSH user
	Port               int           // default 22
	KeyFile            string        // default ~/.ssh/id_ed25519
	Password           string        // optional SSH password (rarely used)
	StrictHostKeyCheck bool          // if true, verify known_hosts
	KnownHostsFile     string        // default ~/.ssh/known_hosts
	Timeout            time.Duration // default 30s
	SudoPassword       string        // empty => `sudo -n` (NOPASSWD required)
}

Opts configures a session's transport + auth.

type SSHSession

type SSHSession struct {
	HostAddr string
	User     string
	// contains filtered or unexported fields
}

SSHSession is a remote command pipeline backed by golang.org/x/crypto/ssh. A single Session multiplexes commands over one TCP/TLS connection; callers should Close() when done.

func NewSSH

func NewSSH(host, user string) *SSHSession

NewSSH returns a lightweight SSH descriptor. It does NOT dial — call Dial() (or NewSSHDial) to establish the transport. This two-phase API keeps the zero-value useful for tests that never touch the network.

func NewSSHDial

func NewSSHDial(o Opts) (*SSHSession, error)

NewSSHDial constructs a session from Opts and dials immediately.

func (*SSHSession) Close

func (s *SSHSession) Close() error

Close tears down the SSH connection.

func (*SSHSession) Dial

func (s *SSHSession) Dial(o Opts) error

Dial opens the SSH connection with up to 3 attempts (exponential backoff).

func (*SSHSession) FileExists

func (s *SSHSession) FileExists(ctx context.Context, path string) (bool, error)

FileExists tests via `test -e`.

func (*SSHSession) Host

func (s *SSHSession) Host() string

Host reports user@host.

func (*SSHSession) ReadFile

func (s *SSHSession) ReadFile(ctx context.Context, path string) ([]byte, error)

ReadFile returns remote contents via sudo cat.

func (*SSHSession) Run

func (s *SSHSession) Run(ctx context.Context, cmd string) (string, string, error)

Run executes cmd and returns stdout / stderr.

func (*SSHSession) RunSudo

func (s *SSHSession) RunSudo(ctx context.Context, cmd string) (string, string, error)

RunSudo wraps cmd under sudo. Uses -n (requires NOPASSWD) unless SudoPassword is set.

func (*SSHSession) WriteFile

func (s *SSHSession) WriteFile(ctx context.Context, path string, content []byte, mode uint32) error

WriteFile writes content to path with mode via sudo tee.

type Session

type Session interface {
	// Host returns a human-readable identifier ("localhost" or "user@host").
	Host() string

	// Run executes cmd in the session context. Returns stdout, stderr, error.
	Run(ctx context.Context, cmd string) (stdout, stderr string, err error)

	// RunSudo executes cmd with sudo/root privileges.
	RunSudo(ctx context.Context, cmd string) (stdout, stderr string, err error)

	// WriteFile writes content to path with mode. Uses sudo if needed.
	WriteFile(ctx context.Context, path string, content []byte, mode uint32) error

	// ReadFile reads the entire contents of path.
	ReadFile(ctx context.Context, path string) ([]byte, error)

	// FileExists returns true if path exists on the target host.
	FileExists(ctx context.Context, path string) (bool, error)

	// Close releases the transport (no-op for local sessions).
	Close() error
}

Session abstracts command execution + file I/O against local or remote hosts. Implementations: LocalSession (current host) and SSHSession (remote).