ores::nats Namespace Reference

NATS transport layer — external message bus, cross-process connectivity. More...

Classes
struct	message
	A received NATS message. More...

Typedefs
using	message_handler = std::function< void(message)>
	Callback type for incoming NATS messages.

Functions
std::string	extract_or_generate_correlation_id (const message &msg)
	Extracts the correlation ID from an inbound NATS message header.
std::span< const std::byte >	as_bytes (std::string_view s) noexcept
	Reinterprets a string's character data as a read-only byte span.
std::string_view	as_string_view (const std::vector< std::byte > &data) noexcept
	Reinterprets a message's byte payload as a string_view.

Detailed Description

NATS transport layer — external message bus, cross-process connectivity.

Provides RAII wrappers around the cnats C library and higher-level facilities for domain services, the Qt client, and JetStream consumers. All components that communicate over NATS depend on this library rather than on cnats directly.

Subject naming conventions:

• Request/reply: ores.<domain>.<operation> (e.g. ores.iam.login)
• Pub/sub events: <tenant_id>.ores.<domain>.<event_name> (e.g. 499d2aaa.ores.refdata.currency_changed)
• JetStream streams: ores.<domain>.js.<stream> (e.g. ores.trading.js.trades)

Sub-namespaces (planned):

• connection: RAII wrappers for natsConnection and natsOptions; TLS configuration; connection lifecycle management.
• service: base class for domain microservices; binds a NATS subject and dispatches incoming requests to handler coroutines.
• client: Qt-side session; sends requests and receives replies via unique per-request _INBOX subjects (fully concurrent, no serialisation).
• messaging: typed request/reply message helpers built on top of the cnats publish/subscribe primitives.
• jetstream: JetStream consumer support; durable subscriptions for chart history replay and work-queue delivery to grid nodes.

Transport security: TLS (tls+tcp://) for encryption and server authentication; JWT RS256 tokens in message headers for client identity.

Contrast with ores.eventing (in-process pub/sub only, no network) and ores.mq (durable PostgreSQL-backed queues, persistent across restarts).

Function Documentation

extract_or_generate_correlation_id()

std::string extract_or_generate_correlation_id

(

const message &

msg

)

Extracts the correlation ID from an inbound NATS message header.

Returns the value of the Nats-Correlation-Id header if present. Generates and returns a new UUID v4 string if the header is absent, making this function safe to call at any service entry point regardless of whether the upstream caller populated the header.

Here is the caller graph for this function:

as_bytes()

std::span< const std::byte > as_bytes ( std::string_view  s )

noexcept

Reinterprets a string's character data as a read-only byte span.

Use this when calling request_sync() or publish() with a JSON/text payload that is already held in a std::string or std::string_view, so callers do not need to scatter reinterpret_cast throughout service code.

Here is the caller graph for this function:

as_string_view()

std::string_view as_string_view ( const std::vector< std::byte > &  data )

noexcept

Reinterprets a message's byte payload as a string_view.

Use this when deserialising a NATS reply payload with rfl::json::read or similar, so callers do not need to scatter reinterpret_cast throughout.