# `Plushie.Transport.Framing`
[🔗](https://github.com/plushie-ui/plushie-elixir/blob/v0.6.0/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.

# `decode_lines`

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

Decode complete lines from accumulated bytes (JSON mode).

Returns `{complete_lines, remaining_buffer}`.

# `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.

## 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).

# `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.

---

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