Object.NetworkProtocol (object v0.1.2)

Binary protocol for efficient Object communication over network.

Implements a high-performance binary protocol with support for:

  • Message framing and fragmentation
  • Request/response and streaming patterns
  • Compression and encryption
  • Version negotiation
  • Heartbeat and health checking

Protocol Format

|  1 byte  |  1 byte  |  2 bytes  |  4 bytes  |  Variable  |
| Version  |   Type   |   Flags   |  Length   |   Payload  |

Message Types

  • 0x01: HELLO - Initial handshake
  • 0x02: HELLO_ACK - Handshake acknowledgment
  • 0x10: REQUEST - Request message
  • 0x11: RESPONSE - Response message
  • 0x12: STREAM_START - Start streaming
  • 0x13: STREAM_DATA - Stream chunk
  • 0x14: STREAM_END - End streaming
  • 0x20: CAST - One-way message
  • 0x30: HEARTBEAT - Keepalive
  • 0x31: HEARTBEAT_ACK - Keepalive response
  • 0xFF: ERROR - Error message

Summary

Types

encode_opts()
message()
message_type()

Functions

create_cast(object_id, method, args, opts \\ [])

Creates a cast (one-way) message.

create_heartbeat()

Creates a heartbeat message.

create_heartbeat_ack(correlation_id)

Creates a heartbeat acknowledgment.

create_request(object_id, method, args, opts \\ [])

Creates a request message.

create_response(correlation_id, result, opts \\ [])

Creates a response message.

decode(data, opts \\ [])

Decodes a binary message into structured format.

encode(message, opts \\ [])

Encodes a message into binary protocol format.

fragment_message(data, chunk_size \\ 65536)

Fragments a large message into smaller chunks.

reassemble_fragments(fragments)

Reassembles fragmented messages.

Types

encode_opts()

@type encode_opts() :: [
  compress: boolean(),
  encrypt: boolean(),
  encryption_key: binary()
]

message()

@type message() :: %{
  version: non_neg_integer(),
  type: message_type(),
  flags: non_neg_integer(),
  id: binary(),
  correlation_id: binary() | nil,
  payload: term(),
  metadata: map()
}

message_type()

@type message_type() ::
  :hello
  | :hello_ack
  | :request
  | :response
  | :stream_start
  | :stream_data
  | :stream_end
  | :cast
  | :heartbeat
  | :heartbeat_ack
  | :error

Functions

create_cast(object_id, method, args, opts \\ [])

@spec create_cast(String.t(), String.t(), list(), Keyword.t()) :: message()

Creates a cast (one-way) message.

create_heartbeat()

@spec create_heartbeat() :: message()

Creates a heartbeat message.

create_heartbeat_ack(correlation_id)

@spec create_heartbeat_ack(binary()) :: message()

Creates a heartbeat acknowledgment.

create_request(object_id, method, args, opts \\ [])

@spec create_request(String.t(), String.t(), list(), Keyword.t()) :: message()

Creates a request message.

create_response(correlation_id, result, opts \\ [])

@spec create_response(binary(), term(), Keyword.t()) :: message()

Creates a response message.

decode(data, opts \\ [])

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

Decodes a binary message into structured format.

encode(message, opts \\ [])

@spec encode(message(), encode_opts()) :: {:ok, binary()} | {:error, term()}

Encodes a message into binary protocol format.

fragment_message(data, chunk_size \\ 65536)

@spec fragment_message(binary(), pos_integer()) :: [binary()]

Fragments a large message into smaller chunks.

reassemble_fragments(fragments)

@spec reassemble_fragments([binary()]) :: {:ok, binary()} | {:error, term()}

Reassembles fragmented messages.