view release on metacpan or  search on metacpan

lib/Chandra/Socket/Hub.pm  view on Meta::CPAN

	$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

=head1 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
L<Chandra::Socket::Client> instances, and dispatches messages by channel
name.

=head1 CONSTRUCTOR

=head2 new

	my $hub = Chandra::Socket::Hub->new(%args);

=over 4

=item name

(Required for Unix transport) Logical name used to derive the socket path.

=item transport

C<'unix'> (default) or C<'tcp'>.

=item port

(Required for TCP) Port number to listen on.

=item bind

Bind address for TCP. Defaults to C<'127.0.0.1'>.

=item tls_cert

Path to a PEM certificate file. Enables TLS when paired with C<tls_key>.
Requires L<IO::Socket::SSL>.

=item tls_key

Path to a PEM private key file for TLS.

=back

=head1 METHODS

=head2 on

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

Register a handler for messages on C<$channel>. The callback receives
the decoded data hash and the sender's L<Chandra::Socket::Connection>.

=head2 on_connect

	$hub->on_connect(sub { my ($conn) = @_; ... });

Called when a client completes the authenticated handshake.

=head2 on_disconnect

	$hub->on_disconnect(sub { my ($conn) = @_; ... });

Called when a client disconnects.

=head2 broadcast

	$hub->broadcast($channel, \%data);

Send a message to all connected clients.

=head2 send_to

	$hub->send_to($client_name, $channel, \%data);

Send a message to a specific client by name. Returns false if the client
is not connected.

=head2 clients

	my @names = $hub->clients;

Returns the names of all connected clients.

=head2 token

	my $token = $hub->token;

Returns the authentication token. Pass this to TCP clients that cannot
read the token file.

=head2 socket_path

	my $path = Chandra::Socket::Hub->socket_path($name);

Class method. Returns the socket file path for a given hub name, using
the same C<$XDG_RUNTIME_DIR> / C<tmpdir> logic as the constructor.

=head2 poll

	$hub->poll;

Non-blocking check for new connections and incoming messages.
Call this in your own event loop, or use C<run()> for a standalone loop.

=head2 run

	$hub->run;

Blocking event loop that calls C<poll()> continuously. Useful for
standalone hub processes.