Add a NATS transport (NatsNetwork) for resonate-on-nats

Open
#5 0 comments 0 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

Assessment

Difficulty
4/5
Estimated time
3-5 days
Newbie friendliness
52/100
Issue type
Feature
Clarity
Mostly clear
Activity status
Quiet
Tech stack
java

Research direction

Start with src/main/java/io/resonatehq/resonate/Network.java and compare the TypeScript and Python NatsNetwork implementations referenced in the issue. Read resonate-on-nats/cmd/client.go to verify the JetStream subjects, headers, inbox replies, and receive subscriptions. Done means Java workers can use the NATS transport while preserving the stated envelope and dependency-packaging requirements.

Written by the indexing model from the issue text.

Description

Summary

resonate-on-nats is a Resonate server that uses NATS JetStream for both storage and transport. It exposes no HTTP endpoint, so the Java SDK's Network.HttpNetwork cannot reach it. The TypeScript and Python SDKs already ship a NatsNetwork implementation of their Network interface; the Java SDK has no equivalent, so Java workers cannot connect to a NATS-backed server.

Proposal

Add a Network.NatsNetwork implementing the Network interface (src/main/java/io/resonatehq/resonate/Network.java) on top of jnats. Since the SDK currently has no external runtime dependencies beyond Jackson, this may warrant a separate artifact or an optional dependency so the core stays lean.

Wire contract

The protocol envelope is unchanged — the same {kind, head, data} JSON with head.version = "2026-04-01" — only the carrier differs:

  • Send: publish the request envelope via JetStream to resonate.requests.{token}, where token is the base64url (no padding) encoding of the routing origin. The routing origin is the lineage root: the substring of the promise/task id before the first ., or "default" for requests without a lineage (schedules, debug).
  • Set head["resonate:origin"] on every request.
  • Reply: create a private inbox subject (_INBOX.*), subscribe to it, and set the Resonate-Reply-To NATS header on the publish. The response envelope (correlated by head.corrId) arrives on the inbox. NATS native request/reply is not used.
  • Recv: subscribe to resonate.recv.{group}.{pid} (unicast) and resonate.recv.{group} with queue group {group} (anycast) for inbound execute/unblock messages.

References

The TypeScript and Python implementations mirror each other closely and serve as the reference for the contract above.

Dominant language
Java
Stars
1
Forks
1
PR merge metrics
No merged PRs in 30d

Contributor guide

Open the contributing guide

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

More from resonatehq/resonate-sdk-java

All issues in resonatehq/resonate-sdk-java

Similar issues

More Java issues

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.