Go API Reference (`trzsz-go/trzsz`)

The trzsz-go project is deliberately architected to be modular. While it ships with CLI wrappers, the core file transfer logic is encapsulated in a public Go package: github.com/trzsz/trzsz-go/trzsz.

This API empowers Go developers to embed native trzsz file transfer capabilities directly into their own custom SSH clients, Telnet wrappers, or bespoke terminal emulators.

Structs and Types

`TrzszOptions`

The configuration structure used to initialize the TrzszFilter. This dictates which peripheral features are enabled during the stream processing.

type TrzszOptions struct {
    // TerminalColumns tracks the width of the terminal. 
    // This is required to accurately render the text-based progress bar.
    TerminalColumns int32

    // DetectDragFile enables parsing of terminal input to detect dropped file paths.
    DetectDragFile bool

    // DetectTraceLog allows the server to request debugging logs to be written locally.
    DetectTraceLog bool

    // EnableZmodem enables intercepting legacy rz/sz signatures.
    EnableZmodem bool

    // EnableOSC52 parses OSC52 escape sequences and writes them to the local clipboard.
    EnableOSC52 bool
}

The `TrzszFilter` Interface

The TrzszFilter is the heart of the library. It acts as a transparent proxy between the user's terminal UI and the remote server's data stream. It uses concurrent goroutines to sniff for trigger sequences without blocking normal interactive I/O.

Instantiation

func NewTrzszFilter(clientIn io.Reader, clientOut io.WriteCloser,
    serverIn io.WriteCloser, serverOut io.Reader, options TrzszOptions) *TrzszFilter

clientIn: The source of local keystrokes (e.g., os.Stdin).
clientOut: The destination for terminal output (e.g., os.Stdout).
serverIn: The pipe sending data to the remote server (e.g., sshSession.StdinPipe()).
serverOut: The pipe receiving data from the remote server (e.g., sshSession.StdoutPipe()).

Operational Methods

func (filter *TrzszFilter) SetTerminalColumns(columns int32) Updates the internal width state. You should call this whenever you catch a SIGWINCH (Window Change) signal to ensure the progress bar scales correctly.
func (filter *TrzszFilter) IsTransferringFiles() bool Returns true if the filter is currently locked in a file transfer phase, meaning standard shell input is currently suspended.
func (filter *TrzszFilter) StopTransferringFiles(stopAndDelete bool) Programmatically aborts an ongoing transfer. If stopAndDelete is true, the filter attempts to delete any partial, corrupted files created during the aborted run.
func (filter *TrzszFilter) UploadFiles(filePaths []string) error Bypasses the trz trigger entirely and programmatically initiates an upload of the specified local paths to the remote server. Returns an error if the files cannot be read or if a transfer is already active.
func (filter *TrzszFilter) ResetTerminal() Recovers the terminal state. If a transfer crashes, the terminal cursor may be left hidden (\x1b[?25l). This method forces the cursor to show.

Configuration Overrides

By default, NewTrzszFilter attempts to read ~/.trzsz.conf. You can programmatically override these values for your application:

func (filter *TrzszFilter) SetDefaultUploadPath(path string)
func (filter *TrzszFilter) SetDefaultDownloadPath(path string)
func (filter *TrzszFilter) SetDragFileUploadCommand(command string)
func (filter *TrzszFilter) SetProgressColorPair(colorPair string)

Advanced Hooks & Callbacks

func (filter *TrzszFilter) SetTunnelConnector(connector func(int) net.Conn) Provides a way to bypass the standard PTY stream entirely. When the server requests a high-speed transfer on a specific port, this callback provides a direct TCP connection. (See the Integration Guide for details).
func (filter *TrzszFilter) SetRedrawScreenFunc(redrawScreenFunc func()) A callback executed immediately after a transfer finishes. Useful if your custom terminal emulator needs to clear dirty artifacting.
func (filter *TrzszFilter) SetTransferStateCallback(transferStateCallback func(transferring bool)) Registers an event listener. Fires with true when a transfer initiates, and false when it completes or errors out.
func (filter *TrzszFilter) Close() Signals the internal channels to close and shuts down the background scanning goroutines. Always defer this to prevent goroutine leaks.

Environment Helpers

func SetAffectedByWindows(affected bool) A global protocol toggle. Set to true if you are executing on a Windows machine. It forces the protocol to handle carriage returns (\r\n) and escape sequences specific to the Windows Console API.

Go API Reference (trzsz-go/trzsz)