Documentation
¶
Overview ¶
Package transport provides abstractions for local and remote command execution and file transfer, supporting both local execution and SSH-based remote execution.
Index ¶
- func IsLocal(spec string) bool
- func IsSSH(spec string) bool
- func ValidatePath(path string) error
- func ValidateRelativePath(basePath, relativePath string) error
- type Local
- func (l *Local) Close() error
- func (l *Local) Exec(ctx context.Context, cmd []string, env map[string]string, cwd string) (int, string, string, error)
- func (l *Local) ExecStream(ctx context.Context, cmd []string, env map[string]string, cwd string, ...) (int, error)
- func (l *Local) Get(ctx context.Context, srcPath, dstPath string) error
- func (l *Local) Mkdir(ctx context.Context, path string) error
- func (l *Local) Put(ctx context.Context, srcPath, dstPath string) error
- func (l *Local) Remove(ctx context.Context, path string) error
- func (l *Local) Stat(ctx context.Context, path string) (os.FileInfo, error)
- func (l *Local) String() string
- type Options
- type SSH
- func (s *SSH) Close() error
- func (s *SSH) Exec(ctx context.Context, cmd []string, env map[string]string, cwd string) (int, string, string, error)
- func (s *SSH) ExecStream(ctx context.Context, cmd []string, env map[string]string, cwd string, ...) (int, error)
- func (s *SSH) Get(ctx context.Context, remotePath, localPath string) error
- func (s *SSH) IsWindows() bool
- func (s *SSH) Mkdir(ctx context.Context, path string) error
- func (s *SSH) NeedsElevation() bool
- func (s *SSH) Put(ctx context.Context, localPath, remotePath string) error
- func (s *SSH) RemoteOS() string
- func (s *SSH) Remove(ctx context.Context, path string) error
- func (s *SSH) Stat(ctx context.Context, path string) (os.FileInfo, error)
- func (s *SSH) String() string
- type SSHOptions
- type Transport
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func ValidatePath ¶
ValidatePath checks if a path is safe and doesn't attempt directory traversal. It returns an error if the path contains traversal attempts or is otherwise unsafe. This is used to validate paths that come from potentially untrusted sources.
func ValidateRelativePath ¶
ValidateRelativePath checks if a path is a valid relative path within a base directory. It ensures the path doesn't escape the base directory.
Types ¶
type Local ¶
type Local struct {
// contains filtered or unexported fields
}
Local implements Transport for local execution.
func (*Local) Exec ¶
func (l *Local) Exec(ctx context.Context, cmd []string, env map[string]string, cwd string) (int, string, string, error)
Exec runs a command locally and returns exit code, stdout, stderr.
func (*Local) ExecStream ¶
func (l *Local) ExecStream(ctx context.Context, cmd []string, env map[string]string, cwd string, stdout, stderr io.Writer) (int, error)
ExecStream runs a command with streaming stdout/stderr.
type Options ¶
type Options struct {
Timeout time.Duration // Default command timeout
RetryAttempts int // Retries on transient failures
RetryDelay time.Duration // Delay between retries
}
Options configures transport behavior.
func DefaultOptions ¶
func DefaultOptions() Options
DefaultOptions returns sensible default options.
type SSH ¶
type SSH struct {
// contains filtered or unexported fields
}
SSH implements Transport for remote execution over SSH.
func NewSSH ¶
func NewSSH(host string, opts SSHOptions) (*SSH, error)
NewSSH creates a new SSH transport.
func (*SSH) Exec ¶
func (s *SSH) Exec(ctx context.Context, cmd []string, env map[string]string, cwd string) (int, string, string, error)
Exec runs a command remotely and returns exit code, stdout, stderr.
func (*SSH) ExecStream ¶
func (s *SSH) ExecStream(ctx context.Context, cmd []string, env map[string]string, cwd string, stdout, stderr io.Writer) (int, error)
ExecStream runs a command with streaming stdout/stderr.
func (*SSH) NeedsElevation ¶
NeedsElevation returns true if commands should run with elevated privileges.
func (*SSH) RemoteOS ¶
RemoteOS returns the configured remote operating system. Returns "linux" if not specified.
type SSHOptions ¶
type SSHOptions struct {
Options
// Authentication
User string // SSH username
KeyFile string // Path to private key file
KeyPassphrase string // Passphrase for encrypted key (optional)
Password string // Password authentication (fallback)
AllowPassword bool // Must be true to use password authentication
Agent bool // Use SSH agent for authentication
// Host verification
KnownHostsFile string // Path to known_hosts file
InsecureIgnoreHost bool // Skip host key verification (dangerous)
// Connection
Port int // SSH port (default 22)
ConnectTimeout time.Duration // Connection timeout
KeepAlive time.Duration // Keep-alive interval
// Remote host info
RemoteOS string // Remote operating system: "linux", "darwin", "windows" (default: "linux")
// Privilege escalation
Elevate bool // Use sudo (Unix) or run as admin (Windows)
}
SSHOptions configures SSH-specific transport behavior.
func DefaultSSHOptions ¶
func DefaultSSHOptions() SSHOptions
DefaultSSHOptions returns sensible default SSH options.
type Transport ¶
type Transport interface {
// Exec runs a command and returns exit code, stdout, stderr.
// cmd is the command as argv (not shell string).
// env is additional environment variables.
// cwd is the working directory (empty = default).
Exec(ctx context.Context, cmd []string, env map[string]string, cwd string) (exitCode int, stdout, stderr string, err error)
// ExecStream runs a command with streaming stdout/stderr.
// Used for long-running processes where we need to monitor output.
ExecStream(ctx context.Context, cmd []string, env map[string]string, cwd string, stdout, stderr io.Writer) (exitCode int, err error)
// Put copies a local file to remote path.
Put(ctx context.Context, localPath, remotePath string) error
// Get copies a remote file to local path.
Get(ctx context.Context, remotePath, localPath string) error
// Mkdir creates a directory (and parents) on remote.
Mkdir(ctx context.Context, remotePath string) error
// Stat returns file info for remote path.
Stat(ctx context.Context, remotePath string) (os.FileInfo, error)
// Remove deletes a file or empty directory.
Remove(ctx context.Context, remotePath string) error
// Close releases any held resources (e.g., SSH connection).
Close() error
// String returns a human-readable description of the transport.
String() string
}
Transport abstracts remote/local execution and file transfer.
func MustParse ¶
MustParse parses a transport spec and panics on error. Useful for tests and initialization.
func Parse ¶
Parse parses a transport specification string and returns a Transport. Supported formats:
- "local" -> LocalTransport
- "ssh://user@host:port" -> SSHTransport
- "ssh://user@host:port?key=/path&insecure=true" -> SSHTransport with options
- "host" (bare hostname) -> SSHTransport with defaults