jetstream_admin Class Reference

JetStream management API. More...

#include <jetstream_admin.hpp>

Collaboration diagram for jetstream_admin:

Public Member Functions
	jetstream_admin (void *js_ctx) noexcept
	Construct from an opaque JetStream context pointer.
void	ensure_stream (std::string_view name, std::vector< std::string > subjects, int max_age_days=7)
	Create a durable stream covering subjects, or update it if a stream with name already exists.
std::vector< domain::stream_info >	list_streams ()
	List all streams on the connected NATS server.
domain::stream_info	get_stream (std::string_view name)
	Get metadata for a single stream by name.
void	purge_stream (std::string_view name)
	Purge all messages from a stream (non-destructive to the stream itself — consumers and configuration are preserved).
std::vector< domain::consumer_info >	list_consumers (std::string_view stream_name)
	List all consumers for a stream.
domain::stream_message	peek_message (std::string_view stream_name, std::uint64_t sequence)
	Peek at a message by sequence number (non-destructive).
domain::stream_message	peek_last_message (std::string_view stream_name, std::string_view subject)
	Peek at the last message published to a subject (non-destructive).
void	delete_message (std::string_view stream_name, std::uint64_t sequence)
	Delete a message by sequence number.
void	publish (std::string_view subject, std::string_view payload)
	Publish a message to a JetStream subject.

Detailed Description

JetStream management API.

Wraps the cnats JetStream management functions. No cnats types appear in this header — all cnats state is held as an opaque void* internally.

Obtain an instance via client::make_admin() after connecting. The admin is lightweight (a single pointer) and can be copied freely. The underlying client must outlive all admin instances derived from it.

All methods throw std::runtime_error on failure.

Usage

auto admin = nats_client.make_admin();
auto streams = admin.list_streams();
for (const auto& s : streams)
    auto consumers = admin.list_consumers(s.name);

Constructor & Destructor Documentation

jetstream_admin()

jetstream_admin ( void *  js_ctx )

explicitnoexcept

Construct from an opaque JetStream context pointer.

Only callable from client::make_admin(). The void* is a jsCtx*.

Member Function Documentation

ensure_stream()

void ensure_stream	(	std::string_view	name,
		std::vector< std::string >	subjects,
		int	max_age_days = 7
	)

Create a durable stream covering subjects, or update it if a stream with name already exists.

Idempotent: safe to call on every service startup. The stream uses file-backed storage and retains messages for up to max_age_days days.

Parameters

name	Stream name (NATS naming rules: A-Z a-z 0-9 - _).
subjects	Subjects the stream captures (fully-qualified, including any subject prefix).
max_age_days	How long messages are retained (default: 7 days).

delete_message()

void delete_message	(	std::string_view	stream_name,
		std::uint64_t	sequence
	)

Delete a message by sequence number.

The message is removed from the stream. This cannot be undone.

publish()

void publish	(	std::string_view	subject,
		std::string_view	payload
	)

Publish a message to a JetStream subject.

The subject must be covered by an existing stream. Blocks until the server acknowledges. Payload is treated as raw bytes.