transport

package
v0.2.7 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Feb 14, 2026 License: Apache-2.0 Imports: 18 Imported by: 0

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

Constants

This section is empty.

Variables

This section is empty.

Functions

func IsLocal

func IsLocal(spec string) bool

IsLocal returns true if the transport spec refers to local execution.

func IsSSH

func IsSSH(spec string) bool

IsSSH returns true if the transport spec refers to SSH execution.

func ValidatePath

func ValidatePath(path string) error

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

func ValidateRelativePath(basePath, relativePath string) error

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 NewLocal

func NewLocal(opts Options) *Local

NewLocal creates a new local transport.

func (*Local) Close

func (l *Local) Close() error

Close is a no-op for local transport.

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.

func (*Local) Get

func (l *Local) Get(ctx context.Context, srcPath, dstPath string) error

Get copies a local file to another local path (same as Put for local).

func (*Local) Mkdir

func (l *Local) Mkdir(ctx context.Context, path string) error

Mkdir creates a directory locally.

func (*Local) Put

func (l *Local) Put(ctx context.Context, srcPath, dstPath string) error

Put copies a local file to another local path.

func (*Local) Remove

func (l *Local) Remove(ctx context.Context, path string) error

Remove deletes a file or empty directory locally.

func (*Local) Stat

func (l *Local) Stat(ctx context.Context, path string) (os.FileInfo, error)

Stat returns file info for a local path.

func (*Local) String

func (l *Local) String() string

String returns a description of this transport.

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) Close

func (s *SSH) Close() error

Close closes the SSH connection.

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) Get

func (s *SSH) Get(ctx context.Context, remotePath, localPath string) error

Get copies a remote file to the local host.

func (*SSH) IsWindows

func (s *SSH) IsWindows() bool

IsWindows returns true if the remote host is Windows.

func (*SSH) Mkdir

func (s *SSH) Mkdir(ctx context.Context, path string) error

Mkdir creates a directory on the remote host.

func (*SSH) NeedsElevation

func (s *SSH) NeedsElevation() bool

NeedsElevation returns true if commands should run with elevated privileges.

func (*SSH) Put

func (s *SSH) Put(ctx context.Context, localPath, remotePath string) error

Put copies a local file to the remote host.

func (*SSH) RemoteOS

func (s *SSH) RemoteOS() string

RemoteOS returns the configured remote operating system. Returns "linux" if not specified.

func (*SSH) Remove

func (s *SSH) Remove(ctx context.Context, path string) error

Remove deletes a file or empty directory on the remote host.

func (*SSH) Stat

func (s *SSH) Stat(ctx context.Context, path string) (os.FileInfo, error)

Stat returns file info for a remote path.

func (*SSH) String

func (s *SSH) String() string

String returns a description of this transport.

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

func MustParse(spec string) Transport

MustParse parses a transport spec and panics on error. Useful for tests and initialization.

func Parse

func Parse(spec string) (Transport, error)

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

func ParseSpec

func ParseSpec(spec string) (Transport, error)

ParseSpec is an alias for Parse for backward compatibility.

func ParseWithOptions

func ParseWithOptions(spec string, opts Options) (Transport, error)

ParseWithOptions parses a transport specification with custom options.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
⌂ 换网址