NAME
POE::Component::Server::JSONUnix::BlockingClient - simple blocking (non-POE) client for POE::Component::Server::JSONUnix
SYNOPSIS
use POE::Component::Server::JSONUnix::BlockingClient;
my $client = POE::Component::Server::JSONUnix::BlockingClient->new(
socket_path => '/tmp/app.sock',
);
my $auth = $client->authenticate;
die $auth->{error} if $auth->{status} ne 'ok';
my $response = $client->call(
command => 'add',
args => { numbers => [ 1, 2, 3 ] },
);
die $response->{error} if $response->{status} ne 'ok';
print "sum is $response->{result}{sum}\n";
$client->disconnect;DESCRIPTION
A minimal synchronous client for POE::Component::Server::JSONUnix. Unlike POE::Component::Server::JSONUnix::Client it does not use POE at all: each "call" writes one newline-delimited JSON request to the server's Unix domain socket and blocks until the matching response arrives (or a timeout expires).
This is the right tool for command-line utilities, cron jobs, and other plain-procedural programs that just want to ask a running daemon a question. If you need concurrent requests, callbacks, or to live inside an event loop, use the POE client instead.
It also knows how to complete the server's Unix-ownership authentication challenge (see "authenticate").
CONSTRUCTOR
new
my $client = POE::Component::Server::JSONUnix::BlockingClient->new(%args);Creates the client and (by default) connects. Recognised arguments:
socket_path
Required. Filesystem path of the server's Unix domain socket.
auto_connect
Connect immediately from new, croaking on failure. Defaults to true. When false, call "connect" yourself.
timeout
Default per-request timeout in seconds (fractional values are fine). A request that receives no response in time returns {status => 'error', error => 'request timed out'}. No timeout by default: "call" blocks until the server answers or hangs up. Can be overridden per request.
on_notice
Code reference called as $cb->($client, $response) for any server message that cannot be matched to the request currently being waited on: a message with no id, or one whose id is not the awaited one (most notably a response arriving after its request already timed out locally). Unmatched messages are dropped silently if this is not set.
METHODS
connect
$client->connect;Connect to the server. A no-op if already connected. Croaks if the connection cannot be made. Returns the client object. May be called again after a disconnect.
disconnect
$client->disconnect;Close the connection. A no-op if not connected. Authentication state lives on the connection, so it is cleared here; after a reconnect the handshake must be performed again.
call
my $response = $client->call(
command => 'add',
args => { numbers => [ 1, 2, 3 ] },
);Send a request and block until its response arrives. Returns the full decoded response envelope, e.g. {id => 7, status => 'ok', result => {...}}.
Failures are reported in-band, as {status => 'error', error => ...} envelopes just as server-side errors are -- a timeout, a connection that is (or comes) down mid-request, or an unserialisable request all produce one, so checking $response->{status} covers everything. Note that a timeout is a local judgement only: the server may still be working on the request, and its late response is routed to on_notice (or dropped) when it eventually arrives during a later call.
Croaks only on usage errors (a missing command).
Arguments:
command
Required. The command name. cmd is accepted as an alias.
args
Arbitrary payload for the command's handler.
timeout
Per-request timeout in seconds, overriding the constructor's timeout.
authenticate
my $response = $client->authenticate;
die $response->{error} if $response->{status} ne 'ok';Perform the server's Unix-ownership challenge: call auth_start, write the returned cookie to a fresh file in the server's temp_dir (the OS stamps the file with this process's effective UID, which is the proof the server checks), then call auth_verify and clean the file up.
Accepts an optional timeout, applied to each of the two requests. Returns the auth_verify response envelope on success, or a synthesised {status => 'error', ...} envelope if any step fails. After success, "authenticated", "uid" and "username" reflect the verified identity.
connected
True while a connection to the server is up.
authenticated
True after a successful "authenticate" on the current connection.
uid
username
The verified identity, or undef before authentication. Cleared on disconnect.
groups
Array reference of the verified user's group names, or undef before authentication. Empty unless the server has a permission policy configured (only then does its auth_verify report groups). Cleared on disconnect.
CAVEATS
One request is on the wire at a time; there is no pipelining and no out-of-order correlation beyond skipping messages that do not match the awaited id. Unsolicited messages pushed by server-side handlers are only noticed (and handed to on_notice) while a call is waiting for its response -- a blocking client has no way to listen between calls.
SEE ALSO
POE::Component::Server::JSONUnix, POE::Component::Server::JSONUnix::Client, IO::Socket::UNIX, JSON::MaybeXS.
AUTHOR
Zane C. Bowers-Hadley, <vvelox at vvelox.net>
COPYRIGHT AND LICENSE
This software is Copyright (c) 2026 by Zane C. Bowers-Hadley.
This is free software, licensed under:
The GNU Lesser General Public License, Version 2.1, February 1999