NAME

Ereshkigal::Client - Small blocking JSON over unix socket client for Ereshkigal.

VERSION

Version 0.0.1

SYNOPSIS

use Ereshkigal::Client;

my $client = Ereshkigal::Client->new( socket => '/var/run/ereshkigal/socket' );

# returns the raw response hash, {status=>..., ...}
my $response = $client->call( 'status' );

# dies unless status is ok, returning the result
my $result = $client->call_ok( 'ban', { ips => ['1.2.3.4'] } );

DESCRIPTION

Connects to a unix socket speaking the newline delimited JSON protocol of POE::Component::Server::JSONUnix, sends a single request, and reads back the response. Used by the ereshkigal CLI for talking to the manager and by the manager for talking to kur instances.

METHODS

new

Initiates the object. Will die on errors.

- socket :: Path of the unix socket to connect to. Must be specified.
    Default :: undef

- timeout :: Timeout in seconds for a call. 0 means no timeout.
    Default :: 30

call

Sends a single request and returns the decoded response hash. Will die on connect failure, timeout, or an undecodable response.

my $response = $client->call( $command, $args );

$args, if defined, is sent as the args value of the request.

If the server answers with the POE::Component::Server::JSONUnix authentication required error, the unix ownership challenge is completed transparently on the same connection and the request is resent, so no special handling is needed for talking to a manager with enable_auth on. The timeout wraps the whole exchange.

call_many

Sends the same single request to multiple sockets concurrently. This is for the manager fanning a command out to its kurs, which is why it is a class method taking a whole hash of sockets rather than using a per socket object.

my $per_name = Ereshkigal::Client->call_many(
    sockets => { sshd => '/var/run/ereshkigal/kur/sshd.sock' },
    command => 'ban',
    args    => { ips => [ '1.2.3.4' ] },
    timeout => 30,
);

- sockets :: A hash of name to unix socket path. Must be specified.
    Default :: undef

- command :: The command to send to every socket. Must be specified.
    Default :: undef

- args :: Sent as the args value of the request, if defined.
    Default :: undef

- timeout :: Timeout in seconds for the whole fan out, bounding it as a
      whole rather than each socket individually, so the wall time is
      the slowest socket capped at one timeout instead of the sum. This
      covers the connects as well, each of which is bounded by an even
      share of what is left of it, so a socket whose listener never
      accepts cannot hang the fan out or starve the rest of it. 0
      means no timeout.
    Default :: 30

The return is a hash keyed the same as sockets, each value being either { result => ... } for a response with an ok status or { error => "..." } for anything else... connect failure, EOF, an undecodable response, an error status response, or the deadline passing. A failure with one socket never disturbs the others.

Unlike "call", no authentication challenge handling happens... kur sockets never challenge and this is not meant for talking to the manager socket.

call_ok

Like "call", but dies if the response status is not ok, and returns the result value of the response instead of the whole response.

my $result = $client->call_ok( $command, $args );