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 ¶
- type Adapter
- func (a *Adapter) Capabilities() filesystem.CapabilitySet
- func (a *Adapter) Checksum(ctx context.Context, logicalPath filesystem.Path, ...) (filesystem.Checksum, error)
- func (a *Adapter) Close() error
- func (a *Adapter) Copy(ctx context.Context, source, destination filesystem.Path, ...) error
- func (a *Adapter) Delete(ctx context.Context, logicalPath filesystem.Path) error
- func (a *Adapter) List(ctx context.Context, directory filesystem.Path, options filesystem.ListOptions) (filesystem.EntryIterator, error)
- func (a *Adapter) Move(ctx context.Context, source, destination filesystem.Path, ...) error
- func (a *Adapter) Open(ctx context.Context, logicalPath filesystem.Path) (io.ReadCloser, error)
- func (a *Adapter) OpenRange(ctx context.Context, logicalPath filesystem.Path, ...) (io.ReadCloser, error)
- func (a *Adapter) OpenWriter(ctx context.Context, logicalPath filesystem.Path, ...) (io.WriteCloser, error)
- func (a *Adapter) SetMetadata(context.Context, filesystem.Path, map[string]string) error
- func (a *Adapter) SetVisibility(context.Context, filesystem.Path, filesystem.Visibility) error
- func (a *Adapter) Stat(ctx context.Context, logicalPath filesystem.Path) (filesystem.Metadata, error)
- func (a *Adapter) TemporaryURL(context.Context, filesystem.Path, time.Duration, ...) (string, error)
- func (a *Adapter) Visibility(context.Context, filesystem.Path) (filesystem.Visibility, error)
- func (a *Adapter) Write(ctx context.Context, logicalPath filesystem.Path, source io.Reader, ...) (filesystem.Metadata, error)
- type Config
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 (*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) 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) List ¶
func (a *Adapter) List(ctx context.Context, directory filesystem.Path, options filesystem.ListOptions) (filesystem.EntryIterator, error)
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 ¶
SetMetadata returns a typed unsupported error.
func (*Adapter) SetVisibility ¶
func (a *Adapter) SetVisibility(context.Context, filesystem.Path, filesystem.Visibility) error
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 ¶
func (a *Adapter) TemporaryURL(context.Context, filesystem.Path, time.Duration, filesystem.TemporaryURLOptions) (string, error)
TemporaryURL returns a typed unsupported error.
func (*Adapter) Visibility ¶
func (a *Adapter) Visibility(context.Context, filesystem.Path) (filesystem.Visibility, error)
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.