NAME

Chandra::Socket::Client - IPC client for connecting to a Chandra Hub

SYNOPSIS

use Chandra::Socket::Client;

# Unix socket — token is read automatically from the token file
my $client = Chandra::Socket::Client->new(
    name => 'window-1',
    hub  => 'myapp',
);

# TCP — token must be passed explicitly
my $client = Chandra::Socket::Client->new(
    name      => 'remote-1',
    transport => 'tcp',
    host      => '10.0.0.5',
    port      => 9000,
    token     => $token,
);

# TCP with TLS (requires IO::Socket::SSL)
my $client = Chandra::Socket::Client->new(
    name      => 'remote-1',
    transport => 'tcp',
    host      => '10.0.0.5',
    port      => 9000,
    token     => $token,
    tls       => 1,
    tls_ca    => '/path/to/ca.pem',   # optional cert verification
);

# Via Chandra::App helper
my $client = $app->client(name => 'window-1', hub => 'myapp');

$client->on('navigate', sub {
    my ($data) = @_;
    $app->navigate($data->{path});
});

$client->send('status_update', { status => 'ready' });

$app->run;

DESCRIPTION

Client connects to a Chandra::Socket::Hub server via Unix domain socket (default) or TCP. It authenticates via a token-based handshake and can send/receive messages on named channels.

For Unix sockets the authentication token is read automatically from the token file created by the Hub. For TCP, pass the token explicitly.

CONSTRUCTOR

new

my $client = Chandra::Socket::Client->new(%args);

name

(Required) Client name sent during the handshake. Must be unique per Hub.

hub

(Required for Unix transport) Name of the Hub to connect to (matches the Hub's name parameter).

transport

'unix' (default) or 'tcp'.

host

Hub host for TCP. Defaults to '127.0.0.1'.

port

(Required for TCP) Hub port number.

token

Authentication token. For Unix sockets this is read from the token file automatically. For TCP it must be provided (see $hub->token).

tls

Set to a true value to connect via TLS. Requires IO::Socket::SSL.

tls_ca

Path to a CA certificate file for server verification. When omitted, peer verification is disabled.

METHODS

on

$client->on($channel => sub { my ($data) = @_; ... });

Register a handler for messages on $channel.

send

$client->send($channel, \%data);

Send a message to the Hub.

request

$client->request($channel, \%data, sub { my ($reply) = @_; ... });

Send a request and register a callback for the correlated reply.

is_connected

if ($client->is_connected) { ... }

Returns true if the underlying connection is alive.

poll

$client->poll;

Non-blocking check for incoming messages. Triggers auto-reconnect if the connection has dropped.

reconnect

$client->reconnect;

Close the current connection (if any) and attempt to reconnect with exponential back-off.

close

$client->close;

Close the connection.

SEE ALSO

Chandra::Socket::Hub, Chandra::Socket::Connection, Chandra::App

cpanm Chandra

perl -MCPAN -e shell
install Chandra