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 time	alloc	ubuntu time	alloc
benc	21.3 ms ± 902 μs	24 MB	1.30 μs ± 90 ns	3.6 KB
bencode	218 ms ± 7.7 ms	737 MB	29.0 μs ± 2.6 μs	121 KB
AttoBencode	44.6 ms ± 4.0 ms	129 MB	3.01 μs ± 102 ns	17 KB
bencoding	39.1 ms ± 2.3 ms	104 MB	2.44 μs ± 175 ns	15 KB

^{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 time	alloc	ubuntu time	alloc
benc	9.17 ms ± 487 μs	42 MB	1.58 μs ± 101 ns	11 KB
bencode	37.8 ms ± 860 μs	113 MB	3.17 μs ± 174 ns	19 KB
AttoBencode	19.7 ms ± 1.8 ms	109 MB	10.1 μs ± 993 ns	295 KB
bencoding	11.9 ms ± 916 μs	67 MB	1.81 μs ± 129 ns	15 KB

^{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

Questions, bug reports, documentation improvements, code contributions welcome! Please open an issue as the first step.