Documentation
¶
Overview ¶
Package sftp implements a vfs.FileSystem over a remote SFTP server.
It is a client. The SFTP *export* in internal/exports/sftp is a different component that happens to speak the same protocol; running both means filesd is bridging SFTP to itself, which is how this package's conformance suite runs without an external server.
Design: docs/superpowers/specs/2026-08-09-sftp-source-design.md.
Index ¶
- type Config
- type FS
- func (f *FS) Caps(string) vfs.Cap
- func (f *FS) Close() error
- func (f *FS) List(ctx context.Context, p string) iter.Seq2[vfs.Entry, error]
- func (f *FS) Mkdir(ctx context.Context, p string) error
- func (f *FS) Open(ctx context.Context, p string, opts vfs.OpenOptions) (vfs.File, error)
- func (f *FS) Put(ctx context.Context, p string, r io.Reader, opts vfs.PutOptions) (vfs.Entry, error)
- func (f *FS) Remove(ctx context.Context, p string, _ bool) error
- func (f *FS) Rename(ctx context.Context, oldpath, newpath string) error
- func (f *FS) Stat(ctx context.Context, p string) (vfs.Entry, error)
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
This section is empty.
Types ¶
type Config ¶
type Config struct {
// Addr is host:port.
Addr string
// User is the SSH username.
User string
// KeyFile is the path to a private key. Preferred over a password.
KeyFile string
// Password authenticates when no key is given. Supplied from the
// daemon's environment via password_env; never stored in config.
Password string
// KnownHosts is the path to a known_hosts file used to verify the
// server. Required — see New.
KnownHosts string
// HostKeyCallback overrides KnownHosts. Tests set it; there is no
// configuration path to it, so an operator cannot disable verification.
HostKeyCallback ssh.HostKeyCallback
}
Config describes the remote server.
type FS ¶
type FS struct {
// contains filtered or unexported fields
}
FS is a view of a remote SFTP tree.
func New ¶
New prepares a client. Nothing is dialled here: a server that is merely slow to start should not make adding a source fail, and the first request connects.
**Host key verification is mandatory.** A known_hosts file (or, for tests, an explicit callback) must be supplied. ssh.InsecureIgnoreHostKey is deliberately unreachable from configuration: connecting to a server whose identity is never checked, over a protocol whose entire security model rests on checking it, is precisely the "looks authenticated, checks nothing" failure this project refuses elsewhere. An operator who has no known_hosts entry should fetch and confirm the fingerprint, which is work the daemon cannot honestly do on their behalf.
func (*FS) List ¶
List streams a directory's children.
pkg/sftp's ReadDir materializes the directory, so this cannot stream all the way down to the wire; what it can do is not add a second copy, and stop fetching nothing further once a caller stops. The limit is the library's, and it is recorded rather than hidden.
func (*FS) Put ¶
func (f *FS) Put(ctx context.Context, p string, r io.Reader, opts vfs.PutOptions) (vfs.Entry, error)
Put writes r to p, creating parents as the contract requires -- SFTP's Create does not.
func (*FS) Remove ¶
Remove deletes p.
SFTP separates removing a file from removing a directory, and refuses a non-empty directory itself, which is exactly the contract's non-recursive behaviour. recursive is not honoured: an unbounded, irreversible delete should arrive as its own decision, the same call the S3 and WebDAV sources make.