Protocol Handlers

Risuko's engine includes specialized handlers for each supported protocol. Each handler is a separate module within risuko-engine.

HTTP/HTTPS

Module: engine/http.rs

The HTTP handler supports multi-threaded range-based downloads:

• Sends a GET request with Range: bytes=0-0 to probe file size and range support
• Divides the file into 1 MiB pieces when it is larger than min-split-size × split; spawns N worker tasks (configurable via split, like aria2's -s/-x) that pull pieces from a shared lock-free queue
• Work-stealing is inherent: any idle worker claims the next free piece, so a slow connection never holds back the rest of the download
• Resume granularity is per-piece (≤1 MiB lost on SIGKILL): each piece tracks an AtomicU32 byte counter that the writer increments per flushed Bytes, and a sidecar JSON snapshot is persisted every 2 s
• Downloads use HTTP Range headers; workers are pinned to HTTP/1.1 to keep each piece on its own TCP connection
• Each piece streams bytes::Bytes directly into a dedicated writer task that issues positioned writes (pwrite on Unix, seek_write on Windows) against a shared file handle, so workers never contend on a seek lock
• Calls fsync once on completion before renaming the .part file into place
• Validates the Content-Range header on every 206 response and aborts on mismatch; sends If-Match when an ETag was recorded for resume
• Falls back to a single-connection download when the file is below min-split-size or the server doesn't support ranges
• Handles redirects, cookies, and custom headers
• Supports proxy connections via the all-proxy option (http://, socks5://, socks5h://; https:// proxies are not supported)
• Optional DNS over HTTPS: when doh-enable + doh-url are set, hostnames resolve via RFC 8484 wire-format queries to the endpoint instead of the system resolver. Applied process-wide to every risuko-http client through a pluggable resolver hook, with an in-memory TTL cache and optional fallback to system DNS (doh-fallback)
• Stalled-transfer watchdog: aborts a worker when the EMA stays below lowest-speed-limit for lowest-speed-limit-timeout (auto-retry restarts it when enabled)
• Multi-URI tasks pick a mirror via uri-selector (feedback / inorder / adaptive)
• Optional .netrc lookup for HTTP Basic auth when the URL has no embedded credentials (disabled with no-netrc)
• Cookies can be primed from a Netscape/Mozilla cookies.txt via load-cookies

Key Options

BitTorrent

Module: engine/torrent.rs

Built on risuko-bt:

• Magnet link resolution (session fast-path for already-managed torrents, then tracker + DHT). Accepts both xt=urn:btih: (v1) and xt=urn:btmh: (v2 multihash) URNs; hybrid magnets carry both
• .torrent file parsing via the bundled bencode decoder; supports v1, pure-v2, and hybrid metainfo (BEP 52 meta version=2 with file tree and piece layers)
• BEP-5 DHT for peer discovery, dual-stack (IPv4 + IPv6 via BEP-32) when an IPv6 socket can be bound; per-torrent continuous get_peers polling and announce_peer keep the peer supply live throughout the download session. Pure-v2 swarms announce the leading 20 bytes of the SHA-256 info-hash on the v1 DHT/trackers per BEP 52
• BEP-14 Local Service Discovery (LSD) for peers on the same LAN
• BEP-10 extension protocol with ut_metadata (BEP-9) and full BEP-11 PEX (ut_pex): received peer-exchange messages are parsed and gossiped peers are fed into the dial channel
• BEP-55 ut_holepunch NAT traversal: advertised in the extended handshake. When a direct dial to a PEX-gossiped peer fails, Risuko asks the relay that gossiped it to perform a rendezvous; as a relay it forwards connect messages so two NATed peers can simultaneously open a connection
• BEP-29 µTP (Micro Transport Protocol): outbound dials attempt TCP first and fall back to µTP when TCP is refused; inbound µTP connections are accepted on the same UDP port as the TCP listener
• BEP-8 Message Stream Encryption (MSE/PE) with selectable plaintext / prefer / require policy
• BEP-52 BitTorrent v2: SHA-256 Merkle piece-tree verification (16 KiB block leaves), reserved-bit 0x08 in handshake byte 7 advertises v2 capability, and the HashRequest / Hashes / HashReject wire messages exchange Merkle layer slices with sibling proofs
• UPnP IGD port forwarding for the TCP listener only (the µTP UDP port and IPv6 are not mapped)
• Rarest-first piece selection with endgame mode; SHA-1 (v1) or SHA-256 Merkle root (v2) verification off the async runtime
• HTTP/HTTPS (BEP-23 compact) and UDP (BEP-15) trackers
• Configurable seeding (ratio, time, or keep-seeding), upload speed limiting
• Tunable per-peer request pipeline and per-torrent peer cap

Key Options

Seeding Behavior

After a torrent download completes, seeding behavior depends on the seed options:

1. onBtDownloadComplete fires when the download finishes
2. If keep-seeding is true, or seed-time > 0, or seed-ratio > 0, the task stays active and seeding continues
3. When keep-seeding is true, seed-time / seed-ratio limits are ignored; seeding runs until the task is stopped manually
4. Otherwise seeding stops when seed-time elapses or seed-ratio is reached (whichever comes first)
5. onDownloadComplete fires when seeding is done (or immediately if no seeding was requested)

ED2K

Module: engine/ed2k/

Downloads files by known hash using ed2k://|file|… links (server links are rejected). Sources come from OP_GET_SOURCES on the configured servers plus any sources, entries in the link; only high-ID sources are used. Download only — no keyword search, no sharing/upload, no Kad DHT, and no encryption. Files over 4 GiB are rejected (the 64-bit large-file extension is not implemented), and downloaded data is not hash-verified.

Key Options

M3U8/HLS

Module: engine/m3u8/

Downloads HTTP Live Streaming content:

• Parses master and media M3U8 playlists (highest-bandwidth variant selected from a master playlist)
• Downloads segments concurrently (bounded by split, default 5) with per-segment retry and a resume-progress sidecar
• Decrypts AES-128-CBC segments (EXT-X-KEY); SAMPLE-AES and other methods are written through undecrypted
• Concatenates segments into a single .ts, optionally remuxing to MP4 via ffmpeg when m3u8-output-format is mp4
• VOD only — live playlists (no #EXT-X-ENDLIST) are rejected

FTP/SFTP

Module: engine/ftp/

File Transfer Protocol handler:

• FTP with optional implicit-TLS encryption (FTPS)
• SFTP (SSH File Transfer Protocol) via russh + russh-sftp
• Server host keys pinned on first use (TOFU) via engine/ssh_known_hosts.rs; subsequent fingerprint mismatches are refused. The same store is shared with the SFTP upload sink so trust state stays consistent across download and upload paths
• Resume from an existing .part via FTP REST or SFTP positional reads; single file per task (no directory listing or multi-file transfer)
• FTPS certificate verification on by default (check-certificate); SFTP auth accepts a password or a PEM private key (sftp-private-key)

Media (yt-dlp)

Module: engine/media.rs

Delegates extraction and download to an external yt-dlp process resolved from PATH (not bundled; check_yt_dlp_available runs yt-dlp --version first). Routing uses engine::media::is_media_uri, an allowlist of ~26 host suffixes (YouTube, Vimeo, Twitch, Bilibili, SoundCloud, TikTok, and others); the force-ytdlp option forces any URL through yt-dlp. The handler:

• Probes the URL with yt-dlp --dump-json --no-playlist --flat-playlist to fetch a JSON info object (title, duration, formats), exposed via the Tauri command get_media_info
• Spawns yt-dlp with --newline --progress-template and parses progress lines into the same atomic counters used by HTTP/BT, so the regular speed/progress UI works
• Picks the format selector from the media-format option (falling back to youtube-format, then yt-format); merges via ffmpeg when it is on PATH
• Watches yt-dlp's before_dl / after_move / Destination: lines to learn the resolved output filename
• Forwards proxy, user-agent, referer, and cookies (all-proxy/proxy, user-agent, referer, cookies file or cookie header)
• For YouTube URLs adds --extractor-args youtube:player_client=web,default

Routed automatically by add_uri whenever is_media_uri matches; the dedicated add_media Tauri command and risuko.addMedia RPC method bypass detection.

ADC / Direct Connect (NMDC + ADC dialects)

Module: engine/adc/

Schemes: adc://, adcs:// (parsed as a TLS flag), dchub://, nmdc://. Default port 411 (ADC), 412 (ADCS). Direct file URIs of the form dchub://hub.host[:port]/?TTH=<base32>&xl=<bytes>&dn=<name> carry the TTH hash, file size and display name.

The transfer implementation (NMDC $Lock/$Key/$ADCGET, the ADC framed protocol, and TTH/Tiger hashing) was removed. The handler now only parses the URI: it validates the scheme, requires a TTH and non-zero xl, stores the size, then returns no source has the requested file without any network I/O. Risuko runs passive-only with no listening socket, so $ConnectToMe / ADC CTM can never complete. adcs:// TLS is not implemented.

Gnutella 0.6

Module: engine/gnutella/

URI scheme: gnutella://host[:port]/uri-res/N2R?urn:sha1:<base32> (also gnet://). Default port 6346. The Gnutella wire protocol itself is not implemented — there is no GNUTELLA CONNECT/0.6 handshake, no GWebCache discovery, and no PING/QUERY/QUERYHIT. The handler:

• Connects directly to the host in the URI and issues an HTTP/1.1 GET /uri-res/N2R?<urn> with an X-Gnutella-Content-URN header (User-Agent: Risuko/0.1)
• Accepts only 200 or 206, requires a Content-Length (no chunked encoding), and checks it is within 4 KiB of the xl= size hint
• Streams the single source to disk with no range resume and no SHA-1 verification (the URN is only a request key)

Gnutella2 (G2)

Module: engine/g2/

URI scheme: g2://host[:port]/sha1/<base32>?xl=<bytes>&dn=<name>. Default port 6346. No G2 wire protocol is implemented; run_g2_download reuses the Gnutella fetch_by_urn path with a hardcoded /uri-res/N2R route since both networks serve content over the same peer-to-peer HTTP/1.1 endpoint. Same single-source fetch, length tolerance, and lack of hash verification as Gnutella.

giFT IPC bridge

Module: engine/gift/

URI scheme: gift://<inner-uri>. Off by default. When gift-enabled is true, the handler connects to a locally-running giftd daemon (default 127.0.0.1:1213, override with gift-host / gift-port) over its line-oriented IPC socket and forwards the inner URI verbatim. Status is parsed from TRANSFER STATUS id=… total=… done=… state=active|complete|... lines so progress bars work like any other transfer. Cancelling the task issues a TRANSFER REMOVE id=… to giftd.

RSS

Module: engine/rss/

Automatic feed subscription and download:

• Add RSS/Atom feed URLs
• Periodic polling for new items (configurable interval)
• Automatic download of new items matching configured rules
• Persistent feed state via StorageBackend

The RSS manager uses tokio::spawn for async polling and requires a tokio runtime context.

Cloud Upload Sinks

Module: engine/upload/

Push completed downloads to a remote destination. The upload subsystem mirrors the RssManager pattern: a single UploadSinkManager owns sinks, routing rules, and a bounded job queue. Each protocol implements an UploadSink trait (upload + test) and is dispatched from manager::build_sink_runtime.

Sink selection is per-task override → first matching rule → default sink id. The manager runs uploads on a tokio::Semaphore (default permits = 2, clamped to 1..=16) and emits engine:upload-{queued,start,complete,error,cancelled} events. Persisted state lives under the upload-sinks key via StorageBackend.

See the Cloud Upload Sinks guide for user-facing configuration.

Protocol Routing

The Tauri add_uri command and the desktop Add Task modal sniff the URI scheme to dispatch transparently. The raw JSON-RPC layer keeps protocol-specific methods so that aria2-style clients still know exactly what they're calling:

Magnet links are sniffed inside add_http_task, the shared target of risuko.addUri, so the CLI and aria2-style clients add magnets too — a magnet: URI is routed to the torrent handler wherever it enters. Scheme sniffing for M3U8, FTP, and the legacy P2P protocols still lives only in the Tauri add_uri command, so a .m3u8, ftp://, or gnutella:// URL sent over plain JSON-RPC is enqueued as an HTTP task. The CLI's download command distinguishes .torrent files (path ends with .torrent and exists on disk → risuko.addTorrent) and media URLs (is_media_uri or --ytdlp → risuko.addMedia); everything else, magnets included, is passed to risuko.addUri. The Node.js API also offers protocol-specific functions (addTorrent, addMagnet, addEd2k, addM3u8, addFtp) that call the engine directly without scheme sniffing.