NAME

Net::NATS2::Client - A Perl client for the NATS messaging system. Based on Net::NATS::Client

SYNOPSIS

#
# Basic Usage
#

$client = Net::NATS2::Client->new(uri => 'nats://localhost:4222');
$client->connect() or die $!;

# Simple Publisher
$client->publish('foo', 'Hello, World!');

# Simple Async Subscriber
$subscription = $client->subscribe('foo', sub {
    my ($message) = @_;
    printf("Received a message: %s\n", $message->data);
});

# Process one message from the server. Could be a PING message.
# Must call at least one per ping-timout (default is 120s).
$client->wait_for_op();

# Process pending operations, with a timeout (in seconds).
# A timeout of 0 is polling.
$client->wait_for_op(3.14);

# Check that the connection is still live. This waits up to one second
# for the server's PONG response.
die 'ERROR: Connection lost!' unless $client->ping(1);

# Unsubscribe
$subscription->unsubscribe();

# Close connection
$client->close();

#
# Headers
#

my $headers = "NATS/1.0\r\nX-Trace-ID: 42\r\n\r\n";
$client->hpublish('foo', $headers, 'Hello, World!');

# Received header messages retain the raw header block separately.
$client->subscribe('foo', sub {
    my ($message) = @_;
    print $message->headers;
    print $message->data;
});

#
# Request/Reply
#

# Setup reply
$client->subscribe("foo", sub {
    my ($request) = @_;
    printf("Received request: %s\n", $request->data);
    $client->publish($request->reply_to, "Hello, Human!");
});

# Send request
$client->request('foo', 'Hello, World!', sub {
    my ($reply) = @_;
    printf("Received reply: %s\n", $reply->data);
});

# Wait synchronously for one reply, as used by JetStream APIs.
my $reply = $client->request_sync('foo', 'Hello, World!', 1);

# Enable reconnect attempts and subscription restoration.
my $client = Net::NATS2::Client->new(
    uri                => 'nats://localhost:4222',
    auto_reconnect     => 1,
    reconnect_attempts => 3,
    reconnect_delay    => 1,
);

# Use JetStream through the connected core client.
use Net::NATS2::JetStream;
my $js = Net::NATS2::JetStream->new(client => $client, timeout => 1);


#
# TLS
#

# Set the socket arguments that will be passed to IO::Socket::SSL
my $socket_args = {
  SSL_cert_file => $cert_file,
  SSL_key_file  => $key_file,
};

my $client = Net::NATS2::Client->new(uri => 'nats://localhost:4222', socket_args => $socket_args);
$client->connect() or die $!;

# Change the default 1024-byte socket read chunk size.
my $client = Net::NATS2::Client->new(
    uri => 'nats://localhost:4222',
    socket_args => { BufferSize => 4096 },
);

HEADERS

hpublish($subject, $headers, $data, $reply_to) sends an HPUB command. publish_with_headers is an alias. $headers must be a complete NATS header block: the NATS/1.0 version line, zero or more header lines, and the final \r\n\r\n delimiter. $reply_to is optional.

The client advertises header support in CONNECT and returns undef from hpublish without writing to the socket if the server's INFO reports that headers are unavailable. Received HMSG messages provide the complete raw header block through $message->headers, its byte count through $message->header_length, and the payload through $message->data.

ENCODING

Protocol lengths are measured in bytes. UTF-8-flagged outbound strings are encoded as UTF-8 before being written; byte strings are sent unchanged. This applies to PUB and HPUB payloads as well as protocol control lines.

RECONNECTION

Automatic reconnect is disabled by default. Set auto_reconnect to a positive value and optionally configure reconnect_attempts (default 3) and reconnect_delay (default 1 second). Set auto_reconnect to 0 for unlimited attempts; omit it entirely to disable reconnection. When a read-side disconnect is detected, the client reconnects to its configured URI and re-establishes each existing subscription with its original subscription ID.

The client does not retry a failed publish automatically: a failed write may have reached the server, and retrying could duplicate delivery.

JETSTREAM

Net::NATS2::JetStream uses a connected core client to provide account information, stream management, synchronous publish acknowledgements, and pull consumer support. See that module's documentation for its API.

READ BUFFER SIZE

The client reads socket data in 1024-byte chunks by default. Pass BufferSize in socket_args to use a different chunk size:

my $client = Net::NATS2::Client->new(
    uri => 'nats://localhost:4222',
    socket_args => { BufferSize => 4096 },
);

UPSTREAM

https://github.com/dshadow/perl-nats2 https://github.com/carwynmoore/perl-nats

AUTHOR

Carwyn Moore

Vick Khera, <vivek at khera.org>,

Kostiantyn Cherednichenko, <dshadowukraine at gmail.com>

COPYRIGHT AND LICENSE

MIT License. See LICENSE for the complete licensing terms.

Copyright (c) 2016 Carwyn Moore, 2026 Kostiantyn Cherednichenko