Module batch_publish 

Batch publishing support for NATS JetStream.

This module provides functionality for publishing multiple messages as an atomic batch to a JetStream stream. Batch publishing ensures that either all messages in a batch are stored or none are.

Overview

Batch publishing works by:

1. Assigning internally a unique batch ID to all messages in a batch
2. Publishing messages with special headers indicating batch membership
3. Committing the batch with a final message containing a commit marker

Thread Safety

The batch publisher types in this module are designed to be used from a single task/thread. They do not implement Send or Sync as they maintain internal mutable state during the batch publishing process.

If you need to share a batch publisher across threads, you should:

• Use separate BatchPublish instances per thread
• Clone the underlying JetStream context (which is Send + Sync + Clone)
• Coordinate batch IDs externally if needed

The underlying NATS client connection is thread-safe and can be shared across threads.

Usage Patterns

Standard API

Use BatchPublish when you need control over individual message publishing:

let mut batch = client.batch_publish().build();
batch.add("events.1", "data1".into()).await?;
batch.add("events.2", "data2".into()).await?;
let ack = batch.commit("events.3", "final".into()).await?;

Convenience API - Bulk Publishing

Use BatchPublishAllBuilder when you have all messages ready:

let messages = vec![/* ... */];
let ack = client.batch_publish_all()
    .publish(stream::iter(messages))
    .await?;

Flow Control

Both APIs support flow control through acknowledgments:

• ack_first() - Wait for server acknowledgment after the first message
• ack_every(n) - Wait for acknowledgment every N messages
• timeout(duration) - Set timeout for acknowledgment requests

Error Handling

All operations return BatchPublishError with specific error kinds:

• BatchPublishNotEnabled - Stream doesn’t have allow_atomic_publish enabled
• BatchPublishIncomplete - Too many outstanding batches (server limit: 50)
• BatchPublishUnsupportedHeader - Message contains Nats-Msg-Id or Nats-Expected-Last-Msg-Id
• MaxMessagesExceeded - Batch exceeds 1000 message limit
• EmptyBatch - Attempting to commit an empty batch

Server errors are automatically mapped to the appropriate error kind based on the error code. Errors during add with flow control may indicate transient issues or configuration problems.

Structs

BatchPubAck

Acknowledgment returned after successfully committing a batch.

BatchPublish

BatchPublishAllBuilder

Builder for bulk publishing multiple messages at once

BatchPublishBuilder

Enums

BatchPublishErrorKind

Kinds of errors that can occur during batch publish operations

Traits

BatchPublishExt

Type Aliases

BatchPublishError

Error type for batch publish operations