wirepact 0.1.0

A teaching protocol crate: protocols are contracts, not HTTP.
Documentation
  • Coverage
  • 14.29%
    5 out of 35 items documented0 out of 1 items with examples
  • Size
  • Source code size: 20.2 kB This is the summed size of all the files inside the crates.io package for this release.
  • Documentation size: 444.2 kB This is the summed size of all files generated by rustdoc for all configured targets
  • Ø build duration
  • this release: 6s Average build duration of successful builds.
  • all releases: 6s Average build duration of successful builds in releases after 2024-10-23.
  • Links
  • Repository
  • crates.io
  • Dependencies
  • Versions
  • Owners
  • X4MU-L

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)

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

Try it:

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

Frame protocol (binary)

[ 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

wirepact = "0.1"

Quick Rust example

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