folk_protocol/lib.rs
1//! # `folk-protocol`
2//!
3//! Wire format for Folk: typed RPC messages and length-prefixed framing.
4//!
5//! ## What this crate provides
6//!
7//! - [`RpcMessage`]: the three message variants of `MessagePack`-RPC
8//! (`Request`, `Response`, `Notify`), encoded as positional `MessagePack` arrays.
9//! - [`FrameCodec`]: a Tokio codec that combines a 4-byte big-endian length prefix
10//! with `rmp_serde` payload encoding/decoding.
11//! - [`Error`]: a single error type for all fallible operations in this crate.
12//!
13//! ## Wire format
14//!
15//! Every message on the wire is:
16//!
17//! ```text
18//! +----------------+---------------------------------+
19//! | 4-byte length | MessagePack-encoded array |
20//! | big-endian | (the RpcMessage payload) |
21//! +----------------+---------------------------------+
22//! ```
23//!
24//! Maximum frame size is [`MAX_FRAME_SIZE`] (16 MiB). See
25//! `folk-spec/spec/02-protocol.md` for the full specification.
26//!
27//! ## Example
28//!
29//! ```rust
30//! use bytes::BytesMut;
31//! use folk_protocol::{FrameCodec, RpcMessage};
32//! use rmpv::Value;
33//! use tokio_util::codec::{Decoder, Encoder};
34//!
35//! let mut codec = FrameCodec::new();
36//! let msg = RpcMessage::request(1, "echo", Value::String("hello".into()));
37//!
38//! let mut buf = BytesMut::new();
39//! codec.encode(msg.clone(), &mut buf).unwrap();
40//!
41//! let decoded = codec.decode(&mut buf).unwrap().unwrap();
42//! assert_eq!(msg, decoded);
43//! ```
44
45pub mod codec;
46pub mod error;
47pub mod message;
48
49pub use codec::FrameCodec;
50pub use error::{Error, MAX_FRAME_SIZE, Result};
51pub use message::RpcMessage;