Expand description
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("dir/", 1048576).build().unwrap();
torrent.write_into_file("sample.torrent").unwrap();
Bencode (de)serialization.
use lava_torrent::bencode::BencodeElem;
let bytes = "d4:spam4:eggse".as_bytes();
let dict = BencodeElem::Dictionary([("spam".to_owned(), "eggs".into())].into());
assert_eq!(BencodeElem::from_bytes(bytes).unwrap()[0], dict);
assert_eq!(dict.encode(), bytes);
assert!(dict.write_into_file("/tmp/foo").is_ok());
assert_eq!(BencodeElem::from_file("/tmp/foo").unwrap()[0], dict);
§Overview
- It is not recommended to use
lava_torrent
in any critical system at this point. - 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
- tracker response parsing =>
tracker
§Feature Flags
None at the moment.
§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, aLavaTorrentError
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.
Modules§
- bencode
- Module for bencode-related parsing/encoding.
- torrent
- Module for
.torrent
files related parsing/encoding/creation. - tracker
- Module containing structs for tracker responses.
Enums§
- Lava
Torrent Error - Custom error.