Falcon

The Universal Resource Transfer Engine

A cross-platform C++ engine for downloading and accessing resources across HTTP, FTP, SFTP, WebDAV, object storage, and P2P networks — packaged as a CLI, a daemon, and a desktop app. The transfer stack is built on open-source components: libcurl, OpenSSL, libtorrent, and libssh2 carry the protocol data planes; the event-driven V2 engine and the aria2-compatible CLI/RPC surface follow aria2's architecture.

中文 | English

Screenshots and design prototypes are showcased on the docs site; the full gallery (52 shots) lives in docs/design/ui-sandbox/.

Features

• Dual Download Engines

  • V1 engine (default): libcurl-based, multi-threaded segmented downloading, resume, per-task speed limits
  • V2 engine (experimental, --http-engine v2): aria2-style event-driven rewrite — non-blocking I/O over epoll/kqueue/poll/WSAPoll, command pattern with connection reuse, persistent resume via .falcon.ctrl control files (If-Range protected), multi-source segmented downloading (P2SP) across mirrors, global & per-task speed limits, connection-level retries, task timeouts, chunked transfer encoding, overwrite protection, and atomic temporary-file publishing

• Multi-Protocol Support organized in tiers around a single transfer core:

  Tier	Protocols	Role
  1 · Core transfer (default on)	HTTP/HTTPS, FTP/FTPS, SFTP, WebDAV	File transfer: resume, segmented downloading, speed limits, proxies
  2 · P2P & multi-source (default on)	BitTorrent/Magnet, Metalink	Piece-level P2P (libtorrent), mirror lists with multi-source segmented transfers (P2SP)
  3 · Compatibility plugins (opt-in)	Thunder, QQDL, FlashGet, ED2K, HLS/DASH	Legacy/private link formats and streaming manifests
  Resource access (default on)	S3, OSS, COS, Kodo, Upyun	Object storage with SigV4, remote browsing, resource search

• Metalink: RFC 5854 .meta4 / Metalink3 .metalink mirror lists, multi-mirror P2SP segmented download through the V2 engine, whole-file hash verification before publish

• Daemon & RPC Service (falcon-daemon): aria2-compatible JSON-RPC over HTTP + WebSocket on a single port (works with AriaNg), live event stream (download start / pause / complete / error / progress), SQLite task persistence with restart recovery, daemon.json config with SIGHUP hot reload, MCP tool endpoint (/mcp) for AI hosts

• P2SP network (falcon-swarmd): standalone rendezvous service for peer discovery (Ed25519 challenge auth, Bearer + rate limiting, group tokens, blacklist), daemon p2sp.share announces swarm-enabled downloads to the rendezvous with TTL renewal and retract on completion, inbound read-only data service (GET /by-sha256/<hex> with Range) for peers to pull verified files, metalink mirror pools augmented with swarm sources (NAT-filtered, hash-verified, works even with sharing off), RPC falcon.swarm.status/falcon.swarm.setShare, CLI --swarm-server single-shot announce; default off

• Desktop Application (Qt6): Fluent-design UI, light/dark themes, frameless window, table & grid task views, cloud storage browsing, resource search, dual backend (in-process engine or daemon RPC with WebSocket event refresh)

• CLI (falcon-cli): 60+ aria2-compatible parameters, batch input files, JSON config

• Performance characteristics:

  • Multi-connection segmented downloading with adaptive sizing
  • Non-blocking I/O with event-driven architecture
  • Connection pooling for reduced latency
  • Speed control and bandwidth throttling (global & per-task)

• Advanced Features:

  • File hash verification (MD5/SHA1/SHA256/SHA512)
  • Resume support for interrupted downloads
  • Multi-mirror failover
  • HTTP proxy (plain and CONNECT tunneling) & SOCKS5

• Cloud Storage Integration:

  • Amazon S3, Alibaba Cloud OSS, Tencent COS, Qiniu Kodo, Upyun
  • Custom endpoints for MinIO / RustFS / private-gateway deployments (AWS SigV4 signing)

• Remote Resource Browsing: Browse FTP/SFTP/S3/OSS/COS/Kodo/Upyun directories

• Resource Search: Built-in search provider framework for torrent and file resources

• Secure Configuration: AES-256-GCM encrypted credential storage with master password protection

Quick Start

