titan_api_codec/codec/
mod.rs

1//! Defines codecs for encoding and decoding messages for versions of the Titan API with optional
2//! compression and possibly other options.
3
4use std::marker::PhantomData;
5
6use crate::{
7    dec::{DecodeError, Decoder},
8    enc::{EncodeError, Encoder},
9};
10
11use bytes::Bytes;
12use serde::de::DeserializeOwned;
13use serde::Serialize;
14use thiserror::Error;
15
16pub mod ws;
17
18/// Errors that can occur while attempting to load a codec.
19#[derive(Debug, Error, PartialEq, Eq)]
20pub enum CodecLoadError {
21    /// Protocol is unsupported.
22    ///
23    /// Normally wil be caused by the client requesting a different version than the server
24    /// supports.
25    #[error("Unsupported protocol {0}")]
26    UnsupportedProtocol(String),
27    /// Requested protocol and encoding is valid, but the encoding method is disabled.
28    #[error("Requested encoding method enabled")]
29    DisabledEncoding(&'static str),
30}
31
32/// An encoder that encodes a specific type of message.
33pub trait TypedEncoder<T> {
34    /// Type of error returned by this encoder if encoding fails.
35    type Error;
36
37    /// Encode the given value to binary.
38    fn encode(&self, value: &T) -> Result<Bytes, Self::Error>;
39    /// Encode the given value to binary, mutating the encoder if doing so provides a benefit.
40    fn encode_mut(&mut self, value: &T) -> Result<Bytes, Self::Error>;
41}
42
43/// A decoder that decodes a specific type of message.
44pub trait TypedDecoder {
45    /// The type of messages this Decoder decodes.
46    type Item;
47    /// Type of error returned by this decoder if decoding fails.
48    type Error;
49
50    /// Attempt to decode the given data into a value.
51    fn decode(&self, data: Bytes) -> Result<Self::Item, Self::Error>;
52    /// Attempt to decode the given data into a value, mutating the decoder's state if doing so
53    /// provides a benefit.
54    fn decode_mut(&mut self, data: Bytes) -> Result<Self::Item, Self::Error>;
55}
56
57/// Represents a specific encoding and decoding scheme for one side of a connection.
58///
59/// The codec defines what messages the user is spected to send to the other side, as well as the
60/// messages that are expected to be received from the other side.
61///
62/// The encoders and decoders generated by the Codec handle any optional transformations, such as
63/// compression, as configured during protocol negotiation.
64pub trait Codec {
65    /// The type of message that is sent to the other side.
66    type SendItem;
67    /// The type of error that is returned if encoding fails.
68    type SendError;
69    /// The type of message that is expected to be received from the other side.
70    type RecvItem;
71    /// The type of error that is returned if decoding fails.
72    type RecvError;
73
74    /// Generates a new encoder for encoding messages to be sent to the other side of the
75    /// connection.
76    fn encoder(
77        &self,
78    ) -> Box<dyn TypedEncoder<Self::SendItem, Error = Self::SendError> + Send + Sync>;
79    /// Generates a new decoder for encoding messages to be sent to the other side of the
80    /// connection.
81    fn decoder(
82        &self,
83    ) -> Box<dyn TypedDecoder<Item = Self::RecvItem, Error = Self::RecvError> + Send + Sync>;
84}
85
86/// Wraps an [`Encoder`], restricting thet type of message that can be encoded.
87pub struct WrappedEncoder<T, E> {
88    encoder: E,
89    _tag: PhantomData<T>,
90}
91
92impl<T, E> WrappedEncoder<T, E>
93where
94    T: Serialize,
95    E: Encoder,
96{
97    /// Creates a new [`WrappedEncoder`] using the given [`Encoder`].
98    ///
99    /// The new encoder is a [`TypedEncoder`] that only encodes values of type `T`.
100    pub fn new(encoder: E) -> Self {
101        Self {
102            encoder,
103            _tag: PhantomData,
104        }
105    }
106}
107
108impl<T, E> TypedEncoder<T> for WrappedEncoder<T, E>
109where
110    T: Serialize,
111    E: Encoder,
112{
113    type Error = EncodeError;
114
115    #[inline]
116    fn encode(&self, value: &T) -> Result<Bytes, Self::Error> {
117        self.encoder.encode(value)
118    }
119
120    #[inline]
121    fn encode_mut(&mut self, value: &T) -> Result<Bytes, Self::Error> {
122        self.encoder.encode_mut(value)
123    }
124}
125
126/// Wraps a [`Decoder`], attempting to decode a specific message type from provided data.
127pub struct WrappedDecoder<T, D> {
128    decoder: D,
129    _tag: PhantomData<T>,
130}
131
132impl<T, E> WrappedDecoder<T, E>
133where
134    T: Serialize,
135    E: Decoder,
136{
137    /// Creates a new [`WrappedDecoder`] using the given [`Decoder`].
138    ///
139    /// The new decoder is a [`TypedDecoder`] that attempts to decode values of type `T` from
140    /// provided data.
141    pub fn new(decoder: E) -> Self {
142        Self {
143            decoder,
144            _tag: PhantomData,
145        }
146    }
147}
148
149impl<T, D> TypedDecoder for WrappedDecoder<T, D>
150where
151    T: DeserializeOwned,
152    D: Decoder,
153{
154    type Item = T;
155    type Error = DecodeError;
156
157    #[inline]
158    fn decode(&self, data: Bytes) -> Result<Self::Item, Self::Error> {
159        self.decoder.decode(data)
160    }
161
162    #[inline]
163    fn decode_mut(&mut self, data: Bytes) -> Result<Self::Item, Self::Error> {
164        self.decoder.decode_mut(data)
165    }
166}
titan_api_codec/codec/mod.rs

titan_api_codec/codec/
mod.rs
