Help us shape the future of Go! Take the 2026 Go Developer Survey

remote

package
v0.3.6 Latest Latest
Warning

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

Go to latest
Published: Sep 20, 2026 License: MIT Imports: 25 Imported by: 0

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

View Source
const (
	ManifestName = ".vrs-manifest.json"
	TrashDirName = ".vrs-trash"
)

Reserved names at export/import targets. They belong to vrs, never to user content.

View Source
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

func IsNotExist(err error) bool

IsNotExist reports whether an Fs error means "does not exist", for both the local and the SFTP backend.

func Reserved

func Reserved(p string) bool

Reserved reports whether a snapshot entry path collides with the names vrs owns at a target.

func TerminalPassphrasePrompt added in v0.3.3

func TerminalPassphrasePrompt(path string) (string, error)

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

type FileProgress func(done, total int, path string, size int64)

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.

func (*LocalFs) Chmod

func (l *LocalFs) Chmod(p string, mode uint32) error

func (*LocalFs) Close

func (l *LocalFs) Close() error

func (*LocalFs) MkdirAll

func (l *LocalFs) MkdirAll(dir string) error

func (*LocalFs) ReadDir

func (l *LocalFs) ReadDir(dir string) ([]FileInfo, error)

func (*LocalFs) ReadFile

func (l *LocalFs) ReadFile(p string) ([]byte, error)

func (*LocalFs) Remove

func (l *LocalFs) Remove(p string) error

func (*LocalFs) Rename

func (l *LocalFs) Rename(oldPath, newPath string) error

func (*LocalFs) SetMtime

func (l *LocalFs) SetMtime(p string, mtime int64) error

func (*LocalFs) Stat

func (l *LocalFs) Stat(p string) (FileInfo, error)

func (*LocalFs) WriteFile

func (l *LocalFs) WriteFile(p string, data []byte, mode uint32) error

type Planned

type Planned struct {
	Rel   string
	Size  int64
	Mode  uint32
	Mtime int64
}

Planned is one file an import will download.

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

func ResolveSSH(user, host string, port int, cfgPath, knownHostsPath string) (SSHConfig, error)

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

type ScanProgress func(scanned int, path string)

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

func Connect(cfg SSHConfig) (*SftpFs, error)

Connect opens an SSH+SFTP session with explicit parameters (tests use this directly; Dial resolves the user's configuration first).

func Dial

func Dial(t Target) (*SftpFs, error)

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.

func DialWith added in v0.3.1

func DialWith(t Target, cfgPath, knownHostsPath string) (*SftpFs, error)

DialWith is Dial with injectable ssh_config and known_hosts paths (tests).

func NewSftpFs

func NewSftpFs(c *sftp.Client) *SftpFs

NewSftpFs wraps an established SFTP client.

func (*SftpFs) Chmod

func (s *SftpFs) Chmod(p string, mode uint32) error

func (*SftpFs) Close

func (s *SftpFs) Close() error

func (*SftpFs) MkdirAll

func (s *SftpFs) MkdirAll(dir string) error

func (*SftpFs) ReadDir

func (s *SftpFs) ReadDir(dir string) ([]FileInfo, error)

func (*SftpFs) ReadFile

func (s *SftpFs) ReadFile(p string) ([]byte, error)

func (*SftpFs) Remove

func (s *SftpFs) Remove(p string) error

func (*SftpFs) Rename

func (s *SftpFs) Rename(oldPath, newPath string) error

func (*SftpFs) SetMtime

func (s *SftpFs) SetMtime(p string, mtime int64) error

func (*SftpFs) Stat

func (s *SftpFs) Stat(p string) (FileInfo, error)

func (*SftpFs) WriteFile

func (s *SftpFs) WriteFile(p string, data []byte, mode uint32) error

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

func ParseTarget(arg string) (Target, error)

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.

func (Target) String

func (t Target) String() string

String renders the target as the user wrote it.

Jump to

Keyboard shortcuts

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