rusty_tpkt/
api.rs

1use std::{any::Any, collections::VecDeque, fmt::Debug};
2
3use dyn_clone::DynClone;
4use thiserror::Error;
5
6#[derive(Error, Debug)]
7pub enum TpktError {
8    /// Indicates issues with parsing of incoming packets or protocol violations with input user data.
9    #[error("TPKT Protocol Error - {}", .0)]
10    ProtocolError(String),
11
12    /// Indicates issues with the underlying TCP socket or hardware.
13    #[error("TPKT IO Error: {:?}", .0)]
14    IoError(#[from] std::io::Error),
15
16    /// Usually indicates a bug or an unhandled error condition.
17    #[error("TPKT Error: {}", .0)]
18    InternalError(String),
19}
20
21/// Information regarding the protocol stack. This is useful for authentication and logging.
22pub trait ProtocolInformation: Any + Send + Debug + DynClone {}
23
24dyn_clone::clone_trait_object!(ProtocolInformation);
25
26/// A trait representing a TPKT connection. There is no distinction between a client and a server connection once they are established.
27pub trait TpktConnection: Send {
28    /// Gets the information regarding the protocols that have been negotiated during the connect phase.
29    fn get_protocol_infomation_list(&self) -> &Vec<Box<dyn ProtocolInformation>>;
30
31    /// Splits a connection into reader and writer components. This must be done before the connection is used.
32    fn split(self) -> impl std::future::Future<Output = Result<(impl TpktReader, impl TpktWriter), TpktError>> + Send;
33}
34
35/// A trait representing the read half of TPKT connection.
36pub trait TpktReader: Send {
37    /// Reads from a TPKT connection. There are three outcomes.
38    /// * Some(data) - Data was read.
39    /// * None - The underlying connection was closed normally.
40    /// * TpktError - May indicate a packet was malformed, there was an IO error or some other internal failure occurred. The stream should be discarded.
41    ///
42    /// This operation is cancel safe.
43    fn recv(&mut self) -> impl std::future::Future<Output = Result<Option<Vec<u8>>, TpktError>> + Send;
44}
45
46/// A trait representing the write half of TPKT connection.
47pub trait TpktWriter: Send {
48    /// Writes to a TPKT connection. This uses a VedDeque as a buffer. This is to ensure the operation is cancel safe so long as the buffer is not dropped while it has data.
49    ///
50    /// This operation is cancel safe as long as the data in the input buffer is not dropped.
51    /// The VecDeque is intended to be used as a FIFO buffer stored on the caller and reused.
52    ///
53    /// On Error the stream should be discarded.
54    fn send(&mut self, input: &mut VecDeque<Vec<u8>>) -> impl std::future::Future<Output = Result<(), TpktError>> + Send;
55}
rusty_tpkt/api.rs

rusty_tpkt/
api.rs
