ores.nats

Table of Contents

ores.nats is the NATS messaging transport library for ORE Studio. It provides all inter-service and client-server communication using NATS, replacing the former binary protocol stack (ores.comms).

Transport Model

All messaging uses NATS with JSON payloads serialised via rfl::json. Three patterns are used:

Request/Reply

Synchronous operations (queries, mutations) use NATS request/reply. The client sends a message to a subject and blocks for a reply: 

client.request("iam.v1.auth.login", json_payload);

The service handler reads the request, executes the operation, and publishes a JSON response to msg.reply_subject.

Queue Subscribe

Each domain service subscribes to its subject namespace using a queue group. NATS delivers each incoming message to exactly one instance in the group, providing load balancing and high availability: 

nats.queue_subscribe("iam.v1.>", "ores.iam.service", handler);

The wildcard > matches all subjects under the prefix.

JetStream

Durable, persistent messaging for asynchronous event streams uses JetStream. The jetstream_admin class provides stream and consumer management, message publishing, and message retrieval.

Subject Naming Convention

Subjects follow this structure: 

{domain}.v1.{entity}.{operation}

Where:

  • {domain} is the owning service (e.g. iam, refdata, trading)
  • v1 is the API version
  • {entity} is the resource being operated on (e.g. accounts, currencies)
  • {operation} is the verb (list, save, delete, history, etc.)

Subject Prefix

In multi-instance deployments a prefix can be prepended: 

{prefix}.{domain}.v1.{entity}.{operation}
# e.g. ores.dev.local1.iam.v1.accounts.list

The prefix is configured via nats_options::subject_prefix. When empty, subjects are used as-is (standard for single-instance or test deployments).

Configuration

NATS connection is configured via nats::config::nats_options:

Option Default Description
url nats://localhost:4222 NATS server URL
subject_prefix (empty) Optional multi-instance prefix

Command-line options (--nats-url, --nats-subject-prefix) are parsed by nats::config::nats_configuration following the same pattern as logging and database configuration.

Services

Each domain service owns a subject namespace and subscribes with a queue group. Requests that do not match any known subject return an error response.

Service Subject Namespace Queue Group Protocol Reference
ores.iam iam.v1.> ores.iam.service ores.iam Messaging Reference
ores.refdata refdata.v1.> ores.refdata.service ores.refdata Messaging Reference
ores.variability variability.v1.> ores.variability.service ores.variability Messaging Reference
ores.assets assets.v1.> ores.assets.service ores.assets Messaging Reference
ores.telemetry telemetry.v1.> ores.telemetry.service ores.telemetry Messaging Reference
ores.dq dq.v1.> ores.dq.service ores.dq Messaging Reference
ores.trading trading.v1.> ores.trading.service ores.trading Messaging Reference
ores.scheduler scheduler.v1.> ores.scheduler.service ores.scheduler Messaging Reference
ores.synthetic synthetic.v1.> ores.synthetic.service ores.synthetic Messaging Reference
ores.reporting reporting.v1.> ores.reporting.service ores.reporting Messaging Reference

Useful Pages