view release on metacpan or  search on metacpan

README  view on Meta::CPAN

    Callback receives:

    $subject - actual subject the message was published to
    $payload - message body
    $reply - reply-to subject (undef if none)
    $headers - raw headers string (only for HMSG)

  subscribe_max($subject, $cb, $max_msgs, [$queue_group])
    Convenience: "subscribe" followed by an auto-unsubscribe after $max_msgs
    messages have been delivered.

  unsubscribe($sid, [$max_msgs])
    Unsubscribe. With $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: "unsub".

  request($subject, $payload, $cb, [$timeout_ms])
    Request/reply. Uses automatic inbox subscription. Alias: "req".

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

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

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

    $cb receives a single argument: "undef" on clean drain, or an error
    string (e.g. "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";
        });

  ping
    Send PING to server.

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

  creds_file($path)
    Read a NATS ".creds" file and apply the embedded JWT and NKey seed via
    "jwt" and "nkey_seed". Apply this BEFORE "connect" so the credentials
    are available during the CONNECT handshake. Dies if the file is
    unreadable or missing either the "USER JWT" or "USER NKEY SEED" block.

  new_inbox
    Returns a fresh subject suitable for use as a private reply target
    ("_INBOX.<rand>.<n>"). Each call burns a slot from the same counter that
    "request" uses, so manual subscribers must treat the returned subject as
    opaque.

  subscription_count
    Returns the number of currently-registered subscriptions, including the
    implicit "_INBOX.>" subscription used by "request".

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

  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).

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

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

  reconnect($enable, [$delay_ms], [$max_attempts])
    Configure reconnection. $delay_ms and $max_attempts are only written
    when supplied; omitted args leave the existing value unchanged.

  reconnect_enabled
    Returns true if reconnect is enabled.

  connect_timeout([$ms])
    Get/set connect timeout.

  ping_interval([$ms])
    Get/set PING interval.

  max_pings_outstanding([$num])
    Get/set max outstanding PINGs.

  priority([$num])
    Get/set EV watcher priority.

  keepalive([$seconds])
    Get/set TCP keepalive.

  batch($coderef)
    Batch multiple publishes into a single write. Suppresses per-publish
    write scheduling; all buffered data is flushed after the coderef
    returns.

        $nats->batch(sub {