Struct OvpnCodec 

pub struct OvpnCodec { /* private fields */ }

Tokio codec for the OpenVPN management interface.

The encoder serializes typed OvpnCommand values into correct wire-format bytes, including proper escaping and multi-line block framing.

The decoder performs the opposite operation. It uses command-tracking state to correctly distinguish single-line from multi-line responses, and accumulates multi-line >CLIENT: notifications into a single OvpnMessage before emitting them.

Sequential usage and pipelining

The OpenVPN management protocol is strictly sequential: the server processes one command at a time and sends its response before reading the next command. The codec maintains a queue of expected response kinds — one per encoded command. This allows callers to pipeline multiple commands (encode A, then B, then C) without waiting for each response, as long as responses arrive in the same order. Outgoing bytes are not buffered by the codec itself — the Encoder implementation writes into the BytesMut that tokio_util::codec::Framed owns, and Framed flushes them to the socket.

Encoding while a multi-line response or >CLIENT: notification is being accumulated is still discouraged (and logged as a warning), because it means the caller is not draining the stream (emptying the read half of the codec).

Notification interleaving

Real-time notifications (>STATE:, >LOG:, >BYTECOUNT:, etc.) can arrive at any time, including in the middle of a multi-line command response. The decoder emits these immediately as OvpnMessage::Notification without disrupting the ongoing accumulation. The completed multi-line response is emitted afterward with the interleaved notification lines excluded.

Consumers should always be prepared to handle Notification variants between sending a command and receiving its response.

Implementations

impl OvpnCodec

pub fn new() -> Self

Create a new codec with default state, ready to encode commands and decode responses.

pub fn with_max_multi_line_lines(self, limit: AccumulationLimit) -> Self

Set the maximum number of lines accumulated in a multi-line response before the decoder returns an error.

pub fn with_max_client_env_entries(self, limit: AccumulationLimit) -> Self

Set the maximum number of ENV entries accumulated for >CLIENT: notifications before the decoder returns an error.

pub fn with_encoder_mode(self, mode: EncoderMode) -> Self

Set the encoder mode for handling unsafe characters in user-supplied strings.

The default is EncoderMode::Sanitize, which silently strips \n, \r, and \0. Use EncoderMode::Strict to reject inputs containing those characters with an error instead.

Trait Implementations

impl Decoder for OvpnCodec

type Item = OvpnMessage

The type of decoded frames.

type Error = Error

The type of unrecoverable frame decoding errors.

fn decode( &mut self, src: &mut BytesMut, ) -> Result<Option<Self::Item>, Self::Error>

Attempts to decode a frame from the provided buffer of bytes.

fn decode_eof( &mut self, buf: &mut BytesMut, ) -> Result<Option<Self::Item>, Self::Error>

A default method available to be called when there are no more bytes available to be read from the underlying I/O.

fn framed<T>(self, io: T) -> Framed<T, Self>

where T: AsyncRead + AsyncWrite, Self: Sized,

Provides a Stream and Sink interface for reading and writing to this Io object, using Decode and Encode to read and write the raw data.

impl Default for OvpnCodec

fn default() -> Self

Returns the “default value” for a type.

impl Encoder<OvpnCommand> for OvpnCodec

type Error = Error

The type of encoding errors.

fn encode( &mut self, item: OvpnCommand, dst: &mut BytesMut, ) -> Result<(), Self::Error>

Encodes a frame into the buffer provided.