nats.go

nats.go is the reference Go client for NATS, the CNCF messaging system used to connect microservices, IoT devices, and edge deployments through publish-subscribe, request-reply, and queueing patterns. Maintained directly by the NATS core team (Synadia), it wraps the wire protocol in an idiomatic Go API covering connection management, automatic reconnection, TLS, and NKey/JWT-based authentication.

Beyond core pub-sub, the client ships a full JetStream package for persistent streaming — creating and managing streams and consumers, durable pull/push consumption, and higher-level KeyValue and Object Store abstractions built on top of JetStream. A separate micro package adds a lightweight framework for building discoverable, observable NATS-based microservices with health and stats endpoints out of the box.

As the reference implementation used across the NATS ecosystem’s documentation and examples, nats.go is the default choice for any Go service that needs lightweight, low-latency messaging without standing up a heavier message broker.

What You Get

• A core nats.Connect client with automatic reconnection, TLS, and NKey/JWT/token/user-password authentication helpers
• Publish, async/sync subscribe, queue groups, and request-reply APIs with configurable timeouts and buffering
• A jetstream subpackage for creating/managing streams and consumers and for durable pull/push message consumption
• Built-in KeyValue and Object Store abstractions layered on JetStream for simple distributed state without a separate database
• A micro subpackage for building discoverable NATS microservices with health checks, stats, and versioned endpoints
• WebSocket transport support (ws.go) for connecting to NATS over browser-compatible WebSocket links

Common Use Cases

• Connecting Go microservices for lightweight pub-sub and request-reply messaging without a heavyweight broker
• Building durable, at-least-once event pipelines using JetStream streams and consumers
• Using the KeyValue store as a fast, replicated key-value layer shared across services
• Exposing service discovery, health, and stats endpoints for a fleet of NATS-based microservices via the micro package
• Distributing large binary payloads (files, blobs) between services using the JetStream Object Store

Under The Hood

Architecture The client centers on a single Conn type in nats.go that owns the TCP/TLS socket, a buffered writer, and background goroutines for reading server frames, flushing writes, and driving reconnection; subscriptions, pending requests, and pub-sub dispatch are all coordinated through this connection object via mutex-protected maps rather than a layered service architecture. JetStream (in the jetstream package) and the micro service framework are built strictly on top of the core Conn/nats.Msg primitives — JetStream issues its stream/consumer management calls as ordinary NATS requests to well-known API subjects (js.go, jsm.go, jetstream/*.go), and micro wraps subscriptions with discovery/health conventions — so a change to the core connection or protocol parser (parser.go) is the one change that would ripple through every higher-level package.

Tech Stack The module targets Go 1.25 and keeps its dependency surface deliberately small: github.com/nats-io/nkeys and github.com/nats-io/nuid for NATS-specific cryptographic identity and ID generation, github.com/klauspost/compress for WebSocket flate compression, and only golang.org/x/crypto/golang.org/x/sys as indirect dependencies — no web framework, ORM, or database driver, since the library itself is the transport layer. A custom ws.go implements the WebSocket handshake and framing directly rather than pulling in a third-party WebSocket package.

Code Quality The project uses Go’s standard testing package (no assertion library like testify) across roughly fifty _test.go files spanning the root package, jetstream, and micro, with a dedicated go_test.mod to isolate test-only dependencies from the published module’s minimal dependency graph. CI runs go vet, staticcheck, golangci-lint, and misspell on every push and PR, and errors are handled explicitly throughout via sentinel Err* variables and errors.New/fmt.Errorf rather than panics, giving callers typed, checkable failure modes.

What Makes It Unique What distinguishes nats.go from a typical message-queue client is that it is a full client for a wire protocol its own maintainers evolve — it doubles as persistent streaming storage (JetStream), a replicated key-value and object store, and a microservice-discovery layer, all reachable through the same connection without introducing Kafka-, Redis-, or gRPC-style separate infrastructure. The WebSocket transport support also lets the identical client code connect from environments (like browsers via WASM) that can’t open raw TCP sockets, which few messaging clients offer natively.