You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@pulsar.apache.org by mm...@apache.org on 2026/07/16 15:31:20 UTC
(pulsar-client-cpp) branch main updated: Scalable Topics: `pulsar::st` producer — per-segment fan-out, key routing, MessageId (#601)
This is an automated email from the ASF dual-hosted git repository.
merlimat pushed a commit to branch main
in repository https://gitbox.apache.org/repos/asf/pulsar-client-cpp.git
The following commit(s) were added to refs/heads/main by this push:
new b4a6c20b Scalable Topics: `pulsar::st` producer — per-segment fan-out, key routing, MessageId (#601)
b4a6c20b is described below
commit b4a6c20b8b00529e7972871825a460bdd7516c76
Author: Matteo Merli <mm...@apache.org>
AuthorDate: Thu Jul 16 08:31:14 2026 -0700
Scalable Topics: `pulsar::st` producer — per-segment fan-out, key routing, MessageId (#601)
* st: teach the classic client the segment:// topic domain
The per-segment producers of a scalable topic attach to its segment://
backing topics through the classic producer machinery, so the classic
TopicName must understand the domain - while the classic user-facing API
must keep rejecting it (only the pulsar::st client may touch segment
topics). Ported from the Java client's TopicName/PulsarClientImpl changes.
- TopicName: new TopicDomain::Segment. segment://<tenant>/<ns>/<parent>/
<descriptor> always parses as the new (cluster-less) format - the local
name contains a '/', so the token-count heuristic must not mistake it for
a legacy V1 name - and requires the descriptor component. isPersistent()
is true for segment topics (they are the persistent backing topics of one
segment, matching Java); new isSegment() accessor. Classic
persistent/non-persistent parsing is unchanged, and topic:// (the
scalable-topic identity scheme) intentionally stays unparseable here -
the st client resolves it before this layer.
- ClientImpl: every user-facing entry point (createProducerAsync, the
subscribe funnel, createReaderAsyncV2, createTableViewAsyncV2,
getPartitionsForTopicAsync) now rejects segment topics with
ResultInvalidTopicName and a message pointing at the pulsar::st API,
mirroring the Java client's scalable-domain check. The new
createSegmentProducerAsync() bypasses the rejection for lib/st (the
Java-parity escape hatch); consumer-side bypasses come with their phases.
- tests/st/StTopicNameTest.cc: segment parse (fields, slashed local name,
roundtrip, persistent/segment flags, never partitioned), descriptor
requirement, classic-format regression, and broker-free rejection of
segment topics through the classic producer/subscribe/reader API.
Verified: 74/74 pulsar-st-tests green; the classic TopicNameTest (16
tests, broker-free) and pulsar-tests/pulsarShared builds stay green;
clang-format-11 clean.
Signed-off-by: Matteo Merli <mm...@apache.org>
* st: MessageId implementation - segment-qualified ids
The scalable-topic MessageId, ported field-for-field from the Java client's
MessageIdV5 so serialized ids interoperate between the two clients.
- MessageIdImpl wraps the classic per-segment MessageId plus the segment it
belongs to (segmentId -1 = the cross-segment sentinels), with the optional
sections the consumer side will fill later: a per-segment position vector
(cumulative-ack StreamConsumer ids), the parent topic:// identity, and
cross-topic vectors (namespace consumers). The producer path fills only
v4MessageId + segmentId. MessageIdFactory (the friend the public header
already declared) is how lib/st mints ids and reaches their state.
- toByteArray()/fromByteArray() implement the MessageIdV5 wire layout
(big-endian: segmentId, classic-id bytes, position vector, parent topic
with -1-absent sentinel, multi-topic vector; trailing sections optional on
read). Malformed input returns an empty (falsy) id on the non-throwing
surface instead of throwing.
- Ordering compares (segmentId, then classic id), matching MessageIdV5;
empty ids sort first and equal each other. operator<< renders
{segment=..., id=..., positions=...}. std::hash combines the segment and
classic-id fields, completing the P6 unordered-container support.
- earliest()/latest() wrap the classic sentinels with the no-segment marker.
tests/st/StMessageIdTest.cc: sentinels, within/across-segment ordering,
empty-id semantics, unordered_set usage, stream output, producer-path and
full-section byte roundtrips, malformed/truncated input, empty
serialization. 83/83 pulsar-st-tests green; gcc-13 parity; clang-format-11
clean.
Signed-off-by: Matteo Merli <mm...@apache.org>
* st: thread assignedBrokerUrl to per-segment producers (broker pinning)
Scalable-topics per-segment producers should connect straight to the
DAG-provided owner broker instead of doing a fresh topic lookup. The
connection machinery already supports this (HandlerBase::grabCnx(url) ->
getConnection -> ClientImpl::connect), so this only threads an optional
assignedBrokerUrl from createSegmentProducerAsync down to the initial
connect:
- HandlerBase::start(assignedBrokerUrl) overload; start() delegates to it
with nullopt (grabCnx() is already grabCnx(std::nullopt), so existing
handlers are unaffected).
- ProducerImpl stores assignedBrokerUrl_ and passes it to the initial
HandlerBase::start(); a defaulted trailing ctor param keeps every other
caller unchanged.
- createSegmentProducerAsync / createProducerAsyncImpl / handleCreateProducer
thread the optional through (default nullopt; the public producer path is
unchanged).
* st: producer seam — ProducerImplBase + ProducerCore forwarders
Define the impl side of the already-declared detail::ProducerCore so a real
producer can be wired behind it:
- lib/st/ProducerImplBase.h: the abstract pulsar::st::ProducerImplBase the
core forwards to (six methods matching ProducerCore; matches the existing
forward-decl in detail/ProducerCore.h).
- lib/st/ProducerCore.cc: out-of-line definitions of the six ProducerCore
methods, each a one-line forward to the impl. Required now that a producer
will actually construct a core (a PULSAR_PUBLIC class must not leave
exported methods undefined — cf. the Transaction/Windows-DLL fix).
- ProducerCore.h: friend pulsar::st::ClientImpl so createProducerAsync can
mint a core from the impl pointer.
* st: StProducerImpl — per-segment producer fan-out (slice 3)
Implement the scalable-topics producer behind detail::ProducerCore, a port of
the Java v5 ScalableTopicProducer:
- Owns one DagWatchSession per topic and one SegmentRouter. Per active segment,
a classic pulsar::Producer is created via createSegmentProducerAsync, pinned
to the DAG-provided owner broker, cached as its creation Future so concurrent
cold senders share one attempt.
- sendAsync routes each OutgoingMessage by key (round-robin when keyless) to a
segment, publishes via the classic producer, and mints the returned id with
the segment id into a pulsar::st::MessageId. Route failure is terminal; a
sealed/terminated segment retries with backoff (<=10, min(100*(n+1),500)ms)
and re-routes onto the layout the DAG watch delivers.
- Layout changes retire producers for departed segments; exclusive access modes
eagerly attach (and fail create() up front if the claim is refused), Shared
attaches lazily on first send.
- lastSequenceId maxes ready producers over the configured initial; flush awaits
the in-flight send snapshot; close is idempotent (dag watch + all producers).
Correctness details baked in from the design review: per-segment config is built
FRESH each time (ProducerConfiguration's copy ctor shares its impl); the current
layout is a never-null default (route yields ResultServiceUnitNotReady, not a
null deref); access modes are mapped by NAME (the st and classic enums differ in
value); a transactional send fails with ResultOperationNotSupported (never
asserts); the in-flight entry is inserted before dispatch (warm sends complete
synchronously); the layout listener captures a weak_ptr (no ownership cycle).
No per-segment dispatch chain is needed — st::Future fires listeners in FIFO
registration order, so same-segment sends dispatch in call order for free; a
FutureTest locks that guarantee in. StClientImpl::createProducerAsync now builds
a real producer (the not-supported stub and its test are gone).
* st: broker-free StProducerImpl unit tests
Cover the pure, connection-independent logic through a small friend accessor:
- Per-segment config isolation — the regression guard for the shallow
ProducerConfiguration copy: building a second segment's config must not rename
or re-mark the first (fresh config per segment).
- Access-mode mapping by name — st and classic ProducerAccessMode enums differ
in numeric value, so WaitForExclusive / ExclusiveWithFencing must not be cast.
- Segment-gone classification — TopicTerminated / AlreadyClosed retry;
ServiceUnitNotReady and ConnectError do not (no retry-loop on a transient
routing miss).
- Minted MessageId carries the real segment id.
* st: take send-path Promise by const-ref (clang-tidy performance)
dispatchSend/handleSegmentFailure took the user's Promise by value but only
capture-copy it into their continuation lambdas — const-ref silences
performance-unnecessary-value-param (the lambdas still capture their own copy).
* st: clang-format the producer changes for clang-format-11
Manual edits to lib/ClientImpl.cc (the broker-pin threading) and the include
order in ProducerCore.cc were not clang-format-11 clean. CI's Formatting Check
pins clang-format 11, while the local toolchain is 18 and differs on lambda
wrapping and include ordering. Reformat only the touched regions.
* st: avoid GCC 13 stringop-overflow false positive in MessageId serialization
The Alpine x86_64 release build (GCC 13.2.1, musl, -Werror) rejects putBytes:
`out.insert(out.end(), p, p + n)` from a cast const std::byte* range trips
-Wstringop-overflow= — GCC loses the destination size through the inlined
vector _M_range_insert / uninitialized_copy chain and reports a size-0 write.
The code is correct; this is a known GCC 13 false positive on vector::insert
from a pointer range.
Append via resize + memcpy instead: resize gives the analyzer a concrete
destination size and sidesteps the flagged insert path entirely. The 9
StMessageIdTest serialization round-trips still pass; the fixed TU compiles
clean under the Alpine release flags.
* st: address review — TLS broker address and weak retry-timer capture
Both from @BewareMyPower's review of the per-segment producer:
- Pin the segment producer to the broker address that matches how this client
connects: `useTls() ? brokerUrlTls : brokerUrl`, the same choice the classic
BinaryProtoLookupService makes. Previously it always took the plaintext URL,
so a TLS client would have been pinned to the wrong address. When the DAG does
not advertise the address we need, the pin is left unset and the normal
segment:// lookup resolves it.
- Capture a weak_ptr (not shared_from_this) in the send-retry backoff timer.
closeAsync() does not cancel these timers, so a strong capture kept the
producer alive until the backoff elapsed; now the producer can be destroyed
and a retry that outlives it fails the send with ResultAlreadyClosed instead
of resurrecting it.
---------
Signed-off-by: Matteo Merli <mm...@apache.org>
---
include/pulsar/st/detail/ProducerCore.h | 2 +
lib/ClientImpl.cc | 83 ++++--
lib/ClientImpl.h | 16 +-
lib/HandlerBase.cc | 6 +-
lib/HandlerBase.h | 7 +
lib/ProducerImpl.cc | 6 +-
lib/ProducerImpl.h | 6 +-
lib/TopicName.cc | 34 ++-
lib/TopicName.h | 6 +
lib/st/MessageIdImpl.h | 76 ++++++
lib/st/ProducerCore.cc | 39 +++
lib/st/ProducerImplBase.h | 58 ++++
lib/st/StClientImpl.cc | 24 +-
lib/st/StMessageId.cc | 271 ++++++++++++++++++
lib/st/StProducerImpl.cc | 471 ++++++++++++++++++++++++++++++++
lib/st/StProducerImpl.h | 134 +++++++++
tests/st/FutureTest.cc | 28 ++
tests/st/StClientTest.cc | 11 -
tests/st/StMessageIdTest.cc | 156 +++++++++++
tests/st/StProducerTest.cc | 118 ++++++++
tests/st/StTopicNameTest.cc | 90 ++++++
21 files changed, 1600 insertions(+), 42 deletions(-)
diff --git a/include/pulsar/st/detail/ProducerCore.h b/include/pulsar/st/detail/ProducerCore.h
index 004dc2ee..13059a34 100644
--- a/include/pulsar/st/detail/ProducerCore.h
+++ b/include/pulsar/st/detail/ProducerCore.h
@@ -33,6 +33,7 @@ namespace pulsar::st {
class ProducerImplBase;
using ProducerImplPtr = std::shared_ptr<ProducerImplBase>;
struct OutgoingMessage;
+class ClientImpl; // lib/st — mints producer cores from createProducerAsync
namespace detail {
@@ -58,6 +59,7 @@ class PULSAR_PUBLIC ProducerCore {
private:
friend class ClientCore;
+ friend class ::pulsar::st::ClientImpl;
explicit ProducerCore(ProducerImplPtr impl) : impl_(std::move(impl)) {}
ProducerImplPtr impl_;
diff --git a/lib/ClientImpl.cc b/lib/ClientImpl.cc
index dc79fce0..510456f4 100644
--- a/lib/ClientImpl.cc
+++ b/lib/ClientImpl.cc
@@ -94,6 +94,15 @@ std::string generateRandomName() {
typedef std::vector<std::string> StringList;
+// segment:// topics are the internal backing topics of a scalable topic and are
+// reachable only through the pulsar::st client, which bypasses this rejection.
+static Error segmentTopicRejected(const std::string& topic) {
+ return Error{ResultInvalidTopicName,
+ "segment:// topics are the internal backing topics of a scalable topic; use the "
+ "pulsar::st API instead: " +
+ topic};
+}
+
static LookupServicePtr defaultLookupServiceFactory(const ServiceInfo& serviceInfo,
const ClientConfiguration& clientConfiguration,
ConnectionPool& pool) {
@@ -204,6 +213,21 @@ LookupServicePtr ClientImpl::getLookup(const std::string& redirectedClusterURI)
void ClientImpl::createProducerAsync(const std::string& topic, const ProducerConfiguration& conf,
CreateProducerV2Callback callback, bool autoDownloadSchema) {
+ createProducerAsyncImpl(topic, conf, std::move(callback), autoDownloadSchema,
+ /* allowSegmentTopic */ false);
+}
+
+void ClientImpl::createSegmentProducerAsync(const std::string& topic, const ProducerConfiguration& conf,
+ CreateProducerV2Callback callback,
+ const std::optional<std::string>& assignedBrokerUrl) {
+ createProducerAsyncImpl(topic, conf, std::move(callback), /* autoDownloadSchema */ false,
+ /* allowSegmentTopic */ true, assignedBrokerUrl);
+}
+
+void ClientImpl::createProducerAsyncImpl(const std::string& topic, const ProducerConfiguration& conf,
+ CreateProducerV2Callback callback, bool autoDownloadSchema,
+ bool allowSegmentTopic,
+ const std::optional<std::string>& assignedBrokerUrl) {
if (conf.isChunkingEnabled() && conf.getBatchingEnabled()) {
throw std::invalid_argument("Batching and chunking of messages can't be enabled together");
}
@@ -222,32 +246,38 @@ void ClientImpl::createProducerAsync(const std::string& topic, const ProducerCon
return;
}
}
+ if (topicName->isSegment() && !allowSegmentTopic) {
+ callback(segmentTopicRejected(topic));
+ return;
+ }
if (autoDownloadSchema) {
- getSchema(topicName).addListener([self{shared_from_this()}, topicName, callback{std::move(callback)}](
- const Error& error, const SchemaInfo& topicSchema) mutable {
- if (error.result != ResultOk) {
- callback(error);
- return;
- }
- ProducerConfiguration conf;
- conf.setSchema(topicSchema);
- self->getPartitionMetadataAsync(topicName).addListener(
- std::bind(&ClientImpl::handleCreateProducer, self, std::placeholders::_1,
- std::placeholders::_2, topicName, conf, callback));
- });
+ getSchema(topicName).addListener(
+ [self{shared_from_this()}, topicName, callback{std::move(callback)}, assignedBrokerUrl](
+ const Error& error, const SchemaInfo& topicSchema) mutable {
+ if (error.result != ResultOk) {
+ callback(error);
+ return;
+ }
+ ProducerConfiguration conf;
+ conf.setSchema(topicSchema);
+ self->getPartitionMetadataAsync(topicName).addListener(
+ std::bind(&ClientImpl::handleCreateProducer, self, std::placeholders::_1,
+ std::placeholders::_2, topicName, conf, callback, assignedBrokerUrl));
+ });
} else {
getPartitionMetadataAsync(topicName).addListener(
- [this, conf, topicName, callback{std::move(callback)}](
+ [this, conf, topicName, callback{std::move(callback)}, assignedBrokerUrl](
const Error& error, const LookupDataResultPtr& partitionMetadata) {
- handleCreateProducer(error, partitionMetadata, topicName, conf, callback);
+ handleCreateProducer(error, partitionMetadata, topicName, conf, callback, assignedBrokerUrl);
});
}
}
void ClientImpl::handleCreateProducer(const Error& error, const LookupDataResultPtr& partitionMetadata,
const TopicNamePtr& topicName, const ProducerConfiguration& conf,
- CreateProducerV2Callback callback) {
+ CreateProducerV2Callback callback,
+ const std::optional<std::string>& assignedBrokerUrl) {
if (!error.result) {
ProducerImplBasePtr producer;
@@ -258,7 +288,10 @@ void ClientImpl::handleCreateProducer(const Error& error, const LookupDataResult
producer = std::make_shared<PartitionedProducerImpl>(
shared_from_this(), topicName, partitionMetadata->getPartitions(), conf, interceptors);
} else {
- producer = std::make_shared<ProducerImpl>(shared_from_this(), *topicName, conf, interceptors);
+ producer =
+ std::make_shared<ProducerImpl>(shared_from_this(), *topicName, conf, interceptors,
+ /* partition */ -1,
+ /* retryOnCreationError */ false, assignedBrokerUrl);
}
} catch (const std::runtime_error& e) {
LOG_ERROR("Failed to create producer: " << e.what());
@@ -319,6 +352,10 @@ void ClientImpl::createReaderAsyncV2(const std::string& topic, const MessageId&
return;
}
}
+ if (topicName->isSegment()) {
+ callback(segmentTopicRejected(topic));
+ return;
+ }
getPartitionMetadataAsync(topicName).addListener(
[this, self{shared_from_this()}, topicName, startMessageId, conf, callback{std::move(callback)}](
@@ -348,6 +385,10 @@ void ClientImpl::createTableViewAsyncV2(const std::string& topic, const TableVie
return;
}
}
+ if (topicName->isSegment()) {
+ callback(segmentTopicRejected(topic));
+ return;
+ }
TableViewImplPtr tableViewPtr =
std::make_shared<TableViewImpl>(shared_from_this(), topicName->toString(), conf);
@@ -586,6 +627,11 @@ void ClientImpl::subscribeToTopicsAsyncV2(const std::string& topic, const std::s
}
}
+ if (topicName->isSegment()) {
+ callback(segmentTopicRejected(topic));
+ return;
+ }
+
getPartitionMetadataAsync(topicName).addListener(
[this, self{shared_from_this()}, topicName, subscriptionName, conf, callback{std::move(callback)}](
const auto& error, const auto& metadata) {
@@ -768,6 +814,11 @@ void ClientImpl::getPartitionsForTopicAsync(const std::string& topic, const GetP
return;
}
}
+ if (topicName->isSegment()) {
+ LOG_ERROR(segmentTopicRejected(topic));
+ callback(ResultInvalidTopicName, StringList());
+ return;
+ }
getPartitionMetadataAsync(topicName).addListener(
[this, self{shared_from_this()}, topicName, callback](const auto& error, const auto& metadata) {
handleGetPartitions(error.result, metadata, topicName, callback);
diff --git a/lib/ClientImpl.h b/lib/ClientImpl.h
index cdabf1fc..7b822c08 100644
--- a/lib/ClientImpl.h
+++ b/lib/ClientImpl.h
@@ -95,6 +95,14 @@ class ClientImpl : public std::enable_shared_from_this<ClientImpl> {
void createProducerAsync(const std::string& topic, const ProducerConfiguration& conf,
CreateProducerV2Callback callback, bool autoDownloadSchema = false);
+ /**
+ * Scalable topics (pulsar::st): create a producer on a segment:// backing
+ * topic, bypassing the segment-domain rejection applied to the public path.
+ */
+ void createSegmentProducerAsync(const std::string& topic, const ProducerConfiguration& conf,
+ CreateProducerV2Callback callback,
+ const std::optional<std::string>& assignedBrokerUrl = std::nullopt);
+
void subscribeAsync(const std::string& topic, const std::string& subscriptionName,
const ConsumerConfiguration& conf, const SubscribeCallback& callback);
@@ -180,9 +188,15 @@ class ClientImpl : public std::enable_shared_from_this<ClientImpl> {
friend class PulsarFriend;
private:
+ void createProducerAsyncImpl(const std::string& topic, const ProducerConfiguration& conf,
+ CreateProducerV2Callback callback, bool autoDownloadSchema,
+ bool allowSegmentTopic,
+ const std::optional<std::string>& assignedBrokerUrl = std::nullopt);
+
void handleCreateProducer(const Error& error, const LookupDataResultPtr& partitionMetadata,
const TopicNamePtr& topicName, const ProducerConfiguration& conf,
- CreateProducerV2Callback callback);
+ CreateProducerV2Callback callback,
+ const std::optional<std::string>& assignedBrokerUrl = std::nullopt);
void handleSubscribe(const Error& error, const LookupDataResultPtr& partitionMetadata,
const TopicNamePtr& topicName, const std::string& consumerName,
diff --git a/lib/HandlerBase.cc b/lib/HandlerBase.cc
index 5bccc0bc..45b6a96e 100644
--- a/lib/HandlerBase.cc
+++ b/lib/HandlerBase.cc
@@ -54,11 +54,13 @@ HandlerBase::~HandlerBase() {
cancelTimer(*creationTimer_);
}
-void HandlerBase::start() {
+void HandlerBase::start() { start(std::nullopt); }
+
+void HandlerBase::start(const optional<std::string>& assignedBrokerUrl) {
// guard against concurrent state changes such as closing
State state = NotStarted;
if (state_.compare_exchange_strong(state, Pending)) {
- grabCnx();
+ grabCnx(assignedBrokerUrl);
}
creationTimer_->expires_after(operationTimeut_);
auto weakSelf = weak_from_this();
diff --git a/lib/HandlerBase.h b/lib/HandlerBase.h
index 16124156..811d2361 100644
--- a/lib/HandlerBase.h
+++ b/lib/HandlerBase.h
@@ -51,6 +51,13 @@ class HandlerBase : public std::enable_shared_from_this<HandlerBase> {
void start();
+ /*
+ * Start and, on the initial connect, go straight to @p assignedBrokerUrl instead of
+ * doing a topic lookup. Used by scalable-topics per-segment producers pinned to the
+ * DAG-provided owner broker. An empty optional behaves exactly like start().
+ */
+ void start(const optional<std::string>& assignedBrokerUrl);
+
ClientConnectionWeakPtr getCnx() const;
void setCnx(const ClientConnectionPtr& cnx);
void resetCnx() { setCnx(nullptr); }
diff --git a/lib/ProducerImpl.cc b/lib/ProducerImpl.cc
index 4697e72b..f1da6f59 100644
--- a/lib/ProducerImpl.cc
+++ b/lib/ProducerImpl.cc
@@ -50,7 +50,8 @@ using std::chrono::milliseconds;
ProducerImpl::ProducerImpl(const ClientImplPtr& client, const TopicName& topicName,
const ProducerConfiguration& conf, const ProducerInterceptorsPtr& interceptors,
- int32_t partition, bool retryOnCreationError)
+ int32_t partition, bool retryOnCreationError,
+ const optional<std::string>& assignedBrokerUrl)
: HandlerBase(client, (partition < 0) ? topicName.toString() : topicName.getTopicPartitionName(partition),
Backoff(milliseconds(client->getClientConfig().getInitialBackoffIntervalMs()),
milliseconds(client->getClientConfig().getMaxBackoffIntervalMs()),
@@ -58,6 +59,7 @@ ProducerImpl::ProducerImpl(const ClientImplPtr& client, const TopicName& topicNa
conf_(conf),
semaphore_(),
partition_(partition),
+ assignedBrokerUrl_(assignedBrokerUrl),
producerName_(conf_.getProducerName()),
userProvidedProducerName_(false),
producerStr_("[" + topic() + ", " + producerName_ + "] "),
@@ -1007,7 +1009,7 @@ void ProducerImpl::disconnectProducer(const optional<std::string>& assignedBroke
void ProducerImpl::disconnectProducer() { disconnectProducer(std::nullopt); }
void ProducerImpl::start() {
- HandlerBase::start();
+ HandlerBase::start(assignedBrokerUrl_);
if (conf_.getLazyStartPartitionedProducers() && conf_.getAccessMode() == ProducerConfiguration::Shared) {
// we need to kick it off now as it is possible that the connection may take
diff --git a/lib/ProducerImpl.h b/lib/ProducerImpl.h
index e7502533..6942fcd3 100644
--- a/lib/ProducerImpl.h
+++ b/lib/ProducerImpl.h
@@ -73,7 +73,8 @@ class ProducerImpl : public HandlerBase, public ProducerImplBase {
ProducerImpl(const ClientImplPtr& client, const TopicName& topic,
const ProducerConfiguration& producerConfiguration,
const ProducerInterceptorsPtr& interceptors, int32_t partition = -1,
- bool retryOnCreationError = false);
+ bool retryOnCreationError = false,
+ const optional<std::string>& assignedBrokerUrl = std::nullopt);
~ProducerImpl();
// overrided methods from ProducerImplBase
@@ -177,6 +178,9 @@ class ProducerImpl : public HandlerBase, public ProducerImplBase {
std::list<std::unique_ptr<OpSendMsg>> pendingMessagesQueue_;
const int32_t partition_; // -1 if topic is non-partitioned
+ // When set, the initial connect goes straight to this broker (no lookup) — used by
+ // scalable-topics per-segment producers pinned to the DAG-provided owner broker.
+ const optional<std::string> assignedBrokerUrl_;
std::string producerName_;
bool userProvidedProducerName_;
std::string producerStr_;
diff --git a/lib/TopicName.cc b/lib/TopicName.cc
index 487eee53..aed56641 100644
--- a/lib/TopicName.cc
+++ b/lib/TopicName.cc
@@ -35,6 +35,7 @@ namespace pulsar {
const std::string TopicDomain::Persistent = "persistent";
const std::string TopicDomain::NonPersistent = "non-persistent";
+const std::string TopicDomain::Segment = "segment";
static const std::string PARTITION_NAME_SUFFIX = "-partition-";
typedef std::unique_lock<std::mutex> Lock;
@@ -105,7 +106,23 @@ bool TopicName::parse(const std::string& topicName, std::string& domain, std::st
domain = pathTokens[0];
size_t numSlashIndexes;
bool isV2Topic;
- if (pathTokens.size() == 4) {
+ if (domain == TopicDomain::Segment) {
+ // segment://<tenant>/<ns>/<parent-topic>/<descriptor>: always the new
+ // (cluster-less) format, with a '/' inside the local name — so the
+ // token-count heuristic below must not mistake it for a legacy V1 name.
+ if (pathTokens.size() < 5) {
+ LOG_ERROR(
+ "Segment topic name is not valid, expected "
+ "segment://<tenant>/<namespace>/<topic>/<descriptor> - "
+ << topicName);
+ return false;
+ }
+ property = pathTokens[1];
+ cluster = "";
+ namespacePortion = pathTokens[2];
+ numSlashIndexes = 3;
+ isV2Topic = true;
+ } else if (pathTokens.size() == 4) {
// New topic name without cluster name
property = pathTokens[1];
cluster = "";
@@ -171,7 +188,12 @@ bool TopicName::operator==(const TopicName& other) const {
bool TopicName::validate() {
// Check if domain matches with TopicDomain::Persistent, in future check "memory" when server is
// ready.
- if (domain_.compare(TopicDomain::Persistent) != 0 && domain_.compare(TopicDomain::NonPersistent) != 0) {
+ if (domain_.compare(TopicDomain::Persistent) != 0 && domain_.compare(TopicDomain::NonPersistent) != 0 &&
+ domain_.compare(TopicDomain::Segment) != 0) {
+ return false;
+ }
+ if (domain_ == TopicDomain::Segment && !isV2Topic_) {
+ // Segment topics only exist in the new (cluster-less) format.
return false;
}
// cluster_ can be empty
@@ -228,7 +250,13 @@ std::string TopicName::toString() const {
return ss.str();
}
-bool TopicName::isPersistent() const { return this->domain_ == TopicDomain::Persistent; }
+// A segment topic is the persistent backing topic of one scalable-topic segment,
+// so it counts as persistent (matching the Java TopicName).
+bool TopicName::isPersistent() const {
+ return this->domain_ == TopicDomain::Persistent || this->domain_ == TopicDomain::Segment;
+}
+
+bool TopicName::isSegment() const { return this->domain_ == TopicDomain::Segment; }
std::string TopicName::getTopicPartitionName(unsigned int partition) const {
std::stringstream topicPartitionName;
diff --git a/lib/TopicName.h b/lib/TopicName.h
index bee8138a..34fa55ab 100644
--- a/lib/TopicName.h
+++ b/lib/TopicName.h
@@ -37,6 +37,11 @@ class PULSAR_PUBLIC TopicDomain {
public:
static const std::string Persistent;
static const std::string NonPersistent;
+ // The per-segment backing topics of a scalable topic (PIP-460):
+ // segment://<tenant>/<ns>/<parent-topic>/<hashStart>-<hashEnd>-<segmentId>.
+ // Internal to the pulsar::st client; the classic user-facing entry points
+ // reject this domain.
+ static const std::string Segment;
}; // class TopicDomain
class PULSAR_PUBLIC TopicName : public ServiceUnitId {
@@ -62,6 +67,7 @@ class PULSAR_PUBLIC TopicName : public ServiceUnitId {
std::string getEncodedLocalName() const;
std::string toString() const;
bool isPersistent() const;
+ bool isSegment() const;
NamespaceNamePtr getNamespaceName();
int getPartitionIndex() const noexcept { return partition_; }
static std::shared_ptr<TopicName> get(const std::string& topicName);
diff --git a/lib/st/MessageIdImpl.h b/lib/st/MessageIdImpl.h
new file mode 100644
index 00000000..0b3f9daf
--- /dev/null
+++ b/lib/st/MessageIdImpl.h
@@ -0,0 +1,76 @@
+/**
+ * Licensed to the Apache Software Foundation (ASF) under one
+ * or more contributor license agreements. See the NOTICE file
+ * distributed with this work for additional information
+ * regarding copyright ownership. The ASF licenses this file
+ * to you under the Apache License, Version 2.0 (the
+ * "License"); you may not use this file except in compliance
+ * with the License. You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing,
+ * software distributed under the License is distributed on an
+ * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ * KIND, either express or implied. See the License for the
+ * specific language governing permissions and limitations
+ * under the License.
+ */
+#pragma once
+
+#include <pulsar/MessageId.h>
+#include <pulsar/st/MessageId.h>
+
+#include <cstdint>
+#include <map>
+#include <memory>
+#include <optional>
+#include <string>
+#include <utility>
+
+namespace pulsar::st {
+
+/**
+ * The hidden state of a pulsar::st::MessageId, mirroring the Java client's
+ * MessageIdV5 field-for-field so the two clients' serialized ids interoperate:
+ * the classic per-segment message id plus the segment it belongs to, and the
+ * optional position-vector sections used by the consumer side (a cumulative-ack
+ * StreamConsumer id also carries the other segments' positions; a namespace
+ * consumer's id carries them per topic). The producer path fills only
+ * v4MessageId + segmentId.
+ */
+class MessageIdImpl {
+ public:
+ /** segmentId of the earliest/latest sentinels, which span all segments. */
+ static constexpr std::int64_t kNoSegment = -1;
+
+ pulsar::MessageId v4MessageId;
+ std::int64_t segmentId = kNoSegment;
+ /** Per-segment positions for cumulative-ack ids. Empty on the producer path. */
+ std::map<std::int64_t, pulsar::MessageId> positionVector;
+ /** The scalable topic this id belongs to, when carried (topic://...). */
+ std::optional<std::string> parentTopic;
+ /** Cross-topic position vectors for namespace consumers, when carried. */
+ std::optional<std::map<std::string, std::map<std::int64_t, pulsar::MessageId>>> multiTopicVector;
+};
+
+/**
+ * INTERNAL factory befriended by the public MessageId handle: the only way
+ * lib/st mints typed ids and reaches back into their hidden state.
+ */
+class MessageIdFactory {
+ public:
+ static MessageId create(std::shared_ptr<MessageIdImpl> impl) { return MessageId(std::move(impl)); }
+
+ /** The producer path: an id for one published message in one segment. */
+ static MessageId create(const pulsar::MessageId& v4MessageId, std::int64_t segmentId) {
+ auto impl = std::make_shared<MessageIdImpl>();
+ impl->v4MessageId = v4MessageId;
+ impl->segmentId = segmentId;
+ return MessageId(std::move(impl));
+ }
+
+ static const std::shared_ptr<MessageIdImpl>& impl(const MessageId& id) { return id.impl_; }
+};
+
+} // namespace pulsar::st
diff --git a/lib/st/ProducerCore.cc b/lib/st/ProducerCore.cc
new file mode 100644
index 00000000..6629b7cf
--- /dev/null
+++ b/lib/st/ProducerCore.cc
@@ -0,0 +1,39 @@
+/**
+ * Licensed to the Apache Software Foundation (ASF) under one
+ * or more contributor license agreements. See the NOTICE file
+ * distributed with this work for additional information
+ * regarding copyright ownership. The ASF licenses this file
+ * to you under the Apache License, Version 2.0 (the
+ * "License"); you may not use this file except in compliance
+ * with the License. You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing,
+ * software distributed under the License is distributed on an
+ * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ * KIND, either express or implied. See the License for the
+ * specific language governing permissions and limitations
+ * under the License.
+ */
+#include <pulsar/st/Producer.h> // complete OutgoingMessage (moved into the impl)
+#include <pulsar/st/detail/ProducerCore.h>
+
+#include <utility>
+
+#include "ProducerImplBase.h"
+
+namespace pulsar::st::detail {
+
+// Thin forwarders to the hidden ProducerImplBase. A const ProducerCore still reaches a
+// non-const pointee through the shared_ptr, so the mutating impl methods need no const.
+Future<MessageId> ProducerCore::sendAsync(OutgoingMessage message) const {
+ return impl_->sendAsync(std::move(message));
+}
+std::string_view ProducerCore::topic() const { return impl_->topic(); }
+std::string_view ProducerCore::producerName() const { return impl_->producerName(); }
+std::optional<int64_t> ProducerCore::lastSequenceId() const { return impl_->lastSequenceId(); }
+Future<void> ProducerCore::flushAsync() const { return impl_->flushAsync(); }
+Future<void> ProducerCore::closeAsync() const { return impl_->closeAsync(); }
+
+} // namespace pulsar::st::detail
diff --git a/lib/st/ProducerImplBase.h b/lib/st/ProducerImplBase.h
new file mode 100644
index 00000000..156b2e91
--- /dev/null
+++ b/lib/st/ProducerImplBase.h
@@ -0,0 +1,58 @@
+/**
+ * Licensed to the Apache Software Foundation (ASF) under one
+ * or more contributor license agreements. See the NOTICE file
+ * distributed with this work for additional information
+ * regarding copyright ownership. The ASF licenses this file
+ * to you under the Apache License, Version 2.0 (the
+ * "License"); you may not use this file except in compliance
+ * with the License. You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing,
+ * software distributed under the License is distributed on an
+ * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ * KIND, either express or implied. See the License for the
+ * specific language governing permissions and limitations
+ * under the License.
+ */
+#pragma once
+
+#include <pulsar/st/Future.h>
+#include <pulsar/st/MessageId.h>
+
+#include <cstdint>
+#include <optional>
+#include <string_view>
+
+namespace pulsar::st {
+
+struct OutgoingMessage;
+
+/**
+ * INTERNAL — the abstract producer the public `detail::ProducerCore` forwards to.
+ *
+ * `detail::ProducerCore` holds a `std::shared_ptr<ProducerImplBase>` and each of its
+ * methods is a one-line forward to the matching virtual here; `StProducerImpl` (the
+ * scalable-topics producer) is the concrete implementation. This lives in `pulsar::st`
+ * (not `detail`) to match the forward declaration in `detail/ProducerCore.h`. It is a
+ * different type from the classic `pulsar::ProducerImplBase` — different namespace, no
+ * collision.
+ *
+ * The observer methods are `const`; the mutating ones are not. `ProducerCore`'s methods
+ * are all `const`, but a `const` handle still reaches a non-const pointee through the
+ * shared_ptr, so the mutating virtuals need not be const.
+ */
+class ProducerImplBase {
+ public:
+ virtual ~ProducerImplBase() = default;
+
+ virtual Future<MessageId> sendAsync(OutgoingMessage message) = 0;
+ virtual std::string_view topic() const = 0;
+ virtual std::string_view producerName() const = 0;
+ virtual std::optional<std::int64_t> lastSequenceId() const = 0;
+ virtual Future<void> flushAsync() = 0;
+ virtual Future<void> closeAsync() = 0;
+};
+
+} // namespace pulsar::st
diff --git a/lib/st/StClientImpl.cc b/lib/st/StClientImpl.cc
index 8b38ab9a..40ec5b7e 100644
--- a/lib/st/StClientImpl.cc
+++ b/lib/st/StClientImpl.cc
@@ -21,6 +21,8 @@
#include <string>
#include <utility>
+#include "StProducerImpl.h"
+
namespace pulsar::st {
namespace {
@@ -41,14 +43,24 @@ Future<T> notImplementedYet(const char* what) {
ClientImpl::ClientImpl(pulsar::ClientImplPtr classicClient, const TransactionPolicy& transactionPolicy)
: classic_(std::move(classicClient)), transactionPolicy_(transactionPolicy) {}
-// The producer/consumer/transaction paths land in follow-up phases. Each takes
-// its config by value (the sink the real implementation will move from), but as
-// a stub it does not consume the config yet — hence the value-param suppressions.
-// NOLINTNEXTLINE(performance-unnecessary-value-param)
-Future<detail::ProducerCore> ClientImpl::createProducerAsync(ProducerConfig) {
- return notImplementedYet<detail::ProducerCore>("createProducer");
+Future<detail::ProducerCore> ClientImpl::createProducerAsync(ProducerConfig config) {
+ auto impl = std::make_shared<StProducerImpl>(classic_, std::move(config));
+ detail::Promise<detail::ProducerCore> promise;
+ // Keep the impl alive until start() resolves; on success mint the public core over it.
+ impl->start().addListener([impl, promise](const Expected<void>& result) {
+ if (result) {
+ promise.setValue(detail::ProducerCore{impl});
+ } else {
+ promise.setError(result.error());
+ }
+ });
+ return promise.getFuture();
}
+// The consumer/transaction paths land in follow-up phases. Each takes its config by
+// value (the sink the real implementation will move from), but as a stub it does not
+// consume the config yet — hence the value-param suppressions.
+
// NOLINTNEXTLINE(performance-unnecessary-value-param)
Future<detail::StreamConsumerCore> ClientImpl::subscribeStreamAsync(StreamConsumerConfig) {
return notImplementedYet<detail::StreamConsumerCore>("subscribeStream");
diff --git a/lib/st/StMessageId.cc b/lib/st/StMessageId.cc
index 4bfa037a..dec63115 100644
--- a/lib/st/StMessageId.cc
+++ b/lib/st/StMessageId.cc
@@ -18,10 +18,281 @@
*/
#include <pulsar/st/MessageId.h>
+#include <cstdint>
+#include <cstring>
+#include <exception>
+#include <functional>
+#include <ostream>
+#include <string>
+#include <utility>
+
+#include "MessageIdImpl.h"
+#include "lib/LogUtils.h"
+
+DECLARE_LOG_OBJECT()
+
namespace pulsar::st {
+namespace {
+
+// The serialized form is the Java client's MessageIdV5 layout (big-endian):
+// int64 segmentId
+// int32 v4Length, v4 bytes (classic MessageId serialization)
+// int32 positionCount, {int64 segmentId, int32 length, bytes} entries
+// int32 parentTopicLength (-1 = absent), utf-8 bytes
+// int32 multiTopicCount (-1 = absent),
+// {int32 topicLength, bytes, int32 positionCount, entries} entries
+// The trailing sections are optional on read, so shorter (older) forms parse.
+
+void putInt32(std::vector<std::byte>& out, std::int32_t value) {
+ auto u = static_cast<std::uint32_t>(value);
+ for (int shift = 24; shift >= 0; shift -= 8) {
+ out.push_back(static_cast<std::byte>((u >> shift) & 0xFF));
+ }
+}
+
+void putInt64(std::vector<std::byte>& out, std::int64_t value) {
+ auto u = static_cast<std::uint64_t>(value);
+ for (int shift = 56; shift >= 0; shift -= 8) {
+ out.push_back(static_cast<std::byte>((u >> shift) & 0xFF));
+ }
+}
+
+void putBytes(std::vector<std::byte>& out, const std::string& bytes) {
+ // Append via resize + memcpy rather than insert(end, ptr, ptr+n): GCC 13's
+ // -Wstringop-overflow false-positives on vector::insert from a cast pointer range under
+ // the Alpine/musl release build (it loses the destination size through the inlined
+ // uninitialized_copy). resize gives the analyzer a known size and sidesteps that path.
+ const std::size_t offset = out.size();
+ out.resize(offset + bytes.size());
+ if (!bytes.empty()) {
+ std::memcpy(out.data() + offset, bytes.data(), bytes.size());
+ }
+}
+
+class Reader {
+ public:
+ explicit Reader(std::span<const std::byte> data) : data_(data) {}
+
+ bool hasRemaining() const { return pos_ < data_.size(); }
+
+ bool readInt32(std::int32_t& value) {
+ if (data_.size() - pos_ < 4) return false;
+ std::uint32_t u = 0;
+ for (int i = 0; i < 4; i++) {
+ u = (u << 8) | std::to_integer<std::uint32_t>(data_[pos_++]);
+ }
+ value = static_cast<std::int32_t>(u);
+ return true;
+ }
+
+ bool readInt64(std::int64_t& value) {
+ if (data_.size() - pos_ < 8) return false;
+ std::uint64_t u = 0;
+ for (int i = 0; i < 8; i++) {
+ u = (u << 8) | std::to_integer<std::uint64_t>(data_[pos_++]);
+ }
+ value = static_cast<std::int64_t>(u);
+ return true;
+ }
+
+ bool readBytes(std::int32_t length, std::string& out) {
+ if (length < 0 || static_cast<std::size_t>(length) > data_.size() - pos_) return false;
+ out.assign(reinterpret_cast<const char*>(data_.data() + pos_), static_cast<std::size_t>(length));
+ pos_ += static_cast<std::size_t>(length);
+ return true;
+ }
+
+ private:
+ std::span<const std::byte> data_;
+ std::size_t pos_ = 0;
+};
+
+void writePositionVector(std::vector<std::byte>& out,
+ const std::map<std::int64_t, pulsar::MessageId>& vector) {
+ putInt32(out, static_cast<std::int32_t>(vector.size()));
+ for (const auto& entry : vector) {
+ putInt64(out, entry.first);
+ std::string serialized;
+ entry.second.serialize(serialized);
+ putInt32(out, static_cast<std::int32_t>(serialized.size()));
+ putBytes(out, serialized);
+ }
+}
+
+bool readPositionVector(Reader& reader, std::map<std::int64_t, pulsar::MessageId>& out) {
+ std::int32_t count;
+ if (!reader.readInt32(count) || count < 0) return false;
+ for (std::int32_t i = 0; i < count; i++) {
+ std::int64_t segmentId;
+ std::int32_t length;
+ std::string bytes;
+ if (!reader.readInt64(segmentId) || !reader.readInt32(length) || !reader.readBytes(length, bytes)) {
+ return false;
+ }
+ out.emplace(segmentId, pulsar::MessageId::deserialize(bytes));
+ }
+ return true;
+}
+
+} // namespace
+
// An empty id: impl_ stays null, so the handle is falsy under operator bool and
// compares equal only to other empty ids.
MessageId::MessageId() = default;
+MessageId::MessageId(std::shared_ptr<MessageIdImpl> impl) : impl_(std::move(impl)) {}
+
+const MessageId& MessageId::earliest() {
+ static const MessageId id =
+ MessageIdFactory::create(pulsar::MessageId::earliest(), MessageIdImpl::kNoSegment);
+ return id;
+}
+
+const MessageId& MessageId::latest() {
+ static const MessageId id =
+ MessageIdFactory::create(pulsar::MessageId::latest(), MessageIdImpl::kNoSegment);
+ return id;
+}
+
+std::vector<std::byte> MessageId::toByteArray() const {
+ if (!impl_) {
+ return {};
+ }
+ std::vector<std::byte> out;
+ putInt64(out, impl_->segmentId);
+
+ std::string v4Bytes;
+ impl_->v4MessageId.serialize(v4Bytes);
+ putInt32(out, static_cast<std::int32_t>(v4Bytes.size()));
+ putBytes(out, v4Bytes);
+
+ writePositionVector(out, impl_->positionVector);
+
+ if (impl_->parentTopic) {
+ putInt32(out, static_cast<std::int32_t>(impl_->parentTopic->size()));
+ putBytes(out, *impl_->parentTopic);
+ } else {
+ putInt32(out, -1);
+ }
+
+ if (impl_->multiTopicVector) {
+ putInt32(out, static_cast<std::int32_t>(impl_->multiTopicVector->size()));
+ for (const auto& entry : *impl_->multiTopicVector) {
+ putInt32(out, static_cast<std::int32_t>(entry.first.size()));
+ putBytes(out, entry.first);
+ writePositionVector(out, entry.second);
+ }
+ } else {
+ putInt32(out, -1);
+ }
+ return out;
+}
+
+MessageId MessageId::fromByteArray(std::span<const std::byte> data) {
+ try {
+ Reader reader(data);
+ auto impl = std::make_shared<MessageIdImpl>();
+
+ std::int32_t v4Length;
+ std::string v4Bytes;
+ if (!reader.readInt64(impl->segmentId) || !reader.readInt32(v4Length) ||
+ !reader.readBytes(v4Length, v4Bytes)) {
+ LOG_WARN("Discarding malformed scalable-topic MessageId: " << data.size() << " bytes");
+ return MessageId();
+ }
+ impl->v4MessageId = pulsar::MessageId::deserialize(v4Bytes);
+
+ if (reader.hasRemaining() && !readPositionVector(reader, impl->positionVector)) {
+ LOG_WARN("Discarding scalable-topic MessageId with a malformed position vector");
+ return MessageId();
+ }
+
+ if (reader.hasRemaining()) {
+ std::int32_t parentLength;
+ if (!reader.readInt32(parentLength)) {
+ return MessageId();
+ }
+ if (parentLength >= 0) {
+ std::string parent;
+ if (!reader.readBytes(parentLength, parent)) {
+ return MessageId();
+ }
+ impl->parentTopic = std::move(parent);
+ }
+ }
+
+ if (reader.hasRemaining()) {
+ std::int32_t topicCount;
+ if (!reader.readInt32(topicCount)) {
+ return MessageId();
+ }
+ if (topicCount >= 0) {
+ std::map<std::string, std::map<std::int64_t, pulsar::MessageId>> multi;
+ for (std::int32_t i = 0; i < topicCount; i++) {
+ std::int32_t topicLength;
+ std::string topic;
+ std::map<std::int64_t, pulsar::MessageId> inner;
+ if (!reader.readInt32(topicLength) || !reader.readBytes(topicLength, topic) ||
+ !readPositionVector(reader, inner)) {
+ return MessageId();
+ }
+ multi.emplace(std::move(topic), std::move(inner));
+ }
+ impl->multiTopicVector = std::move(multi);
+ }
+ }
+ return MessageIdFactory::create(std::move(impl));
+ } catch (const std::exception& e) {
+ // The classic MessageId deserialization throws on malformed proto bytes.
+ LOG_WARN("Discarding malformed scalable-topic MessageId: " << e.what());
+ return MessageId();
+ }
+}
+
+std::strong_ordering MessageId::operator<=>(const MessageId& other) const {
+ // Empty ids sort before every real id and tie with each other.
+ if (!impl_ || !other.impl_) {
+ return static_cast<bool>(impl_) <=> static_cast<bool>(other.impl_);
+ }
+ if (auto cmp = impl_->segmentId <=> other.impl_->segmentId; cmp != 0) {
+ return cmp;
+ }
+ if (impl_->v4MessageId == other.impl_->v4MessageId) {
+ return std::strong_ordering::equal;
+ }
+ return impl_->v4MessageId < other.impl_->v4MessageId ? std::strong_ordering::less
+ : std::strong_ordering::greater;
+}
+
+bool MessageId::operator==(const MessageId& other) const {
+ if (!impl_ || !other.impl_) {
+ return static_cast<bool>(impl_) == static_cast<bool>(other.impl_);
+ }
+ return impl_->segmentId == other.impl_->segmentId && impl_->v4MessageId == other.impl_->v4MessageId;
+}
+
+std::ostream& operator<<(std::ostream& s, const MessageId& messageId) {
+ if (!messageId.impl_) {
+ return s << "{empty}";
+ }
+ return s << "{segment=" << messageId.impl_->segmentId << ", id=" << messageId.impl_->v4MessageId
+ << ", positions=" << messageId.impl_->positionVector.size() << "}";
+}
+
} // namespace pulsar::st
+
+std::size_t std::hash<pulsar::st::MessageId>::operator()(
+ const pulsar::st::MessageId& messageId) const noexcept {
+ const auto& impl = pulsar::st::MessageIdFactory::impl(messageId);
+ if (!impl) {
+ return 0;
+ }
+ std::size_t seed = std::hash<std::int64_t>()(impl->segmentId);
+ auto combine = [&seed](std::size_t h) { seed ^= h + 0x9e3779b9 + (seed << 6) + (seed >> 2); };
+ combine(std::hash<std::int64_t>()(impl->v4MessageId.ledgerId()));
+ combine(std::hash<std::int64_t>()(impl->v4MessageId.entryId()));
+ combine(std::hash<std::int32_t>()(impl->v4MessageId.batchIndex()));
+ combine(std::hash<std::int32_t>()(impl->v4MessageId.partition()));
+ return seed;
+}
diff --git a/lib/st/StProducerImpl.cc b/lib/st/StProducerImpl.cc
new file mode 100644
index 00000000..e9fe1cf1
--- /dev/null
+++ b/lib/st/StProducerImpl.cc
@@ -0,0 +1,471 @@
+/**
+ * Licensed to the Apache Software Foundation (ASF) under one
+ * or more contributor license agreements. See the NOTICE file
+ * distributed with this work for additional information
+ * regarding copyright ownership. The ASF licenses this file
+ * to you under the Apache License, Version 2.0 (the
+ * "License"); you may not use this file except in compliance
+ * with the License. You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing,
+ * software distributed under the License is distributed on an
+ * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ * KIND, either express or implied. See the License for the
+ * specific language governing permissions and limitations
+ * under the License.
+ */
+#include "StProducerImpl.h"
+
+#include <pulsar/MessageBuilder.h>
+
+#include <algorithm>
+#include <chrono>
+#include <memory>
+#include <string>
+#include <unordered_set>
+#include <utility>
+#include <variant>
+#include <vector>
+
+#include "MessageIdImpl.h"
+#include "lib/ExecutorService.h"
+#include "lib/LogUtils.h"
+
+DECLARE_LOG_OBJECT()
+
+namespace pulsar::st {
+
+StProducerImpl::StProducerImpl(pulsar::ClientImplPtr classic, ProducerConfig config)
+ : classic_(std::move(classic)),
+ config_(std::move(config)),
+ topic_(config_.topic),
+ producerName_(config_.producerName.value_or(std::string{})),
+ currentLayout_(std::make_shared<SegmentLayout>()) {}
+
+Future<void> StProducerImpl::start() {
+ dagWatch_ = std::make_shared<DagWatchSession>(classic_, config_.topic, /*createIfMissing*/ true);
+ std::weak_ptr<StProducerImpl> weak = weak_from_this();
+ // Register the layout listener BEFORE start() so the very first layout is delivered to it.
+ dagWatch_->setLayoutChangeListener(
+ [weak](const SegmentLayout& newLayout, const SegmentLayout& oldLayout) {
+ if (auto self = weak.lock()) self->onLayoutChange(newLayout, oldLayout);
+ });
+ dagWatch_->start().addListener([weak](const Expected<SegmentLayout>& result) {
+ if (auto self = weak.lock()) self->onStartResult(result);
+ });
+ return startPromise_.getFuture();
+}
+
+void StProducerImpl::onStartResult(const Expected<SegmentLayout>& result) {
+ // Only the failure path is handled here: the DagWatchSession fails start()'s future (without
+ // invoking the layout listener) when the lookup fails before the first layout arrives. On
+ // success the listener runs immediately after and drives completeStart().
+ if (!result) {
+ startPromise_.setError(result.error());
+ }
+}
+
+void StProducerImpl::onLayoutChange(const SegmentLayout& newLayout, const SegmentLayout& /*oldLayout*/) {
+ std::vector<Future<pulsar::Producer>> retired;
+ bool first = false;
+ {
+ std::lock_guard<std::mutex> lock(mutex_);
+ first = !sawFirstLayout_;
+ sawFirstLayout_ = true;
+ currentLayout_ = std::make_shared<SegmentLayout>(newLayout);
+
+ std::unordered_set<std::uint64_t> active;
+ for (const auto& segment : newLayout.activeSegments()) active.insert(segment.segmentId);
+ for (auto it = segmentProducers_.begin(); it != segmentProducers_.end();) {
+ if (active.find(it->first) == active.end()) {
+ retired.push_back(std::move(it->second));
+ it = segmentProducers_.erase(it);
+ } else {
+ ++it;
+ }
+ }
+ }
+
+ // Close producers for segments that left the layout, fire-and-forget.
+ for (auto& future : retired) {
+ future.addListener([](const Expected<pulsar::Producer>& result) {
+ if (result) {
+ pulsar::Producer producer = *result;
+ producer.closeAsync([](pulsar::Result) {});
+ }
+ });
+ }
+
+ if (first) {
+ completeStart();
+ } else if (requiresExclusiveAttach(config_.accessMode)) {
+ // Exclusive modes claim newly-active segments eagerly (best-effort; failures are logged).
+ for (const auto& segment : newLayout.activeSegments()) {
+ getOrCreateSegmentProducerAsync(segment.segmentId);
+ }
+ }
+}
+
+void StProducerImpl::completeStart() {
+ if (!requiresExclusiveAttach(config_.accessMode)) {
+ startPromise_.setSuccess(); // Shared: segment producers are created lazily on first send.
+ return;
+ }
+ auto layout = snapshotLayout();
+ const auto& segments = layout->activeSegments();
+ if (segments.empty()) {
+ startPromise_.setSuccess();
+ return;
+ }
+ // Exclusive: eagerly attach every active segment; the create fails up front if the exclusive
+ // claim is refused, exactly like the Java strict eager attach.
+ auto remaining = std::make_shared<std::atomic<int>>(static_cast<int>(segments.size()));
+ for (const auto& segment : segments) {
+ getOrCreateSegmentProducerAsync(segment.segmentId)
+ .addListener([self = shared_from_this(), remaining](const Expected<pulsar::Producer>& result) {
+ if (!result) {
+ self->startPromise_.setError(
+ result.error()); // first error wins (complete is idempotent)
+ return;
+ }
+ if (remaining->fetch_sub(1) == 1) self->startPromise_.setSuccess();
+ });
+ }
+}
+
+pulsar::ProducerConfiguration StProducerImpl::buildSegmentConfiguration(const Segment& segment) const {
+ // Build a FRESH config every time: pulsar::ProducerConfiguration's copy constructor shares its
+ // impl, so copy-then-mutate would clobber every other segment's config.
+ pulsar::ProducerConfiguration conf;
+ conf.setSchema(config_.schema);
+ conf.setAccessMode(toClassicAccessMode(config_.accessMode));
+ if (config_.sendTimeoutMs) conf.setSendTimeout(static_cast<int>(*config_.sendTimeoutMs));
+ conf.setBlockIfQueueFull(config_.blockIfQueueFull);
+ if (config_.initialSequenceId) conf.setInitialSequenceId(*config_.initialSequenceId);
+ for (const auto& [key, value] : config_.properties) conf.setProperty(key, value);
+ if (config_.producerName) {
+ conf.setProducerName(*config_.producerName + "-seg-" + std::to_string(segment.segmentId));
+ }
+ // Legacy segments wrap an externally-managed persistent:// topic; mark the connection so the
+ // regular->scalable migration precheck (PIP-475) recognizes it. Real segment:// topics aren't.
+ if (segment.isLegacy()) {
+ conf.setProperty("__pulsar.v5.managed", "true");
+ }
+ // PIP-486 entry-bucketing: only the encryption-disables-batching branch is portable today; the
+ // EntryBucketBatcherBuilder branch has no C++ seam yet (TODO when a batcher-builder lands).
+ if (conf.isEncryptionEnabled()) {
+ conf.setBatchingEnabled(false);
+ }
+ return conf;
+}
+
+Future<pulsar::Producer> StProducerImpl::getOrCreateSegmentProducerAsync(std::uint64_t segmentId) {
+ std::lock_guard<std::mutex> lock(mutex_);
+ if (auto it = segmentProducers_.find(segmentId); it != segmentProducers_.end()) {
+ return it->second; // concurrent cold senders share the one creation attempt
+ }
+
+ const Segment* segment = nullptr;
+ for (const auto& candidate : currentLayout_->activeSegments()) {
+ if (candidate.segmentId == segmentId) {
+ segment = &candidate;
+ break;
+ }
+ }
+ detail::Promise<pulsar::Producer> promise;
+ if (segment == nullptr) {
+ // Transient — don't cache, so a later routing attempt re-resolves against a fresh layout.
+ promise.setError(Error{ResultUnknownError,
+ "segment " + std::to_string(segmentId) + " is not in the active layout"});
+ return promise.getFuture();
+ }
+
+ pulsar::ProducerConfiguration conf = buildSegmentConfiguration(*segment);
+ const std::string attachTopic = segment->attachTopicName();
+ // Pin to the DAG-provided owner broker, picking the address that matches how this client
+ // connects — the same choice the classic lookup makes (BinaryProtoLookupService uses
+ // `useTls() ? brokerUrlTls : brokerUrl`). If the DAG did not advertise the address we need,
+ // leave the pin unset and fall back to the normal segment:// lookup, which resolves it.
+ const bool useTls = classic_->getServiceInfo().useTls();
+ const std::string* url =
+ useTls ? currentLayout_->brokerUrlTls(segmentId) : currentLayout_->brokerUrl(segmentId);
+ std::optional<std::string> assignedBrokerUrl;
+ if (url != nullptr) {
+ assignedBrokerUrl = *url;
+ }
+
+ auto future = promise.getFuture();
+ segmentProducers_.insert_or_assign(segmentId, future);
+ classic_->createSegmentProducerAsync(
+ attachTopic, conf,
+ [promise](std::variant<pulsar::Error, pulsar::Producer> result) {
+ if (auto* producer = std::get_if<pulsar::Producer>(&result)) {
+ promise.setValue(std::move(*producer));
+ } else {
+ promise.setError(std::get<pulsar::Error>(result));
+ }
+ },
+ assignedBrokerUrl);
+ return future;
+}
+
+Future<MessageId> StProducerImpl::sendAsync(OutgoingMessage message) {
+ detail::Promise<MessageId> userPromise;
+ auto userFuture = userPromise.getFuture();
+
+ if (closed_.load()) {
+ userPromise.setError(Error{ResultAlreadyClosed, "producer is closed"});
+ return userFuture;
+ }
+ if (message.transaction) {
+ userPromise.setError(Error{ResultOperationNotSupported,
+ "transactions are not implemented yet in the scalable-topics client"});
+ return userFuture;
+ }
+
+ // Register in the in-flight set (for flush) BEFORE dispatching: a warm send can complete
+ // synchronously, which would otherwise run the removal listener before insertion.
+ std::uint64_t inFlightId = 0;
+ {
+ std::lock_guard<std::mutex> lock(mutex_);
+ inFlightId = nextInFlightId_++;
+ inFlight_.insert_or_assign(inFlightId, userFuture);
+ }
+ std::weak_ptr<StProducerImpl> weak = weak_from_this();
+ userFuture.addListener([weak, inFlightId](const Expected<MessageId>&) {
+ if (auto self = weak.lock()) {
+ std::lock_guard<std::mutex> lock(self->mutex_);
+ self->inFlight_.erase(inFlightId);
+ }
+ });
+
+ auto layout = snapshotLayout();
+ Expected<std::uint64_t> route =
+ message.key.has_value() ? router_.route(*message.key, *layout) : router_.routeRoundRobin(*layout);
+ if (!route) {
+ // Route failure (no active segment yet / uncovered hash) is terminal, not retried.
+ userPromise.setError(route.error());
+ return userFuture;
+ }
+ dispatchSend(std::move(message), *route, /*attempt*/ 0, userPromise);
+ return userFuture;
+}
+
+void StProducerImpl::dispatchSend(OutgoingMessage message, std::uint64_t segmentId, int attempt,
+ const detail::Promise<MessageId>& userPromise) {
+ auto self = shared_from_this();
+ getOrCreateSegmentProducerAsync(segmentId).addListener(
+ [self, message = std::move(message), segmentId, attempt,
+ userPromise](const Expected<pulsar::Producer>& created) mutable {
+ if (!created) {
+ self->handleSegmentFailure(created.error(), std::move(message), segmentId, attempt,
+ userPromise);
+ return;
+ }
+ pulsar::Producer producer = *created;
+ pulsar::Message classicMessage = self->buildClassicMessage(message);
+ producer.sendAsync(
+ classicMessage, [self, message = std::move(message), segmentId, attempt, userPromise](
+ pulsar::Result result, const pulsar::MessageId& v4Id) mutable {
+ if (result == pulsar::ResultOk) {
+ userPromise.setValue(
+ MessageIdFactory::create(v4Id, static_cast<std::int64_t>(segmentId)));
+ } else {
+ self->handleSegmentFailure(Error{result, ""}, std::move(message), segmentId, attempt,
+ userPromise);
+ }
+ });
+ });
+}
+
+void StProducerImpl::handleSegmentFailure(Error error, OutgoingMessage message, std::uint64_t segmentId,
+ int attempt, const detail::Promise<MessageId>& userPromise) {
+ if (!isSegmentGoneError(error.result, error.message) || attempt >= kSendRetryMaxAttempts ||
+ closed_.load()) {
+ userPromise.setError(std::move(error));
+ return;
+ }
+ // The segment was sealed/terminated under us. Drop its cached producer so the retry recreates it
+ // against the layout the DAG watch is about to deliver, then re-route after a short backoff.
+ {
+ std::lock_guard<std::mutex> lock(mutex_);
+ segmentProducers_.erase(segmentId);
+ }
+ LOG_INFO("[" << topic_ << "] segment " << segmentId << " is gone; retrying send, attempt "
+ << (attempt + 1) << " of " << kSendRetryMaxAttempts);
+ auto timer = classic_->getIOExecutorProvider()->get()->createDeadlineTimer();
+ const std::int64_t delayMs = std::min<std::int64_t>(100 * (attempt + 1), kSendRetryMaxBackoffMs);
+ timer->expires_from_now(std::chrono::milliseconds(delayMs));
+ // Capture a weak ref: closeAsync() does not cancel these timers, so a strong one would keep the
+ // producer alive until the backoff elapses. If the producer is gone by then, fail the send
+ // instead of resurrecting it. (`timer` is captured to keep itself alive until it fires.)
+ std::weak_ptr<StProducerImpl> weak = weak_from_this();
+ timer->async_wait([weak, message = std::move(message), attempt, userPromise,
+ timer](const ASIO_ERROR& ec) mutable {
+ auto self = weak.lock();
+ if (ec || !self || self->closed_.load()) {
+ userPromise.setError(Error{ResultAlreadyClosed, "producer closed during send retry"});
+ return;
+ }
+ auto layout = self->snapshotLayout();
+ Expected<std::uint64_t> route = message.key.has_value() ? self->router_.route(*message.key, *layout)
+ : self->router_.routeRoundRobin(*layout);
+ if (!route) {
+ userPromise.setError(route.error());
+ return;
+ }
+ self->dispatchSend(std::move(message), *route, attempt + 1, userPromise);
+ });
+}
+
+pulsar::Message StProducerImpl::buildClassicMessage(const OutgoingMessage& message) const {
+ pulsar::MessageBuilder builder;
+ // The classic client copies the content synchronously, so publishing the borrowed view here
+ // still honors the zero-copy (BytesView) lifetime contract.
+ if (message.usesView) {
+ builder.setContent(message.payloadView.data(), message.payloadView.size());
+ } else {
+ builder.setContent(message.payload.data(), message.payload.size());
+ }
+ if (message.key) builder.setPartitionKey(*message.key);
+ for (const auto& [key, value] : message.properties) builder.setProperty(key, value);
+ if (message.eventTime) {
+ builder.setEventTimestamp(static_cast<uint64_t>(
+ std::chrono::duration_cast<std::chrono::milliseconds>(message.eventTime->time_since_epoch())
+ .count()));
+ }
+ if (message.sequenceId) builder.setSequenceId(*message.sequenceId);
+ if (message.deliverAt) {
+ builder.setDeliverAt(static_cast<uint64_t>(
+ std::chrono::duration_cast<std::chrono::milliseconds>(message.deliverAt->time_since_epoch())
+ .count()));
+ }
+ if (!message.replicationClusters.empty()) builder.setReplicationClusters(message.replicationClusters);
+ return builder.build();
+}
+
+std::optional<std::int64_t> StProducerImpl::lastSequenceId() const {
+ std::int64_t max = config_.initialSequenceId.value_or(-1);
+ std::lock_guard<std::mutex> lock(mutex_);
+ for (const auto& [segmentId, future] : segmentProducers_) {
+ if (future.isReady()) {
+ auto result = future.get();
+ if (result) {
+ max = std::max(max, result->getLastSequenceId());
+ }
+ }
+ }
+ return max < 0 ? std::nullopt : std::optional<std::int64_t>(max);
+}
+
+Future<void> StProducerImpl::flushAsync() {
+ std::vector<Future<MessageId>> pending;
+ std::vector<Future<pulsar::Producer>> producers;
+ {
+ std::lock_guard<std::mutex> lock(mutex_);
+ pending.reserve(inFlight_.size());
+ for (const auto& [id, future] : inFlight_) pending.push_back(future);
+ producers.reserve(segmentProducers_.size());
+ for (const auto& [id, future] : segmentProducers_) producers.push_back(future);
+ }
+
+ detail::Promise<void> promise;
+ // +1 base count so an empty snapshot completes immediately.
+ auto remaining = std::make_shared<std::atomic<int>>(static_cast<int>(pending.size()) + 1);
+ auto reportedError = std::make_shared<std::atomic<bool>>(false);
+ auto finishOne = [promise, remaining]() {
+ if (remaining->fetch_sub(1) == 1) promise.setSuccess(); // no-op if already errored
+ };
+
+ // Nudge the ready classic producers so any batched sends complete; the actual completion is
+ // tracked by the in-flight user futures below.
+ for (auto& producerFuture : producers) {
+ if (producerFuture.isReady()) {
+ auto result = producerFuture.get();
+ if (result) {
+ pulsar::Producer producer = *result;
+ producer.flushAsync([](pulsar::Result) {});
+ }
+ }
+ }
+ for (auto& future : pending) {
+ future.addListener([promise, reportedError, finishOne](const Expected<MessageId>& result) {
+ if (!result && !reportedError->exchange(true)) promise.setError(result.error());
+ finishOne();
+ });
+ }
+ finishOne();
+ return promise.getFuture();
+}
+
+Future<void> StProducerImpl::closeAsync() {
+ if (closed_.exchange(true)) {
+ detail::Promise<void> promise;
+ promise.setSuccess(); // idempotent: already closed
+ return promise.getFuture();
+ }
+ if (dagWatch_) dagWatch_->close();
+
+ std::vector<Future<pulsar::Producer>> producers;
+ {
+ std::lock_guard<std::mutex> lock(mutex_);
+ producers.reserve(segmentProducers_.size());
+ for (auto& [id, future] : segmentProducers_) producers.push_back(future);
+ segmentProducers_.clear();
+ }
+
+ detail::Promise<void> promise;
+ auto remaining = std::make_shared<std::atomic<int>>(static_cast<int>(producers.size()) + 1);
+ auto finishOne = [promise, remaining]() {
+ if (remaining->fetch_sub(1) == 1) promise.setSuccess();
+ };
+ for (auto& producerFuture : producers) {
+ producerFuture.addListener([finishOne](const Expected<pulsar::Producer>& result) {
+ if (result) {
+ pulsar::Producer producer = *result;
+ producer.closeAsync(
+ [finishOne](pulsar::Result) { finishOne(); }); // swallow per-producer errors
+ } else {
+ finishOne(); // creation itself failed — nothing to close
+ }
+ });
+ }
+ finishOne();
+ return promise.getFuture();
+}
+
+std::shared_ptr<const SegmentLayout> StProducerImpl::snapshotLayout() const {
+ std::lock_guard<std::mutex> lock(mutex_);
+ return currentLayout_;
+}
+
+bool StProducerImpl::isSegmentGoneError(pulsar::Result result, const std::string& message) {
+ if (result == pulsar::ResultTopicTerminated || result == pulsar::ResultAlreadyClosed) return true;
+ // Some paths surface a sealed segment as a generic error carrying the terminated text.
+ return message.find("TopicTerminated") != std::string::npos ||
+ message.find("terminated") != std::string::npos;
+}
+
+bool StProducerImpl::requiresExclusiveAttach(ProducerAccessMode mode) {
+ return mode != ProducerAccessMode::Shared;
+}
+
+pulsar::ProducerConfiguration::ProducerAccessMode StProducerImpl::toClassicAccessMode(
+ ProducerAccessMode mode) {
+ // The st and classic enums do NOT share numeric values — map by name.
+ switch (mode) {
+ case ProducerAccessMode::Shared:
+ return pulsar::ProducerConfiguration::Shared;
+ case ProducerAccessMode::Exclusive:
+ return pulsar::ProducerConfiguration::Exclusive;
+ case ProducerAccessMode::ExclusiveWithFencing:
+ return pulsar::ProducerConfiguration::ExclusiveWithFencing;
+ case ProducerAccessMode::WaitForExclusive:
+ return pulsar::ProducerConfiguration::WaitForExclusive;
+ }
+ return pulsar::ProducerConfiguration::Shared;
+}
+
+} // namespace pulsar::st
diff --git a/lib/st/StProducerImpl.h b/lib/st/StProducerImpl.h
new file mode 100644
index 00000000..24a2db02
--- /dev/null
+++ b/lib/st/StProducerImpl.h
@@ -0,0 +1,134 @@
+/**
+ * Licensed to the Apache Software Foundation (ASF) under one
+ * or more contributor license agreements. See the NOTICE file
+ * distributed with this work for additional information
+ * regarding copyright ownership. The ASF licenses this file
+ * to you under the Apache License, Version 2.0 (the
+ * "License"); you may not use this file except in compliance
+ * with the License. You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing,
+ * software distributed under the License is distributed on an
+ * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ * KIND, either express or implied. See the License for the
+ * specific language governing permissions and limitations
+ * under the License.
+ */
+#pragma once
+
+#include <pulsar/Producer.h>
+#include <pulsar/ProducerConfiguration.h>
+#include <pulsar/st/Producer.h>
+
+#include <atomic>
+#include <cstdint>
+#include <memory>
+#include <mutex>
+#include <optional>
+#include <string>
+#include <string_view>
+#include <unordered_map>
+
+#include "DagWatchSession.h"
+#include "ProducerImplBase.h"
+#include "SegmentLayout.h"
+#include "lib/ClientImpl.h"
+
+namespace pulsar::st {
+
+/**
+ * The scalable-topics producer: a faithful port of the Java v5 ScalableTopicProducer.
+ *
+ * A scalable topic's segments are ordinary persistent topics, so this owns ONE
+ * DagWatchSession per topic and, per active segment, a classic pulsar::Producer
+ * pinned to the DAG-provided owner broker (created lazily on first send, or eagerly
+ * for exclusive access modes). Each publish is routed by key to a segment through
+ * the SegmentRouter, the classic producer publishes it, and the returned classic
+ * MessageId is wrapped with the segment id into a pulsar::st::MessageId. When a
+ * segment is sealed/terminated under the producer, the send retries with backoff and
+ * re-routes onto the new layout the DAG watch delivers.
+ *
+ * Unlike Java, no per-segment dispatch chain is needed: the C++ Future fires its
+ * listeners in registration (FIFO) order, so multiple sends waiting on one segment's
+ * creation future dispatch in call order for free.
+ */
+class StProducerImpl final : public ProducerImplBase, public std::enable_shared_from_this<StProducerImpl> {
+ public:
+ StProducerImpl(pulsar::ClientImplPtr classic, ProducerConfig config);
+
+ /**
+ * Start the DAG watch and become ready. The returned future completes once the
+ * initial layout arrives (and, for exclusive access modes, once every active
+ * segment's producer is attached), or fails if the lookup/attach fails.
+ */
+ Future<void> start();
+
+ // ProducerImplBase
+ Future<MessageId> sendAsync(OutgoingMessage message) override;
+ std::string_view topic() const override { return topic_; }
+ std::string_view producerName() const override { return producerName_; }
+ std::optional<std::int64_t> lastSequenceId() const override;
+ Future<void> flushAsync() override;
+ Future<void> closeAsync() override;
+
+ private:
+ friend struct StProducerTestAccess; // broker-free access to the pure config/routing helpers
+
+ // Number of send attempts once a segment is gone (seal/terminate), and the cap on
+ // the per-attempt backoff — matches the Java v5 producer.
+ static constexpr int kSendRetryMaxAttempts = 10;
+ static constexpr std::int64_t kSendRetryMaxBackoffMs = 500;
+
+ // Build a FRESH classic producer configuration for one segment. Never copy-then-mutate
+ // a shared base: pulsar::ProducerConfiguration's copy constructor shares its impl, so a
+ // per-segment copy would clobber every sibling.
+ pulsar::ProducerConfiguration buildSegmentConfiguration(const Segment& segment) const;
+
+ Future<pulsar::Producer> getOrCreateSegmentProducerAsync(std::uint64_t segmentId);
+
+ // start()'s future handler: only surfaces a start-time failure. The success path (apply
+ // the initial layout and complete startPromise_) is driven by the layout listener, which
+ // the DagWatchSession invokes right after completing start()'s future.
+ void onStartResult(const Expected<SegmentLayout>& result);
+ // The layout-change listener: fires for every accepted layout (the first has an empty
+ // oldLayout). Swaps the current layout, retires producers for departed segments, and on
+ // the first call completes startPromise_ (eagerly attaching all segments for exclusive
+ // modes).
+ void onLayoutChange(const SegmentLayout& newLayout, const SegmentLayout& oldLayout);
+ void completeStart();
+
+ void dispatchSend(OutgoingMessage message, std::uint64_t segmentId, int attempt,
+ const detail::Promise<MessageId>& userPromise);
+ // On a send failure: retry after backoff on a fresh layout if the segment is gone and the
+ // attempt budget remains, otherwise fail the user's future.
+ void handleSegmentFailure(Error error, OutgoingMessage message, std::uint64_t segmentId, int attempt,
+ const detail::Promise<MessageId>& userPromise);
+ pulsar::Message buildClassicMessage(const OutgoingMessage& message) const;
+
+ std::shared_ptr<const SegmentLayout> snapshotLayout() const;
+ static bool isSegmentGoneError(pulsar::Result result, const std::string& message);
+ static bool requiresExclusiveAttach(ProducerAccessMode mode);
+ static pulsar::ProducerConfiguration::ProducerAccessMode toClassicAccessMode(ProducerAccessMode mode);
+
+ pulsar::ClientImplPtr classic_;
+ const ProducerConfig config_;
+ const std::string topic_;
+ const std::string producerName_;
+ DagWatchSessionPtr dagWatch_;
+ SegmentRouter router_;
+ detail::Promise<void> startPromise_;
+ std::atomic<bool> closed_{false};
+
+ mutable std::mutex mutex_;
+ bool sawFirstLayout_ = false; // guarded by mutex_
+ std::shared_ptr<const SegmentLayout> currentLayout_; // guarded by mutex_ (never null)
+ std::unordered_map<std::uint64_t, Future<pulsar::Producer>> segmentProducers_; // guarded by mutex_
+ std::unordered_map<std::uint64_t, Future<MessageId>> inFlight_; // guarded by mutex_ (for flush)
+ std::uint64_t nextInFlightId_ = 0; // guarded by mutex_
+};
+
+using StProducerImplPtr = std::shared_ptr<StProducerImpl>;
+
+} // namespace pulsar::st
diff --git a/tests/st/FutureTest.cc b/tests/st/FutureTest.cc
index 316eaf1b..47e660de 100644
--- a/tests/st/FutureTest.cc
+++ b/tests/st/FutureTest.cc
@@ -27,6 +27,7 @@
#include <string>
#include <thread>
#include <utility>
+#include <vector>
using namespace pulsar::st;
using pulsar::st::detail::Promise;
@@ -82,6 +83,33 @@ TEST(FutureTest, testListenerAfterCompletionRunsSynchronously) {
ASSERT_EQ(seen, 9);
}
+// The scalable-topics producer relies on listeners firing in registration order to
+// preserve send ordering to a segment without a per-segment dispatch chain (which
+// Java needs only because JDK CompletableFuture gives no fire-order guarantee). Lock
+// that guarantee in here.
+TEST(FutureTest, testListenersFireInRegistrationOrder) {
+ Promise<int> promise;
+ Future<int> future = promise.getFuture();
+ std::vector<int> order;
+ for (int i = 0; i < 5; i++) {
+ future.addListener([&order, i](const Expected<int>&) { order.push_back(i); });
+ }
+ promise.setValue(1);
+ ASSERT_EQ(order, (std::vector<int>{0, 1, 2, 3, 4}));
+}
+
+TEST(FutureTest, testListenerAddedAfterCompletionRunsAfterEarlierOnes) {
+ Promise<int> promise;
+ Future<int> future = promise.getFuture();
+ std::vector<int> order;
+ future.addListener([&order](const Expected<int>&) { order.push_back(0); });
+ promise.setValue(1); // fires listener 0
+ // A listener registered after completion runs synchronously, and after the ones
+ // that were already registered — so a late same-segment send never jumps the queue.
+ future.addListener([&order](const Expected<int>&) { order.push_back(1); });
+ ASSERT_EQ(order, (std::vector<int>{0, 1}));
+}
+
TEST(FutureTest, testCompleteIsFirstWriterWins) {
Promise<int> promise;
ASSERT_TRUE(promise.setValue(1));
diff --git a/tests/st/StClientTest.cc b/tests/st/StClientTest.cc
index 839b7ee1..7c67a917 100644
--- a/tests/st/StClientTest.cc
+++ b/tests/st/StClientTest.cc
@@ -73,17 +73,6 @@ TEST(StClientTest, testBuildWithPoliciesWithoutBroker) {
ASSERT_TRUE(client->close());
}
-TEST(StClientTest, testProducerCreationReportsNotSupportedYet) {
- auto client = PulsarClient::builder().serviceUrl("pulsar://localhost:6650").build();
- ASSERT_TRUE(client);
-
- auto producer = client->newProducer().topic("st-topic").create();
- ASSERT_FALSE(producer);
- ASSERT_EQ(producer.error().result, ResultOperationNotSupported);
-
- ASSERT_TRUE(client->close());
-}
-
TEST(StClientTest, testTransactionReportsNotSupportedYet) {
auto client = PulsarClient::builder().serviceUrl("pulsar://localhost:6650").build();
ASSERT_TRUE(client);
diff --git a/tests/st/StMessageIdTest.cc b/tests/st/StMessageIdTest.cc
new file mode 100644
index 00000000..cba876d1
--- /dev/null
+++ b/tests/st/StMessageIdTest.cc
@@ -0,0 +1,156 @@
+/**
+ * Licensed to the Apache Software Foundation (ASF) under one
+ * or more contributor license agreements. See the NOTICE file
+ * distributed with this work for additional information
+ * regarding copyright ownership. The ASF licenses this file
+ * to you under the Apache License, Version 2.0 (the
+ * "License"); you may not use this file except in compliance
+ * with the License. You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing,
+ * software distributed under the License is distributed on an
+ * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ * KIND, either express or implied. See the License for the
+ * specific language governing permissions and limitations
+ * under the License.
+ */
+#include <gtest/gtest.h>
+#include <pulsar/st/MessageId.h>
+
+#include <cstddef>
+#include <sstream>
+#include <unordered_set>
+#include <vector>
+
+#include "lib/st/MessageIdImpl.h"
+
+using namespace pulsar::st;
+
+namespace {
+
+MessageId makeId(std::int64_t segmentId, std::int64_t ledgerId, std::int64_t entryId,
+ std::int32_t batchIndex = -1, std::int32_t partition = -1) {
+ return MessageIdFactory::create(pulsar::MessageId(partition, ledgerId, entryId, batchIndex), segmentId);
+}
+
+} // namespace
+
+TEST(StMessageIdTest, testSentinels) {
+ ASSERT_TRUE(static_cast<bool>(MessageId::earliest()));
+ ASSERT_TRUE(static_cast<bool>(MessageId::latest()));
+ ASSERT_TRUE(MessageId::earliest() == MessageId::earliest());
+ ASSERT_FALSE(MessageId::earliest() == MessageId::latest());
+ ASSERT_TRUE(MessageId::earliest() < MessageId::latest());
+}
+
+TEST(StMessageIdTest, testOrderingWithinAndAcrossSegments) {
+ MessageId a = makeId(1, 10, 1);
+ MessageId b = makeId(1, 10, 2);
+ MessageId c = makeId(2, 5, 0);
+
+ // Same segment: classic id order decides.
+ ASSERT_TRUE(a < b);
+ ASSERT_TRUE(b > a);
+ // Different segments: segment id decides, regardless of ledger/entry.
+ ASSERT_TRUE(b < c);
+ ASSERT_TRUE(a <= a);
+ ASSERT_TRUE(a == makeId(1, 10, 1));
+ ASSERT_FALSE(a == b);
+ ASSERT_FALSE(a == c);
+}
+
+TEST(StMessageIdTest, testEmptyIdComparisons) {
+ MessageId empty1;
+ MessageId empty2;
+ MessageId real = makeId(0, 1, 1);
+ ASSERT_TRUE(empty1 == empty2);
+ ASSERT_FALSE(empty1 == real);
+ ASSERT_TRUE(empty1 < real); // empty sorts first
+}
+
+TEST(StMessageIdTest, testHashSupportsUnorderedContainers) {
+ std::unordered_set<MessageId> ids;
+ ids.insert(makeId(1, 10, 1));
+ ids.insert(makeId(1, 10, 2));
+ ids.insert(makeId(2, 10, 1));
+ ids.insert(makeId(1, 10, 1)); // duplicate
+ ASSERT_EQ(ids.size(), 3u);
+ ASSERT_EQ(std::hash<MessageId>()(makeId(1, 10, 1)), std::hash<MessageId>()(makeId(1, 10, 1)));
+}
+
+TEST(StMessageIdTest, testStreamOutput) {
+ std::ostringstream out;
+ out << makeId(7, 10, 3);
+ ASSERT_NE(out.str().find("segment=7"), std::string::npos);
+
+ std::ostringstream emptyOut;
+ emptyOut << MessageId();
+ ASSERT_EQ(emptyOut.str(), "{empty}");
+}
+
+TEST(StMessageIdTest, testByteArrayRoundtripProducerPath) {
+ MessageId original = makeId(42, 1234, 5678, 3, 5);
+ std::vector<std::byte> bytes = original.toByteArray();
+ ASSERT_FALSE(bytes.empty());
+
+ MessageId restored = MessageId::fromByteArray(std::span<const std::byte>(bytes));
+ ASSERT_TRUE(static_cast<bool>(restored));
+ ASSERT_TRUE(restored == original);
+
+ const auto& impl = MessageIdFactory::impl(restored);
+ ASSERT_EQ(impl->segmentId, 42);
+ ASSERT_EQ(impl->v4MessageId.ledgerId(), 1234);
+ ASSERT_EQ(impl->v4MessageId.entryId(), 5678);
+ ASSERT_EQ(impl->v4MessageId.batchIndex(), 3);
+ ASSERT_EQ(impl->v4MessageId.partition(), 5);
+ ASSERT_TRUE(impl->positionVector.empty());
+ ASSERT_FALSE(impl->parentTopic.has_value());
+ ASSERT_FALSE(impl->multiTopicVector.has_value());
+}
+
+TEST(StMessageIdTest, testByteArrayRoundtripFullSections) {
+ auto impl = std::make_shared<MessageIdImpl>();
+ impl->v4MessageId = pulsar::MessageId(-1, 10, 20, -1);
+ impl->segmentId = 3;
+ impl->positionVector.emplace(1, pulsar::MessageId(-1, 100, 1, -1));
+ impl->positionVector.emplace(2, pulsar::MessageId(-1, 200, 2, -1));
+ impl->parentTopic = "topic://public/default/orders";
+ std::map<std::string, std::map<std::int64_t, pulsar::MessageId>> multi;
+ multi["topic://public/default/other"].emplace(9, pulsar::MessageId(-1, 900, 9, -1));
+ impl->multiTopicVector = multi;
+
+ MessageId original = MessageIdFactory::create(impl);
+ auto bytes = original.toByteArray();
+ MessageId restored = MessageId::fromByteArray(std::span<const std::byte>(bytes));
+ ASSERT_TRUE(static_cast<bool>(restored));
+ ASSERT_TRUE(restored == original);
+
+ const auto& r = MessageIdFactory::impl(restored);
+ ASSERT_EQ(r->positionVector.size(), 2u);
+ ASSERT_EQ(r->positionVector.at(1).ledgerId(), 100);
+ ASSERT_EQ(r->positionVector.at(2).ledgerId(), 200);
+ ASSERT_TRUE(r->parentTopic.has_value());
+ ASSERT_EQ(*r->parentTopic, "topic://public/default/orders");
+ ASSERT_TRUE(r->multiTopicVector.has_value());
+ ASSERT_EQ(r->multiTopicVector->size(), 1u);
+ ASSERT_EQ(r->multiTopicVector->at("topic://public/default/other").at(9).ledgerId(), 900);
+}
+
+TEST(StMessageIdTest, testMalformedBytesYieldEmptyId) {
+ ASSERT_FALSE(static_cast<bool>(MessageId::fromByteArray({})));
+
+ std::vector<std::byte> tooShort(6, std::byte{1});
+ ASSERT_FALSE(static_cast<bool>(MessageId::fromByteArray(std::span<const std::byte>(tooShort))));
+
+ std::vector<std::byte> garbage(64, std::byte{0xFF});
+ ASSERT_FALSE(static_cast<bool>(MessageId::fromByteArray(std::span<const std::byte>(garbage))));
+
+ // A truncated valid id must not parse.
+ auto bytes = makeId(1, 2, 3).toByteArray();
+ bytes.resize(bytes.size() / 2);
+ ASSERT_FALSE(static_cast<bool>(MessageId::fromByteArray(std::span<const std::byte>(bytes))));
+}
+
+TEST(StMessageIdTest, testEmptyIdSerializesToNothing) { ASSERT_TRUE(MessageId().toByteArray().empty()); }
diff --git a/tests/st/StProducerTest.cc b/tests/st/StProducerTest.cc
new file mode 100644
index 00000000..9af869f5
--- /dev/null
+++ b/tests/st/StProducerTest.cc
@@ -0,0 +1,118 @@
+/**
+ * Licensed to the Apache Software Foundation (ASF) under one
+ * or more contributor license agreements. See the NOTICE file
+ * distributed with this work for additional information
+ * regarding copyright ownership. The ASF licenses this file
+ * to you under the Apache License, Version 2.0 (the
+ * "License"); you may not use this file except in compliance
+ * with the License. You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing,
+ * software distributed under the License is distributed on an
+ * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ * KIND, either express or implied. See the License for the
+ * specific language governing permissions and limitations
+ * under the License.
+ */
+#include <gtest/gtest.h>
+#include <pulsar/MessageId.h>
+#include <pulsar/ProducerConfiguration.h>
+
+#include <cstdint>
+#include <string>
+
+#include "lib/st/MessageIdImpl.h"
+#include "lib/st/StProducerImpl.h"
+
+namespace pulsar::st {
+
+// Test-only access to StProducerImpl's private, broker-independent helpers. These read
+// only config_ and the segment argument (never the classic client), so they can run with
+// a null client and no connection.
+struct StProducerTestAccess {
+ static pulsar::ProducerConfiguration segmentConfig(StProducerImpl& producer, const Segment& segment) {
+ return producer.buildSegmentConfiguration(segment);
+ }
+ static pulsar::ProducerConfiguration::ProducerAccessMode toClassic(ProducerAccessMode mode) {
+ return StProducerImpl::toClassicAccessMode(mode);
+ }
+ static bool segmentGone(pulsar::Result result, const std::string& message) {
+ return StProducerImpl::isSegmentGoneError(result, message);
+ }
+};
+
+namespace {
+
+ProducerConfig baseConfig() {
+ ProducerConfig config;
+ config.topic = "topic://public/default/orders";
+ config.producerName = "orders-producer";
+ return config;
+}
+
+Segment normalSegment(std::uint64_t id) {
+ Segment segment;
+ segment.segmentId = id;
+ segment.segmentTopicName = "segment://public/default/orders/0000-ffff-" + std::to_string(id);
+ return segment;
+}
+
+Segment legacySegment(std::uint64_t id) {
+ Segment segment = normalSegment(id);
+ segment.legacyTopicName = "persistent://public/default/orders-partition-" + std::to_string(id);
+ return segment;
+}
+
+// Guards the ProducerConfiguration shallow-copy defect: pulsar::ProducerConfiguration's copy
+// constructor shares its impl, so building a second segment's config by copy-then-mutate would
+// clobber the first. Each segment must get an independent, freshly-built config.
+TEST(StProducerTest, testPerSegmentConfigsAreIsolated) {
+ StProducerImpl producer(nullptr, baseConfig());
+
+ auto confA = StProducerTestAccess::segmentConfig(producer, normalSegment(3));
+ auto confB = StProducerTestAccess::segmentConfig(producer, legacySegment(7));
+
+ // If the configs shared state, building B would rename A too.
+ EXPECT_EQ(confA.getProducerName(), "orders-producer-seg-3");
+ EXPECT_EQ(confB.getProducerName(), "orders-producer-seg-7");
+
+ // The legacy managed-metadata marker belongs to the legacy segment only.
+ EXPECT_EQ(confB.getProperties().count("__pulsar.v5.managed"), 1u);
+ EXPECT_EQ(confA.getProperties().count("__pulsar.v5.managed"), 0u);
+}
+
+// The st and classic ProducerAccessMode enums do NOT share numeric values (st orders
+// ExclusiveWithFencing before WaitForExclusive; classic is the reverse), so a cast would be
+// wrong — the mapping must go by name.
+TEST(StProducerTest, testAccessModeMappedByName) {
+ using Classic = pulsar::ProducerConfiguration;
+ EXPECT_EQ(StProducerTestAccess::toClassic(ProducerAccessMode::Shared), Classic::Shared);
+ EXPECT_EQ(StProducerTestAccess::toClassic(ProducerAccessMode::Exclusive), Classic::Exclusive);
+ EXPECT_EQ(StProducerTestAccess::toClassic(ProducerAccessMode::ExclusiveWithFencing),
+ Classic::ExclusiveWithFencing);
+ EXPECT_EQ(StProducerTestAccess::toClassic(ProducerAccessMode::WaitForExclusive),
+ Classic::WaitForExclusive);
+}
+
+TEST(StProducerTest, testSegmentGoneClassification) {
+ EXPECT_TRUE(StProducerTestAccess::segmentGone(ResultTopicTerminated, ""));
+ EXPECT_TRUE(StProducerTestAccess::segmentGone(ResultAlreadyClosed, ""));
+ // A not-ready layout is a transient routing failure, NOT a gone segment — treating it as
+ // gone would spin the retry loop instead of failing terminally.
+ EXPECT_FALSE(StProducerTestAccess::segmentGone(ResultServiceUnitNotReady, ""));
+ EXPECT_FALSE(StProducerTestAccess::segmentGone(ResultConnectError, ""));
+}
+
+TEST(StProducerTest, testMintedMessageIdCarriesSegmentId) {
+ MessageId id = MessageIdFactory::create(pulsar::MessageId::earliest(), 42);
+ ASSERT_TRUE(static_cast<bool>(id));
+ const auto& impl = MessageIdFactory::impl(id);
+ ASSERT_TRUE(impl);
+ EXPECT_EQ(impl->segmentId, 42);
+ EXPECT_NE(impl->segmentId, MessageIdImpl::kNoSegment);
+}
+
+} // namespace
+} // namespace pulsar::st
diff --git a/tests/st/StTopicNameTest.cc b/tests/st/StTopicNameTest.cc
new file mode 100644
index 00000000..1e3f4a5b
--- /dev/null
+++ b/tests/st/StTopicNameTest.cc
@@ -0,0 +1,90 @@
+/**
+ * Licensed to the Apache Software Foundation (ASF) under one
+ * or more contributor license agreements. See the NOTICE file
+ * distributed with this work for additional information
+ * regarding copyright ownership. The ASF licenses this file
+ * to you under the Apache License, Version 2.0 (the
+ * "License"); you may not use this file except in compliance
+ * with the License. You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing,
+ * software distributed under the License is distributed on an
+ * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ * KIND, either express or implied. See the License for the
+ * specific language governing permissions and limitations
+ * under the License.
+ */
+#include <gtest/gtest.h>
+#include <pulsar/Client.h>
+
+#include "lib/TopicName.h"
+
+// The segment:// domain — the per-segment backing topics of a scalable topic —
+// must parse in the classic TopicName (the per-segment producers attach to
+// them), while every classic user-facing entry point rejects it: only the
+// pulsar::st client may touch segment topics.
+
+using namespace pulsar;
+
+static const std::string kSegmentTopic = "segment://public/default/orders/0000-7fff-1";
+
+TEST(StTopicNameTest, testSegmentTopicParses) {
+ auto topicName = TopicName::get(kSegmentTopic);
+ ASSERT_TRUE(topicName);
+ ASSERT_EQ(topicName->getDomain(), "segment");
+ ASSERT_EQ(topicName->getProperty(), "public");
+ ASSERT_EQ(topicName->getNamespacePortion(), "default");
+ // The local name keeps the '<parent-topic>/<descriptor>' shape.
+ ASSERT_EQ(topicName->getLocalName(), "orders/0000-7fff-1");
+ ASSERT_TRUE(topicName->isV2Topic());
+ ASSERT_EQ(topicName->toString(), kSegmentTopic);
+ // A segment topic is the persistent backing topic of one segment.
+ ASSERT_TRUE(topicName->isPersistent());
+ ASSERT_TRUE(topicName->isSegment());
+ // Never partitioned.
+ ASSERT_EQ(topicName->getPartitionIndex(), -1);
+}
+
+TEST(StTopicNameTest, testSegmentTopicRequiresDescriptor) {
+ // Missing the '<descriptor>' path component.
+ ASSERT_FALSE(TopicName::get("segment://public/default/orders"));
+ ASSERT_FALSE(TopicName::get("segment://public/default"));
+}
+
+TEST(StTopicNameTest, testClassicTopicsUnaffected) {
+ auto v2 = TopicName::get("persistent://public/default/orders");
+ ASSERT_TRUE(v2);
+ ASSERT_TRUE(v2->isPersistent());
+ ASSERT_FALSE(v2->isSegment());
+
+ // A 5-component persistent name still parses as the legacy V1 format.
+ auto v1 = TopicName::get("persistent://tenant/cluster/ns/orders");
+ ASSERT_TRUE(v1);
+ ASSERT_FALSE(v1->isV2Topic());
+ ASSERT_EQ(v1->getCluster(), "cluster");
+ ASSERT_FALSE(v1->isSegment());
+
+ // topic:// (the scalable-topic identity scheme) stays out of the classic
+ // TopicName: the pulsar::st client resolves it before reaching here.
+ ASSERT_FALSE(TopicName::get("topic://public/default/orders"));
+}
+
+// The classic user-facing entry points must reject segment topics before any
+// network activity, so these run without a broker.
+
+TEST(StTopicNameTest, testClassicApiRejectsSegmentTopics) {
+ Client client("pulsar://localhost:6650");
+
+ Producer producer;
+ ASSERT_EQ(client.createProducer(kSegmentTopic, producer), ResultInvalidTopicName);
+
+ Consumer consumer;
+ ASSERT_EQ(client.subscribe(kSegmentTopic, "sub", consumer), ResultInvalidTopicName);
+
+ Reader reader;
+ ASSERT_EQ(client.createReader(kSegmentTopic, MessageId::earliest(), {}, reader), ResultInvalidTopicName);
+
+ client.close();
+}