One-Line Install (Nightly)

Installs the desktop app from the daily build (anonymous download, idempotent — rerun to upgrade):

## 本地测试口径

CI 与本地开发按改动面三路分流——改一行文档不该全量编译。

1. **文档改动**（`*.md`、`docs/**`、图片）：不编译。主 CI workflow 的
   `paths-ignore` 已跳过这些路径。
2. **代码改动**：只跑改动子集，不全量。
   - `ctest -R '<改动测试>' -C Debug`
3. **全量**（`ctest --build-config Debug --output-on-failure`）：仅以下情形触发——CMakeLists.txt、
   `.github/**`、Docker/Compose 配置、发布前。

# Linux / macOS
curl -fsSL https://raw.githubusercontent.com/cuihairu/falcon/main/scripts/install.sh | bash

# Windows (PowerShell 5.1+)
irm https://raw.githubusercontent.com/cuihairu/falcon/main/scripts/install.ps1 | iex

Platform	Artifact	Notes
Linux x86_64	falcon-desktop-linux-nightly.AppImage	Installed to ~/.local/bin/falcon-desktop
Linux aarch64	falcon-desktop-linux-arm64-nightly.AppImage	Available after the first arm64 nightly build
macOS Apple Silicon	falcon-desktop-macos-arm64-nightly.dmg	Installed to /Applications; right-click → Open on first launch (ad-hoc signed, not notarized)
Windows x64	falcon-desktop-setup-nightly.exe	Inno Setup installer, run silently to Program Files; user PATH (registry) + Start menu shortcut; legacy %LOCALAPPDATA%\Falcon zip layouts are cleaned up automatically
macOS Intel	—	Not built yet; use the source build below

Build from Source

# Clone repository
git clone https://github.com/cuihairu/falcon.git
cd falcon

# Build from source
cmake -B build -S . -DCMAKE_BUILD_TYPE=Release
cmake --build build -j

All nightly CI builds are attached to the Releases page (rolling nightly tag).

Basic Usage

# Simple download
falcon-cli https://example.com/file.zip

# Multi-threaded download (5 connections)
falcon-cli -x 5 https://example.com/large_file.iso

# Download with speed limit (1MB/s)
falcon-cli --max-download-limit=1M https://example.com/video.mp4

# Resume behavior is enabled by default; explicit aria2-style switch is also supported
falcon-cli --continue true https://example.com/partial.zip

# Batch input with concurrent tasks
falcon-cli -i urls.txt -j 3

# Custom headers and proxy
falcon-cli --proxy http://127.0.0.1:7890 \
  -H "Authorization: Bearer TOKEN" \
  https://example.com/file.bin

# Try the experimental V2 engine
falcon-cli --http-engine v2 https://example.com/file.zip

aria2-Compatible Parameters

# Connection settings
falcon-cli -x 16 -s 16 --min-split-size=1M https://example.com/file.zip
# -x: Max connections per task
# -s: Max connections per server

# Retry settings
falcon-cli -r 5 --retry-wait 10 https://example.com/file.zip

# Timeout settings
falcon-cli --timeout 30 https://example.com/file.zip

# HTTP authentication
falcon-cli --http-user=user --http-passwd=pass https://example.com/file.zip

# User agent
falcon-cli --user-agent="Falcon/1.0" https://example.com/file.zip

# Output directory and file name
falcon-cli -d /tmp/downloads -o custom_name.zip https://example.com/file.zip

Run falcon-cli --help for the full parameter list.

Supported Protocols

Protocol	Status	Description
HTTP/HTTPS	Enabled	Standard web protocols with resume support
FTP/FTPS	Enabled	File Transfer Protocol with passive mode
Metalink	Enabled	RFC 5854 .meta4 / Metalink3 .metalink mirror lists with whole-file hash verification
SFTP	Enabled	libssh2 data plane with known_hosts verification and resume
WebDAV	Enabled	dav:// / davs:// over libcurl with Basic/Digest auth and resume
BitTorrent	Enabled	libtorrent data plane (falls back to the built-in pure-C++ mode when absent)
Thunder	Optional plugin	Implemented in repo but disabled by default in top-level CMake
QQDL	Optional plugin	Implemented in repo but disabled by default in top-level CMake
FlashGet	Optional plugin	Implemented in repo but disabled by default in top-level CMake
ED2K	Optional plugin	Implemented in repo but disabled by default in top-level CMake
HLS/DASH	Optional plugin	Implemented in repo but disabled by default in top-level CMake

