folz / bento

:bento: A fast, correct, pure-Elixir library for reading and writing Bencoded metainfo (.torrent) files.

Bento

Bento is a new Bencoding library for Elixir focusing on incredibly fast speed without sacrificing simplicity, completeness, or correctness.

It takes inspiration from Poison, a pure-Elixir JSON library, and uses several techniques found there to achieve this speed:

• Extensive sub-binary matching.
• A hand-rolled parser using several techniques known to benefit HiPE for native compilation.
• IO list encoding.
• Single-pass decoding.

Additionally, and unlike some other Elixir bencoding libraries, Bento will also reject all malformed input. This guarantees you're working with a well-formed bencoded file.

Preliminary benchmarking shows that Bento performs over 2x faster when encoding, and at least as fast when decoding, compared to other existing Elixir libraries.

Documentation

Documentation is available on Hexdocs.

Installation

Bento is available in Hex. The package can be installed by:

1. Add bento to your list of dependencies in mix.exs:

{:bento, "~> 1.0"}

2. Then, update your dependencies.

$ mix do deps.get + deps.compile

Usage

Encoding an Elixir data type:

iex> Bento.encode([1, "two", [3]])
{:ok, "li1e3:twoli3eee"}
iex> Bento.encode!(%{"foo" => ["bar", "baz"], "qux" => "norf"})
"d3:fool3:bar3:baze3:qux4:norfe"

Decoding a bencoded string:

iex> Bento.decode("li1e3:twoli3eee")
{:ok, [1, "two", [3]]}
iex> Bento.decode!("d3:fool3:bar3:baze3:qux4:norfe")
%{"foo" => ["bar", "baz"], "qux" => "norf"}

Bento is also metainfo-aware and comes with a *.torrent decoder out of the box:

iex> File.read!("./test/_data/ubuntu-14.04.4-desktop-amd64.iso.torrent") |> Bento.torrent!()
%Bento.Metainfo.Torrent{
  info: %Bento.Metainfo.SingleFile{
    length: 1069547520,
    md5sum: nil,
    "piece length": 524288,
    pieces: <<109, 235, 143, 234, 36, 25, 142, 36, 20, 3, 227, 227, 134, 136,
      205, 130, 176, 104, 192, 33, 45, 230, 152, 2, 239, 131, 240, 217, 180,
      251, 153, 170, 31, 127, 175, 166, 9, 254, 133, 8, 42, 229, 43, 139, 86,
      ...>>,
    private: 0,
    name: "ubuntu-14.04.4-desktop-amd64.iso"
  },
  announce: "http://torrent.ubuntu.com:6969/announce",
  "announce-list": [
    ["http://torrent.ubuntu.com:6969/announce"],
    ["http://ipv6.torrent.ubuntu.com:6969/announce"]
  ],
  "creation date": ~U[2016-02-18 20:12:51Z],
  comment: "Ubuntu CD releases.ubuntu.com",
  "created by": nil,
  encoding: nil
}

In addition to parsing torrents via Bento.torrent!/1, It's also available decoding any bencoded data into any struct you choose, like so:

defmodule Name do
  defstruct [:family, :given]
end

iex> Bento.decode!("d6:family4:Folz5:given6:Rodneye", as: %Name{})
%Name{family: "Folz", given: "Rodney"}

Benchmarking

$ MIX_ENV=bench mix bench

We currently benchmark against: Bento (this project), bencode, Bencodex, and bencoder.

We are aware of, but unable to benchmark against: exbencode (build errors), and elixir_bencode (module name conflicts with Bencode).

PRs that add libraries to the benchmarks are greatly appreciated!

License

See LICENSE.

bento's Issues

Adding support for magnet link generation

Hi! I'm already using Bento to parse torrent files, and I would like to know if you'd accept a PR that implements magnet link generation from a torrent file.

Happy holidays :)

Torrents with additonal "<blah>.utf-8" fields are unable to be parsed.

This is due to :erlang.binary_to_existing_atom not being able to turn "name.utf-8" into an atom (the period is what causes it to trip up).

Stacktrace

** (exit) an exception was raised:
** (ArgumentError) errors were found at the given arguments:

• 1st argument: invalid UTF8 encoding

  :erlang.binary_to_existing_atom("name.utf-8", :utf8)
  (bento 0.9.2) lib/bento/metainfo.ex:48: anonymous fn/1 in Bento.Metainfo.transform/1
  (elixir 1.12.0) lib/enum.ex:1553: Enum."-map/2-lists^map/1-0-"/2
  (elixir 1.12.0) lib/enum.ex:1553: Enum."-map/2-lists^map/1-0-"/2
  (bento 0.9.2) lib/bento/metainfo.ex:30: Bento.Metainfo.info/1
  (bento 0.9.2) lib/bento/metainfo.ex:41: Bento.Metainfo.info!/1
  (bento 0.9.2) lib/bento.ex:92: Bento.torrent!/1
  

"name.utf-8" appears to be from clients such as Vuze/Azeurus for handling old torrents that did not write the name/path's in utf-8 (see here).

I am not sure how to "properly" handle this, but for now I will just have it filter out any keys with .utf-8 in the data metainfo before parsing. Id be happy to merge those changes in, or any different change you would suggest.

Thanks for the useful library!

Implement ourselves `Poison.Decode.decode/2`

This reconstruction is based on three considerations:

• The development of Poison does not seem to be very active.
• After this reconstruction is implemented, our code will not rely on any external code at all.
• #15 (comment)

Unable to encode Tuple

When Bento.encode/1 encounters a Tuple, an error will be reported.

iex(1)> Bento.encode {:does, :not, :work}     
** (Protocol.UndefinedError) protocol Bento.Encoder not implemented for {:does, :not, :work} of type Tuple
    (bento 1.0.0-dev) lib/bento/encoder.ex:35: Bento.Encoder.impl_for!/1
    (bento 1.0.0-dev) lib/bento/encoder.ex:56: Bento.Encoder.encode/1
    (bento 1.0.0-dev) lib/bento.ex:36: Bento.encode!/2
    (bento 1.0.0-dev) lib/bento.ex:22: Bento.encode/2
    iex:1: (file)