Struct distant_net::common::FramedTransport

pub struct FramedTransport<T> {
    pub backup: Backup,
    /* private fields */
}

Represents a wrapper around a Transport that reads and writes using frames defined by a Codec.

Fields

backup: Backup

Stores outgoing frames in case of transmission issues

Implementations

impl<T> FramedTransport<T>

pub fn new(inner: T, codec: BoxedCodec) -> Self

pub fn plain(inner: T) -> Self

Creates a new FramedTransport using the PlainCodec

pub fn set_codec(&mut self, codec: BoxedCodec)

Replaces the current codec with the provided codec. Note that any bytes in the incoming or outgoing buffers will remain in the transport, meaning that this can cause corruption if the bytes in the buffers do not match the new codec.

For safety, use clear to wipe the buffers before further use.

pub fn codec(&self) -> &dyn Codec

Returns a reference to the codec used by the transport.

Note

Be careful when accessing the codec to avoid corrupting it through unexpected modifications as this will place the transport in an undefined state.

pub fn mut_codec(&mut self) -> &mut dyn Codec

Returns a mutable reference to the codec used by the transport.

Note

Be careful when accessing the codec to avoid corrupting it through unexpected modifications as this will place the transport in an undefined state.

pub fn clear(&mut self)

Clears the internal transport buffers.

pub fn as_inner(&self) -> &T

Returns a reference to the inner value this transport wraps.

pub fn as_mut_inner(&mut self) -> &mut T

Returns a mutable reference to the inner value this transport wraps.

pub fn into_inner(self) -> T

Consumes this transport, returning the inner value that it wraps.

impl<T: Transport + 'static> FramedTransport<T>

pub fn into_boxed(self) -> FramedTransport<Box<dyn Transport>>

Converts this instance to a FramedTransport whose inner Transport is Boxed.

impl<T: Transport> FramedTransport<T>

pub async fn ready(&self, interest: Interest) -> Result<Ready>

Waits for the transport to be ready based on the given interest, returning the ready status

pub async fn readable(&self) -> Result<()>

Waits for the transport to be readable to follow up with try_read_frame.

pub async fn writeable(&self) -> Result<()>

Waits for the transport to be writeable to follow up with try_write_frame.

pub async fn readable_or_writeable(&self) -> Result<Ready>

Waits for the transport to be readable or writeable, returning the Ready status.

pub fn try_flush(&mut self) -> Result<usize>

Attempts to flush any remaining bytes in the outgoing queue, returning the total bytes written as a result of the flush. Note that a return of 0 bytes does not indicate that the underlying transport has closed, but rather that no bytes were flushed such as when the outgoing queue is empty.

This is accomplished by continually calling the inner transport’s try_write. If 0 is returned from a call to try_write, this will fail with [ErrorKind::WriteZero].

This call may return an error with ErrorKind::WouldBlock in the case that the transport is not ready to write data.

pub async fn flush(&mut self) -> Result<()>

Flushes all buffered, outgoing bytes using repeated calls to try_flush.

pub fn try_read_frame(&mut self) -> Result<Option<OwnedFrame>>

Reads a frame of bytes by using the Codec tied to this transport. Returns Ok(Some(frame)) upon reading a frame, or Ok(None) if the underlying transport has closed.

This call may return an error with ErrorKind::WouldBlock in the case that the transport is not ready to read data or has not received a full frame before waiting.

pub fn try_read_frame_as<D: DeserializeOwned>(&mut self) -> Result<Option<D>>

Reads a frame using try_read_frame and then deserializes the bytes into D.

pub async fn read_frame(&mut self) -> Result<Option<OwnedFrame>>

Continues to invoke try_read_frame until a frame is successfully read, an error is encountered that is not ErrorKind::WouldBlock, or the underlying transport has closed.

pub async fn read_frame_as<D: DeserializeOwned>(&mut self) -> Result<Option<D>>

Reads a frame using read_frame and then deserializes the bytes into D.

pub fn try_write_frame<'a, F>(&mut self, frame: F) -> Result<()>where
    F: TryInto<Frame<'a>>,
    F::Error: Into<Box<dyn Error + Send + Sync>>,

Writes a frame of bytes by using the Codec tied to this transport.

This is accomplished by continually calling the inner transport’s try_write. If 0 is returned from a call to try_write, this will fail with ErrorKind::WriteZero.

This call may return an error with ErrorKind::WouldBlock in the case that the transport is not ready to write data or has not written the entire frame before waiting.

pub fn try_write_frame_for<D: Serialize>(&mut self, value: &D) -> Result<()>

Serializes value into bytes and passes them to try_write_frame.

pub async fn write_frame<'a, F>(&mut self, frame: F) -> Result<()>where
    F: TryInto<Frame<'a>>,
    F::Error: Into<Box<dyn Error + Send + Sync>>,

Invokes try_write_frame followed by a continuous calls to try_flush until a frame is successfully written, an error is encountered that is not ErrorKind::WouldBlock, or the underlying transport has closed.

pub async fn write_frame_for<D: Serialize>(&mut self, value: &D) -> Result<()>

Serializes value into bytes and passes them to write_frame.

pub async fn do_frozen<F, X>(&mut self, f: F) -> Result<()>where
    F: FnMut(&mut Self) -> X,
    X: Future<Output = Result<()>>,

Executes the async function while the Backup of this transport is frozen.

pub async fn synchronize(&mut self) -> Result<()>

Places the transport in synchronize mode where it communicates with the other side how many frames have been sent and received. From there, any frames not received by the other side are sent again and then this transport waits for any missing frames that it did not receive from the other side.

Note

This will clear the internal incoming and outgoing buffers, so any frame that was in transit in either direction will be dropped.

