ballerinax/nats

Overview

This module provides the capability to send and receive messages by connecting to the NATS server.

NATS messaging enables the communication of data that is segmented into messages among computer applications and services. Data is encoded and framed as a message and sent by a publisher. The message is received, decoded, and processed by one or more subscribers. NATS makes it easy for programs to communicate across different environments, languages, cloud providers, and on-premise systems. Clients connect to the NATS system usually via a single URL and then subscribe or publish messages to a subject.

Basic Usage

Setting up the Connection

First, you need to set up the connection with the NATS Basic server. The following ways can be used to connect to a NATS Basic server.

  1. Connect to a server using the default URL:
1nats:Client natsClient = check new(nats:DEFAULT_URL);
  1. Connect to a server using the URL:
1nats:Client natsClient = check new("nats://serverone:4222");
  1. Connect to one or more servers with custom configurations:
1nats:ConnectionConfiguration config = {
2 connectionName: "my-nats",
3 noEcho: true
4};
5nats:Client natsClient = check new(["nats://serverone:4222", "nats://servertwo:4222"], config);

Publishing Messages

Publishing Messages to the NATS Basic Server

Once connected, publishing is accomplished via one of the three methods below.

  1. Publish with the subject and the message content:
1string message = "hello world";
2nats:Error? result =
3 natsClient->publishMessage({ content: message.toBytes(), subject: "demo.nats.basic"});
  1. Publish as a request that expects a reply:
1string message = "hello world";
2nats:Message|nats:Error reqReply =
3 natsClient->requestMessage({ content: message.toBytes(), subject: "demo.nats.basic"}, 5);
  1. Publish messages with a replyTo subject:
1string message = "hello world";
2nats:Error? result = natsClient->publish({ content: message.toBytes(), subject: "demo.nats.basic",
3 replyTo: "demo.reply" });

Listening to Incoming Messages

Listening to Messages from a NATS Server
  1. Listen to incoming messages with the onMessage remote method:
1// Binds the consumer to listen to the messages published to the 'demo.example.*' subject
2@nats:ServiceConfig {
3 subject: "demo.example.*"
4}
5service nats:Service on new nats:Listener(nats:DEFAULT_URL) {
6
7 remote function onMessage(nats:Message message) {
8 }
9}
  1. Listen to incoming messages and reply directly with the onRequest remote method:
1// Binds the consumer to listen to the messages published to the 'demo.example.*' subject
2@nats:ServiceConfig {
3 subject: "demo.example.*"
4}
5service nats:Service on new nats:Listener(nats:DEFAULT_URL) {
6
7 // The returned message will be published to the replyTo subject of the consumed message
8 remote function onRequest(nats:Message message) returns string? {
9 return "Reply Message";
10 }
11}

Advanced Usage

Setting up TLS

The Ballerina NATS module allows the use of TLS in communication. This setting expects a secure socket to be set in the connection configuration as shown below.

Configuring TLS in the nats:Listener
1nats:SecureSocket secured = {
2 cert: {
3 path: "<path>/truststore.p12",
4 password: "password"
5 },
6 key: {
7 path: "<path>/keystore.p12",
8 password: "password"
9 }
10};
11nats:Listener natsListener = check new("nats://serverone:4222", secureSocket = secured);
Configuring TLS in the nats:Client
1nats:SecureSocket secured = {
2 cert: {
3 path: "<path>/truststore.p12",
4 password: "password"
5 },
6 key: {
7 path: "<path>/keystore.p12",
8 password: "password"
9 }
10};
11nats:Client natsClient = check new("nats://serverone:4222", secureSocket = secured);

Listeners

[1]

Listener

Represents the NATS listener to which a subscription service should be bound in order to receive messages.

Clients

[1]

Client

The client provides the capability to publish messages to the NATS server.

Object Types

[1]

Service

The NATS service type

Records

[10]

CertKey

Represents combination of certificate, private key and private key password if encrypted.

ConnectionConfiguration

Configurations related to initializing the NATS client and listener.

Credentials

Configurations related to basic authentication.

Message

Represents the message, which a NATS server sends to its subscribed services.

PendingLimits

The configurations to set limits on the maximum number of messages or maximum size of messages this consumer will hold before it starts to drop new messages waiting for the resource functions to drain the queue.

Ping

Configurations related to pinging the server.

RetryConfig

Configurations related to connection reconnect attempts.

SecureSocket

Configurations related to facilitating a secure communication.

ServiceConfigData

The configurations for the NATS basic subscription.

Tokens

Configurations related to token based authentication.

Constants

[1]

DEFAULT_URL

Default URL for NATS connections.

Enums

[1]

Protocol

Represents protocol options.

Annotations

[1]

ServiceConfig

The annotation, which is used to configure the basic subscription.

Errors

[1]

Error

Represents the NATS module related errors.