benc

Bencode encoding and decoding library

Bencode

Bencode is a simple encoding format for loosely structured data, comparable to JSON. It is used primarily in the BitTorrent protocol. For a description of the format see

• The BitTorrent Protocol Specification (BEP-3)
• Bencode on Wikipedia

Features

This library offers

• A nice API
• Correctness
• Speed

This library does not attempt to support

• Lazy or incremental parsing
• Failing with detailed error messages

Getting started

Please see the Haddocks for Data.Bencode.Decode and Data.Bencode.Encode.

Alternatives

There are currently three other Bencode libraries on Hackage:

• bencode
• AttoBencode
• bencoding

All of these are in some combination of buggy, slow, and unmaintained.

Click for details

• bencode:
  • Bugs (e.g. crashes on input "i-e")
  • Very slow parsing
  • No high-level encoding API
  • [Minor] Lax parsing (e.g. admits the invalid "i-0e")
• AttoBencode
  • Slow parsing
  • [Minor] Lax parsing (e.g. admits the invalid "i-0e")
• bencoding
  • Bugs (e.g. crashes on parsing non-UTF-8 into Text)
  • Questionable design of dict encoding/decoding API, where human error can lead to mis-parsing Bencode or writing invalid Bencode.
  • [Minor] Lax parsing (e.g. admits the invalid "i-0e")

API comparison

See the benchmark file as a comparison point of the library APIs.

Benchmarks

Below is a comparison of decoding and encoding of two torrent files, performed with GHC 9.6.3. See the benchmark file for details.

Decoding

Library	crossref	ubuntu
benc	27.6 ms ± 2.1 ms	1.46 μs ± 93 ns
bencode	218 ms ± 11 ms	28.4 μs ± 1.5 μs
AttoBencode	44.8 ms ± 3.8 ms	2.97 μs ± 171 ns
bencoding	39.7 ms ± 3.7 ms	2.38 μs ± 181 ns

^{Note: bencode parses from a lazy ByteString unlike the rest which parse from strict ByteStrings, and so is expected to be a little slower.}

Encoding

Library	crossref	ubuntu
benc	11.8 ms ± 1.0 ms	1.91 μs ± 179 ns
bencode	42.4 ms ± 3.1 ms	3.19 μs ± 173 ns
AttoBencode	20.2 ms ± 1.1 ms	10.2 μs ± 387 ns
bencoding	11.6 ms ± 1.1 ms	1.79 μs ± 100 ns

^{Note: AttoBencode encodes to a strict ByteString via a lazy ByteString, unlike the rest, which only prepare the lazy ByteString. As such, it is expected to be slower.}

Contributing

Contributions, bug reports, suggestions welcome! Please open an issue.