wirepact 0.1.0

A teaching protocol crate: protocols are contracts, not HTTP.
Documentation
# WirePact

**WirePact** is a deliberately small application protocol for learning TCP.

It is **not HTTP**. It is a **contract** — an agreement between client and server about how bytes are framed and interpreted.

## Why this exists

Many developers first encounter "protocol" through HTTP. WirePact exists to make the underlying idea visible:

> A protocol is a promise about how two sides will read and write bytes.

## Two encodings, one meaning

WirePact defines the same messages in two encodings:

| Encoding | Best for | Framing |
|----------|----------|---------|
| **Line** | `nc`, humans, quick debugging | newline-terminated UTF-8 lines |
| **Frame** | Rust, Go, Python, production-style clients | 4-byte big-endian length + type byte + payload |

Both sides can speak either encoding on the same TCP port. The server detects which one you are using.

## Line protocol (text)

```text
HELLO sam
WELCOME sam
PING
PONG
ECHO hello world
ECHO hello world
GOODBYE
BYE
```

Try it:

```bash
printf 'HELLO sam\nPING\nECHO hi\nGOODBYE\n' | nc localhost 7100
```

## Frame protocol (binary)

```text
[ u32 length BE ][ u8 type ][ payload... ]
```

Message types:

| Type | Name | Payload |
|------|------|---------|
| 1 | Hello | `u16 name_len` + name bytes |
| 2 | Welcome | same |
| 3 | Ping | empty |
| 4 | Pong | empty |
| 5 | Echo | raw bytes |
| 6 | EchoReply | raw bytes |
| 7 | Goodbye | empty |
| 8 | Bye | empty |
| 255 | Error | `u8 code` + `u16 msg_len` + message |

Default max frame size: 64 KiB.

## Install

```toml
wirepact = "0.1"
```

## Quick Rust example

```rust
use wirepact::{LineCodec, Message};

let mut codec = LineCodec::new();
codec.feed(b"HELLO sam\nPING\n");
let msgs = codec.decode_messages()?;
assert_eq!(msgs[0], Message::Hello { name: "sam".into() });
assert_eq!(msgs[1], Message::Ping);
```

## License

MIT OR Apache-2.0