Tcl client library for the NATS message broker

Learn more about NATS here and Tcl/Tk here.

Feature-wise, the package is comparable to other NATS clients and is inspired by the official nats.py and nats.go.

With this package you can bring the power of the publish/subscribe mechanism to your Tcl and significantly simplify development of distributed applications.

The API reference documentation is split into Core NATS, JetStream and Key-Value Store.

Supported platforms

The package is written in pure Tcl, without any C code, and so will work anywhere with Tcl 8.6 and Tcllib. If you need to connect to a NATS server using TLS, of course you will need the TclTLS package too. On Windows, these packages are normally included in Tcl installers, and on Linux they should be available from your distribution's package manager.

Installing

The package is available in two forms:

1. As a classic Tcl package using pkgIndex.tcl. Download/clone the repository to one of places listed in your $auto_path. Or you can extend $auto_path with a new folder, e.g.:

   lappend auto_path <path>
   

   or using an environment variable:

   export TCLLIBPATH=<path>
   

2. As a Tcl module, where all implementation is put into a single *.tm file. This improves package loading time. Note that Tcl modules are loaded from different locations than $auto_path. You can check them with the following command:

   tcl::tm::path list
   

   and you can extend this list with:

   tcl::tm::path add <path>
   

Both forms can be loaded as:

package require nats

If you are using a "batteries-included" Tcl distribution, like Magicsplat or AndroWish, you might already have the package.

Supported features

• Publish and receive messages, also with headers (NATS version 2.2+)
• Synchronous and asynchronous requests (optimized: under the hood a single wildcard subscription is used for all requests)
• Queue groups
• Gather multiple responses to a request
• Publishing and consuming messages from JetStream, providing "at least once" or "exactly once" delivery guarantee
• Management of JetStream streams, consumers and Key-Value buckets
• Key-Value store, including watchers
• Hub/leaf JetStream topology
• Standard configure method with many options
• Protected connections using TLS
• Automatic reconnection in case of network or server failure
• Authentication with a login+password, an authentication token or a TLS certificate
• Cluster support (including receiving additional server addresses from INFO messages)
• Configurable logging, compatible with the logger package
• (Windows-specific) If the iocp package is available, the client will use it for better TCP socket performance
• Extensive test suite with 230+ unit tests, checking nominal use cases, error handling, timings and the wire protocol ensures that the Tcl client behaves in line with official NATS clients

Examples

Look into the examples folder.

Implemented ADRs

ADRs (architecture decision records) provide a single source of truth that all NATS clients should follow. Thus, they have been immensely helpful in understanding the NATS design and rationale behind it. The Tcl client follows these ADRs:

ADR	Title	Comment
ADR-1	JetStream JSON API Design
ADR-4	NATS Message Headers
ADR-6	Naming Rules
ADR-8	JetStream based Key-Value Stores	Including Oct 2023 updates with API v1.1
ADR-9	JetStream Consumer Idle Heartbeats
ADR-10	JetStream Extended Purge
ADR-13	Pull Subscribe internals
ADR-15	JetStream Subscribe Workflow
ADR-17	Ordered Consumer
ADR-19	API prefixes for materialized JetStream views
ADR-31	JetStream Direct Get
ADR-33	Metadata for Stream and Consumer
ADR-36	Subject Mapping Transforms in Streams

API documentation in this repository focuses on specific details of the Tcl implementation. Users are expected to have sufficient understanding of NATS in general, so other information is provided through links to ADRs and other external docs.

Missing features (in comparison to official NATS clients)

• Authentication with NKey & JWT.
• WebSocket is not supported. The only available transport is TCP.
• Object Store