Documentation
¶
Overview ¶
Package sftpx browses and transfers files over OpenSSH's sftp subsystem.
Index ¶
- Constants
- Variables
- func Copy(ctx context.Context, dst FS, dstPath string, src FS, srcPath string, ...) error
- func Problem(fs FS, dest, name string, err error) error
- func Reason(err error) error
- type DirProgress
- type DirResult
- type Entry
- type FS
- type Local
- func (Local) Chmod(p string, m os.FileMode) error
- func (Local) Create(p string) (io.WriteCloser, error)
- func (Local) Home() string
- func (Local) Join(dir, name string) string
- func (Local) Label() string
- func (Local) List(dir string) ([]Entry, error)
- func (Local) Mkdir(p string) error
- func (Local) Open(p string) (io.ReadCloser, error)
- func (Local) Parent(dir string) string
- func (Local) Remove(p string) error
- func (Local) Rename(old, neu string) error
- func (Local) Replace(src, dst string) error
- func (Local) Stat(p string) (Entry, error)
- type Progress
- type Session
- func (s *Session) Chmod(p string, m os.FileMode) error
- func (s *Session) Close() error
- func (s *Session) Create(p string) (io.WriteCloser, error)
- func (s *Session) Home() string
- func (s *Session) Join(dir, name string) string
- func (s *Session) Label() string
- func (s *Session) List(dir string) ([]Entry, error)
- func (s *Session) Mkdir(p string) error
- func (s *Session) Open(p string) (io.ReadCloser, error)
- func (s *Session) Parent(dir string) string
- func (s *Session) Remove(p string) error
- func (s *Session) Rename(old, neu string) error
- func (s *Session) Replace(src, dst string) error
- func (s *Session) Stat(p string) (Entry, error)
Constants ¶
const PartialSuffix = ".omassh-part"
PartialSuffix names the file a transfer is still writing. It sits beside the destination rather than in a temporary directory, because the move onto the destination has to stay on the same filesystem to be a move at all.
Variables ¶
var ErrIsDirectory = errors.New("is a directory")
ErrIsDirectory is what Copy refuses a source that has no bytes of its own. CopyDir descends a directory instead of copying it, and needs to tell that refusal apart from a transfer that actually went wrong.
Functions ¶
func Copy ¶
Copy transfers one file between two filesystems. Either side may be local or remote, so the same call handles upload and download.
func Problem ¶ added in v0.10.9
Problem puts a failed operation on a name into omassh's words.
pkg/sftp turns the two status codes with os equivalents into os.ErrNotExist and os.ErrPermission and hands back the rest as they came, so a server refusing a name that is already taken reached the user as `sftp: "Failure" (SSH_FX_FAILURE)` — a protocol constant, shown to someone who has just typed a directory name.
SSH_FX_FAILURE does not say why, so the reason is established here rather than guessed at: the destination and the directory meant to hold it are asked about, the same way a forward binds its port itself before asking ssh to. What none of that explains is reported as the server refusing, which is all the protocol actually said.
func Reason ¶ added in v0.11.32
Reason is what an error from the far side says, in words rather than in the protocol's own vocabulary.
pkg/sftp maps the two status codes with os equivalents and hands back the rest as they came, so everything else — a name that is not an ordinary file, a full disk, a quota, a server that simply says no — arrived as `sftp: "Failure" (SSH_FX_FAILURE)`. Only two operations ever asked it to say that better; a transfer reported the constant straight into the bar, and the browser is where people meet the widest variety of servers.
A status can arrive wrapped in a path error — the library does that for a remove and not for an open — so this unwraps through whatever it finds rather than relying on which is outermost.
os wraps a file error in the operation and the whole path — "open /Users/…/from/report.csv: permission denied" — and the bar keeps the subject separately, so left in, the path is what survives truncation and the reason is what goes.
Types ¶
type DirProgress ¶ added in v0.12.0
DirProgress reports where a directory copy has reached: the file on its way now, named relative to the directory that was picked, and how far through that one file the copy is.
type DirResult ¶ added in v0.12.0
type DirResult struct {
Files int // files that arrived
Bytes int64 // what they came to
Skipped int // names with no bytes to copy — see CopyDir
// Failed is the file or directory the copy stopped on, relative to the
// one picked, or "" for the picked directory itself. The name is kept
// here rather than written into the error because it comes off the far
// side, and the caller is the half of this that knows how to make remote
// text safe to draw.
Failed string
}
DirResult is what a directory copy moved. It is worth reading after a failure too: the copy stops where it stopped, and this says how far it got and on what.
func CopyDir ¶ added in v0.12.0
func CopyDir(ctx context.Context, dst FS, dstPath string, src FS, srcPath string, fn DirProgress) (DirResult, error)
CopyDir copies a directory and everything under it to the other side.
The tree is walked by the listing rather than by following each name, and that is what keeps it finite: List reports a symlink as the link rather than as the thing it points at, so the walk descends only real directories, and a real directory cannot contain itself. Following instead would turn one link pointing at an ancestor into a copy that never ends.
That leaves the links themselves. Nothing in FS can write one, so a link is copied the way copying its own row already copies it — followed, and the file it names moved. A link to a directory has no bytes to move, so it is counted in Skipped and stepped over rather than failing a tree that is otherwise fine: one link is a poor reason to abandon ten thousand files.
Each file still lands atomically, by the part-file dance in Copy. The tree as a whole does not, and cannot: a copy that fails halfway leaves behind what it had already written, which is why Failed says where it stopped rather than pretending nothing happened.
type FS ¶
type FS interface {
Home() string
Join(dir, name string) string
Parent(dir string) string
List(dir string) ([]Entry, error)
Mkdir(p string) error
Remove(p string) error
Rename(old, neu string) error
// Replace moves src over dst, whether or not dst is already there. It is
// how a transfer lands: the file written beside the destination becomes
// the destination in one step, so a reader never sees half of it.
Replace(src, dst string) error
Chmod(p string, mode os.FileMode) error
Open(p string) (io.ReadCloser, error)
Create(p string) (io.WriteCloser, error)
Stat(p string) (Entry, error)
Label() string
}
FS is the small slice of filesystem behaviour the browser needs. Local and remote panes implement the same interface so the UI has one code path.
type Local ¶
type Local struct{}
Local is the machine Omassh runs on.
type Progress ¶
type Progress func(done, total int64)
Progress reports bytes copied so far for one file.
type Session ¶
type Session struct {
// contains filtered or unexported fields
}
Session is a live SFTP connection to one host.
Rather than dial SSH itself, Omassh runs `ssh -s <host> sftp` and speaks the SFTP protocol over that child's stdio. OpenSSH therefore performs the connection exactly as it would for an interactive session: ProxyJump chains, ProxyCommand, certificates, Match blocks, IdentityAgent and known_hosts all apply, with no second implementation of any of it to keep in step.
func Connect ¶
Connect opens an SFTP session to h.
BatchMode is forced on: the child's stdin carries the SFTP protocol, so ssh has nowhere to prompt for a passphrase, and failing immediately with a clear message beats hanging on a prompt no one can see.
func (*Session) Remove ¶
Remove deletes a file, or a directory and everything beneath it. SFTP has no recursive delete, so the walk happens here.
By Lstat rather than Stat, because a symlink is a name and deleting one has to delete the name rather than what it points at. Following it was quiet and expensive: deleting a link to a directory emptied that directory, and deleting a directory that merely *contained* such a link destroyed everything on the far side of it — files outside the thing being deleted, that nobody had selected, while the confirmation said "this cannot be undone" about what the listing had shown as a single file. The local pane has never done this; os.RemoveAll does not follow one either.
func (*Session) Replace ¶ added in v0.9.10
Replace moves src over dst.
SFTP's own RENAME refuses when the destination exists, so this asks for posix-rename@openssh.com, which OpenSSH's server has. Where a server does not, there is no atomic way to do it: removing first leaves a moment with nothing there, which is still better than the alternative this replaced — truncating the destination before the transfer had produced anything to put in it.