view release on metacpan or  search on metacpan

lib/EV/Nats.pm  view on Meta::CPAN

=head2 subscribe_max($subject, $cb, $max_msgs, [$queue_group])

Convenience: L</subscribe> followed by an auto-unsubscribe after
C<$max_msgs> messages have been delivered.

=head2 unsubscribe($sid, [$max_msgs])

Unsubscribe. With C<$max_msgs>, the server is told to deliver that
many more messages and then drop the subscription. The auto-unsub
state is restored on reconnect (so the partial count survives a
disconnect). Alias: C<unsub>.

=head2 request($subject, $payload, $cb, [$timeout_ms])

Request/reply. Uses automatic inbox subscription. Alias: C<req>.

    $nats->request('service', 'data', sub {
        my ($response, $err) = @_;
        die $err if $err;
        print "got: $response\n";
    }, 5000);

Callback receives C<($response, $error)>. For replies that include
NATS message headers (HMSG), a third argument C<$headers> with the
raw header block is also passed. Error is set on timeout
("request timeout") or no responders ("no responders").

=head2 drain([$cb])

Graceful shutdown: sends UNSUB for all subscriptions, flushes pending
writes with a PING fence, fires C<$cb> when the server confirms with
PONG, then disconnects. No new messages will be received after drain
is initiated.

C<$cb> receives a single argument: C<undef> on clean drain, or an error
string (e.g. C<"disconnected">) if the connection dropped before the
PONG arrived.

    $nats->drain(sub {
        my ($err) = @_;
        die "drain failed: $err" if $err;
        print "drained, safe to exit\n";
    });

=head2 ping

Send PING to server.

=head2 flush([$cb])

Send PING as a write fence; the subsequent PONG guarantees all prior
messages were processed by the server. If C<$cb> is given, it is invoked
when the PONG arrives. The callback receives a single argument: C<undef>
on success, or an error string (e.g. C<"disconnected">) if the connection
dropped before the PONG arrived.

=head2 creds_file($path)

Read a NATS C<.creds> file and apply the embedded JWT and NKey seed
via L</jwt> and L</nkey_seed>. Apply this BEFORE C<connect> so the
credentials are available during the CONNECT handshake. Dies if the
file is unreadable or missing either the C<USER JWT> or
C<USER NKEY SEED> block.

=head2 new_inbox

Returns a fresh subject suitable for use as a private reply target
(C<_INBOX.E<lt>randE<gt>.E<lt>nE<gt>>). Each call burns a slot from
the same counter that L</request> uses, so manual subscribers must
treat the returned subject as opaque.

=head2 subscription_count

Returns the number of currently-registered subscriptions, including
the implicit C<_INBOX.E<gt>> subscription used by L</request>.

=head2 server_info

Returns the raw JSON string of the most recent INFO frame received
from the server (or C<undef> before the first INFO). Useful for
inspecting C<server_id>, C<version>, C<cluster>, C<connect_urls>,
etc.

=head2 max_payload([$limit])

Server-advertised maximum payload size in bytes. Returns the current
value; with an argument, overrides it (publishes above this croak
locally before reaching the wire).

=head2 waiting_count

Number of writes queued locally during connect or reconnect (i.e.
C<publish>/C<request> calls made while the connection is not yet
ready). They flush when the handshake completes.

=head2 skip_waiting

Drop all queued writes without sending them. Useful before
C<disconnect> if reconnect is enabled and you don't want stale
publishes replayed.

=head2 reconnect($enable, [$delay_ms], [$max_attempts])

Configure reconnection. C<$delay_ms> and C<$max_attempts> are only
written when supplied; omitted args leave the existing value unchanged.

=head2 reconnect_enabled

Returns true if reconnect is enabled.

=head2 connect_timeout([$ms])

Get/set connect timeout.

=head2 ping_interval([$ms])

Get/set PING interval.

=head2 max_pings_outstanding([$num])

Get/set max outstanding PINGs.