Skip to content

README.md

Latest commit

 

History

History
118 lines (84 loc) · 4.5 KB

README.md

File metadata and controls

118 lines (84 loc) · 4.5 KB
Raw
FetchForge logo

⚒️ FetchForge

A modern, self-hosted web download manager. Segmented concurrent downloads · Resumable transfers · Live progress via SSE · Zero runtime dependencies.

Node.js · Zero-Dependency · MIT License

English · 简体中文 · 繁體中文

FetchForge is a modern download engine that runs entirely on your own machine. It splits large files into parallel segments for maximum throughput, supports resuming interrupted transfers, streams live progress to the browser over Server-Sent Events, and ships with a polished web dashboard plus a full CLI. Everything is built on Node.js built-ins only — no npm install required.

✨ Features

Feature Description
🚀 Segmented concurrent downloads Large files are split into 4 parallel segments by default for dramatically faster transfer
🔁 Resumable transfers Interrupted downloads resume from the exact byte offset — no re-downloading
📡 Live progress via SSE Real-time progress, speed, and state updates streamed to the browser
🌐 Auto proxy support Honors HTTP_PROXY / HTTPS_PROXY / NO_PROXY via Node's native fetch (undici)
🖥️ Beautiful web dashboard Poster-style hero, live stats, search, and state filters
⌨️ Full CLI add, list, start, pause, resume, cancel, server
💾 Persistent task queue Download history survives restarts; active tasks auto-resume
🧱 Zero runtime dependencies Node.js built-ins only — http, fs, events, fetch

🚀 Quick Start

Requirements

  • Node.js ≥ 18 (native fetch required)

1. Clone & run (zero install)

git clone https://github.com/gitstq/FetchForge.git
cd FetchForge

# Web dashboard → http://localhost:3000
npm start

# Or via CLI
node src/cli.js server

2. Web dashboard

Open http://localhost:3000, paste a file URL, and click Start. Watch segments merge into one file in your downloads/ folder.

3. CLI usage

node src/cli.js add https://example.com/big-file.zip   # add & start
node src/cli.js list                                   # show the queue
node src/cli.js pause <id>                             # pause
node src/cli.js resume <id>                            # resume from offset
node src/cli.js cancel <id>                            # cancel & clean parts
node src/cli.js server                                 # start web server

⚙️ Configuration

Configuration is handled entirely via environment variables.

Variable Default Description
PORT 3000 Web server port
FF_DOWNLOADS_DIR ./downloads Where finished files are saved
FF_DATA_DIR ./data Where the task queue is persisted
HTTP_PROXY / HTTPS_PROXY / NO_PROXY — Auto-detected for network egress

🧱 How it works

  1. Prepare — issues a HEAD request to learn file size and whether the server supports Range requests.
  2. Segment — if the file is large enough (> 1 MB) and Accept-Ranges: bytes is present, the file is split into N parallel segments.
  3. Download — each segment streams to its own .part file via native fetch.
  4. Resume — existing .part file sizes are read on restart, and each segment continues from that byte offset.
  5. Merge — completed parts are concatenated into the final file and temp parts are cleaned up.
  6. Notify — progress events stream to the dashboard over SSE and are persisted to the queue.

📁 Project layout

FetchForge/
├── src/
│   ├── server.js       # HTTP server · REST API · SSE · static files
│   ├── downloader.js   # Core engine: DownloadTask / DownloadManager
│   ├── store.js        # Task queue persistence
│   └── cli.js          # Command-line interface
├── public/
│   ├── index.html      # Web dashboard
│   ├── styles.css      # Styles
│   └── app.js          # Frontend logic
├── assets/logo.svg     # Project icon
├── tests/test.js       # Unit tests (zero-dependency)
└── package.json

✅ Testing

npm run check   # syntax check all sources
npm test        # run unit tests (5 cases)

🤝 Contributing

Contributions are welcome! Please read CONTRIBUTING.md first.

📜 License

MIT © gitstq