sftp

package
v0.16.0 Latest Latest
Warning

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

 Go to latest Published: Nov 8, 2026 License: MIT Imports: 22 Imported by: 0

Documentation

Index

Constants

View Source 
const (
	DefaultConcurrentFiles = 5
	DefaultThreadsPerFile  = 64
	DefaultChunkSize       = 32 * 1024
	DefaultResumeMinSize   = 1024 * 1024
	DefaultTempSuffix      = ".xops-tmp"
)

Variables

This section is empty.

Functions

func AvailableStorageSpace added in v0.15.0 

func AvailableStorageSpace(vfs *sftp.StatVFS) uint64

AvailableStorageSpace returns the available space in bytes from StatVFS.

func FormatByteSize added in v0.15.0 

func FormatByteSize(bytes uint64) string

FormatByteSize formats a byte count into a human-readable size string (e.g. "24.5 KB", "40.0 GB").

func TotalStorageSpace added in v0.15.0 

func TotalStorageSpace(vfs *sftp.StatVFS) uint64

TotalStorageSpace returns the total space in bytes from StatVFS.

Types

type Client 

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

func NewClient 

func NewClient(ctx context.Context, sshCli *ssh.Client, opts ...Option) (*Client, error)

NewClient creates an SFTP subsystem on an existing SSH connection. Setup is bounded by ctx and an internal maximum timeout, including subsystem and protocol handshakes.

func (*Client) Close 

func (c *Client) Close() error

Close closes this SFTP subsystem. A blocked subsystem close may close the shared SSH transport as a bounded last-resort interrupt.

func (*Client) Config 

func (c *Client) Config() TransferConfig

Config 返回当前传输配置

func (*Client) CreatePrivateExclusive 

func (c *Client) CreatePrivateExclusive(ctx context.Context, name string, write func(io.Writer) error) (attempted, created bool, retErr error)

CreatePrivateExclusive creates a file with mode 0600 in the initial SFTP OPEN, invokes write while holding that exact handle, then closes it. The v1 client cannot send creation permissions; a separate bounded subsystem with the upstream packet codec is used only for this operation, preserving existing v1 rename/extension semantics. created distinguishes an acknowledged exclusive open from a lost/rejected reply; callers must not infer ownership from a failed open.

func (*Client) Cwd 

func (c *Client) Cwd(ctx context.Context) (cwd string, retErr error)

Cwd returns the remote working directory using the caller's cancellation boundary.

func (*Client) Do 

func (c *Client) Do(ctx context.Context, operation func(*sftp.Client) error) error

Do runs a low-level SFTP operation with context cancellation. It deliberately adds no command policy or presentation concerns; callers retain ownership of operation-specific error context. Cancellation interrupts this SFTP subsystem, so the client must not be reused afterwards.

func (*Client) Download 

func (c *Client) Download(ctx context.Context, remotePath, localPath string, progress ProgressCallback) error

Download 下载入口：支持文件或目录（顶层路径使用 Stat 解引用符号链接，与 OpenSSH scp 单路径行为一致； 目录递归遍历内部则通过 DownloadLink 保留子项符号链接）。

func (*Client) DownloadDirectory 

func (c *Client) DownloadDirectory(ctx context.Context, remoteDir, localDir string, progress ProgressCallback) error

func (*Client) DownloadFile 

func (c *Client) DownloadFile(ctx context.Context, remotePath, localPath string, size int64, mode os.FileMode, progress ProgressCallback) (retErr error)
func (c *Client) DownloadLink(ctx context.Context, remotePath, localPath string, progress ProgressCallback) error

func (*Client) JoinPath 

func (c *Client) JoinPath(elem ...string) string

JoinPath 辅助函数：处理远程路径拼接 (SFTP 协议强制使用 forward slash)

func (*Client) Lstat 

func (c *Client) Lstat(ctx context.Context, remotePath string) (os.FileInfo, error)

Lstat returns the FileInfo for a remote path without following symbolic links, using the caller's cancellation boundary.

func (*Client) RealPath 

func (c *Client) RealPath(ctx context.Context, remotePath string) (string, error)

RealPath returns the canonicalized absolute path on the remote host, using the caller's cancellation boundary.

func (*Client) RemoteCopy 

func (c *Client) RemoteCopy(ctx context.Context, src, dst string) (retErr error)

RemoteCopy copies a remote file, directory, or symbolic link through SFTP. Symbolic links are copied as links and are never followed during traversal.

func (*Client) RemoveAll 

func (c *Client) RemoveAll(ctx context.Context, remotePath string) error

RemoveAll removes a remote file, directory tree, or symbolic link through SFTP. Symbolic links are removed as links and are never followed.

func (*Client) Rename 

func (c *Client) Rename(ctx context.Context, src, dst string) error

