sansio_codec/lib.rs
1//! # SansIO Codec - Protocol Codecs for SansIO
2//!
3//! `sansio-codec` provides reusable codec implementations for the sansio ecosystem,
4//! including frame decoders, string codecs, and transport abstractions.
5//!
6//! ## Features
7//!
8//! - **Frame Decoders**: Line-based frame decoders for parsing delimited streams
9//! - **String Codecs**: UTF-8 string encoding/decoding
10//! - **Transport Abstractions**: Tagged message types with transport metadata
11//! - **Sans-IO Design**: Pure protocol logic without I/O dependencies
12//!
13//! ## Quick Start
14//!
15//! ```toml
16//! [dependencies]
17//! sansio-codec = "0.0.8"
18//! ```
19//!
20//! ## Building a Pipeline with Codecs
21//!
22//! ```rust,no_run
23//! use sansio::Pipeline;
24//! use sansio_codec::{
25//! LineBasedFrameDecoder, TaggedByteToMessageCodec, TaggedStringCodec, TerminatorType,
26//! };
27//! use sansio_transport::{TaggedBytesMut, TaggedString};
28//!
29//! let mut pipeline = Pipeline::<TaggedBytesMut, TaggedString>::new();
30//!
31//! // Add line-based frame decoder
32//! let frame_decoder = TaggedByteToMessageCodec::new(Box::new(
33//! LineBasedFrameDecoder::new(8192, true, TerminatorType::BOTH)
34//! ));
35//! pipeline.add_back(frame_decoder);
36//!
37//! // Add string codec
38//! pipeline.add_back(TaggedStringCodec::new());
39//!
40//! // Add your business logic handler
41//! // pipeline.add_back(your_handler);
42//!
43//! pipeline.finalize();
44//! ```
45//!
46//! For shared pipelines (e.g., UDP servers), use `RcPipeline`:
47//!
48//! ```rust,no_run
49//! use sansio::RcPipeline;
50//! use sansio_codec::{TaggedByteToMessageCodec, TaggedStringCodec};
51//! use sansio_transport::{TaggedBytesMut, TaggedString};
52//! use std::rc::Rc;
53//!
54//! let mut pipeline = RcPipeline::<TaggedBytesMut, TaggedString>::new();
55//! // ... add handlers ...
56//! pipeline.finalize();
57//! let pipeline = Rc::new(pipeline); // Now shareable
58//! ```
59//!
60//! ## Modules
61//!
62//! - [`byte_to_message_decoder`]: Frame decoders for parsing byte streams
63//! - [`string_codec`]: UTF-8 string encoding/decoding handlers
64//!
65//! ## Transport Context
66//!
67//! The transport module provides tagged message types that carry metadata:
68//!
69//! ```rust
70//! use sansio_transport::{TransportContext, TaggedBytesMut, TransportProtocol};
71//! use std::time::Instant;
72//! use bytes::BytesMut;
73//!
74//! let msg = TaggedBytesMut {
75//! now: Instant::now(),
76//! transport: TransportContext {
77//! local_addr: "127.0.0.1:8080".parse().unwrap(),
78//! peer_addr: "127.0.0.1:1234".parse().unwrap(),
79//! transport_protocol: TransportProtocol::TCP,
80//! ecn: None,
81//! },
82//! message: BytesMut::from("Hello"),
83//! };
84//! ```
85
86#![doc(
87 html_logo_url = "https://raw.githubusercontent.com/webrtc-rs/sansio/master/doc/sansio-white.png"
88)]
89#![warn(rust_2018_idioms)]
90#![warn(missing_docs)]
91
92/// Byte-to-message frame decoders for parsing delimited streams
93pub mod byte_to_message_decoder;
94
95/// UTF-8 string encoding/decoding handlers
96pub mod string_codec;
97
98// Re-export commonly used types
99pub use byte_to_message_decoder::{
100 LineBasedFrameDecoder, MessageDecoder, TaggedByteToMessageCodec, TerminatorType,
101};
102pub use string_codec::TaggedStringCodec;