# 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:
| **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:
| 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