Skip to main content

​
Introduction

NATS Server is a high-performance messaging system built on a simple yet powerful architecture. At its core, NATS provides subject-based publish-subscribe messaging with support for request-reply patterns, all designed for horizontal scalability and operational simplicity.

​
Architectural Layers

NATS Server operates with two distinct architectural layers:

​
Core NATS

Core NATS provides the foundational messaging layer with:
  • At-most-once delivery: Messages are delivered to connected subscribers or discarded
  • Pure pub-sub: Fire-and-forget messaging with no persistence
  • Subject-based routing: Messages are routed based on hierarchical subject names
  • Minimal overhead: Designed for high throughput and low latency
Core NATS is stateless and requires no disk I/O, making it extremely fast and suitable for scenarios where message delivery guarantees are handled by the application layer.

​
JetStream Layer

JetStream adds persistence and streaming capabilities on top of Core NATS:
  • At-least-once delivery: Messages are persisted and can be replayed
  • Stream storage: Messages are stored in streams for replay and recovery
  • Consumer semantics: Multiple consumer types for different delivery patterns
  • Horizontal scalability: Streams can be replicated across cluster members
JetStream is optional and can be enabled per-account, allowing you to use persistence only where needed while keeping the rest of your messaging lightweight.

​
Subject-Based Messaging Model

NATS uses a hierarchical subject naming system that forms the foundation of message routing. Subjects are UTF-8 strings composed of tokens separated by dots (.).

​
Subject Format

orders.electronics.laptops.shipped
Subjects support two types of wildcards:
  • Single token wildcard (*): Matches exactly one token
    • orders.*.laptops.shipped matches orders.electronics.laptops.shipped
  • Multi-token wildcard (>): Matches one or more trailing tokens
    • orders.> matches all orders subjects

​
Subject Matching with Sublist

The server uses an optimized data structure called a Sublist to efficiently match published messages to subscriptions. The Sublist implements a trie-based algorithm that provides O(1) average-case lookups with support for wildcard matching. Key characteristics from server/sublist.go:26-29:
  • Routes messages from publishers to interested subscribers
  • Handles wildcard subscriptions efficiently
  • Maintains a cache for frequently matched subjects
  • Supports notification channels for subscription changes

​
Client Connection Architecture

NATS Server supports multiple connection types, each serving a different purpose:

​
Connection Types

From server/client.go:45-60:
  • CLIENT: End-user applications connecting to NATS
  • ROUTER: Cluster connections between NATS servers
  • GATEWAY: Connections linking separate clusters into super-clusters
  • LEAF: Leaf node connections for hub-and-spoke topologies
  • SYSTEM: Internal system clients for server operations
  • JETSTREAM: Internal clients for JetStream operations

​
Protocol Support

The server supports multiple client protocols:
  • NATS Protocol: The native text-based protocol
  • WebSocket: For browser-based and firewall-friendly connections
  • MQTT: MQTT 3.1.1 compatibility for IoT devices

​
Connection Lifecycle

Client connections follow a specific lifecycle from server/client.go:140-157:
  1. Initial connection: TCP connection established
  2. INFO exchange: Server sends INFO, optionally receives CONNECT
  3. Authentication: Credentials validated
  4. Active messaging: Client can publish and subscribe
  5. Ping/Pong: Keepalive mechanism maintains connection health
  6. Graceful shutdown: DRAIN protocol for clean disconnection

​
Scalability and Performance Characteristics

​
Horizontal Scalability

NATS achieves horizontal scalability through several mechanisms:
  • Clustering: Multiple servers form a full mesh for high availability
  • Gateways: Connect clusters across regions without full mesh overhead
  • Leaf nodes: Extend reach with hub-and-spoke connections
  • Account isolation: Each account maintains separate subscription space

​
Performance Optimizations

Key performance features:
  • Zero-copy message routing: Messages flow through the server without unnecessary copying
  • Lock-free data structures: Atomic operations minimize contention
  • Adaptive buffering: Dynamic buffer sizing from server/client.go:110-113
  • Compression: Optional S2 compression for route and gateway connections
  • Optimistic routing: Gateway interest-based routing reduces unnecessary traffic

​
Memory and Resource Management

The server implements several strategies for efficient resource utilization:
  • Buffer pooling: Reusable buffers reduce GC pressure
  • Subscription caching: Hot paths cached for faster lookup
  • Connection limits: Per-account connection and subscription limits
  • Slow consumer detection: Automatic handling of backed-up consumers

​
Message Flow

When a message is published:
  1. Subject parsing: The server tokenizes the subject
  2. Subscription matching: Sublist efficiently finds matching subscriptions
  3. Account isolation: Only subscriptions within the same account receive the message
  4. Queue distribution: For queue subscribers, one member receives the message
  5. Delivery: Message written to matching client connections
  6. Import/Export: Messages cross account boundaries only via explicit exports/imports

​
Multi-Tenancy with Accounts

NATS implements strong multi-tenancy through accounts, which create isolated subject spaces. Each account:
  • Maintains its own subscription tree
  • Cannot see messages from other accounts by default
  • Can selectively export streams or services to other accounts
  • Can import streams or services from other accounts
See the Accounts page for detailed information on multi-tenancy.

​
Server Topologies

NATS supports various deployment topologies:

​
Single Server

Simplest deployment for development and small-scale production.

​
Cluster

Full mesh of servers providing high availability and load distribution. See Clustering.

​
Super-Cluster

Multiple clusters connected via gateways for geo-distribution. See Gateways.

​
Hub and Spoke

Leaf nodes connecting to a central hub or cluster. See Gateways.

​
Next Steps

Clustering

Learn how NATS servers form clusters for high availability

Gateways

Explore super-clusters and multi-region connectivity

Accounts

Understand multi-tenancy and account isolation

Build docs developers (and LLMs) love

Get started for freeTalk to us