nats-server

nats-server is the reference server implementation for NATS.io, a lightweight and highly performant messaging system built for cloud, edge, and IoT-scale distributed systems. Written in Go with zero required external broker dependencies, it implements the core NATS protocol for publish/subscribe, request/reply, and queue-group messaging, alongside JetStream, its built-in persistence layer for streaming, at-least-once delivery, and Key/Value and Object Store APIs.

Deployed as a single static binary or Docker image, nats-server supports Raft-based clustering, gateway-linked super-clusters for multi-region topologies, leaf nodes for edge deployments, and TLS plus decentralized JWT/NKey-based authentication and account-level multi-tenancy. It is a CNCF-hosted project that has undergone a third-party security audit by Trail of Bits and backs infrastructure for IoT fleets, service meshes, and event-driven microservices.

What You Get

• Core NATS protocol support: publish/subscribe, request/reply, and queue-group load-balanced messaging over a lightweight text protocol
• JetStream persistence: at-least-once and exactly-once delivery, message replay, and built-in Key/Value and Object Store backed by streams
• Clustering and super-clusters: Raft-based clustering plus gateway-linked super-clusters for multi-region and multi-cloud topologies
• Leaf nodes: lightweight edge deployments that extend a core cluster to IoT devices and remote sites without full mesh connectivity
• Built-in security: TLS, decentralized JWT/NKey authentication, and account-based multi-tenancy with fine-grained subject permissions

Common Use Cases

• Service-to-service messaging in microservice architectures that need low-latency pub/sub or request/reply
• Event streaming and durable message replay for event-driven systems via JetStream
• IoT and edge fan-in/fan-out where leaf nodes bridge thousands of edge devices to a central cluster
• Distributed key/value coordination and configuration propagation using JetStream’s KV store
• Multi-region service mesh backbones built on NATS super-clusters and gateways

Under The Hood

Architecture nats-server is organized as a single server package (github.com/nats-io/nats-server/v2/server) fronted by a thin main.go that parses CLI flags into an Options struct (opts.go) and boots a Server via NewServer/Run. Core message routing lives in client.go and route.go, which implement per-connection state machines for clients, routes (cluster links), gateways (super-cluster links), and leaf nodes, all funneling through a central subject-interest trie for pub/sub dispatch. JetStream is layered on top as a large but self-contained subsystem (jetstream_cluster.go, jetstream_api.go, consumer.go) that reuses the same Raft-based clustering primitives as core clustering rather than introducing a separate consensus mechanism. Cross-cutting concerns, auth (auth.go, auth_callout.go), config parsing (a dedicated conf/ package with its own lexer/parser), and monitoring, are implemented as adjacent files within the same package rather than separate modules, which keeps the codebase navigable despite its size but means several core files run to thousands of lines. Changing the core Options struct or NewServer’s startup sequence would ripple through nearly every subsystem, since almost everything is constructed from a single Server struct.

Tech Stack nats-server targets a recent Go toolchain (per go.mod) and depends on a small, deliberately minimal set of first-party and adjacent-team libraries: nkeys and jwt for decentralized authentication, klauspost/compress for JetStream’s on-disk compression, minio/highwayhash for fast checksums, and the golang.org/x crypto, sys, and time packages for TLS, platform, and rate-limiting primitives. There is no ORM, database driver, or web framework; persistence for JetStream is a custom file-based store implemented directly in the server package rather than delegated to an external database. Build and release tooling uses GoReleaser for multi-platform binaries and Docker images, and CI runs across multiple dedicated GitHub Actions workflows covering standard tests, long-running cluster tests, nightly builds, protocol-specific tests, and vulnerability scanning.

Code Quality Testing is extensive and idiomatic Go: over 130 _test.go files sit alongside their implementation files, using the standard library testing package plus table-driven patterns, with long-running and cluster test suites separated into their own CI workflow given their runtime cost. Error handling favors typed, generated error values, jetstream_errors.go and a generated companion file define a structured ApiError catalog rather than ad hoc string errors, kept in sync via go generate. Code quality is enforced via golangci-lint with several linters enabled (govet, staticcheck, ineffassign, misspell, unused, forbidigo), plus a dedicated vulnerability-scanning workflow and a published third-party security audit. Naming follows standard Go convention and the project tracks coverage via Coveralls over time.

API Design As an embeddable Go module, nats-server exposes a single high-level entry point, server.NewServer(opts) followed by Start() or the Run() helper used in main.go, that mirrors the CLI’s own bootstrapping, so embedding the server in a test harness or another Go program requires little more than the CLI itself uses. Configuration is dual-path: either an Options struct built programmatically, or a NATS-specific config-file format parsed by a hand-written lexer/parser, which supports includes, environment-variable interpolation, and duration/size units, more expressive than plain JSON/YAML but adds a domain-specific syntax to learn. In-repo documentation for the Go API itself is thin; the README is intentionally minimal and mostly links out to the separate docs.nats.io site, so developers embedding the server lean on external docs and the nats.go client’s own examples rather than nats-server’s own README.