pub async fn from_client_handshake(transport: T) -> Result<Self>

Shorthand for creating a FramedTransport with a PlainCodec and then immediately performing a client_handshake, returning the updated FramedTransport on success.

pub async fn client_handshake(&mut self) -> Result<()>

Perform the client-side of a handshake. See handshake for more details.

pub async fn from_server_handshake(transport: T) -> Result<Self>

Shorthand for creating a FramedTransport with a PlainCodec and then immediately performing a [server_handshake], returning the updated FramedTransport on success.

pub async fn server_handshake(&mut self) -> Result<()>

Perform the server-side of a handshake. See handshake for more details.

pub async fn handshake(&mut self, handshake: Handshake) -> Result<()>

Performs a handshake in order to establish a new codec to use between this transport and the other side. The parameter handshake defines how the transport will handle the handshake with Client being used to pick the compression and encryption used while Server defines what the choices are for compression and encryption.

This will reset the framed transport’s codec to PlainCodec in order to communicate which compression and encryption to use. Upon selecting an encryption type, a shared secret key will be derived on both sides and used to establish the EncryptionCodec, which in combination with the CompressionCodec (if any) will replace this transport’s codec.

Client

1. Wait for options from server
2. Send to server a compression and encryption choice
3. Configure framed transport using selected choices
4. Invoke on_handshake function

Server

1. Send options to client
2. Receive choices from client
3. Configure framed transport using client’s choices
4. Invoke on_handshake function

Failure

The handshake will fail in several cases:

• If any frame during the handshake fails to be serialized
• If any unexpected frame is received during the handshake
• If using encryption and unable to derive a shared secret key

If a failure happens, the codec will be reset to what it was prior to the handshake request, and all internal buffers will be cleared to avoid corruption.

pub async fn exchange_keys(&mut self) -> Result<SecretKey32>

Places the transport into key-exchange mode where it attempts to derive a shared secret key with the other transport.

impl FramedTransport<InmemoryTransport>

pub fn pair(
    buffer: usize
) -> (FramedTransport<InmemoryTransport>, FramedTransport<InmemoryTransport>)

Produces a pair of inmemory transports that are connected to each other using a PlainCodec.

Sets the buffer for message passing for each underlying transport to the given buffer size.

pub fn link(&mut self, other: &mut Self, buffer: usize)

Links the underlying transports together using InmemoryTransport::link.

Trait Implementations

impl<T> Authenticate for FramedTransport<T>where
    T: Transport,

fn authenticate<'life0, 'async_trait>(
    &'life0 mut self,
    handler: impl 'async_trait + AuthHandler + Send
) -> Pin<Box<dyn Future<Output = Result<()>> + Send + 'async_trait>>where
    'life0: 'async_trait,
    Self: 'async_trait,

Performs authentication by leveraging the handler for any received challenge.

impl<T> Authenticator for FramedTransport<T>where
    T: Transport,

fn initialize<'life0, 'async_trait>(
    &'life0 mut self,
    initialization: Initialization
) -> Pin<Box<dyn Future<Output = Result<InitializationResponse>> + Send + 'async_trait>>where
    'life0: 'async_trait,
    Self: 'async_trait,

Issues an initialization notice and returns the response indicating which authentication methods to pursue

fn challenge<'life0, 'async_trait>(
    &'life0 mut self,
    challenge: Challenge
) -> Pin<Box<dyn Future<Output = Result<ChallengeResponse>> + Send + 'async_trait>>where
    'life0: 'async_trait,
    Self: 'async_trait,

Issues a challenge and returns the answers to the questions asked.

fn verify<'life0, 'async_trait>(
    &'life0 mut self,
    verification: Verification
) -> Pin<Box<dyn Future<Output = Result<VerificationResponse>> + Send + 'async_trait>>where
    'life0: 'async_trait,
    Self: 'async_trait,

Requests verification of some kind and text, returning true if passed verification.

fn info<'life0, 'async_trait>(
    &'life0 mut self,
    info: Info
) -> Pin<Box<dyn Future<Output = Result<()>> + Send + 'async_trait>>where
    'life0: 'async_trait,
    Self: 'async_trait,

Reports information with no response expected.

fn error<'life0, 'async_trait>(
    &'life0 mut self,
    error: Error
) -> Pin<Box<dyn Future<Output = Result<()>> + Send + 'async_trait>>where
    'life0: 'async_trait,
    Self: 'async_trait,

Reports an error occurred during authentication, consuming the authenticator since no more challenges should be issued.

fn start_method<'life0, 'async_trait>(
    &'life0 mut self,
    start_method: StartMethod
) -> Pin<Box<dyn Future<Output = Result<()>> + Send + 'async_trait>>where
    'life0: 'async_trait,
    Self: 'async_trait,

Reports that the authentication has started for a specific method.

fn finished<'life0, 'async_trait>(
    &'life0 mut self
) -> Pin<Box<dyn Future<Output = Result<()>> + Send + 'async_trait>>where
    'life0: 'async_trait,
    Self: 'async_trait,

Reports that the authentication has finished successfully, consuming the authenticator since no more challenges should be issued.

impl<T: Clone> Clone for FramedTransport<T>

fn clone(&self) -> FramedTransport<T>

Returns a copy of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl<T> Debug for FramedTransport<T>

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl<T> Reconnectable for FramedTransport<T>where
    T: Transport,

fn reconnect<'life0, 'async_trait>(
    &'life0 mut self
) -> Pin<Box<dyn Future<Output = Result<()>> + Send + 'async_trait>>where
    'life0: 'async_trait,
    Self: 'async_trait,

Attempts to reconnect an already-established connection.