nats_client Class Reference

Authenticated NATS client for both interactive and service-to-service use. More...

#include <nats_client.hpp>

Collaboration diagram for nats_client:

Classes
struct	login_info
	Login state for the interactive path. More...

Public Types
using	token_provider = std::function< std::string(bool force)>
	Callable that returns a current Bearer token.

Public Member Functions
	nats_client ()=default
	Default-construct for interactive use. Call connect() next.
void	connect (config::nats_options opts)
	Connect to NATS and take ownership of the connection.
void	disconnect ()
	Disconnect and clear all auth state.
bool	is_connected () const noexcept
void	set_auth (login_info info)
	Store authentication info after a successful login.
void	clear_auth ()
	Clear authentication info on logout.
const login_info &	auth () const
	Return current auth info.
	nats_client (client &nats, token_provider provider)
	Construct for service-to-service use.
bool	is_logged_in () const noexcept
message	request (std::string_view subject, std::string_view json_body)
	Unauthenticated synchronous request.
message	authenticated_request (std::string_view subject, std::string_view json_body, std::chrono::milliseconds timeout=std::chrono::seconds(30))
	Authenticated synchronous request — string body overload.
message	authenticated_request (std::string_view subject, std::span< const std::byte > body, std::chrono::milliseconds timeout=std::chrono::seconds(10))
	Authenticated synchronous request — byte-span overload.
std::shared_ptr< client >	get_client () const
	Return the underlying client (interactive path only).

Detailed Description

Authenticated NATS client for both interactive and service-to-service use.

Wraps a NATS connection with JWT-based authentication, supporting two usage paths:

Interactive path (shell, Qt): the caller manages the connection lifecycle and supplies the JWT externally after a successful login.

nats_client nc;
nc.connect(opts);
// ... send login request via nc.request() ...
nc.set_auth({.jwt = token, .username = user, ...});
auto reply = nc.authenticated_request(subject, body);

Token refresh is reactive: the client throws session_expired_error on token_expired or max_session_exceeded (X-Error header). The caller is responsible for re-authenticating and calling set_auth() with the new token.

Service path (backend services): a token_provider callback is injected at construction. The provider is responsible for acquiring and proactively refreshing the JWT; nats_client calls it before each authenticated request.

auto provider = make_service_token_provider(raw_nats, user, pass);
nats_client nc(raw_nats, std::move(provider));
auto reply = nc.authenticated_request(subject, body);

The two paths are mutually exclusive on a given instance.

Member Typedef Documentation

token_provider

using token_provider = std::function<std::string(bool force)>

Callable that returns a current Bearer token.

Used by the service path. The provider owns all acquisition and proactive refresh logic; nats_client calls it before each request. When called with force=true the provider must discard any cached token and re-authenticate unconditionally (used after the server returns X-Error: token_expired to handle extreme clock-skew cases where the client's own expiry timer has not yet fired).

Constructor & Destructor Documentation

nats_client()

nats_client	(	client &	nats,
		token_provider	provider
	)

Construct for service-to-service use.

Parameters

nats	Already-connected NATS client (not owned; must outlive this).
provider	Callable that returns a current Bearer token. The provider owns acquisition and proactive refresh.

Member Function Documentation

connect()

void connect

(

config::nats_options

opts

)

Connect to NATS and take ownership of the connection.

Exceptions

std::runtime_error

if the connection fails.

Here is the caller graph for this function:

auth()

const nats_client::login_info & auth

(

)

const

Return current auth info.

Exceptions

std::runtime_error

if not logged in.

Here is the caller graph for this function:

request()

message request	(	std::string_view	subject,
		std::string_view	json_body
	)

Unauthenticated synchronous request.

Used for pre-login calls (login itself, JWKS fetch, bootstrap status).

Here is the caller graph for this function:

authenticated_request() [1/2]

message authenticated_request	(	std::string_view	subject,
		std::string_view	json_body,
		std::chrono::milliseconds	timeout = std::chrono::seconds(30)
	)

Authenticated synchronous request — string body overload.

Convenience for callers that already have the payload as a string.

Here is the caller graph for this function:

authenticated_request() [2/2]

message authenticated_request	(	std::string_view	subject,
		std::span< const std::byte >	body,
		std::chrono::milliseconds	timeout = std::chrono::seconds(10)
	)

Authenticated synchronous request — byte-span overload.

For callers that work with pre-serialised byte buffers.

get_client()

std::shared_ptr< client > get_client

(

)

const

Return the underlying client (interactive path only).

Returns nullptr if constructed via the service path.