Crate lava_torrent[−][src]
lava_torrent
is a library for parsing/encoding/creating bencode and .torrent files. It is
dual-licensed under Apache 2.0 and MIT.
Quick Start
Read a torrent (v1) and print it and its info hash.
use lava_torrent::torrent::v1::Torrent; let torrent = Torrent::read_from_file("sample.torrent").unwrap(); println!("{}", torrent); println!("Info hash: {}", torrent.info_hash());
Create a torrent (v1) from files in a directory and save the .torrent file.
use lava_torrent::torrent::v1::TorrentBuilder; let torrent = TorrentBuilder::new("announce".to_owned(), "dir/", 1048576).build().unwrap(); torrent.write_into_file("sample.torrent").unwrap();
Overview
- It is not recommended to use
lava_torrent
in any critical system at this point. - Currently, only v1 torrents are supported. Merkle tree torrents can be supported if there's enough demand. v2 torrents might be supported once it's stabilized.
- Methods for parsing and encoding are generally bound to structs (i.e. they are
"associated methods"). Methods that are general enough are placed at the module-level (e.g.
lava_torrent::bencode::write::encode_bytes()
).
Functionality
- bencode parsing/encoding (i.e. "bencoding/bdecoding") =>
BencodeElem
- torrent parsing/encoding (based on
BencodeElem
) =>Torrent
- torrent creation =>
TorrentBuilder
Performance
lava_torrent
is designed with performance and maintenance cost in mind. Some naive
profiling has been performed.
Copying
Parsing a .torrent (v1) file would take at least 2 copies:
- load bencode bytes from file
- parse from bytes (bytes are copied, for example, when they are converted to
String
)
Creating a .torrent (v1) file and writing its bencoded form to disk would take at least 3 copies:
- load file content from disk
- feed the file content to a SHA1 hasher when constructing a
Torrent
- encode the resulting struct and write it to disk
It might be possible to further reduce the number of copies, but in my opinion that would make the code harder to maintain. Unless there is evidence suggesting otherwise, I think the current balance between performance and maintenance cost is good enough. Please open a GitHub issue if you have any suggestion.
Correctness
lava_torrent
is written without using any existing parser or parser generator.
The BitTorrent specification is also rather vague on certain points. Thus, bugs
should not be a surprise. If you do find one, please open a GitHub issue.
That said, a lot of unit tests and several integration tests are written to minimize the possibility of incorrect behaviors.
Known Issues
-
BEP 3 specifies that a bencode integer has no size limit. This is a reasonable choice as it allows the protocol to be used in the future when file sizes grow significantly. However, using a 64-bit signed integer to represent a bencode integer should be more-than sufficient even in 2018. Therefore, while technically we should use something like
bigint
to represent bencode integers,i64
is used in the current implementation. If a bencode integer larger thani64::max_value()
is found, anError
will be returned. -
Several private methods will panic if something that "just won't happen" happens. For the purpose of full disclosure this behavior is mentioned here, but in reality panic should never be triggered. If you want to locate these private methods try searching for "panic", "unwrap", and "expect" in
*.rs
files.
Implemented BEPs
NOTE: Only the parsing/encoding aspects are implemented.
Other Stuff
- Feature Request: To request a feature please open a GitHub issue (please try to request only 1 feature per issue).
- Contribution: PR is always welcome.
- What's with "lava": Originally I intended to start a project for downloading/crawling stuff. When downloading files, a stream of bits will be moving around--like lava.
- Other "lava" crates: The landscape for downloading/crawling stuff is fairly mature at this point, which means reinventing the wheels now is rather pointless... So this might be the only crate published under the "lava" name.
- Similar crates: bip-rs
Modules
bencode |
Module for bencode-related parsing/encoding. |
error |
Custom error. |
torrent |
Module for |