framing

Frame encoding and decoding for the plushie wire protocol.

Transports that deliver raw byte streams need framing logic. This module provides it for both MessagePack (4-byte length prefix) and JSONL (newline delimiter) modes.

Transports with built-in framing (e.g. Erlang Ports with {packet, 4}) don’t need this module.

The decode paths reject frames or lines past max_message_size by returning Error(BufferOverflow(size, limit)). Oversized frames are always a protocol violation; silently dropping them would risk desync, and the payload cannot legitimately exceed the cap.

Types

FramingError

</>

Error returned when a wire frame exceeds the per-message size cap.

Carries both the offending size and the configured limit for structured handling on the caller side.

pub type FramingError {
  BufferOverflow(size: Int, limit: Int)
}

Constructors

```
BufferOverflow(size: Int, limit: Int)
```

Values

decode_lines

</>

pub fn decode_lines(
  buffer: BitArray,
) -> Result(#(List(BitArray), BitArray), FramingError)

Split a buffer on newline boundaries.

Returns complete lines and any remaining partial line, or Error(BufferOverflow) when a completed line or the tail exceeds max_message_size.

decode_packets

</>

pub fn decode_packets(
  buffer: BitArray,
) -> Result(#(List(BitArray), BitArray), FramingError)

Extract complete length-prefixed frames from a buffer.

Returns the decoded messages and any remaining partial data, or Error(BufferOverflow) when a length prefix declares an oversized frame.

encode_line

</>

pub fn encode_line(
  data: BitArray,
) -> Result(BitArray, FramingError)

Encode a message with a newline terminator.

Returns Error(BufferOverflow) when data exceeds max_message_size.

encode_packet

</>

pub fn encode_packet(
  data: BitArray,
) -> Result(BitArray, FramingError)

Encode a message with a 4-byte big-endian length prefix.

Returns Error(BufferOverflow) when data exceeds max_message_size.

max_message_size

</>

pub const max_message_size: Int

Per-message size cap in bytes (64 MiB). Matches the renderer’s cap so both ends reject the same threshold.

validate_message

</>

pub fn validate_message(
  data: BitArray,
) -> Result(Nil, FramingError)

Validate one complete wire message against max_message_size.

validate_message_size

</>

pub fn validate_message_size(
  size: Int,
) -> Result(Nil, FramingError)

Validate the size of one complete wire message.