Surge Overview

Relevant source files

• README.md
• cmd/cmd_test.go
• docs/SETTINGS.md
• docs/USAGE.md
• go.mod
• go.sum
• internal/tui/settings_reset_test.go
• internal/tui/view_test.go
• internal/utils/filename.go
• internal/utils/filename_test.go
• internal/version/version.go
• main.go

Surge is a high-performance, keyboard-driven download manager written in Go. It is designed for power users, offering a sophisticated Terminal User Interface (TUI), a headless server mode for remote environments, and a robust concurrent download engine that maximizes bandwidth utilization through multi-connection chunking and multi-mirror support.

System Capabilities

Surge distinguishes itself from standard browser downloaders by implementing several advanced optimization strategies:

• Concurrent Chunking: Files are split into segments and downloaded in parallel using up to 32 connections by default README.md28-30 docs/SETTINGS.md144
• Multi-Mirror Distribution: Surge can pull from multiple source URLs simultaneously, automatically handling worker distribution and failover across mirrors README.md33
• Optimization Strategies: Implements HealthChecks to restart slow workers, Work Stealing to reassign tasks from slow to fast workers, and Hedged Requests to mitigate tail latency README.md38
• Streaming Mode: Supports sequential downloading for media files, allowing users to preview content before the full download completes README.md34 docs/SETTINGS.md149
• Daemon Architecture: A single background engine manages all tasks. Multiple UI instances (TUI or CLI) can connect to this centralized daemon via a token-protected API README.md35 README.md140-144
• Intelligent Filename Determination: Uses heuristics including Content-Disposition headers, query parameters, URL paths, and ZIP header sniffing to resolve the correct filename internal/utils/filename.go23-123

High-Level Architecture

The system is divided into a backend engine (the "Server") and various frontend interfaces. Communication between these layers occurs via an HTTP API and Server-Sent Events (SSE).

System Component Map

Sources: README.md20-38 go.mod5-20 cmd/cmd_test.go24-28 internal/tui/view_test.go133 main.go10-15

---

Primary Execution Modes

Surge can be operated in several modes depending on the environment and use case. For a detailed guide on setup and flags, see Getting Started.

Mode	Command	Description
Interactive TUI	surge	Launches the full dashboard for managing and visualizing downloads README.md86
Headless Server	surge server	Runs the engine as a background daemon with an enabled HTTP API README.md106
Remote TUI	surge connect	Connects a local TUI instance to a remote Surge daemon README.md154
CLI Automation	surge add <url>	Direct command-line interaction for scripting and batching docs/USAGE.md12
System Service	surge service install	Manages Surge as a background system daemon README.md121

---

Subsystem Integration

The following diagram illustrates how the major code entities interact during a typical download lifecycle, bridging the gap between UI commands and the SQLite persistence layer.

Engine Entity Interaction

Sources: README.md35 go.mod5-20 cmd/cmd_test.go24-28 docs/SETTINGS.md97

---

Project Infrastructure

Surge utilizes a modern CI/CD pipeline to ensure cross-platform compatibility and automated asset delivery.

• Build System: Uses GoReleaser to compile binaries for Linux, Windows, and Darwin with specific ldflags for versioning README.md49
• Update Mechanism: Includes a version check subsystem in internal/version that queries the GitHub Releases API to notify users of updates internal/version/version.go14-39 docs/SETTINGS.md118
• Persistence: Uses SQLite to maintain download history and state across restarts docs/SETTINGS.md97
• Single Instance Enforcement: Uses github.com/gofrs/flock to ensure only one instance of the engine runs at a time go.mod13
• Process Management: Manages its own PID and port files in runtime directories (e.g., XDG_RUNTIME_DIR or %TEMP%) to allow CLI tools to discover and control the running daemon cmd/cmd_test.go105-137 cmd/cmd_test.go205-232 docs/SETTINGS.md100
• CORS Support: The embedded server includes corsMiddleware to allow browser extension integration cmd/cmd_test.go143-157

For technical details on the build process and contribution guidelines, see Build System and CI/CD.

---

Child Pages

• Getting Started: Installation methods (Homebrew, AUR, Scoop, Docker), font requirements (JetBrains Mono Nerd Font), environment variables (SURGE_TOKEN, SURGE_HOST), and basic usage examples.
• Build System and CI/CD: Deep dive into the compilation process, GoReleaser configuration, GitHub Actions workflows, and automated release packaging.