Skip to content

Support ADR 50 Fast Ingest with constants #1628

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
scottf merged 2 commits into from
Sep 7, 2026
+48 −0
Merged

Support ADR 50 Fast Ingest with constants #1628

Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
b86eb79
Support ADR 50 Fast Ingest with constants
scottf Sep 7, 2026
ed8d4e3
address review
scottf Sep 7, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
48 changes: 48 additions & 0 deletions src/main/java/io/nats/client/support/NatsJetStreamConstants.java
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -154,10 +154,58 @@ public interface NatsJetStreamConstants {
String NATS_BATCH_SEQUENCE_HDR = "Nats-Batch-Sequence";
String NATS_BATCH_COMMIT_HDR = "Nats-Batch-Commit";

// Values for NATS_BATCH_COMMIT_HDR.
// Presence of the header marks the commit message, the value selects the mode.
// STORE is the original 2.12 value, a boolean true, and stores the final message.
// EOB commits the batch without storing the final message. Server 2.14+
String NATS_BATCH_COMMIT_STORE = "1";

@synadia-claude-reviewer synadia-claude-reviewer Bot Sep 7, 2026

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The value "1" for NATS_BATCH_COMMIT_STORE is not immediately obvious. Could this be a boolean-ish wire value (1 = true/store)? A brief comment noting the exact wire format or a link to the ADR/spec would help future readers — the name implies "store" but the value doesn't make that self-evident.

@scottf scottf Sep 7, 2026

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Good instinct - "1" is exactly a boolean true. Expanded the comment block above the constants: the header's presence marks the commit message, the value selects the mode, and "1" is the original 2.12 value from before eob existed. Skipped an ADR link since no other constant in this file carries one.

String NATS_BATCH_COMMIT_EOB = "eob";

// Fast ingest batch publish reply subject, which carries the batch control state.
// <prefix>.<batch-id>.<initial-flow>.<gap-mode>.<batch-sequence>.<operation>.$FI
// The server parses this right to left, so the prefix may itself contain dots.
String FAST_BATCH_SUFFIX = "$FI";
String FAST_BATCH_GAP_OK = "ok";
String FAST_BATCH_GAP_FAIL = "fail";

// Fast ingest batch publish operations, the subject token just before FAST_BATCH_SUFFIX.
// These are subject tokens, not header values, so they are strings on the wire.
String FAST_BATCH_OP_START = "0";
String FAST_BATCH_OP_APPEND = "1";
String FAST_BATCH_OP_COMMIT = "2";
String FAST_BATCH_OP_COMMIT_EOB = "3";
String FAST_BATCH_OP_PING = "4";

// Fast ingest flow control message types, the value of the "type" field.
// A publish ack has no "type" field, which is what tells the two apart.
String FAST_BATCH_TYPE_ACK = "ack";
String FAST_BATCH_TYPE_GAP = "gap";
String FAST_BATCH_TYPE_ERR = "err";

String NATS_PIN_ID_HDR = "Nats-Pin-Id";

int JS_CONSUMER_NOT_FOUND_ERR = 10014;
int JS_NO_MESSAGE_FOUND_ERR = 10037;
int JS_WRONG_LAST_SEQUENCE = 10071;
int JS_SEQUENCE_TEMPORARILY_UNKNOWN = 10164;

// Atomic batch publish server errors
int JS_ATOMIC_PUBLISH_DISABLED = 10174;
int JS_ATOMIC_PUBLISH_MISSING_SEQ = 10175;
int JS_ATOMIC_PUBLISH_INCOMPLETE_BATCH = 10176;
int JS_ATOMIC_PUBLISH_UNSUPPORTED_HEADER = 10177;
int JS_ATOMIC_PUBLISH_INVALID_BATCH_ID = 10179;

@synadia-claude-reviewer synadia-claude-reviewer Bot Sep 7, 2026

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Error code 10178 is missing between JS_ATOMIC_PUBLISH_UNSUPPORTED_HEADER (10177) and JS_ATOMIC_PUBLISH_INVALID_BATCH_ID (10179). Similarly, 10180–10198 are skipped before 10199. If these are intentionally unhandled by the client (server-internal or reserved), a brief comment would prevent future contributors from wondering if they were accidentally omitted.

@scottf scottf Sep 7, 2026

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

10178 is JSConsumerPushWithPriorityGroupErr (push consumers + priority groups), not a batch error, so it's correctly absent - same for most of 10180-10197.

But checking that range turned up 10198 JSMirrorWithAtomicPublishErr, which is ours and was missing. Added as JS_MIRROR_WITH_ATOMIC_PUBLISH.

Not annotating the remaining gaps: this is a curated set of batch-publish codes, not a contiguous range, and comments about other features' codes would rot here.

int JS_MIRROR_WITH_ATOMIC_PUBLISH = 10198;
int JS_ATOMIC_PUBLISH_TOO_LARGE_BATCH = 10199;
int JS_ATOMIC_PUBLISH_INVALID_BATCH_COMMIT = 10200;
int JS_ATOMIC_PUBLISH_DUPLICATE_MESSAGE = 10201;
int JS_ATOMIC_PUBLISH_TOO_MANY_INFLIGHT = 10210;

// Fast ingest batch publish server errors
int JS_BATCH_PUBLISH_DISABLED = 10205;
int JS_BATCH_PUBLISH_INVALID_PATTERN = 10206;
int JS_BATCH_PUBLISH_INVALID_BATCH_ID = 10207;
int JS_BATCH_PUBLISH_UNKNOWN_BATCH_ID = 10208;
int JS_MIRROR_WITH_BATCH_PUBLISH = 10209;
int JS_BATCH_PUBLISH_TOO_MANY_INFLIGHT = 10211;

@synadia-claude-reviewer synadia-claude-reviewer Bot Sep 7, 2026

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Code 10209 is absent in both the atomic and batch-publish error groups. JS_BATCH_PUBLISH_TOO_MANY_INFLIGHT jumps from 10208 to 10211 (10209/10210 are already taken by atomic publish). Intentional? If so, a comment helps. If not, it may indicate a missing constant.

@scottf scottf Sep 7, 2026

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Correct, though not for the stated reason - 10209 is JSMirrorWithBatchPublishErr, not a code taken by atomic publish. Added as JS_MIRROR_WITH_BATCH_PUBLISH, alongside its atomic twin 10198.

Both come from ADR-50's "Mirrors and Sources" section; I'd pulled error codes from the publish path only and missed the stream-config ones. The full set now matches every batch/atomic code in the server's errors.json - 16 of 16, verified programmatically.

}