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//! use std::rc::Rc;
29//!
30//! let pipeline = Rc::new(Pipeline::<TaggedBytesMut, TaggedString>::new());
31//!
32//! // Add line-based frame decoder
33//! let frame_decoder = TaggedByteToMessageCodec::new(Box::new(
34//! LineBasedFrameDecoder::new(8192, true, TerminatorType::BOTH)
35//! ));
36//! pipeline.add_back(frame_decoder);
37//!
38//! // Add string codec
39//! pipeline.add_back(TaggedStringCodec::new());
40//!
41//! // Add your business logic handler
42//! // pipeline.add_back(your_handler);
43//!
44//! pipeline.update();
45//! ```
46//!
47//! ## Modules
48//!
49//! - [`byte_to_message_decoder`]: Frame decoders for parsing byte streams
50//! - [`string_codec`]: UTF-8 string encoding/decoding handlers
51//!
52//! ## Transport Context
53//!
54//! The transport module provides tagged message types that carry metadata:
55//!
56//! ```rust
57//! use sansio_transport::{TransportContext, TaggedBytesMut, TransportProtocol};
58//! use std::time::Instant;
59//! use bytes::BytesMut;
60//!
61//! let msg = TaggedBytesMut {
62//! now: Instant::now(),
63//! transport: TransportContext {
64//! local_addr: "127.0.0.1:8080".parse().unwrap(),
65//! peer_addr: "127.0.0.1:1234".parse().unwrap(),
66//! transport_protocol: TransportProtocol::TCP,
67//! ecn: None,
68//! },
69//! message: BytesMut::from("Hello"),
70//! };
71//! ```
72
73#![doc(
74 html_logo_url = "https://raw.githubusercontent.com/sansio-org/sansio/master/doc/sansio-white.png"
75)]
76#![warn(rust_2018_idioms)]
77#![warn(missing_docs)]
78
79/// Byte-to-message frame decoders for parsing delimited streams
80pub mod byte_to_message_decoder;
81
82/// UTF-8 string encoding/decoding handlers
83pub mod string_codec;
84
85// Re-export commonly used types
86pub use byte_to_message_decoder::{
87 LineBasedFrameDecoder, MessageDecoder, TaggedByteToMessageCodec, TerminatorType,
88};
89pub use string_codec::TaggedStringCodec;