NATS Connector

Overview

The NATS connector enables publish/subscribe messaging on a NATS server or cluster, with optional token or JWT credentials-file authentication.

Connector Types:

• NatsReader - Subscribe to a subject
• NatsWriter - Publish to a subject

NATS Reader

Subscribe to a subject:

{
  "type": "NatsReader",
  "config": {
    "url": "nats://localhost:4222",
    "subject": "sensors.temperature"
  }
}

Queue Group for Load Balancing

When queue is set, NATS distributes messages across all readers in the same queue group, so only one subscriber receives each message:

{
  "type": "NatsReader",
  "config": {
    "url": "nats://nats.example.com:4222",
    "subject": "factory.events.>",
    "queue": "meddle-workers"
  }
}

Token Authentication

{
  "type": "NatsReader",
  "config": {
    "url": "nats://nats.example.com:4222",
    "subject": "secure.events",
    "token": "s3cr3t-token"
  }
}

JWT Credentials File (NATS NGS / Decentralised Auth)

{
  "type": "NatsReader",
  "config": {
    "url": "tls://connect.ngs.global:4222",
    "subject": "events.>",
    "credsFile": "/etc/meddle/nats.creds"
  }
}

NATS Writer

Publish to a subject:

{
  "type": "NatsWriter",
  "config": {
    "url": "nats://localhost:4222",
    "subject": "processed.events"
  }
}

With JWT Credentials

{
  "type": "NatsWriter",
  "config": {
    "url": "tls://connect.ngs.global:4222",
    "subject": "processed.events",
    "credsFile": "/etc/meddle/nats.creds"
  }
}

Configuration Parameters

• url: NATS server URL (nats://host:port or tls://host:port); comma-separate for cluster URLs
• subject: Subject to subscribe or publish to (supports * and > wildcards on reader)
• queue: (Reader) Queue group name for load-balanced delivery
• token: (Optional) Token for token authentication
• credsFile: (Optional) Path to a NATS credentials (.creds) file for JWT/nkey auth

Subject Wildcards (Reader Only)

NATS subjects are dot-separated. Wildcards:

• * matches exactly one token: sensors.*.temperature
• > matches one or more trailing tokens: factory.events.>

Queue Groups

Queue groups give NATS-native horizontal scaling without external coordination:

• Multiple readers with the same queue share the message stream; each message goes to exactly one subscriber in the group.
• Multiple readers with different queue names (or no queue) each receive a full copy of every message.

Authentication

The connector picks credentials from the configuration in this order:

1. credsFile if set, using NATS user credentials (JWT + nkey seed)
2. token if set, using token authentication
3. Otherwise the connection is anonymous

Reconnection is automatic with a 2 second backoff and unlimited retries.

Related Connectors

• MQTT - Pub/sub for IoT devices
• Kafka - Durable log-based messaging
• AMQP - RabbitMQ pub/sub alternative