Documentation
¶
Index ¶
- Constants
- Variables
- func Definition() contract.Definition
- type APIBackend
- func (a *APIBackend) Close() error
- func (a *APIBackend) Connect(ctx context.Context, host string, port int, user string, keyFile string, ...) error
- func (a *APIBackend) Exec(ctx context.Context, command string) (*ExecResult, error)
- func (a *APIBackend) Get(ctx context.Context, remotePath, localPath string) (int64, error)
- func (a *APIBackend) GetDir(ctx context.Context, remoteDir, localDir string) (*DirTransferResult, error)
- func (a *APIBackend) Ping(ctx context.Context) error
- func (a *APIBackend) Put(ctx context.Context, localPath, remotePath string) (int64, error)
- func (a *APIBackend) PutDir(ctx context.Context, localDir, remoteDir string) (*DirTransferResult, error)
- type Backend
- type BackendFactory
- type Connector
- func (c *Connector) Capabilities() contract.Capabilities
- func (c *Connector) Create(_ context.Context, _ *resource.Resource) error
- func (c *Connector) Definition() contract.Definition
- func (c *Connector) Destroy(_ context.Context, _ *resource.Resource) error
- func (c *Connector) Exec(ctx context.Context, res *resource.Resource, command string) (*ExecResult, error)
- func (c *Connector) ExecJSON(ctx context.Context, res *resource.Resource, command string) (string, error)
- func (c *Connector) Get(ctx context.Context, res *resource.Resource, remotePath, localPath string) (*TransferResult, error)
- func (c *Connector) GetDir(ctx context.Context, res *resource.Resource, remoteDir, localDir string) (*DirTransferResult, error)
- func (c *Connector) HostStatusJSON(ctx context.Context, res *resource.Resource) (string, error)
- func (c *Connector) ID() string
- func (c *Connector) Put(ctx context.Context, res *resource.Resource, localPath, remotePath string) (*TransferResult, error)
- func (c *Connector) PutDir(ctx context.Context, res *resource.Resource, localDir, remoteDir string) (*DirTransferResult, error)
- func (c *Connector) ResourceTypes() []string
- func (c *Connector) Start(_ context.Context, _ *resource.Resource) error
- func (c *Connector) Status(ctx context.Context, res *resource.Resource) (resource.State, error)
- func (c *Connector) Stop(ctx context.Context, res *resource.Resource) error
- type DirTransferEntry
- type DirTransferResult
- type DirUploadPreview
- type ExecResult
- type HostKeyConfig
- type HostStatus
- type TransferResult
Constants ¶
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 ¶
var OperationFields = []string{FieldID, FieldCommand, FieldLocalPath, FieldRemotePath}
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) 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) Put ¶
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 NewWithBackendFactory ¶
func NewWithBackendFactory(secrets secret.Reader, factory BackendFactory) *Connector
func (*Connector) Capabilities ¶
func (c *Connector) Capabilities() contract.Capabilities
func (*Connector) Definition ¶
func (c *Connector) Definition() contract.Definition
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 ¶
HostStatusJSON returns the connectivity status of a remote host as JSON.
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 ¶
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 ¶
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.