sftp

package
v0.4.0 Latest Latest
Warning

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

Go to latest
Published: Oct 26, 2026 License: Apache-2.0 Imports: 17 Imported by: 0

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

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

func New(cfg Config) (*FS, error)

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

func (f *FS) Caps(string) vfs.Cap

Caps reports the SFTP capability set.

func (*FS) Close

func (f *FS) Close() error

Close releases the connection.

func (*FS) List

func (f *FS) List(ctx context.Context, p string) iter.Seq2[vfs.Entry, error]

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

func (f *FS) Mkdir(ctx context.Context, p string) error

Mkdir creates a directory.

func (*FS) Open

func (f *FS) Open(ctx context.Context, p string, opts vfs.OpenOptions) (vfs.File, error)

Open returns a read handle, seeking first when a range is asked for.

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

func (f *FS) Remove(ctx context.Context, p string, _ bool) error

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.

func (*FS) Rename

func (f *FS) Rename(ctx context.Context, oldpath, newpath string) error

Rename moves oldpath to newpath.

func (*FS) Stat

func (f *FS) Stat(ctx context.Context, p string) (vfs.Entry, error)

Stat returns metadata for one path.

Jump to

Keyboard shortcuts

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