Documentation
¶
Overview ¶
Package xfer implements file transfer: the SFTP engine, md5 verification, relay between two assets, and the stdio bridge rsync uses via `rsync -e`.
SFTP rides on its own connection token. The token must be created with protocol="sftp" and connect_method="web_sftp": an ssh/web_cli token's SFTP subsystem lands on the KoKo virtual root and every path fails with "please select one of the assets" (DESIGN.md「KoKo 协议」的「认证」).
Index ¶
Constants ¶
const ( // DefaultChunk is the transfer chunk size. DefaultChunk = 1 << 20 // DefaultParallel is the number of concurrent chunk streams. DefaultParallel = 4 )
Defaults.
Variables ¶
var ErrVerifyFailed = errors.New("md5 verification failed")
ErrVerifyFailed reports an md5 mismatch.
Functions ¶
func RunBridge ¶
RunBridge parses the ssh-style arguments, opens the asset, and bridges stdio until the remote command exits. It returns the remote exit code.
Two argument shapes are accepted, matching what rsync produces:
classic rsync: jms ssh-pipe -l <asset> <server> <remote command...> openrsync: jms ssh-pipe <asset>@<server> <remote command...>
Nothing but the caller's protocol bytes may reach Stdout: stdout is rsync's data channel, so a single diagnostic line there corrupts the transfer. Every diagnostic goes to Stderr.
Types ¶
type Bridge ¶
type Bridge struct {
Stdin io.Reader
Stdout io.Writer
Stderr io.Writer
// contains filtered or unexported fields
}
Bridge is the stdio relay behind `rsync -e`: it speaks the SSH protocol on stdin/stdout and forwards the remote command to the asset.
type Engine ¶
type Engine struct {
Session *auth.Session
Asset assets.Info
// Cols and Rows size any PTY the remote side needs.
Cols, Rows int
// AssetName and Account let a caller that has not resolved the asset
// yet run a transfer anyway: Run resolves it on demand. They are
// consulted only when Asset.ID is empty, so a caller holding a
// resolved asset (the usual case) can leave them unset.
AssetName string
Account string
// Protocol is the asset protocol to resolve with; empty means "ssh",
// because SFTP rides on the asset's ssh protocol even though its
// connection token uses protocol="sftp".
Protocol string
// contains filtered or unexported fields
}
Engine performs transfers against one asset.
type RemoteHasher ¶
type RemoteHasher struct {
Engine *Engine
}
RemoteHasher computes an md5 on the remote side through the terminal.
The SFTP subsystem has no hashing primitive, so the digest is produced by running md5sum over an SSH exec channel, exactly as the Python implementation did. The terminal is opened per call and closed again: a transfer verifies once, and holding a second connection open across a multi-hour copy would only add an idle link for a middlebox to drop.
type Result ¶
type Result struct {
Bytes int64
Duration time.Duration
// MD5Local and MD5Remote are set when Verify was requested. For a
// relay both sides are remote: MD5Local is the source digest and
// MD5Remote the destination digest.
MD5Local string
MD5Remote string
Verified bool
}
Result is the outcome of one Task.
func Relay ¶
func Relay(ctx context.Context, src, dst *Engine, remoteSrc, remoteDst string, t Task) (Result, error)
Relay copies between two assets, streaming through this process.
remoteSrc and remoteDst are paths inside src.Asset and dst.Asset respectively; neither side is local. t.Chunk, t.Parallel and t.Verify apply; t.Direction and t.Local are ignored.
type Task ¶
type Task struct {
Direction Direction
// Local is the local path; for a relay both sides are remote.
Local string
// Remote is the path inside the asset.
Remote string
// Verify asks for an md5 comparison after the transfer.
Verify bool
// Chunk and Parallel override the defaults when non-zero.
Chunk int
Parallel int
}
Task is one file transfer.