sftpx

package
v0.23.0 Latest Latest
Warning

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

Go to latest
Published: Oct 27, 2026 License: MIT Imports: 16 Imported by: 0

Documentation

Overview

Package sftpx browses and transfers files over OpenSSH's sftp subsystem.

Index

Constants

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

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

func Copy(ctx context.Context, dst FS, dstPath string, src FS, srcPath string, fn Progress) error

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

func Problem(fs FS, dest, name string, err error) error

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

func Reason(err error) error

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

type DirProgress func(rel string, done, total int64)

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 Entry

type Entry struct {
	Name    string
	Size    int64
	Mode    os.FileMode
	ModTime time.Time
	IsDir   bool
}

Entry is one row in a file listing, on either side of a transfer.

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.

func (Local) Chmod

func (Local) Chmod(p string, m os.FileMode) error

func (Local) Create

func (Local) Create(p string) (io.WriteCloser, error)

func (Local) Home

func (Local) Home() string

func (Local) Join

func (Local) Join(dir, name string) string

func (Local) Label

func (Local) Label() string

func (Local) List

func (Local) List(dir string) ([]Entry, error)

func (Local) Mkdir

func (Local) Mkdir(p string) error

func (Local) Open

func (Local) Open(p string) (io.ReadCloser, error)

func (Local) Parent

func (Local) Parent(dir string) string

func (Local) Remove

func (Local) Remove(p string) error

func (Local) Rename

func (Local) Rename(old, neu string) error

func (Local) Replace added in v0.9.10

func (Local) Replace(src, dst string) error

os.Rename already replaces an existing destination on every platform Omassh runs on.

func (Local) Stat

func (Local) Stat(p string) (Entry, error)

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

func Connect(h store.Host, opts ...string) (*Session, error)

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) Chmod

func (s *Session) Chmod(p string, m os.FileMode) error

func (*Session) Close

func (s *Session) Close() error

func (*Session) Create

func (s *Session) Create(p string) (io.WriteCloser, error)

func (*Session) Home

func (s *Session) Home() string

func (*Session) Join

func (s *Session) Join(dir, name string) string

func (*Session) Label

func (s *Session) Label() string

func (*Session) List

func (s *Session) List(dir string) ([]Entry, error)

func (*Session) Mkdir

func (s *Session) Mkdir(p string) error

func (*Session) Open

func (s *Session) Open(p string) (io.ReadCloser, error)

func (*Session) Parent

func (s *Session) Parent(dir string) string

func (*Session) Remove

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

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) Rename

func (s *Session) Rename(old, neu string) error

func (*Session) Replace added in v0.9.10

func (s *Session) Replace(src, dst string) error

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.

func (*Session) Stat

func (s *Session) Stat(p string) (Entry, error)

Jump to

Keyboard shortcuts

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