Struct Stream 

pub struct Stream<S: AsFd, C: TlsSession> { /* private fields */ }

A thin wrapper around a kTLS offloaded socket.

This implements Read and Write, AsyncRead and AsyncWrite (when feature async-io-tokio is enabled).

Behaviours

Once receives a close_notify alert from the peer, all subsequent read operations will return EOF (unless the inner buffer contains unread data); once the caller explicitly calls (poll_)shutdown on the stream, a close_notify alert would be sent to the peer and all subsequent write operations will return 0 bytes, indicating that the stream is closed for writing. When the Stream is dropped, it will also perform graceful shutdown automatically.

For TLS 1.2, once one party sends a close_notify alert, the other party MUST respond with a close_notify alert of its own and close down the connection immediately, according to RFC 5246, section 7.2.1; for TLS 1.3, both parties need not wait to receive a “close_notify” alert before closing their read side of the connection, according to RFC 8446, section 6.1.

Implementations

impl<S: AsFd, C: TlsSession> Stream<S, C>

pub fn new<K, E>( socket: S, secrets: K, session: C, buffer: Option<Buffer>, ) -> Result<Self, Error>

where ExtractedSecrets: TryFrom<K, Error = E>, Error: From<E>,

Constructs a new Stream from the provided socket, extracted TLS secrets and TLS session context. An optional buffer may be provided for early data received during handshake.

Prerequisites

The socket must have TLS ULP configured with setup_ulp.

Errors

Unsupported protocol version or cipher suite, or failure to set up kTLS params on the socket.

pub fn as_mut_raw( &mut self, ) -> Result<RawStreamMut<'_, S, C>, AccessRawStreamError>

Returns a RawStreamMut which provides low-level access to the inner socket.

This requires a mutable reference to the Stream to ensure a exclusive access to the inner socket.

Notes

• All buffered data MUST be properly consumed (See AccessRawStreamError::HasBufferedData).

  The buffered data typically consists of:

  • Early data received during handshake.
  • Application data received due to improper usage of RawStreamMut::handle_io_error.

• The caller MAY handle any io::Errors returned by direct I/O operations on the inner socket with RawStreamMut::handle_io_error.

• The caller MUST NOT shutdown the inner socket directly, which will lead to undefined behaviours.

Errors

See AccessRawStreamError.

pub fn refresh_traffic_keys(&mut self) -> Result<(), Error>

Context::refresh_traffic_keys against the inner socket.

Use with caution, and do check Context::refresh_traffic_keys for details.

Errors

See Context::refresh_traffic_keys.

impl<S> Stream<S, DummyTlsSession>

where S: AsFd,

pub fn new_dummy( socket: S, secrets: ExtractedSecrets, session: DummyTlsSession, buffer: Option<Buffer>, ) -> Result<Self, Error>

Creates a new Stream with a DummyTlsSession.

This doesn’t require the socket to have TLS ULP configured, we will configure it here.

See also Stream::new.

Errors

See Stream::new.

impl<C> Stream<TcpStream, C>

where C: TlsSession,

pub fn shutdown(&mut self)

Shuts down both read and write sides of the TLS stream.

impl<C> Stream<UnixStream, C>

where C: TlsSession,

pub fn shutdown(&mut self)

Shuts down both read and write sides of the TLS stream.

Trait Implementations

impl<S, C> AsyncRead for Stream<S, C>

where S: AsFd + AsyncRead, C: TlsSession,

Available on crate feature async-io-tokio only.

fn poll_read( self: Pin<&mut Self>, cx: &mut Context<'_>, buf: &mut ReadBuf<'_>, ) -> Poll<Result<()>>

Attempts to read from the AsyncRead into buf.

impl<S, C> AsyncWrite for Stream<S, C>

where S: AsFd + AsyncWrite, C: TlsSession,

Available on crate feature async-io-tokio only.

