transfer

package
v0.9.7 Latest Latest
Warning

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

Go to latest
Published: Nov 6, 2026 License: MIT Imports: 19 Imported by: 0

Documentation

Overview

Package transfer runs file transfers between the BBS and a caller by driving external protocol programs (lrzsz, sexyz and the like) over the caller's SSH or telnet session. ProtocolConfig describes a sysop-defined protocol loaded by LoadProtocols; ExecuteSend and ExecuteReceive run it, while RunCommandDirect and RunCommandWithPTY handle the binary-safe piping between the session and the child process.

Index

Constants

View Source
const (
	ConnTypeAny    = ""       // Available on all connection types
	ConnTypeSSH    = "ssh"    // SSH sessions only
	ConnTypeTelnet = "telnet" // Telnet sessions only
)

Connection type constants for ProtocolConfig.ConnectionType.

Variables

View Source
var ErrBinaryNotFound = errors.New("transfer binary not found")

ErrBinaryNotFound is returned by ExecuteSend/ExecuteReceive when the external transfer binary (e.g. sexyz) cannot be found on disk. Callers should check errors.Is(err, ErrBinaryNotFound) and display a sysop-friendly message to the user instead of a generic "transfer failed" notice.

Functions

func ExecuteZmodemReceive

func ExecuteZmodemReceive(ctx context.Context, s ssh.Session, targetDir string) error

ExecuteZmodemReceive initiates a Zmodem receive (rz) into a specified directory using a PTY. It requires the 'rz' command to be available on the system path. targetDir should be the absolute path to the directory where received files will be stored. ctx controls cancellation and timeout; pass nil for no timeout.

func ExecuteZmodemSend

func ExecuteZmodemSend(ctx context.Context, s ssh.Session, filePaths ...string) error

ExecuteZmodemSend initiates a Zmodem send (sz) of one or more files using a PTY. It requires the 'sz' command to be available on the system path. filePaths should be absolute paths to the files being sent. ctx controls cancellation and timeout; pass nil for no timeout.

func RunCommandDirect

func RunCommandDirect(ctx context.Context, s ssh.Session, cmd *exec.Cmd, stdinIdleTimeout time.Duration) error

RunCommandDirect executes an external command with its stdin/stdout/stderr piped directly to the SSH session — no PTY allocated. This is essential for binary file-transfer protocols (ZMODEM, YMODEM, XMODEM) where a PTY's line discipline would corrupt the data stream.

ctx controls cancellation and timeout: when ctx.Done() fires, the process is killed and the function returns ctx.Err(). Pass context.Background() for no timeout. Callers should use context.WithTimeout for transfer timeouts.

stdinIdleTimeout, when > 0, kills the process if no bytes arrive from the client for that duration. Use this for receive (upload) mode: if the client never responds to the initial handshake (e.g. user cancels the SyncTerm upload dialog without sending a ZModem abort), the process would otherwise retry indefinitely. Pass 0 to disable.

func RunCommandWithPTY

func RunCommandWithPTY(ctx context.Context, s ssh.Session, cmd *exec.Cmd, stdinIdleTimeout time.Duration) error

RunCommandWithPTY executes an external command attached to the user's SSH session using a PTY. It handles setting raw mode, resizing, and copying I/O.

ctx controls cancellation and timeout: when ctx.Done() fires, the process is killed and the function returns ctx.Err(). Pass context.Background() for no timeout.

Types

type ProtocolConfig

type ProtocolConfig struct {
	Key            string   `json:"key"`             // Selection key shown to users (e.g. "Z", "ZST")
	Name           string   `json:"name"`            // Display name shown to users
	Description    string   `json:"description"`     // Short description for help text
	SendCmd        string   `json:"send_cmd"`        // Executable for sending (download to user)
	SendArgs       []string `json:"send_args"`       // Arguments for send command
	RecvCmd        string   `json:"recv_cmd"`        // Executable for receiving (upload from user)
	RecvArgs       []string `json:"recv_args"`       // Arguments for receive command
	BatchSend      bool     `json:"batch_send"`      // True if the protocol supports multi-file batch sends
	UsePTY         bool     `json:"use_pty"`         // True if the command requires a PTY
	Default        bool     `json:"default"`         // True if this is the default protocol when none is selected
	ConnectionType string   `json:"connection_type"` // "" = any, "ssh" = SSH only, "telnet" = telnet only
}

ProtocolConfig defines a user-visible file transfer protocol. The send/receive commands are external programs (e.g., lrzsz, sexyz).

Argument placeholders:

{filePath}     — expanded to one or more file paths (send only)
{fileListPath} — replaced by a temp file path containing one filename per
                 line; commonly prefixed with "@" for sexyz (e.g. "@{fileListPath}")
{targetDir}    — expanded to the upload target directory (recv only)

If {filePath} is absent from send_args, file paths are appended at the end.

func DefaultProtocol

func DefaultProtocol(protocols []ProtocolConfig) (ProtocolConfig, bool)

DefaultProtocol returns the first protocol marked as default, or the first protocol in the slice if none is marked default. Returns false if the slice is empty.

func FindProtocol

func FindProtocol(ps []ProtocolConfig, key string) (ProtocolConfig, bool)

FindProtocol returns the protocol whose Key matches key, ignoring case, and true. When nothing matches it returns DefaultProtocol(ps) and false, so the caller gets a usable fallback (the zero ProtocolConfig if ps is empty) and can tell that the requested key was not found.

func LoadProtocols

func LoadProtocols(path string) ([]ProtocolConfig, error)

LoadProtocols reads a JSON array of ProtocolConfig definitions from path.

func (*ProtocolConfig) ExecuteReceive

func (p *ProtocolConfig) ExecuteReceive(ctx context.Context, s ssh.Session, targetDir string) error

ExecuteReceive runs this protocol's receive command to accept files from the user. targetDir must be an absolute path to the directory where received files will be stored. ctx controls cancellation and timeout; when ctx.Done() fires, the transfer is aborted.

func (*ProtocolConfig) ExecuteSend

func (p *ProtocolConfig) ExecuteSend(ctx context.Context, s ssh.Session, filePaths ...string) error

ExecuteSend runs this protocol's send command to transfer files to the user. filePaths must be absolute paths to the files being sent. ctx controls cancellation and timeout; when ctx.Done() fires, the transfer is aborted. Pass a context with timeout (e.g. context.WithTimeout) for transfer time limits.

Jump to

Keyboard shortcuts

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