Skip to content

Commit c417b1f

Browse files
feat: add new commands to get (#46)
* feat: improve the get command to be able to do things like - surge get <id> info - surge get <id> pause - surge get <id> resume - surge get <id> delete * fix: ensure startDownload doesnt duplicate id and uses the one given by get * docs: update readme * test: added integration tests for the new get commands
1 parent 75739bf commit c417b1f

7 files changed

Lines changed: 478 additions & 156 deletions

File tree

‎README.md‎

Lines changed: 46 additions & 25 deletions
Original file line numberDiff line numberDiff line change
@@ -18,7 +18,6 @@ Designed for power users who prefer a keyboard-driven workflow and want full con
1818

1919
[![Get it on GitHub](https://img.shields.io/badge/Get%20it%20on-GitHub-blue?style=for-the-badge&logo=github)](https://github.com/surge-downloader/surge/releases/latest)
2020

21-
2221
### Homebrew (macOS/Linux)
2322

2423
```bash
@@ -43,24 +42,30 @@ go build -o surge .
4342
```
4443

4544
---
45+
4646
<details><summary>
4747
<h2> Architecture & Modes </h2>
4848
</summary>
4949

5050
Surge employs a **Strict Single Instance Architecture** to ensure data integrity and efficient resource usage.
5151

5252
### 1. The Engine (Host)
53+
5354
Only **one** instance of Surge runs at a time (the "Host"). This instance holds the lock file (`~/.surge/surge.lock`) and manages all downloads.
55+
5456
- **TUI Mode**: Starts the interactive dashboard.
5557
- **Headless Mode**: Starts as a background daemon (`surge --headless`).
5658

5759
### 2. The Client (CLI)
60+
5861
If you run `surge` or `surge get` while another instance is running, it automatically acts as a **Client**.
62+
5963
- It detects the running Host.
6064
- Offloads the download request to the Host via HTTP.
6165
- Exits immediately (fire-and-forget) or waits if acting as a temporary host.
6266

6367
This means you can open multiple terminals and queue downloads freely; they will all be managed by the single active engine.
68+
6469
</details>
6570

6671
---
@@ -113,18 +118,36 @@ surge get --batch urls.txt
113118

114119
```
115120

121+
### Managing Downloads (CLI)
122+
123+
You can check status, pause, resume, or delete a specific download using its ID.
124+
125+
```bash
126+
# Get status info
127+
surge get <ID> info
128+
129+
# Pause a download
130+
surge get <ID> pause
131+
132+
# Resume a paused download
133+
surge get <ID> resume
134+
135+
# Delete a download
136+
surge get <ID> delete
137+
```
138+
116139
---
117140

118141
## Features
119142

120-
* **High-speed Downloads** with multi-connection support
121-
* **Beautiful TUI** built with Bubble Tea & Lipgloss
122-
* **Pause/Resume** downloads seamlessly
123-
* **Real-time Progress** with speed graphs and ETA
124-
* **Auto-retry** on connection failures
125-
* **Batch Downloads**
126-
* **Browser Extension** integration
127-
* **Clipboard Integration**
143+
- **High-speed Downloads** with multi-connection support
144+
- **Beautiful TUI** built with Bubble Tea & Lipgloss
145+
- **Pause/Resume** downloads seamlessly
146+
- **Real-time Progress** with speed graphs and ETA
147+
- **Auto-retry** on connection failures
148+
- **Batch Downloads**
149+
- **Browser Extension** integration
150+
- **Clipboard Integration**
128151

129152
---
130153

@@ -140,35 +163,33 @@ Not all connections are created equal; there are fast connections and slow conne
140163
The top 3 optimizations we did in Surge are:
141164

142165
1. **Split the Largest Chunk:** Split the largest chunk whenever possible so that workers do not remain idle.
143-
144166
2. **Work Stealing:** Near the end, when fast workers are finished and slow workers are still processing, make the fast, idle workers "steal work" from the slow workers.
145-
146167
3. **Restart Slow Workers:** Calculate the mean speed of all workers. If a worker is performing at less than **0.3x** of the mean, restart it in the hopes that it will secure a better pathway to the server, which will be faster.
147168
</details>
148169

149170
---
150171

151172
## Benchmarks
152173

153-
| Tool | Time | Speed | vs Surge |
154-
| --- | --- | --- | --- |
155-
| **Surge** | 28.93s | **35.40 MB/s** | — |
156-
| aria2c | 40.04s | 25.57 MB/s | 1.38× slower |
157-
| curl | 57.57s | 17.79 MB/s | 1.99× slower |
158-
| wget | 61.81s | 16.57 MB/s | 2.14× slower |
174+
| Tool | Time | Speed | vs Surge |
175+
| --------- | ------ | -------------- | ------------ |
176+
| **Surge** | 28.93s | **35.40 MB/s** | — |
177+
| aria2c | 40.04s | 25.57 MB/s | 1.38× slower |
178+
| curl | 57.57s | 17.79 MB/s | 1.99× slower |
179+
| wget | 61.81s | 16.57 MB/s | 2.14× slower |
159180

160181
<details>
161182
<summary>Test Environment</summary>
162183

163-
*Results averaged over 5 runs*
184+
_Results averaged over 5 runs_
164185

165-
| | |
166-
| --- | --- |
167-
| **File** | 1GB.bin ([link](https://sin-speed.hetzner.com/1GB.bin)) |
168-
| **OS** | Windows 11 Pro |
169-
| **CPU** | AMD Ryzen 5 5600X |
170-
| **RAM** | 16 GB DDR4 |
171-
| **Network** | 360 Mbps / 45 MB/s |
186+
| | |
187+
| ----------- | ------------------------------------------------------- |
188+
| **File** | 1GB.bin ([link](https://sin-speed.hetzner.com/1GB.bin)) |
189+
| **OS** | Windows 11 Pro |
190+
| **CPU** | AMD Ryzen 5 5600X |
191+
| **RAM** | 16 GB DDR4 |
192+
| **Network** | 360 Mbps / 45 MB/s |
172193

173194
Run your own: `python benchmark.py -n 5`
174195

0 commit comments

Comments
 (0)