Cloud Storage Support

Library-level browsing is implemented for Amazon S3, Alibaba Cloud OSS, Tencent COS, Qiniu Kodo, and Upyun (packages/libfalcon-storage): listing, tree views, object info, mkdir / rename / recursive delete, quota queries, and custom-endpoint (MinIO / RustFS / private-gateway) support with AWS Signature V4 request signing for S3-compatible services that require authentication. The desktop application ships a cloud storage page backed by these modules.

Note: the CLI currently does not expose storage-browsing commands. Flags like --list, --tree, --search, --add-config, --set-master-password shown in some older examples are not implemented — use the desktop GUI or call the libraries directly.

Secure Configuration

libfalcon-drives provides an encrypted configuration manager (SQLite-backed, AES-256-GCM credential encryption protected by a master password). The desktop application uses it in its settings page. CLI management commands are not exposed yet.

Advanced Features

Resource Search

libfalcon-drives includes a search provider framework (resource_search): a provider interface with URL validation, magnet-link parsing, filtering/sorting/truncation, and a generic crawler-backed provider. CLI search commands are not implemented yet; see the library API for integration.

Remote Directory Browsing

libfalcon-storage implements the ResourceBrowser interface for FTP, SFTP, S3, OSS, COS, Kodo, and Upyun — format-tree/table listings, path validation, and recursive operations. The desktop cloud storage page is built on it.

MCP Tool Server

The daemon exposes an MCP (Model Context Protocol) endpoint at POST /mcp (Streamable HTTP, same port as the RPC). AI hosts such as Claude Desktop or Cursor can list and call 10 download tools (falcon_add_download, falcon_list_tasks, falcon_get_task, pause/resume/remove, pause_all/resume_all, global stats, task files) — add a URL and ask "what's the progress?" in natural language. Enable it with --enable-mcp or daemon.json "mcp": {"enabled": true}; auth reuses rpc.secret via Authorization: Bearer (the endpoint refuses all requests when no secret is configured). Host-side configuration (Streamable HTTP):

{
  "mcpServers": {
    "falcon": {
      "url": "http://127.0.0.1:6800/mcp",
      "headers": { "Authorization": "Bearer <your rpc.secret>" }
    }
  }
}

Stage 2 is complete (stdio wrapper falcon-mcp, SSE progress subscription via GET /mcp, global-option and seeding tools); see docs/design/mcp_server_design.md for the full contract.

UI Prototypes

The desktop main view ships in the "warm console" theme (variant A) and has a "cold utility" variant candidate (variant B). Both dark-theme prototypes below are rendered from the real Qt widget tree (offscreen sandbox) with demo task data:

Variant	Direction	Key tokens
A · warm console (current production theme)	warm dark neutral base + falcon salmon accent, shared with the docs site	window #1b1714 / card #262019 / text #f2ede8 / accent #ffa07a
B · cold utility (variant candidate)	Motrix-style: deeper neutral base, higher-contrast text, restrained blue accent	window #131519 / card #1b1e24 / text #f5f7fa / accent #5b9df5

Source assets and regeneration instructions live in docs/design/prototypes/; the interactive comparison page is on the docs site.

Architecture

Falcon follows a modular architecture with aria2-inspired event-driven design:

graph TD
    APP["<b>Applications</b><br/>falcon-cli · falcon-daemon · desktop (Qt6)"]
    CORE["<b>Falcon Core</b> (aria2-style)<br/>DownloadEngineV2 event loop · command queue<br/>request groups · socket reuse · task manager"]
    PROTO["<b>libfalcon-protocols</b><br/>HTTP · FTP · BitTorrent · Metalink · HLS · private protocols"]
    STOR["<b>libfalcon-storage</b><br/>S3 · OSS · COS · Kodo · Upyun resource browsing"]
    DRV["<b>libfalcon-drives</b><br/>cloud drives · resource search · encrypted config"]
    INFRA["<b>Infrastructure</b><br/>libcurl · OpenSSL · libtorrent · spdlog · SQLite · nlohmann/json"]

    APP --> CORE
    PROTO --> CORE
    STOR --> CORE
    DRV --> CORE
    CORE --> INFRA

