sftp

package
v2.0.3 Latest Latest
Warning

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

Go to latest
Published: Oct 22, 2026 License: MIT Imports: 23 Imported by: 0

Documentation

Overview

Package sftp provides a capability-based SFTP adapter using pkg/sftp and golang.org/x/crypto/ssh. Open acquires caller-owned sessions; quiesce operations and close streams before Adapter.Close. Host-key policy and server namespace isolation remain caller-owned; link preflight is not atomic path confinement. Remote controls after acquisition have no package-set deadline.

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

This section is empty.

Types

type Adapter

type Adapter struct {
	// contains filtered or unexported fields
}

Adapter multiplexes a shared SFTP session with synchronized reconnect/closed state. Safe completion requires quiescent Close and caller-owned stream cleanup. Link checks do not stop server-side swaps or confine unsafe subroots; configure account isolation. Capability negotiation is captured at initial acquisition.

func New deprecated

func New(ctx context.Context, configuration Config) (*Adapter, error)

New validates SSH security settings and opens the initial SFTP session.

Deprecated: use Open, which names the caller-owned session acquisition.

func Open

func Open(ctx context.Context, configuration Config) (*Adapter, error)

Open validates SSH security settings and opens a caller-owned SFTP session.

func (*Adapter) Capabilities

func (a *Adapter) Capabilities() filesystem.CapabilitySet

Capabilities reports protocol and server-extension support.

func (*Adapter) Checksum

func (a *Adapter) Checksum(ctx context.Context, logicalPath filesystem.Path, algorithm filesystem.ChecksumAlgorithm) (filesystem.Checksum, error)

Checksum streams a remote file through the requested local digest.

func (*Adapter) Close

func (a *Adapter) Close() error

Close releases the current SFTP and SSH connections.

func (*Adapter) Copy

func (a *Adapter) Copy(ctx context.Context, source, destination filesystem.Path, options filesystem.CopyOptions) error

Copy streams into a temporary destination and requires explicit overwrite because SFTP has no portable conditional destination operation.

func (*Adapter) Delete

func (a *Adapter) Delete(ctx context.Context, logicalPath filesystem.Path) error

Delete removes a file without replaying an ambiguous request.

func (*Adapter) List

List collects and sorts a result-capped view, reconnecting once on lost connections while walking. Upstream ReadDir allocation is not capped by returned entries; concurrent server changes are not a transactional snapshot.

func (*Adapter) Move

func (a *Adapter) Move(ctx context.Context, source, destination filesystem.Path, options filesystem.MoveOptions) error

Move uses the POSIX rename extension and never emulates rename with copy-and-delete.

func (*Adapter) Open

func (a *Adapter) Open(ctx context.Context, logicalPath filesystem.Path) (io.ReadCloser, error)

Open opens a remote stream and reconnects once if opening fails because the current connection was already lost.

func (*Adapter) OpenRange

func (a *Adapter) OpenRange(ctx context.Context, logicalPath filesystem.Path, byteRange filesystem.ByteRange) (io.ReadCloser, error)

OpenRange validates positive representable range syntax and limits reads. It seeks without a file-size precheck, so an offset beyond EOF may yield an empty stream rather than ErrInvalidRange. The caller closes the stream.

func (*Adapter) OpenWriter

func (a *Adapter) OpenWriter(ctx context.Context, logicalPath filesystem.Path, options filesystem.WriteOptions) (io.WriteCloser, error)

OpenWriter returns a streaming writer that publishes its remote temporary file on Close without replaying an uncertain upload.

func (*Adapter) SetMetadata

func (a *Adapter) SetMetadata(context.Context, filesystem.Path, map[string]string) error

SetMetadata returns a typed unsupported error.

func (*Adapter) SetVisibility

SetVisibility returns a typed unsupported error.

func (*Adapter) Stat

func (a *Adapter) Stat(ctx context.Context, logicalPath filesystem.Path) (filesystem.Metadata, error)

Stat retrieves metadata and reconnects once after a lost connection.

func (*Adapter) TemporaryURL

TemporaryURL returns a typed unsupported error.

func (*Adapter) Visibility

Visibility returns a typed unsupported error.

func (*Adapter) Write

func (a *Adapter) Write(ctx context.Context, logicalPath filesystem.Path, source io.Reader, options filesystem.WriteOptions) (filesystem.Metadata, error)

Write publishes through a temporary file. A consumed source is never replayed after connection loss. Sync-unsupported is tolerated, not durable persistence proof. IfNoneMatch is rejected; overwrite uses the negotiated POSIX rename extension, and post-rename Stat/cancellation can fail after publish.

type Config

type Config struct {
	// Address is the SSH server host and port.
	Address string
	// User is the SSH username.
	User string
	// Auth contains one or more SSH authentication methods.
	Auth []ssh.AuthMethod
	// HostKeyCallback is mandatory, but the adapter cannot prove it verifies keys.
	// Supply a trusted verifier; callbacks/authentication referents remain borrowed.
	HostKeyCallback ssh.HostKeyCallback
	// Root is the absolute remote directory containing all logical paths.
	Root string
	// AllowUnsafeSubroot permits a Root other than "/". SFTP cannot atomically
	// reject links and use a path; callers must enforce confinement at the server.
	AllowUnsafeSubroot bool
	// Timeout bounds TCP dialing; zero selects 30 seconds. The operation
	// context's cancellation or deadline bounds SSH setup.
	Timeout time.Duration
	// MaxListEntries bounds one listing; zero selects 10,000.
	MaxListEntries int
}

Config contains SSH connection and remote-root settings.

Jump to

Keyboard shortcuts

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