NATS

MAPS provides a NATS interface for core pub/sub and optional JetStream features (streams, key-value, object store).
Use it to bridge MAPS topics with NATS subjects or to expose MAPS as a NATS server endpoint.

---

Quick Start (Minimal)

interfaces:
  - name: "NATS Interface"
    url: "tcp://0.0.0.0:4222/"
    protocol: nats
    auth: default

• Binds on TCP 4222.
• Uses your auth: default security profile.

---

JetStream Features (Optional)

Enable per your needs:

interfaces:
  - name: "NATS + JetStream"
    url: "tcp://0.0.0.0:4222/"
    protocol: nats
    auth: default
    enableStreams: true
    enableKeyValues: true
    enableObjectStore: true

• Streams: persistent subjects (JetStream).
• KeyValues: NATS KV buckets (for small config/state).
• ObjectStore: NATS large-object buckets.

---

Configuration Reference

These map 1:1 to NatsConfigDTO (and common protocol fields via ProtocolConfigFactory).

Field	Type	Default	Description
url	string	—	Bind or connect URL, e.g. tcp://0.0.0.0:4222/.
protocol	enum	—	Must be nats.
auth	string	—	Auth profile (see Security docs).
keepAlive	int (s)	impl default	TCP keepalive/heartbeat interval.
maximumBufferSize	int (B)	impl default	Max per-connection buffer before backpressure.
maximumReceive	int (B)	impl default	Max inbound message size accepted.
namespaceRoot	string	""	Prefix that maps MAPS namespaces ⇆ NATS subjects.
enableStreams	boolean	false	Enable JetStream streams.
enableKeyValues	boolean	false	Enable JetStream key-value buckets.
enableObjectStore	boolean	false	Enable JetStream object store.
enableStreamDelete	boolean	false	Allow stream deletion operations.
(common TLS/settings)	—	—	Handled by common protocol config (certs, ciphers, timeouts).

Note: If namespaceRoot is set, MAPS will anchor subject mappings under that root. Leave empty for flat/global mapping.

---

Mapping & Routing

• Subjects ↔ Topics: MAPS normalizes NATS subjects into topic paths; wildcards are preserved (> ⇆ #, * ⇆ +).
• Streams: When enableStreams=true, MAPS exposes JetStream controls to create/update/delete streams (guarded by enableStreamDelete).
• KV/Object: When enabled, MAPS routes KV puts/gets and object operations via the same interface.

---

Examples

Core with Size Guards

interfaces:
  - name: "NATS Core (guarded)"
    url: "tcp://0.0.0.0:4222/"
    protocol: nats
    auth: default
    maximumBufferSize: 10485760   # 10 MiB
    maximumReceive: 1048576       # 1 MiB cap
    keepAlive: 30

Namespaced JetStream

interfaces:
  - name: "NATS JetStream (namespaced)"
    url: "tcp://0.0.0.0:4222/"
    protocol: nats
    auth: default
    namespaceRoot: "maps"
    enableStreams: true
    enableKeyValues: true
    enableObjectStore: true
    enableStreamDelete: false

---

Operational Notes

• Backpressure: maximumBufferSize protects memory on bursts; tune alongside broker flow control.
• Safety: keep enableStreamDelete=false in production to avoid accidental data loss.
• Security: rely on your MAPS auth profile (mTLS, users, ACLs).
• Interop: subjects are case-sensitive; keep a consistent naming convention when bridging.