/ 
Net-Async-NATS-0.002
River stage zero No dependents
/ Net::Async::NATS

NAME

Net::Async::NATS - Async NATS client for IO::Async

VERSION

version 0.002

SYNOPSIS

use IO::Async::Loop;
use Net::Async::NATS;

my $loop = IO::Async::Loop->new;
my $nats = Net::Async::NATS->new(
    host => 'localhost',
    port => 4222,
);
$loop->add($nats);

await $nats->connect;

# Subscribe
my $sub = await $nats->subscribe('greet.*', sub {
    my ($subject, $payload, $reply_to) = @_;
    print "Got: $payload on $subject\n";
});

# Publish
await $nats->publish('greet.world', 'Hello!');

# Request/Reply
my ($payload) = await $nats->request('service.echo', 'ping', timeout => 5);

# Unsubscribe
await $nats->unsubscribe($sub);

# Disconnect
await $nats->disconnect;

DESCRIPTION

Net::Async::NATS is an asynchronous client for the NATS messaging system, built on IO::Async. It implements the full NATS client wire protocol over TCP using IO::Async::Stream.

Features:

  • Publish/Subscribe messaging

  • Request/Reply with auto-generated inbox subjects

  • Wildcard subscriptions (* and >)

  • Queue group subscriptions

  • Automatic PING/PONG keepalive handling

  • Reconnect with subscription replay

  • Server INFO processing and cluster URL discovery

host

NATS server hostname. Default: localhost.

port

NATS server port. Default: 4222.

name

Client name sent in CONNECT. Default: net-async-nats-perl.

verbose

If true, server sends +OK for each protocol message. Default: false.

pedantic

If true, server performs strict protocol checking. Default: false.

reconnect

If true, automatically reconnect on disconnect. Default: true.

max_reconnect_attempts

Maximum number of reconnect attempts. Default: 10.

reconnect_wait

Seconds between reconnect attempts. Default: 2.

user

Optional username for authentication.

pass

Optional password for authentication. Used together with "user".

auth_token

Optional authentication token. Alternative to username/password auth.

on_connect

Optional callback invoked when the connection is established and the CONNECT handshake completes. Called as $cb-($nats, $info)> where $info is the server INFO hashref.

on_disconnect

Optional callback invoked when the connection is lost. Called as $cb-($nats, $reason)> where $reason is a short string such as read_eof or write_eof.

on_error

Optional callback invoked when the server sends a -ERR message. Called as $cb-($nats, $error_message)>.

server_info

my $info = $nats->server_info;

Returns the server INFO hashref received during the CONNECT handshake. Keys include server_id, version, max_payload, etc. Returns an empty hashref before connecting.

is_connected

if ($nats->is_connected) { ... }

Returns true if the client is currently connected to the NATS server.

connect

await $nats->connect;

Connect to the NATS server. Returns a Future that resolves when the connection is established and the CONNECT handshake is complete.

publish

await $nats->publish($subject, $payload);
await $nats->publish($subject, $payload, reply_to => $reply);

Publish a message to the given subject. Payload can be a string or undef (empty message). Optional reply_to sets the reply subject.

subscribe

my $sub = await $nats->subscribe($subject, sub {
    my ($subject, $payload, $reply_to) = @_;
});

# With queue group
my $sub = await $nats->subscribe($subject, $callback, queue => 'workers');

Subscribe to a subject. The callback receives the matched subject, payload, and optional reply-to subject. Returns a Net::Async::NATS::Subscription object.

Wildcards: * matches a single token, > matches one or more tokens at the tail of the subject.

unsubscribe

await $nats->unsubscribe($sub);
await $nats->unsubscribe($sub, max_msgs => 5);

Unsubscribe from a subscription. With max_msgs, auto-unsubscribe after receiving that many additional messages.

request

my ($payload, $subject) = await $nats->request($subject, $data,
    timeout => 5,
);

Send a request and wait for a single reply. Uses an auto-generated inbox subject. Returns the reply payload and subject. Times out after timeout seconds (default: 30).

ping

await $nats->ping;

Send a PING and wait for the server's PONG response.

disconnect

await $nats->disconnect;

Gracefully disconnect from the NATS server.

SEE ALSO

SUPPORT

Issues

Please report bugs and feature requests on GitHub at https://github.com/Getty/p5-net-async-nats/issues.

CONTRIBUTING

Contributions are welcome! Please fork the repository and submit a pull request.

AUTHOR

Torsten Raudssus <torsten@raudssus.de>

COPYRIGHT AND LICENSE

This software is copyright (c) 2026 by Torsten Raudssus.

This is free software; you can redistribute it and/or modify it under the same terms as the Perl 5 programming language system itself.