# `Plushie.Transport.Framing`
[🔗](https://github.com/plushie-ui/plushie-elixir/blob/v0.7.2/lib/plushie/transport/framing.ex#L1)

Frame encoding and decoding for the plushie wire protocol.

Transports that deliver raw byte streams (SSH channels, raw sockets)
need to frame protocol messages. This module provides the framing
logic for both MessagePack (4-byte length prefix) and JSON (newline
delimiter) modes.

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

## MessagePack framing

Each message is prefixed with a 4-byte big-endian unsigned integer
indicating the payload size:

    <<size::32-big, payload::binary-size(size)>>

## JSON framing

Each message is terminated by a newline character (`\n`). Messages
must not contain embedded newlines.

## Size cap

Both framings reject messages larger than
`Elixir.Plushie.Transport.Framing.max_message_size/0` (64 MiB) by raising
`Plushie.Transport.BufferOverflowError`. Oversized frames are a
protocol violation: silently dropping them risks desync, and the
payload cannot legitimately exceed the cap.

# `decode_lines`

```elixir
@spec decode_lines(buffer :: binary()) :: {[binary()], binary()}
```

Decode complete lines from accumulated bytes (JSON mode).

Returns `{complete_lines, remaining_buffer}`.

Raises `Plushie.Transport.BufferOverflowError` when a completed
line exceeds the 64 MiB cap, or when the partial tail has already
grown past the cap without a newline.

# `decode_packets`

```elixir
@spec decode_packets(buffer :: binary()) :: {[binary()], binary()}
```

Decode complete frames from accumulated bytes (MessagePack mode).

Returns `{complete_messages, remaining_buffer}` where
`complete_messages` is a list of binaries (each a complete protocol
message) and `remaining_buffer` is leftover bytes waiting for more
data.

Raises `Plushie.Transport.BufferOverflowError` when a length prefix
declares a frame larger than the 64 MiB cap.

## Examples

    iex> data = <<0, 0, 0, 3, "abc", 0, 0, 0, 2, "de">>
    iex> {messages, _buffer} = Plushie.Transport.Framing.decode_packets(data)
    iex> messages
    ["abc", "de"]

    iex> partial = <<0, 0, 0, 5, "he">>
    iex> {messages, buffer} = Plushie.Transport.Framing.decode_packets(partial)
    iex> {messages, buffer}
    {[], <<0, 0, 0, 5, "he">>}

# `encode_line`

```elixir
@spec encode_line(data :: iodata()) :: iodata()
```

Encode a protocol message with a newline terminator (JSON mode).

Raises `Plushie.Transport.BufferOverflowError` when the encoded
line exceeds the 64 MiB cap.

# `encode_packet`

```elixir
@spec encode_packet(data :: iodata()) :: iodata()
```

Encode a protocol message with a 4-byte length prefix (MessagePack mode).

Returns iodata that can be written to the transport.

Raises `Plushie.Transport.BufferOverflowError` when the payload
exceeds the 64 MiB cap.

# `max_message_size`

```elixir
@spec max_message_size() :: pos_integer()
```

The per-message size cap in bytes.

Matches the renderer's cap so both ends reject the same threshold.

---

*Consult [api-reference.md](api-reference.md) for complete listing*