How trzsz/trzsz-go works
Project Type and Purpose
• trzsz-go is a command-line file-transfer tool and library written in Go. It implements the trz/tsz protocol (similar to rz/sz) for uploading/downloading files over local shells or SSH sessions, with additional features like drag-and-drop, clipboard integration, and tmux relay.
• It is not a web or service-based system; it is an open-source CLI utility plus a reusable Go library for embedding trz/tsz support in custom SSH clients.
File-Structure Analysis
• Top-level “cmd” directory: three executables (trz, tsz, trzsz) with their own main.go entrypoints.
• “trzsz” directory: core library modules, each file implementing one aspect of the protocol or I/O (comm.go, buffer.go, pipeline.go, zmodem.go, transfer.go, filter.go, progress.go, escape.go, relay.go, archive.go, utils_*.go, pty_*.go, version.go).
• Packaging & CI: “.github/workflows”, goreleaser.yaml, Makefile, “debian/…”, “inno_setup/…”.
• Examples: “examples/ssh_client.go” shows how to embed the library in a custom SSH client.
README Insights
• Describes usage patterns: local shell wrapping, SSH wrapping, tmux relay, zmodem fallback, dragfile, osc52 clipboard.
Main Components & Their Relationships
a. User & Terminal
• The end user invokes one of the CLI binaries (trz, tsz, trzsz) in a terminal (local shell or SSH session).
b. CLI Entrypoints (cmd/)
• These binaries parse flags (--dragfile, --relay, --zmodem, --osc52).
• They initialize the Core Transfer Engine and hand off to the shell or SSH.
c. Core Transfer Library (trzsz/)
• comm: abstracted stdin/stdout reads and writes over a pty.
• pty_unix/windows: create and manage pseudo-terminals on each OS.
• buffer & pipeline: stage and multiplex data streams (stdin, stdout, stderr).
• filter & escape: detect and emit control sequences to enter transfer mode.
• zmodem: packet construction, parsing, CRC, protocol state machine.
• transfer: high-level upload/download orchestration, progress callbacks.
• archive: optional tar/gzip bundling for directories.
• relay: tmux-aware SSH jump-server relay logic.
• utils_*: OS-specific support (clipboard, file dialogs).
d. Shell or SSH Process
• The CLI spawns a local shell or an SSH client process, connecting its pty to comm.
• Data flows bidirectionally: user ↔ CLI Engine ↔ remote shell.
e. External Services/Dependencies
• Optionally invokes lrzsz for zmodem fallback on the client.
• On Windows: may require winpty or inno setup for installers.
f. Packaging & CI
• GitHub Actions and goreleaser produce multi-OS binaries.
• Debian and Inno Setup scripts package .deb and .exe installers.
• Makefile orchestrates build, test, and install.
Architectural Patterns and Principles
• Layered design: CLI layer → Core library layer → OS abstraction layer → External process layer.
• Modular packages: each concern (I/O, protocol, UI, OS) lives in its own Go file.
• Dependency injection: the CLI passes configured options into the library’s entrypoints.
• Cross-platform abstraction: build tags (_unix, _windows, _darwin) hide OS details.
Summary Checklist
• A side-panel for packaging/CI workflows.