ssh

package
v0.5.0-beta.1 Latest Latest
Warning

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

Go to latest
Published: Sep 30, 2026 License: MIT Imports: 21 Imported by: 0

Documentation

Index

Constants

View Source
const (
	FieldID         = "id"
	FieldCommand    = "command"
	FieldLocalPath  = "local_path"
	FieldRemotePath = "remote_path"
)

Operation fields are the only keys an SSH operation's config may carry. Everything that decides where and how to connect — host, port, user, key, host-key settings — comes from the configured resource named by id. The admin lane enforces this list (it refuses every other key by name), and the operations' input schemas are built from it, so discovery advertises exactly what enforcement accepts.

Variables

OperationFields is every key an ssh operation accepts. Connection settings are not among them: they come from the configured resource.

Functions

func Definition

func Definition() contract.Definition

Types

type APIBackend

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

APIBackend implements Backend using the golang.org/x/crypto/ssh library.

func NewAPIBackend

func NewAPIBackend() *APIBackend

NewAPIBackend creates an unconnected APIBackend. Call Connect before use.

func (*APIBackend) Close

func (a *APIBackend) Close() error

func (*APIBackend) Connect

func (a *APIBackend) Connect(ctx context.Context, host string, port int, user string, keyFile string, hostKey HostKeyConfig) error

func (*APIBackend) Exec

func (a *APIBackend) Exec(ctx context.Context, command string) (*ExecResult, error)

func (*APIBackend) Get

func (a *APIBackend) Get(ctx context.Context, remotePath, localPath string) (int64, error)

Get copies a file from the remote host to a local path.

func (*APIBackend) GetDir

func (a *APIBackend) GetDir(ctx context.Context, remoteDir, localDir string) (*DirTransferResult, error)

GetDir recursively downloads a remote directory tree. It is the same walk as PutDir with the ends exchanged, including the refusal to follow a symlink out of the tree — a download is where "it is only reading" quietly becomes "it wrote outside the destination".

func (*APIBackend) Ping

func (a *APIBackend) Ping(ctx context.Context) error

func (*APIBackend) Put

func (a *APIBackend) Put(ctx context.Context, localPath, remotePath string) (int64, error)

Put copies a local file to the remote host.

The write goes to a temporary name in the destination directory and is then renamed over the target. A deploy that dies midway therefore leaves the previous file intact instead of a truncated one — which matters when the target is a compose file or an env file that something is about to read.

func (*APIBackend) PutDir

func (a *APIBackend) PutDir(ctx context.Context, localDir, remoteDir string) (*DirTransferResult, error)

PutDir recursively uploads a local directory tree.

The walk, the escape check, the temp-and-rename per file and the between-files cancellation all live in go-sftpsync; this is the binding. Recursion is not reimplemented here on purpose — see WP-9 in docs/plans/connector-work-packages.md for why that library exists.

type Backend

type Backend interface {
	// Connect establishes an SSH connection to the given host.
	Connect(ctx context.Context, host string, port int, user string, keyFile string, hostKey HostKeyConfig) error

	// Exec runs a command on the connected remote host.
	Exec(ctx context.Context, command string) (*ExecResult, error)

	// Ping verifies the connection is alive by running a simple command.
	Ping(ctx context.Context) error

	// Put copies a local file to remotePath on the connected host, creating or
	// truncating it, and returns the number of bytes written.
	Put(ctx context.Context, localPath, remotePath string) (int64, error)

	// Get copies remotePath from the connected host to localPath, creating or
	// truncating it, and returns the number of bytes written.
	Get(ctx context.Context, remotePath, localPath string) (int64, error)

	// PutDir recursively copies the localDir tree to remoteDir on the
	// connected host, and reports what it moved.
	PutDir(ctx context.Context, localDir, remoteDir string) (*DirTransferResult, error)

	// GetDir recursively copies the remoteDir tree from the connected host to
	// localDir, and reports what it moved.
	GetDir(ctx context.Context, remoteDir, localDir string) (*DirTransferResult, error)

	// Close terminates the SSH connection.
	Close() error
}

Backend defines how the SSH connector communicates with remote hosts.

type BackendFactory

type BackendFactory func() Backend

type Connector

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

Connector manages remote servers via SSH.

func New

func New(secrets secret.Reader) *Connector

New creates an SSH connector.

func NewWithBackendFactory

func NewWithBackendFactory(secrets secret.Reader, factory BackendFactory) *Connector

func (*Connector) Capabilities

func (c *Connector) Capabilities() contract.Capabilities

func (*Connector) Create

func (c *Connector) Create(_ context.Context, _ *resource.Resource) error

func (*Connector) Definition

func (c *Connector) Definition() contract.Definition

func (*Connector) Destroy

func (c *Connector) Destroy(_ context.Context, _ *resource.Resource) error

func (*Connector) Exec

func (c *Connector) Exec(ctx context.Context, res *resource.Resource, command string) (*ExecResult, error)

Exec runs an arbitrary command on the remote host described by the resource.

func (*Connector) ExecJSON

func (c *Connector) ExecJSON(ctx context.Context, res *resource.Resource, command string) (string, error)

