Raxol.Agent.Tunnel.Frame (Raxol Agent v2.6.0)

Copy Markdown View Source

Wire frame for the reverse co-driving tunnel.

A single outbound link carries many logical channels, demultiplexed by channel_id. Four frame kinds ride the link (ported from omnigent's ws.open / ws.frame / ws.close plus a hello handshake):

  • :hello -- sent once by the host after it dials out; carries its identity and capabilities. channel_id is nil.
  • :open -- open a new channel; payload %{"path", "meta"}. The opener allocates the channel_id; the peer spawns the channel's local handler.
  • :data -- channel I/O; payload %{"data", "binary"} (base64 when binary).
  • :close -- close a channel; payload %{"code", "reason"}.

Frames serialize to JSON so any byte transport (a real WebSocket, an in-memory link) can carry them. Decoding maps the kind through an explicit whitelist -- never String.to_atom/1 on link input.

Summary

Types

kind()
t()

Functions

close(channel_id, code \\ 1000, reason \\ "")

A close frame for channel_id.

data(channel_id, data, opts \\ [])

A data frame carrying data for channel_id.

decode(binary)

Decode a JSON binary from the link into a frame.

encode(frame)

Serialize a frame to a JSON binary for the link.

hello(host_id, capabilities)

A host hello frame announcing identity + capabilities.

new_channel_id()

Generate a fresh channel id (4 random bytes, lowercase hex).

open(channel_id, path, meta \\ %{})

An open frame for channel_id targeting path with optional meta.

read_data(frame)

Decode a data frame's payload back to its raw bytes/text.

Types

kind()

@type kind() :: :hello | :open | :data | :close

t()

@type t() :: %Raxol.Agent.Tunnel.Frame{
  channel_id: binary() | nil,
  kind: kind(),
  payload: map()
}

Functions

close(channel_id, code \\ 1000, reason \\ "")

@spec close(binary(), non_neg_integer(), binary()) :: t()

A close frame for channel_id.

data(channel_id, data, opts \\ [])

@spec data(binary(), binary(), keyword()) :: t()

A data frame carrying data for channel_id.

Text data rides verbatim; pass binary: true to base64-encode arbitrary bytes.

decode(binary)

@spec decode(binary()) :: {:ok, t()} | {:error, term()}

Decode a JSON binary from the link into a frame.

encode(frame)

@spec encode(t()) :: binary()

Serialize a frame to a JSON binary for the link.

hello(host_id, capabilities)

@spec hello(binary(), [binary()]) :: t()

A host hello frame announcing identity + capabilities.

new_channel_id()

@spec new_channel_id() :: binary()

Generate a fresh channel id (4 random bytes, lowercase hex).

open(channel_id, path, meta \\ %{})

@spec open(binary(), binary(), map()) :: t()

An open frame for channel_id targeting path with optional meta.

read_data(frame)

@spec read_data(t()) :: binary()

Decode a data frame's payload back to its raw bytes/text.