boitalettres/doc/draft.md

# Just Enough Doc

## Run `simple` example

This example is meant to show basic service-based IMAP server with boitalettres library.

- [Source code](../examples/simple.rs)

```shell
$ export RUST_LOG="info,simple=trace,boitalettres=trace" 
$ export RUSTFLAGS="--cfg tokio_unstable"
$ cargo run --example simple
```

- Test it manually

Theoretically, IMAP server expected end of lines with `\r\n` but implementations are more liberal.
To check with `\r\n`, use the `socat` command line.
The `nc` command line will send only `\n` when run on Linux, our current implementation supports it.

```
$ socat readline tcp4:127.0.0.1:4567,crnl
$ nc 127.0.0.1 4567
```

If you want to trace this `simple` example with the [`tokio-console`](https://github.com/tokio-rs/console/tree/main/tokio-console) utility, run:

```shell
$ RUSTFLAGS="tokio_unstable" cargo run --example simple --features "tokio/tracing"
```

- [Basic python testing script](../scripts/test_imap.py)

```shell
$ python scripts/test_imap.py
```

## Notes

- The library use the `tracing` library for logging, a basic setup is shown in the `simple` example with the `tracing-subscriber` crate.

## References

- [`imap-codec`](https://docs.rs/imap-codec): IMAP protocol model+encoder/decoder
- [`tower`](https://docs.rs/tower): Service-based request handling library