ExecJSON runs a command and returns the result as JSON.

func (*Connector) Get

func (c *Connector) Get(ctx context.Context, res *resource.Resource, remotePath, localPath string) (*TransferResult, error)

Get downloads a file from the remote host described by the resource.

func (*Connector) GetDir

func (c *Connector) GetDir(ctx context.Context, res *resource.Resource, remoteDir, localDir string) (*DirTransferResult, error)

GetDir recursively downloads a remote directory tree from the host described by the resource.

func (*Connector) HostStatusJSON

func (c *Connector) HostStatusJSON(ctx context.Context, res *resource.Resource) (string, error)

HostStatusJSON returns the connectivity status of a remote host as JSON.

func (*Connector) ID

func (c *Connector) ID() string

func (*Connector) Put

func (c *Connector) Put(ctx context.Context, res *resource.Resource, localPath, remotePath string) (*TransferResult, error)

Put uploads a local file to the remote host described by the resource.

func (*Connector) PutDir

func (c *Connector) PutDir(ctx context.Context, res *resource.Resource, localDir, remoteDir string) (*DirTransferResult, error)

PutDir recursively uploads a local directory tree to the remote host described by the resource.

func (*Connector) ResourceTypes

func (c *Connector) ResourceTypes() []string

func (*Connector) Start

func (c *Connector) Start(_ context.Context, _ *resource.Resource) error

func (*Connector) Status

func (c *Connector) Status(ctx context.Context, res *resource.Resource) (resource.State, error)

func (*Connector) Stop

func (c *Connector) Stop(ctx context.Context, res *resource.Resource) error

type DirTransferEntry

type DirTransferEntry struct {
	Path   string `json:"path"`
	Action string `json:"action"`
	Mode   string `json:"mode,omitempty"`
	Size   int64  `json:"size,omitempty"`
	Target string `json:"target,omitempty"`
	Reason string `json:"reason,omitempty"`
}

DirTransferEntry is one path the walk reached. Paths are relative to the transfer root and slash-separated on both ends, so the two sides compare.

type DirTransferResult

type DirTransferResult struct {
	Direction  string             `json:"direction"`
	LocalPath  string             `json:"local_path"`
	RemotePath string             `json:"remote_path"`
	DryRun     bool               `json:"dry_run"`
	Files      int                `json:"files"`
	Dirs       int                `json:"dirs"`
	Symlinks   int                `json:"symlinks"`
	Skipped    int                `json:"skipped"`
	Bytes      int64              `json:"bytes"`
	DurationMS int64              `json:"duration_ms"`
	Entries    []DirTransferEntry `json:"entries"`
}

DirTransferResult reports what a recursive transfer moved.

It is a Cerberus type rather than go-sftpsync's own Result, per docs/adr/0003-connector-response-dtos.md. Nothing in that library's result is credential-bearing, so this DTO exists to reshape rather than to exclude: os.FileMode marshals as an opaque integer and time.Duration as a nanosecond count, neither of which is readable in CLI output or in an agent's context. It is also the type decodeConnectorPayload decodes into, which wants a shape that cannot change under a dependency's release schedule.

LocalPath and RemotePath name the two ends rather than source and destination, matching TransferResult and the config keys the CLI sends; Direction says which way the bytes went.

type DirUploadPreview

type DirUploadPreview struct {
	Files    int
	Dirs     int
	Symlinks int
	Skipped  int
	Bytes    int64
	Warnings []string
}

DirUploadPreview describes the local tree a put_dir would send.

The counts come from a second walk rather than from go-sftpsync's dry-run mode, because a preview runs before the connector is resolved and so has no SFTP client to hand the library. The walk therefore mirrors the library's: same root handling, same per-entry lstat, same symlink rule, same depth bound. TestPreviewMatchesLibraryDryRun is the guard against the two drifting apart.

func PreviewDirUpload

func PreviewDirUpload(localDir string) DirUploadPreview

PreviewDirUpload walks localDir and reports what a put_dir would move.

It returns no error. Everything it cannot read becomes a warning: an operator reading a preview is deciding whether to proceed, and a walk that failed on one unreadable subdirectory is still worth seeing the rest of.

type ExecResult

type ExecResult struct {
	Stdout   string `json:"stdout" cerb:"untrusted"`
	Stderr   string `json:"stderr" cerb:"untrusted"`
	ExitCode int    `json:"exit_code"`
}

ExecResult holds the output of a remote command execution.

type HostKeyConfig

type HostKeyConfig struct {
	KnownHostsFile       string
	AllowInsecureHostKey bool
}

HostKeyConfig controls how the SSH connector verifies remote host keys.

type HostStatus

type HostStatus struct {
	Reachable bool          `json:"reachable"`
	Latency   time.Duration `json:"latency"`
	OS        string        `json:"os" cerb:"untrusted"`
}

HostStatus holds connectivity and OS information about a remote host.

type TransferResult

type TransferResult struct {
	LocalPath  string `json:"local_path"`
	RemotePath string `json:"remote_path"`
	Bytes      int64  `json:"bytes"`
}

TransferResult reports the outcome of a file transfer.

Jump to

Keyboard shortcuts

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