# Toe Beans
This crate provides:
- A library for:
- Serializing and deserializing DHCP messages.
- Client and server logic.
- A client and server binary that wraps the library.
This crate is heavily documented on [docs.rs](https://docs.rs/toe-beans).
## Usage
### Library
`cargo add toe-beans` to install it as a dependency.
You may disable either of the default feature flags (`v4_client`/`v4_server`) if you don't need the other.
Check out the [binaries' code](https://codeberg.org/black-cat/toe-beans/src/branch/main/src/bin) and the docs.rs link above for examples of how to use the library.
### Binary
`cargo install toe-beans` will install both the server and client binaries.
You may use the `--bin` cli arg to install only one of the binaries.
## Safety
The `unsafe_code` lint is set to `forbid` which means that unsafe code is not allowed (unless through a third-party crate).
Nearly all of the code within the listen loop of the server is panic free to prevent the server from crashing from a bad
request.
## Performance
A significant amount of work has been put into optimizing the library code. At the moment, only the library code has benchmarking. It uses criterion.
> Note that Options make up the majority of a dhcp message, so how many, or which type, of options you have effect the results. Some libraries might lazily encode/decode which artificially improves their results.
Our benchmarks are split into few options (lower bound) and many options (upper bound) to give an idea of worst/best cases.
The Message is fully processed (no part is lazily evaluated and thus excluded from the benchmark).
Here are the results as of June 14, 2025:
```
benchmark from_bytes (many options)
time: 332.27 nanoseconds
benchmark from_bytes (few options)
time: 103.35 nanoseconds
benchmark to_bytes (many options)
time: 165.52 nanoseconds
benchmark to_bytes (few options)
time: 66.779 nanoseconds
```
## Status
Currently, only dhcpv4/ipv4 is handled.
Ipv6 support will be added in the future.
The standard RFCs are closely followed, but its hard to promise 100% compatibility with them.
Subtle differences may exist.
The message library code is complete with the exception of needing to implement more options.
The server library/binary have successfully assigned/validated an ip address on a [live router](https://codeberg.org/black-cat/antennas).
The server is currently single threaded, configured through a toml file, and leases are stored in another toml file.
The client binary is still a work in progress, but the client library code is more complete.
Unit and integration tests exist but need to be expanded. A docker-compose example using `dhclient` is available.
## Comparison
The last time I checked (two years ago), and I could very much be wrong, the only substantial dhcp rust projects are this one and [dhcproto](https://crates.io/crates/dhcproto) (which has a server implementation called [dora](https://github.com/bluecatengineering/dora)). Massive shoutout Evan Cameron and the contributors of dhcproto for
their excellent work!
I actually chose _not_ to look at dhcproto very much in order to come up with my own solutions
for toe-beans, so the projects are surprisingly different despite implementing the same core RFCs.
Therefore, I apologize if I say anything wrong/outdated.
dhcproto was first published 2 years prior to toe-bean's first commit, and it shows in that dhcproto is further along in available options, ipv6 support, and multithreading. I'm not sure on how far along their server is. However, `dora-dhcp`, the crate for their server has not yet been published.
Ultimately, both projects have their merit, and I'm sure they'll both get better over time.
## Shameless Plug
Check out these other projects on <https://black-cat.us>!
## License
Distributed under the terms of the GNU GPL License (Version 3 or later)