libtorrent 2.1.2 fixes v2 web-seed request merging

libtorrent 2.1.2 fixes the merging of web-seed requests for BitTorrent v2 torrents. The release changelog calls it “fix web seed coalesced requests for v2 torrents.” If you use web seeds to download lawful content such as open datasets or public-domain archives, the relevant check is whether your client’s libtorrent build includes that correction—not simply whether the application itself is up to date.

This is a specific request-handling fix, not a general cure for slow torrents or stalled magnet links.

What was wrong with the requests?

A web seed supplies the torrent’s file data from a web server rather than another BitTorrent peer. BEP 19 defines the GetRight-style mechanism: the .torrent file can list download URLs in a top-level url-list field, outside the info dictionary. For HTTP, a client can request byte ranges and combine consecutive blocks into larger requests, reducing the number of requests sent to the server.

That combining operation is coalescing. The patch behind this fix identifies a failure at file boundaries in v2 torrents.

The boundary matters because BitTorrent v2’s layout starts each non-empty file at a piece boundary. A file’s last piece can be shorter than the torrent’s nominal piece length, leaving an alignment gap before the next file.

For example, with a 64 KiB piece length, a 48 KiB first file ends at offset 48 KiB, while the next non-empty file starts at offset 64 KiB in the torrent’s piece address space. Consecutive piece numbers therefore do not guarantee contiguous payload bytes in that address space.

The corrected code tracks the actual ending byte offset of the accumulated request. It merges the next block only when that block starts exactly there, stopping at the gap after a shortened piece. The patch’s comments specifically identify this shortened-piece case as applying to v2-only torrents. It still permits merging across full piece boundaries and within a shortened piece. The patch also adds tests for these cases and strengthens checks for hash failures and peer errors in simulations.

How to apply the fix

1. Check the library version, not just the client version. Consult your application’s version information and its package or build notes. The libtorrent release number and the BitTorrent protocol version are different things. qBittorrent, for example, uses libtorrent-rasterbar, but its application version alone does not identify the library in your particular installation.
2. Use a supported client build that includes the correction. libtorrent 2.1.2 explicitly lists it. For another branch or a distributor’s patched package, look for confirmation that this fix was included; do not infer that from a “libtorrent 2.x” label. Avoid replacing library files manually: libtorrent’s ABI guidance promises compatibility within the same major-and-minor series, not across all 2.x releases.
3. Retry the same authorized torrent and compare its errors. Record the client and library versions, torrent type, web-seed URL and relevant log messages. Successful completion and verified pieces are more useful checks than a momentary speed increase.
4. If it still fails, inspect the web seed itself. Check that its URLs resolve to the correct files and that the server handles the requested ranges. For multi-file torrents, BEP 19 requires the base URL to map to the torrent’s name and file paths. A missing file, incorrect path or changed payload is not repaired by the request-merging fix.

Do not disable integrity checks to make a transfer appear successful. BEP 19 says that when a downloaded piece’s checksum does not match, the connection must be closed and the web-seed URL should be discarded.

Why this does not fix missing magnet metadata

A magnet link that remains at “retrieving metadata” has not yet reached normal file-data downloading. BEP 9 lets peers exchange the torrent’s info dictionary; it does not transfer the entire .torrent file. Because BEP 19’s url-list sits outside that dictionary, ordinary metadata exchange does not convey that web-seed list.

If a publisher provides an official .torrent containing web seeds, use that file to check whether your client receives the intended URLs. Do not assume that retrieving metadata from a bare magnet also retrieves every distribution setting. For the earlier discovery stage, see how a magnet link finds metadata and peers.