Crate lava_torrent [] [src]

lava_torrent is a library for parsing/encoding 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. Experimental/Unstable

use lava_torrent::torrent::v1::TorrentBuilder;

let torrent = TorrentBuilder::new("announce".to_string(), "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

Unstable Functionality

  • torrent creation (Experimental/Unstable, currently multi-file torrents creation is still in development, and the code is not yet optimized) => TorrentBuilder

Performance

lava_torrent is designed with performance and maintenance cost in mind.

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 2 copies:

  • load file content and construct a Torrent from it
  • encode the resulting struct and write it to disk (note: when encoding torrents, converting file paths (OsStr) to utf8 strings (String) also requires copies, but that should not be significant)

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

  1. 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 than i64::max_value() is found, an Error will be returned.

  2. 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).
  • Contribute: 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.

torrent

Module for .torrent files related parsing/encodeing.

Structs

Error

Custom Error type.

Enums

ErrorKind

Works with Error to differentiate between different kinds of errors.

Type Definitions

Result

Custom Result type.