NAME

Chandra::Socket::Hub - IPC server for coordinating Chandra instances

SYNOPSIS

use Chandra::Socket::Hub;

my $hub = Chandra::Socket::Hub->new(name => 'myapp');

$hub->on('status', sub {
    my ($data, $client) = @_;
    print "Got status from ${\$client->name}\n";
});

$hub->on_connect(sub {
    my ($client) = @_;
    $client->send('welcome', { version => '1.0' });
});

$hub->broadcast('config', { theme => 'dark' });
$hub->send_to('window-1', 'navigate', { path => '/' });

$hub->run;  # standalone event loop

DESCRIPTION

Hub acts as the server in a hub/client IPC topology. It listens on a Unix domain socket (default) or TCP socket, accepts connections from Client instances, and dispatches messages by channel name.

SECURITY

The Unix socket is created with 0600 permissions and placed in $XDG_RUNTIME_DIR (or the system temp directory) to limit access.

Hub generates a random authentication token on startup and writes it to a token file (.token beside the socket) with 0600 permissions. Clients must present the correct token during the handshake or the connection is rejected. For TCP transport, pass the token explicitly via the token parameter to Chandra::Socket::Client.

Use $hub->token to retrieve the current token (e.g. for passing to TCP clients).

For TCP transport over a network, enable TLS by passing tls_cert and tls_key to the Hub, and tls => 1 to the Client. This requires IO::Socket::SSL to be installed. Without TLS, TCP traffic (including the auth token) is sent in plaintext.