Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.

Awesome Lists | Featured Topics | Projects

https://github.com/meooow25/benc

Bencode encoding and decoding library
https://github.com/meooow25/benc

bencode haskell

Last synced: about 2 months ago
JSON representation

Bencode encoding and decoding library

Host: GitHub
URL: https://github.com/meooow25/benc
Owner: meooow25
License: mit
Created: 2023-11-04T13:31:21.000Z (about 1 year ago)
Default Branch: master
Last Pushed: 2024-05-20T21:37:13.000Z (7 months ago)
Last Synced: 2024-10-04T08:19:10.457Z (3 months ago)
Topics: bencode, haskell
Language: Haskell
Homepage:
Size: 748 KB
Stars: 0
Watchers: 1
Forks: 0
Open Issues: 0
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- License: LICENSE

Awesome Lists containing this project

README

        # benc

[![Hackage](https://img.shields.io/hackage/v/benc?logo=haskell&color=blue)](https://hackage.haskell.org/package/benc)

[![Haskell-CI](https://github.com/meooow25/benc/actions/workflows/haskell-ci.yml/badge.svg)](https://github.com/meooow25/benc/actions/workflows/haskell-ci.yml)

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)](https://www.bittorrent.org/beps/bep_0003.html)

* [Bencode on Wikipedia](https://en.wikipedia.org/wiki/Bencode)

## 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`](https://hackage.haskell.org/package/benc/docs/Data-Bencode-Decode.html)

and [`Data.Bencode.Encode`](https://hackage.haskell.org/package/benc/docs/Data-Bencode-Encode.html).

## Alternatives

There are currently three other Bencode libraries on Hackage:

* [bencode](https://hackage.haskell.org/package/bencode)

* [AttoBencode](https://hackage.haskell.org/package/AttoBencode)

* [bencoding](https://hackage.haskell.org/package/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](https://github.com/meooow25/benc/blob/master/compare/Bench.hs)

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](https://github.com/meooow25/benc/blob/master/compare/Bench.hs)

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 `ByteString`s, 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](https://github.com/meooow25/benc/issues) as the first

step.