Bencode encoding and decoding library.
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
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:
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")
- Bugs (e.g. crashes on input
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.