NAME
Chandra::Socket::Connection - Wire protocol and connection wrapper for Chandra IPC
DESCRIPTION
Handles length-prefixed JSON framing for communication between Chandra::Socket::Hub and Chandra::Socket::Client processes.
You normally do not create Connection objects directly; the Hub and Client manage them internally.
WIRE PROTOCOL
Each frame consists of a 4-byte big-endian length prefix followed by a UTF-8 JSON payload:
[ 4-byte length N ][ N bytes of JSON ]Messages are JSON objects with at least a channel key and a data key. Additional keys (from, _id, _reply_to) are used internally for routing and request/response correlation.
LIMITS
- MAX_FRAME_SIZE
-
16 MB. Any single frame larger than this causes an immediate disconnect.
- MAX_BUFFER_SIZE
-
64 MB. If the internal receive buffer exceeds this, the connection is dropped to prevent memory exhaustion.
Malformed JSON payloads are logged via warn and discarded.
METHODS
new
my $conn = Chandra::Socket::Connection->new(
socket => $sock,
name => 'client-1', # optional
);send
$conn->send($channel, \%data);
$conn->send($channel, \%data, { _id => 1 });Encode and send a framed message. Returns true on success.
reply
$conn->reply($original_msg, \%response_data);Send a response correlated to a request (uses _reply_to).
recv
my @messages = $conn->recv;Non-blocking read. Returns decoded message hashes, or an empty list if no complete frames are available. Sets is_connected to false on EOF or error.
is_connected
if ($conn->is_connected) { ... }name / set_name
my $name = $conn->name;
$conn->set_name('new-name');socket
my $fh = $conn->socket;Returns the underlying socket filehandle.
close
$conn->close;encode_frame (class method)
my $bytes = Chandra::Socket::Connection->encode_frame(\%msg);Encode a message hash to a wire frame. Useful for testing.
decode_frames (class method)
my @msgs = Chandra::Socket::Connection->decode_frames($bytes);Decode one or more frames from a byte string. Useful for testing.