Documentation
¶
Overview ¶
Package sshcore is rapp's transport layer: one SSH connection per rapp invocation, shared by every remote read a module performs. It silently redials once when the transport drops (see Exec) and keeps the link alive between polls with keepalive requests.
Index ¶
Constants ¶
const ( DefaultConnectTimeout = 10 * time.Second DefaultExecTimeout = 30 * time.Second DefaultKeepaliveInterval = 30 * time.Second )
Defaults applied by Dial when the corresponding Options field is zero.
Variables ¶
This section is empty.
Functions ¶
func BuildAuth ¶
func BuildAuth(cfg AuthConfig) ([]ssh.AuthMethod, error)
BuildAuth assembles the ssh.AuthMethod chain: ssh-agent (if SSH_AUTH_SOCK is set) → private keys → password prompt. Later methods are lazy - the password prompt only appears if everything before it was rejected. Prompted secrets are cached so the silent reconnect can re-authenticate without asking again (a prompt in the middle of a live TUI would wreck it).
Types ¶
type AuthConfig ¶
type AuthConfig struct {
// KeyPath is an explicit private key (--key). Loaded eagerly: a broken
// path or bad passphrase fails at startup, not mid-connect.
KeyPath string
// ForcePassword skips agent and key auth entirely (--password).
ForcePassword bool
}
AuthConfig selects how BuildAuth assembles the auth chain.
type Conn ¶
type Conn struct {
// contains filtered or unexported fields
}
Conn is one SSH connection to a remote host. Safe for concurrent use; reconnects are single-flight (see reconnect).
func Dial ¶
Dial opens the SSH connection used for the whole rapp run. host is "host" or "host:port" (default port 22).
func (*Conn) Addr ¶
Addr returns the remote address the connection was dialed with ("host:port"), for modules that want to label their output.
func (*Conn) Exec ¶
Exec runs cmd on the remote host and returns its stdout and stderr.
Commands must be idempotent: if the transport drops mid-command, Exec silently redials once and runs cmd again. rapp remote commands are read-only by convention (see docs/ARCHITECTURE.md), so the retry is safe.
Errors:
- *ExitError - cmd ran and exited non-zero (never triggers a retry; captured stdout/stderr are still returned);
- ctx.Err() - the caller's ctx was canceled or timed out. If ctx has no deadline, Options.ExecTimeout is applied as a backstop;
- *ConnLostError - the transport died and the silent reconnect (or the retried command) failed too.
func (*Conn) ExecOnce ¶
ExecOnce runs cmd exactly once and never silently retries it, for side-effecting commands (kill, renice) where a transparent replay after a mid-command reconnect would be wrong - the same reason SFTP writes are not retried (see Conn.SFTP). A dead link is still redialed *before* running, since that reconnect does not risk double-execution; only a failure *during* the command is surfaced to the caller instead of replayed. Error contract otherwise matches Exec.
type ConnLostError ¶
type ConnLostError struct {
Err error
}
ConnLostError reports that the SSH transport died and the single silent reconnect attempt (or the retried command) failed as well.
func (*ConnLostError) Error ¶
func (e *ConnLostError) Error() string
func (*ConnLostError) Unwrap ¶
func (e *ConnLostError) Unwrap() error
type ExitError ¶
ExitError reports a remote command that ran to completion and exited with a non-zero status. Stdout/stderr captured by Exec are still returned alongside it.
type Options ¶
type Options struct {
// ConnectTimeout bounds the initial dial and every silent redial.
// 0 → DefaultConnectTimeout.
ConnectTimeout time.Duration
// ExecTimeout bounds Exec only when the caller's ctx has no deadline -
// the "never hang" backstop. Modules that poll (htop) pass their own
// tick deadline, which always wins. 0 → DefaultExecTimeout.
ExecTimeout time.Duration
// KeepaliveInterval is how often a keepalive request probes the
// connection between Execs, so a dead link is noticed before the next
// command rather than in the middle of it.
// 0 → DefaultKeepaliveInterval; negative disables keepalives.
KeepaliveInterval time.Duration
// HostKeyCallback verifies the remote host key. nil → ~/.ssh/known_hosts
// with an interactive trust-on-first-use prompt for unknown hosts.
HostKeyCallback ssh.HostKeyCallback
}
Options tunes a Conn. The zero value gets sensible defaults; see the field comments.
Source Files