Documentation
¶
Overview ¶
Package remote implements the transport layer for vrs export/import: target parsing, SSH/SFTP connections, filesystem abstraction, and the sync engines (snapshot → target, target → working tree).
Index ¶
- Constants
- func ApplyImport(plan *ImportPlan, src Fs, srcRoot string, dst Fs, dstRoot, trashBase string, ...) error
- func IsNotExist(err error) bool
- func Reserved(p string) bool
- func TerminalPassphrasePrompt(path string) (string, error)
- type ExportResult
- type FileInfo
- type FileProgress
- type Fs
- type ImportPlan
- type LocalFs
- func (l *LocalFs) Chmod(p string, mode uint32) error
- func (l *LocalFs) Close() error
- func (l *LocalFs) MkdirAll(dir string) error
- func (l *LocalFs) ReadDir(dir string) ([]FileInfo, error)
- func (l *LocalFs) ReadFile(p string) ([]byte, error)
- func (l *LocalFs) Remove(p string) error
- func (l *LocalFs) Rename(oldPath, newPath string) error
- func (l *LocalFs) SetMtime(p string, mtime int64) error
- func (l *LocalFs) Stat(p string) (FileInfo, error)
- func (l *LocalFs) WriteFile(p string, data []byte, mode uint32) error
- type Planned
- type SSHConfig
- type ScanProgress
- type SftpFs
- func (s *SftpFs) Chmod(p string, mode uint32) error
- func (s *SftpFs) Close() error
- func (s *SftpFs) MkdirAll(dir string) error
- func (s *SftpFs) ReadDir(dir string) ([]FileInfo, error)
- func (s *SftpFs) ReadFile(p string) ([]byte, error)
- func (s *SftpFs) Remove(p string) error
- func (s *SftpFs) Rename(oldPath, newPath string) error
- func (s *SftpFs) SetMtime(p string, mtime int64) error
- func (s *SftpFs) Stat(p string) (FileInfo, error)
- func (s *SftpFs) WriteFile(p string, data []byte, mode uint32) error
- type Target
Constants ¶
const ( ManifestName = ".vrs-manifest.json" TrashDirName = ".vrs-trash" )
Reserved names at export/import targets. They belong to vrs, never to user content.
const RepoConfigName = ".vrsignore"
RepoConfigName is the repository's own config file. It is tracked and versioned like any other file, but never shipped: a target directory is not a vrs repository. Nested files of the same name are user content (per-directory scoping, like gitignore) and do ship.
Variables ¶
This section is empty.
Functions ¶
func ApplyImport ¶
func ApplyImport(plan *ImportPlan, src Fs, srcRoot string, dst Fs, dstRoot, trashBase string, prog FileProgress) error
ApplyImport performs a plan: download files (preserving mtimes, so repeats are incremental), then move pruned files to trashBase.
func IsNotExist ¶
IsNotExist reports whether an Fs error means "does not exist", for both the local and the SFTP backend.
func Reserved ¶
Reserved reports whether a snapshot entry path collides with the names vrs owns at a target.
func TerminalPassphrasePrompt ¶ added in v0.3.3
TerminalPassphrasePrompt reads a key passphrase from the terminal with echo disabled. It refuses when stdin is not a TTY (scripts, MCP) — no silent hangs.
Types ¶
type ExportResult ¶
type ExportResult struct {
Snapshot int64
Written []string // snapshot paths uploaded
ModeOnly int // files present and correct but chmod'ed
Skipped int // already at the recorded state
Pruned []string // target paths moved to trash (--prune)
}
ExportResult reports what an export did.
func ExportTree ¶
func ExportTree(entries map[string]snap.Entry, src snap.ContentSource, dst Fs, root string, prune bool, prog FileProgress) (*ExportResult, error)
ExportTree materializes snapshot entries onto dst, rooted at root. src provides file content by hash (the vrs store). Incremental via the target manifest; the manifest is rewritten only after everything succeeded, so an interrupted export leaves the target consistent.
type FileInfo ¶
type FileInfo struct {
Name string
Size int64
Mode uint32 // permission bits
Mtime int64 // unix nanos; 0 = unknown
IsDir bool
Regular bool // plain file (not a symlink, socket, …)
}
FileInfo is the minimal file description the sync engine needs, uniform across local and SFTP filesystems.
type FileProgress ¶ added in v0.3.4
FileProgress reports a file being transferred: done is 1-based, total is the number of files in the pass (0 if unknown), size in bytes.
type Fs ¶
type Fs interface {
ReadDir(dir string) ([]FileInfo, error)
Stat(p string) (FileInfo, error)
ReadFile(p string) ([]byte, error)
// WriteFile writes data to p atomically (temp + rename) and applies mode.
WriteFile(p string, data []byte, mode uint32) error
Chmod(p string, mode uint32) error
SetMtime(p string, mtime int64) error
MkdirAll(dir string) error
Remove(p string) error
Rename(oldPath, newPath string) error
Close() error
}
Fs abstracts the filesystem the sync engine talks to. Implementations: local directories (LocalFs) and SFTP connections (SftpFs).
type ImportPlan ¶
type ImportPlan struct {
Source string
Files []Planned // remote files to download (overlay)
Pruned []string // local tracked files absent from the source (--prune)
// contains filtered or unexported fields
}
ImportPlan is the computed difference between a source tree and the working tree, before anything is touched.
func PlanImport ¶
func PlanImport(src Fs, srcRoot string, dst Fs, dstRoot string, ign snap.Ignore, prune bool, scan ScanProgress) (*ImportPlan, error)
PlanImport walks the source tree and computes what an import would do, without touching anything. ign is the repository's ignore rules; they filter the download set exactly as a save would.
type LocalFs ¶
type LocalFs struct{}
LocalFs is the local-filesystem implementation of Fs.
func NewLocalFs ¶
func NewLocalFs() *LocalFs
NewLocalFs returns a filesystem backed by the caller's machine.
type SSHConfig ¶
type SSHConfig struct {
User string
Addr string // host:port
IdentityFiles []string // explicit keys from ssh_config (may be empty)
KnownHosts string // known_hosts file
IdentitiesOnly bool // offer only IdentityFiles (agent keys used just to supply those identities)
// PassphrasePrompt, when set, is asked for the passphrase of an
// encrypted identity file the agent doesn't already hold. Nil means
// encrypted keys are skipped (scripts, tests).
PassphrasePrompt func(path string) (string, error)
}
SSHConfig holds resolved connection parameters for an SSH target.
func ResolveSSH ¶
ResolveSSH expands an ssh_config alias into concrete connection parameters. An explicit port (URI form) overrides the config's Port; a missing config file falls back to defaults; an empty cfgPath skips alias resolution entirely (tests).
type ScanProgress ¶ added in v0.3.4
ScanProgress is called as a source walk considers each file: scanned counts files seen so far. Calls are cheap — callers throttle.
type SftpFs ¶
type SftpFs struct {
// contains filtered or unexported fields
}
SftpFs is the SFTP implementation of Fs.
func Connect ¶
Connect opens an SSH+SFTP session with explicit parameters (tests use this directly; Dial resolves the user's configuration first).
func Dial ¶
Dial opens an SFTP filesystem for an SSH target, resolving the user's ~/.ssh/config, keys and known_hosts. Encrypted keys the agent doesn't hold prompt for a passphrase when run on a terminal.
type Target ¶
type Target struct {
Kind string // "local" | "ssh"
User string // ssh only
Host string // ssh only, after alias resolution
Port int // ssh only; 0 = unspecified (ssh_config Port, else 22)
Path string // absolute local path, or absolute remote path
Arg string // the target as the user wrote it (used in messages)
}
Target is a parsed export/import destination.
func ParseTarget ¶
ParseTarget recognizes:
ssh://[user@]host[:port]/abs/path (URI form — the only way to give a port) [user@]host:/abs/path (scp form) local paths (relative or absolute, ~ expanded)
Remote paths must be absolute. In the URI form an explicit port overrides ~/.ssh/config's Port; everything else (user, hostname alias, identity) still resolves through ssh_config like ssh itself.