Plushie.Transport.Framing (Plushie v0.6.0)

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.

Summary

Functions

decode_lines(buffer)

Decode complete lines from accumulated bytes (JSON mode).

decode_packets(buffer)

Decode complete frames from accumulated bytes (MessagePack mode).

encode_line(data)

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

encode_packet(data)

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

Functions

decode_lines(buffer)

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

Decode complete lines from accumulated bytes (JSON mode).

Returns {complete_lines, remaining_buffer}.

decode_packets(buffer)

@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(data)

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

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

encode_packet(data)

@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.