Loading

Event-Driven Architecture

Falcon uses an event-driven command pattern inspired by aria2:

1. Command Execution: All download operations are encapsulated as command objects
2. I/O Multiplexing: Uses epoll (Linux), kqueue (macOS/BSD), or poll (fallback)
3. Connection Pooling: Reuses HTTP/HTTPS connections for better performance
4. Non-Blocking I/O: All sockets are non-blocking, driven by events

Development

Prerequisites

• CMake 3.15+
• C++17 compatible compiler (GCC 11+ / Clang 14+ / MSVC 2019+ recommended)
• libcurl 7.68+
• OpenSSL 1.1.1+
• nlohmann/json 3.10+
• spdlog 1.9+
• SQLite 3.35+
• libtorrent-rasterbar 2.0+ (optional, BitTorrent plugin)
• Qt 6 (optional, desktop application)

Build Options

# Enable/disable components and protocol plugins
cmake -B build -S . \
  -DFALCON_BUILD_CLI=ON \
  -DFALCON_BUILD_DAEMON=ON \
  -DFALCON_BUILD_DESKTOP=ON \
  -DFALCON_ENABLE_HTTP=ON \
  -DFALCON_ENABLE_FTP=ON \
  -DFALCON_ENABLE_METALINK=ON \
  -DFALCON_ENABLE_BITTORRENT=ON \
  -DFALCON_ENABLE_SFTP=ON \
  -DFALCON_ENABLE_WEBDAV=ON \
  -DFALCON_ENABLE_THUNDER=ON \
  -DFALCON_ENABLE_QQDL=ON \
  -DFALCON_ENABLE_FLASHGET=ON \
  -DFALCON_ENABLE_ED2K=ON \
  -DFALCON_ENABLE_HLS=ON \
  -DFALCON_ENABLE_CLOUD_STORAGE=ON \
  -DFALCON_ENABLE_RESOURCE_BROWSER=ON \
  -DFALCON_ENABLE_RESOURCE_SEARCH=ON \
  -DFALCON_ENABLE_CONFIG_MANAGER=ON

HTTP, FTP, BitTorrent, SFTP, WebDAV, Metalink, cloud storage, resource browsing/search, and the config manager are ON by default; the private-protocol plugins (Thunder/QQDL/FlashGet/ED2K/HLS) are OFF by default.

Contributing

We welcome contributions! Please see our Contributing Guide for details.

Code Style

• Follow Google C++ Style Guide
• Use clang-format for code formatting
• Write unit tests for new features

License

This project is licensed under the Apache License 2.0 - see the LICENSE file for details.

Acknowledgments

• libcurl for HTTP/FTP/SFTP support
• libtorrent for BitTorrent support
• nlohmann/json for JSON handling
• spdlog for logging
• OpenSSL for cryptographic operations
• SQLite for task persistence and configuration storage
• Qt 6 for the desktop application

Roadmap

Completed

• Core download engines (V1 libcurl + experimental event-driven V2 engine)
• HTTP/HTTPS, FTP/FTPS plugins
• Metalink downloads (multi-mirror P2SP segmentation + whole-file hash verification)
• CLI (60+ aria2-compatible options)
• Daemon: aria2-compatible JSON-RPC (HTTP + WebSocket event stream), SQLite persistence, SIGHUP hot reload, MCP tool endpoint (10 download tools)
• P2SP phase 1+2: falcon-swarmd rendezvous service, daemon announce/retract with TTL renewal, RPC falcon.swarm.status/setShare, CLI --swarm-server, inbound /by-sha256 data service, swarm sources in metalink mirror pools (NAT-filtered, hash-verified)
• Desktop application (Qt6, Fluent design, light/dark themes, cloud drive browsing)
• Private protocol support (Thunder, QQDL, FlashGet, ED2K)
• SFTP, WebDAV protocols (libssh2 / libcurl data planes)
• Cloud storage browsing (S3, Alibaba Cloud OSS, Tencent COS, Qiniu Kodo, Upyun)
• Resource search, encrypted configuration management

In Progress

• More private protocols and cloud-drive direct-link parsing

Planned

• Further private protocol and cloud-drive direct-link parsing enhancements
• Mobile support

---

The Falcon Team