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, TaggedBytesMut, TaggedString
26//! };
27//! use std::rc::Rc;
28//!
29//! let pipeline = Rc::new(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.update();
44//! ```
45//!
46//! ## Modules
47//!
48//! - [`byte_to_message_decoder`]: Frame decoders for parsing byte streams
49//! - [`string_codec`]: UTF-8 string encoding/decoding handlers
50//! - [`transport`]: Transport context and tagged message types
51//!
52//! ## Transport Context
53//!
54//! The transport module provides tagged message types that carry metadata:
55//!
56//! ```rust
57//! use sansio_codec::{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/// Transport context and tagged message types
86pub mod transport;
87
88// Re-export commonly used types
89pub use byte_to_message_decoder::{
90 LineBasedFrameDecoder, MessageDecoder, TaggedByteToMessageCodec, TerminatorType,
91};
92pub use string_codec::TaggedStringCodec;
93pub use transport::{
94 EcnCodepoint, FiveTuple, FourTuple, TaggedBytesMut, TaggedString, Transmit, TransportContext,
95 TransportProtocol,
96};