Struct FrameCodec 

pub struct FrameCodec { /* private fields */ }

Encodes and decodes WSCALL binary frames (protocol v3).

Protocol v3 uses a composite payload format: JSON metadata followed by raw binary attachment sections, eliminating the Base64 overhead of protocol v1. The frame header is 5 bytes (frame_len:u32 | message_type:u8); the per-frame encryption byte present in protocol v2 has been removed in favour of connection-level encryption (wire_encryption).

The encryption mode is a connection-level property stored in the codec (wire_encryption). It is determined once at connection setup (PSK config or ECDH handshake) and applies to every frame on that connection; the frame header no longer carries a per-frame encryption byte.

The symmetric ciphers are constructed once when a key is configured and shared via Arc across every clone of the codec. This avoids redoing the key schedule (which for AES-256-GCM is especially expensive) on every frame.

Implementations

impl FrameCodec

pub fn plaintext() -> Self

Builds a codec configured for plaintext transport.

pub fn with_chacha20_key(self, key: [u8; 32]) -> Self

Configures a ChaCha20-Poly1305 key.

The cipher is constructed eagerly so that subsequent frame encoding never pays for the key schedule again. Also sets wire_encryption to EncryptionKind::ChaCha20.

pub fn with_aes256_key(self, key: [u8; 32]) -> Self

Configures an AES256-GCM key.

The cipher is constructed eagerly so that subsequent frame encoding never pays for the AES key expansion again. Also sets wire_encryption to EncryptionKind::Aes256.

pub fn wire_encryption(&self) -> EncryptionKind

Returns the connection-level encryption mode used by this codec.

pub fn with_max_frame_bytes(self, max: usize) -> Self

Sets the maximum total frame size (including the 4-byte length prefix).

Frames exceeding this limit are rejected during encode/decode.

pub fn max_frame_bytes(&self) -> usize

Returns the configured maximum frame size.

pub fn encode(&self, packet: &PacketEnvelope) -> Result<Vec<u8>, ProtocolError>

Encodes an envelope into a binary WSCALL frame (protocol v3 composite format).

Frame layout: frame_len:u32 | message_type:u8 | payload

The composite payload layout (before encryption):

| meta_len:u32(be) | JSON_bytes | att_count:u8 | [att sections...] |

The encryption mode is taken from self.wire_encryption (connection-level), not from packet.encryption.

pub fn decode(&self, frame: Bytes) -> Result<PacketEnvelope, ProtocolError>

Decodes a binary WSCALL frame back into an envelope (protocol v3 composite format).

Frame layout: frame_len:u32 | message_type:u8 | payload

The encryption mode is taken from self.wire_encryption (connection-level).

Accepts Bytes so that plaintext attachment payloads can be extracted via zero-copy slicing of the original buffer (no intermediate Vec).

Trait Implementations

impl Clone for FrameCodec

fn clone(&self) -> FrameCodec

Returns a duplicate of the value.

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

Performs copy-assignment from source.

impl Debug for FrameCodec

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

Formats the value using the given formatter.

impl Default for FrameCodec

fn default() -> Self

Returns the “default value” for a type.