Rename renames one remote entry through SFTP.

func (*Client) ReplaceRemoteFile 

func (c *Client) ReplaceRemoteFile(ctx context.Context, tempPath, remotePath string) error

ReplaceRemoteFile promotes a temporary remote file to its destination while preserving an existing destination when the replacement fails. Cancellation interrupts this SFTP subsystem, so the client must not be reused afterwards.

func (*Client) SFTPClient 

func (c *Client) SFTPClient() *sftp.Client

SFTPClient returns the underlying *sftp.Client.

func (*Client) Stat 

func (c *Client) Stat(ctx context.Context, remotePath string) (os.FileInfo, error)

Stat returns the FileInfo for a remote path using the caller's cancellation boundary.

func (*Client) StatVFS added in v0.15.0 

func (c *Client) StatVFS(ctx context.Context, remotePath string) (*sftp.StatVFS, error)

StatVFS returns VFS statistics for the remote path. If the server does not support the statvfs@openssh.com extension, it returns an error.

func (*Client) StreamTransfer 

func (c *Client) StreamTransfer(ctx context.Context, source *Client, r io.Reader, w io.Writer, size int64, progress ProgressCallback) error

StreamTransfer copies exactly size bytes between two SFTP clients. The caller retains ownership of r and w. Cancellation interrupts both clients' SFTP subsystems, so both SFTP clients become unusable afterwards. Shared SSH transports remain open unless a subsystem close itself blocks and requires the bounded transport fallback documented on Client.

func (*Client) Upload 

func (c *Client) Upload(ctx context.Context, localPath, remotePath string, progress ProgressCallback) error

Upload 上传入口：支持文件或目录（顶层路径使用 os.Stat 解引用符号链接，与 OpenSSH scp 单路径行为一致； 目录递归遍历内部则通过 UploadLink 保留子项符号链接）。

func (*Client) UploadDirectory 

func (c *Client) UploadDirectory(ctx context.Context, localDir, remoteDir string, progress ProgressCallback) error

func (*Client) UploadFile 

func (c *Client) UploadFile(ctx context.Context, localPath, remotePath string, size int64, mode os.FileMode, progress ProgressCallback) (retErr error)
func (c *Client) UploadLink(ctx context.Context, localPath, remotePath string, progress ProgressCallback) error

func (*Client) WithFileProgress added in v0.15.0 

func (c *Client) WithFileProgress(callback FileProgressCallback) *Client

WithFileProgress returns a new Client instance sharing the same underlying connection but with the specified per-file progress callback. This is safe for concurrent use.

func (*Client) WithForce 

func (c *Client) WithForce(force bool) *Client

WithForce returns a new Client instance sharing the same underlying connection but with the specified Force configuration. This is safe for concurrent use.

type FileProgressCallback added in v0.15.0 

type FileProgressCallback func(p FileTransferProgress)

FileProgressCallback is invoked as chunks of an individual file are transferred. This callback must be thread-safe as multiple files may be transferred concurrently.

type FileTransferProgress added in v0.15.0 

type FileTransferProgress struct {
	Path        string // File path or relative path
	Size        int64  // Total file size in bytes
	Transferred int64  // Bytes transferred so far for this file
	Increment   int64  // Bytes transferred in this step
}

FileTransferProgress contains progress details for an individual file within a transfer.

type Option 

type Option func(*Client)

func WithChunkSize 

func WithChunkSize(size int) Option

func WithConcurrentFiles 

func WithConcurrentFiles(con int) Option

func WithDiagnostics added in v0.15.0 

func WithDiagnostics(observer corelog.DiagnosticObserver) Option

WithDiagnostics installs a caller-owned observer for subsystem setup.

func WithForce 

func WithForce(force bool) Option

func WithResume 

func WithResume(enable bool) Option

func WithResumeMinSize 

func WithResumeMinSize(size int64) Option

func WithSudo added in v0.16.0 

func WithSudo(sudo bool) Option

WithSudo enables privileged SFTP execution using an elevated sftp-server binary.

func WithThreadsPerFile 

func WithThreadsPerFile(t int) Option

type ProgressCallback 

type ProgressCallback func(n int64)

ProgressCallback 进度回调，n 为本次增量传输的字节数 此函数必须是并发安全的

type TransferConfig 

type TransferConfig struct {
	ConcurrentFiles int   // 同时传输的文件数
	ThreadsPerFile  int   // 单个文件的并发分块数
	ChunkSize       int64 // 分块大小
	EnableResume    bool
	ResumeMinSize   int64
	TempSuffix      string
	Force           bool
	Sudo            bool
}

TransferConfig 定义传输配置

func DefaultConfig 

func DefaultConfig() TransferConfig

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.
⌂ 换网址