> Status: draft. Part of the Harmovela 0.2 transport-nats profile.
Define how Harmovela runs over NATS, supporting subject-based publish/subscribe with optional JetStream durability.
Harmovela over NATS uses JSON-encoded Harmovela events as NATS message bodies:
Harmovela topics map to NATS subjects using a configurable prefix:
| Harmovela context | NATS subject pattern | Example |
|---|---|---|
Topic tasks.task_01 | aep.tasks.task_01 | aep.tasks.task_01 |
Source agent:researcher | aep.agent.researcher | aep.agent.researcher |
Wildcard subscription task.* | aep.task.> | aep.task.> |
| Session-scoped | aep.sess.<session_id> | aep.sess.sess_01 |
The default subject prefix is aep. Implementations should make this configurable.
| Pattern | Behavior |
|---|---|
aep.type.<type> | Route by event type (e.g. aep.type.task.progress) |
aep.source.<source> | Route by event source |
aep.topic.<topic> | Route by explicit Harmovela topic |
aep.sess.<session_id> | Route to all events for a session |
aep.conv.<conversation_id> | Route to all events for a conversation |
Producers should publish on the most specific subject. Consumers subscribe with wildcards.
best_effort: fire-and-forget publish. No acknowledgement or replay guarantee.at_least_once: JetStream consumer with explicit ack. Messages are persisted and re-delivered on timeout.replayable: JetStream stream with configurable retention. Consumers replay from any sequence number.| Harmovela Delivery Mode | NATS Mechanism |
|---|---|
best_effort | Core NATS publish |
at_least_once | JetStream push consumer with AckWait |
replayable | JetStream pull consumer with DeliverPolicy |
| NATS State | Session State |
|---|---|
| Connection established | CREATED |
| First subscription created | OPENED |
| Capability negotiation complete | READY |
| Connection drain + close | CLOSED |
| Connection lost (no reconnect) | ERROR |
The transport should support:
nats://localhost:4222 (default)tls:// URLsnats.Conn.Subscribe(subject, handler) for inbound.nats.Conn.Publish(subject, data) for outbound.js.AddStream(&nats.StreamConfig{...}) to create a stream on first use.js.Subscribe(subject, handler, ...opts) for durable consumers.