Struct FrameWriter 

pub struct FrameWriter { /* private fields */ }

WebSocket frame encoder.

Encodes messages into RFC 6455 wire format. If the role is Client, frames are masked with a random 4-byte key. If Server, no masking.

Usage

use nexus_net::ws::{FrameWriter, Role};

let mut writer = FrameWriter::new(Role::Server);
let mut dst = vec![0u8; writer.max_encoded_len(5)];
let n = writer.encode_text(b"Hello", &mut dst);
assert_eq!(&dst[..n], &[0x81, 0x05, 0x48, 0x65, 0x6C, 0x6C, 0x6F]);

Implementations

impl FrameWriter

pub fn new(role: Role) -> FrameWriter

Create a writer for the given role.

pub fn encode_text(&mut self, payload: &[u8], dst: &mut [u8]) -> usize

Encode a text message frame. Returns bytes written.

Panics

Panics if dst is too small. Use max_encoded_len.

pub fn encode_binary(&mut self, payload: &[u8], dst: &mut [u8]) -> usize

Encode a binary message frame. Returns bytes written.

pub fn encode_ping( &mut self, payload: &[u8], dst: &mut [u8], ) -> Result<usize, EncodeError>

Encode a ping control frame. Returns bytes written.

Returns Err if payload exceeds 125 bytes (RFC 6455 §5.5).

pub fn encode_pong( &mut self, payload: &[u8], dst: &mut [u8], ) -> Result<usize, EncodeError>

Encode a pong control frame. Returns bytes written.

Returns Err if payload exceeds 125 bytes (RFC 6455 §5.5).

pub fn encode_close( &mut self, code: u16, reason: &[u8], dst: &mut [u8], ) -> Result<usize, EncodeError>

Encode a close frame. Returns bytes written.

Returns Err if code + reason exceeds 125 bytes.

pub fn max_encoded_len(&self, payload_len: usize) -> usize

Maximum encoded size for a given payload length. Accounts for header (2-10 bytes) + optional mask (4 bytes).

pub fn encode_empty_close(&mut self, dst: &mut [u8]) -> usize

Encode an empty close frame (no status code on the wire).

Used when CloseCode::NoStatus is intended — RFC 6455 §7.4.1 reserves code 1005 from appearing in close frame payloads.

pub fn encode_close_code( &mut self, code: CloseCode, reason: &str, dst: &mut [u8], ) -> Result<usize, EncodeError>

Encode a close frame with structured CloseCode and UTF-8 reason.

Panics

Panics if code is CloseCode::NoStatus (RFC 6455 reserves 1005 from appearing on the wire — use encode_empty_close). Panics if 2 + reason.len() exceeds 125 bytes.

pub fn build_header( &mut self, byte0: u8, payload_len: usize, ) -> (FrameHeader, Option<[u8; 4]>)

Build just the frame header. Returns (header_bytes, length, optional mask_key).

For use with WriteBuf: append payload, apply mask if Some, prepend header.

pub fn encode_text_into(&mut self, payload: &[u8], dst: &mut WriteBuf)

Encode a complete frame into a WriteBuf.

Clears the WriteBuf, appends payload, applies mask if client, prepends header. Result: contiguous [header | masked_payload].

pub fn encode_binary_into(&mut self, payload: &[u8], dst: &mut WriteBuf)

Encode a binary frame into a WriteBuf.

pub fn encode_ping_into( &mut self, payload: &[u8], dst: &mut WriteBuf, ) -> Result<(), EncodeError>

Encode a ping frame into a WriteBuf.

pub fn encode_pong_into( &mut self, payload: &[u8], dst: &mut WriteBuf, ) -> Result<(), EncodeError>

Encode a pong frame into a WriteBuf.

pub fn encode_close_into( &mut self, code: u16, reason: &[u8], dst: &mut WriteBuf, ) -> Result<(), EncodeError>

Encode a close frame into a WriteBuf.

pub fn encode_text_writer<F, E>( &mut self, dst: &mut WriteBuf, f: F, ) -> Result<(), E>

where F: FnOnce(&mut WriteBufWriter<'_>) -> Result<(), E>,

Encode a text frame, writing the payload via a closure.

The closure writes directly into the WriteBuf — no intermediate allocation. The WS frame header (including payload length) is prepended after the closure returns.

writer.encode_text_writer(&mut wbuf, |w| {
    use std::io::Write;
    serde_json::to_writer(w, &msg)
})?;

pub fn encode_binary_writer<F, E>( &mut self, dst: &mut WriteBuf, f: F, ) -> Result<(), E>

where F: FnOnce(&mut WriteBufWriter<'_>) -> Result<(), E>,

Encode a binary frame, writing the payload via a closure.

pub fn encode_text_fixed( &mut self, dst: &mut WriteBuf, len: usize, f: impl FnOnce(&mut [u8]), )

Encode a text frame with a fixed-size payload via closure.

The closure receives &mut [u8] of exactly len bytes.

pub fn encode_binary_fixed( &mut self, dst: &mut WriteBuf, len: usize, f: impl FnOnce(&mut [u8]), )

Encode a binary frame with a fixed-size payload via closure.