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//! - [`transport`]: Transport context and tagged message types
52//!
53//! ## Transport Context
54//!
55//! The transport module provides tagged message types that carry metadata:
56//!
57//! ```rust
58//! use sansio_transport::{TransportContext, TaggedBytesMut, TransportProtocol};
59//! use std::time::Instant;
60//! use bytes::BytesMut;
61//!
62//! let msg = TaggedBytesMut {
63//! now: Instant::now(),
64//! transport: TransportContext {
65//! local_addr: "127.0.0.1:8080".parse().unwrap(),
66//! peer_addr: "127.0.0.1:1234".parse().unwrap(),
67//! transport_protocol: TransportProtocol::TCP,
68//! ecn: None,
69//! },
70//! message: BytesMut::from("Hello"),
71//! };
72//! ```
73
74#![doc(
75 html_logo_url = "https://raw.githubusercontent.com/sansio-org/sansio/master/doc/sansio-white.png"
76)]
77#![warn(rust_2018_idioms)]
78#![warn(missing_docs)]
79
80/// Byte-to-message frame decoders for parsing delimited streams
81pub mod byte_to_message_decoder;
82
83/// UTF-8 string encoding/decoding handlers
84pub mod string_codec;
85
86// Re-export commonly used types
87pub use byte_to_message_decoder::{
88 LineBasedFrameDecoder, MessageDecoder, TaggedByteToMessageCodec, TerminatorType,
89};
90pub use string_codec::TaggedStringCodec;