Documentation
¶
Overview ¶
Package remote defines the backend-neutral command and file-operation interfaces for a target machine. It receives parsed destinations and backend implementations from runtime setup, and feeds remoteexec, workspacefs, pathstub, and agenttransfer with sessions, file clients, platform metadata, and agent upload hooks.
Index ¶
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
This section is empty.
Types ¶
type Backend ¶
type Backend interface {
// Type returns the implementation identifier (e.g. "ssh", "docker").
Type() Type
// Addr is a human-readable identifier of the target (host:port,
// container name, etc.). Used in logs and recording metadata.
Addr() string
// User is the remote user identity, when applicable. May be empty
// for backends like Docker where there is no notion of an SSH user.
User() string
// Start establishes the connection. May be a no-op for
// backend-specific reasons. The context governs the dial and any
// preflight checks; once Start returns the backend manages its
// own connection lifecycle.
Start(ctx context.Context) error
// IsConnected reports whether the backend is currently usable.
IsConnected() bool
// LastErr returns the most recent connection error, or nil when the
// last attempt succeeded.
LastErr() error
// KeepAliveInterval, when > 0, is the period at which the manager
// should call SendKeepAlive to keep the connection alive.
KeepAliveInterval() time.Duration
// SendKeepAlive sends a backend-appropriate keepalive ping. Errors
// returned here are treated as fatal to the connection.
SendKeepAlive(ctx context.Context) error
// NewSession creates a fresh command execution session. Implementations
// must allow multiple concurrent sessions.
NewSession(ctx context.Context) (Session, error)
// Files returns a FileClient for file operations against the remote
// (used by agent binary transfer and the FUSE workspace mount).
// May lazily start a long-lived server-side worker.
Files(ctx context.Context) (FileClient, error)
// UploadAgent installs the mproxy-agent binary on the remote at the
// given path. Backends that can self-host the agent via FileClient
// (SSH+SFTP) may delegate; backends that need a bootstrap primitive
// (Docker CopyToContainer) implement it directly.
UploadAgent(ctx context.Context, localPath, remotePath string, mode os.FileMode) (resolvedRemote string, err error)
// DetectPlatform queries the remote for its OS, architecture, and
// optional CPU variant. Implementations may leave any field empty
// when the backend cannot derive that piece of information; they
// should return a non-nil error only when nothing useful could be
// determined. Callers are expected to fall back to a sensible
// default (typically the local GOOS/GOARCH) on error.
DetectPlatform(ctx context.Context) (PlatformInfo, error)
// Close terminates the connection and releases resources.
Close() error
}
Backend is a single connection to a remote command-execution + filesystem target. Implementations are expected to be safe for concurrent use after Start returns.
type Destination ¶
type Destination struct {
Type Type
// User is the SSH user, when present. Empty for Docker/Compose and for
// SSH destinations that do not carry an explicit user.
User string
// Host is the SSH hostname/IP for type=ssh, the container name/ID for
// type=docker, or the Compose project name for type=compose ("." = current).
Host string
// Port is the SSH port, zero when not specified. Unused for docker/compose.
Port int
// Service is the Docker Compose service name for type=compose.
// Empty for ssh and docker.
Service string
// Sequence is the 1-based replica index for type=compose. Zero means
// "unspecified — expect exactly one running match". Unused for ssh/docker.
Sequence int
// Raw is the original input string.
Raw string
}
Destination identifies a parsed target on the command line.
SSH form: ssh://[user@]host[:port] or bare [user@]host Docker form: docker://container_name_or_id Compose form: compose://project/service[/sequence]
project may be "." to auto-detect from the working directory.
A bare string with no scheme prefix defaults to defaultType passed to ParseDestination — typically the value of --backend.
func ParseDestination ¶
func ParseDestination(s string, defaultType Type) (Destination, error)
ParseDestination parses a destination string. defaultType selects the backend when no scheme prefix is present. Returns an error when the scheme is unknown or the host portion is empty.
type FileClient ¶
type FileClient interface {
Open(path string) (RemoteFile, error)
Create(path string) (RemoteWriteFile, error)
OpenFile(path string, flags int, mode os.FileMode) (RemoteWriteFile, error)
Stat(path string) (os.FileInfo, error)
Lstat(path string) (os.FileInfo, error)
ReadDir(path string) ([]os.FileInfo, error)
Readlink(path string) (string, error)
Mkdir(path string, mode os.FileMode) error
MkdirAll(path string, mode os.FileMode) error
Remove(path string) error
Rename(oldpath, newpath string) error
Symlink(target, linkpath string) error
Link(oldpath, newpath string) error
Chmod(path string, mode os.FileMode) error
Chown(path string, uid, gid int) error
Chtimes(path string, atime, mtime time.Time) error
Truncate(path string, size int64) error
Statfs(path string) (*Statfs, error)
// Getwd returns the remote server's default working directory, used
// for "~" expansion. Backends without a meaningful working dir
// should return "/".
Getwd() (string, error)
}
FileClient is the backend-agnostic file-operation surface.
type PlatformInfo ¶
type PlatformInfo struct {
OS string // "linux", "darwin", "windows", "freebsd", ...
Arch string // "amd64", "arm64", "arm", "386", ...
Variant string // optional, e.g. "v7" for armv7l
}
PlatformInfo describes the remote machine's OS, architecture, and (when meaningful) CPU variant. Field naming follows Go's GOOS/GOARCH convention so values can be plugged into agent-binary path resolution without further translation.
Empty fields mean "not detected". Callers must treat each field independently; a backend may know the OS but not the architecture.
type RemoteFile ¶
type RemoteFile interface {
io.ReadCloser
ReadAt(p []byte, off int64) (int, error)
// Sync flushes the file's contents and metadata to durable storage
// on the remote. Backends whose underlying protocol cannot express
// fsync should return nil rather than an unsupported-operation error.
Sync() error
}
RemoteFile is the read-side handle returned by FileClient.Open. It matches the subset of *sftp.File / *os.File that workspacefs and pathstub rely on.
type RemoteWriteFile ¶
type RemoteWriteFile interface {
io.WriteCloser
ReadAt(p []byte, off int64) (int, error)
WriteAt(p []byte, off int64) (int, error)
Stat() (os.FileInfo, error)
Truncate(size int64) error
// Sync flushes the file's writes to durable storage on the remote.
// Backends whose underlying protocol cannot express fsync (e.g. an
// SFTP server that lacks the fsync@openssh.com extension) should
// return nil rather than an error so the FUSE layer can treat the
// op as a successful no-op.
Sync() error
}
RemoteWriteFile is the write-side handle returned by FileClient.Create and FileClient.OpenFile.
type Session ¶
type Session interface {
StdinPipe() (io.WriteCloser, error)
StdoutPipe() (io.Reader, error)
StderrPipe() (io.Reader, error)
Setenv(name, value string) error
Start(cmd string) error
Wait() error
Close() error
}
Session is a single command execution channel. The shape follows the subset of golang.org/x/crypto/ssh.Session that command runners need, while remaining implementable by non-SSH backends.
Source Files