view release on metacpan or  search on metacpan

README  view on Meta::CPAN

    $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". Croaks on
    an undef or empty subject.

        $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"), no
    responders ("no responders"), or a dropped connection ("disconnected"). A
    $timeout_ms of 0 disables the timeout; the callback then waits
    indefinitely.

  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. Croaks unless connected. Calling "drain" again while a drain is
    in progress croaks if a callback is given, and is otherwise a silent
    no-op.

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

  ping
    Send PING to server. Croaks unless connected.

  flush([$cb])
    Send PING as a write fence; the subsequent PONG guarantees all prior
    messages were processed by the server. Croaks unless connected. 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. Queueing past
    "reconnect_buf_size" croaks.

  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. Passing
    a false $enable also cancels a pending reconnect attempt.

  reconnect_enabled
    Returns true if reconnect is enabled.

  reconnect_buf_size([$bytes])
    Get/set the cap on writes queued while disconnected (default 8 MiB; 0
    disables the cap). May also be passed to "new". A publish that would
    exceed the cap croaks with "reconnect buffer full" instead of queueing.

  connect_timeout([$ms])
    Get/set connect timeout. Read at the start of each connect attempt.

  ping_interval([$ms])
    Get/set PING interval. Takes effect immediately on a live connection,
    including disabling (0) a running timer.

  max_pings_outstanding([$num])
    Get/set max outstanding PINGs. 0 disables the staleness check.

  priority([$num])
    Get/set EV watcher priority (-2 .. +2; anything else croaks). Applies to
    watchers created by the next (re)connect.