fn poll_write( self: Pin<&mut Self>, cx: &mut Context<'_>, buf: &[u8], ) -> Poll<Result<usize>>

Attempt to write bytes from buf into the object.

fn poll_flush(self: Pin<&mut Self>, cx: &mut Context<'_>) -> Poll<Result<()>>

Attempts to flush the object, ensuring that any buffered data reach their destination.

fn poll_shutdown(self: Pin<&mut Self>, cx: &mut Context<'_>) -> Poll<Result<()>>

Initiates or attempts to shut down this writer, returning success when the I/O connection has completely shut down.

fn poll_write_vectored( self: Pin<&mut Self>, cx: &mut Context<'_>, bufs: &[IoSlice<'_>], ) -> Poll<Result<usize, Error>>

Like poll_write, except that it writes from a slice of buffers.

fn is_write_vectored(&self) -> bool

Determines if this writer has an efficient poll_write_vectored implementation.

impl<S: Debug + AsFd, C: Debug + TlsSession> Debug for Stream<S, C>

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

Formats the value using the given formatter.

impl<S: AsFd, C: TlsSession> Drop for Stream<S, C>

fn drop(&mut self)

Executes the destructor for this type.

impl<S, C> Read for Stream<S, C>

where S: AsFd + Read, C: TlsSession,

fn read(&mut self, buf: &mut [u8]) -> Result<usize>

Pull some bytes from this source into the specified buffer, returning how many bytes were read.

fn read_vectored(&mut self, bufs: &mut [IoSliceMut<'_>]) -> Result<usize, Error>

Like read, except that it reads into a slice of buffers.

fn is_read_vectored(&self) -> bool

🔬This is a nightly-only experimental API. (can_vector)

Determines if this Reader has an efficient read_vectored implementation.

fn read_to_end(&mut self, buf: &mut Vec<u8>) -> Result<usize, Error>

Reads all bytes until EOF in this source, placing them into buf.

fn read_to_string(&mut self, buf: &mut String) -> Result<usize, Error>

Reads all bytes until EOF in this source, appending them to buf.

fn read_exact(&mut self, buf: &mut [u8]) -> Result<(), Error>

Reads the exact number of bytes required to fill buf.

fn read_buf(&mut self, buf: BorrowedCursor<'_>) -> Result<(), Error>

🔬This is a nightly-only experimental API. (read_buf)

Pull some bytes from this source into the specified buffer.

fn read_buf_exact(&mut self, cursor: BorrowedCursor<'_>) -> Result<(), Error>

🔬This is a nightly-only experimental API. (read_buf)

Reads the exact number of bytes required to fill cursor.

fn by_ref(&mut self) -> &mut Self

where Self: Sized,

Creates a “by reference” adapter for this instance of Read.

fn bytes(self) -> Bytes<Self>

where Self: Sized,

Transforms this Read instance to an Iterator over its bytes.

fn chain<R>(self, next: R) -> Chain<Self, R>

where R: Read, Self: Sized,

Creates an adapter which will chain this stream with another.

fn take(self, limit: u64) -> Take<Self>

where Self: Sized,

Creates an adapter which will read at most limit bytes from it.

impl<S, C> Write for Stream<S, C>

where S: AsFd + Write, C: TlsSession,

fn write(&mut self, buf: &[u8]) -> Result<usize>

Writes a buffer into this writer, returning how many bytes were written.

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

Flushes this output stream, ensuring that all intermediately buffered contents reach their destination.

fn write_vectored(&mut self, bufs: &[IoSlice<'_>]) -> Result<usize, Error>

Like write, except that it writes from a slice of buffers.

fn is_write_vectored(&self) -> bool

🔬This is a nightly-only experimental API. (can_vector)

Determines if this Writer has an efficient write_vectored implementation.

fn write_all(&mut self, buf: &[u8]) -> Result<(), Error>

Attempts to write an entire buffer into this writer.

fn write_all_vectored(&mut self, bufs: &mut [IoSlice<'_>]) -> Result<(), Error>

🔬This is a nightly-only experimental API. (write_all_vectored)

Attempts to write multiple buffers into this writer.

fn write_fmt(&mut self, args: Arguments<'_>) -> Result<(), Error>

Writes a formatted string into this writer, returning any error encountered.

fn by_ref(&mut self) -> &mut Self

where Self: Sized,

Creates a “by reference” adapter for this instance of Write.

impl<'__pin, S: AsFd, C: TlsSession> Unpin for Stream<S, C>

where PinnedFieldsOf<__Origin<'__pin, S, C>>: Unpin,