You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@iggy.apache.org by hg...@apache.org on 2026/10/16 19:55:46 UTC

(iggy) branch feat/sdk-partition-routing updated (89500c468 -> 3504d9b50)

This is an automated email from the ASF dual-hosted git repository.

hubcio pushed a change to branch feat/sdk-partition-routing
in repository https://gitbox.apache.org/repos/asf/iggy.git


    omit 89500c468 fix(swift): route polls and offsets through partition routes
    omit 64441ef89 test(node): stop both consumers before deleting the e2e stream
    omit 895c921cd fix(sdk): retry route discovery after a backup namespace miss
    omit ff06f117f fix(connectors): reconnect stopped source links before retrying
    omit 0dccf673b test(integration): account for managed reconnects in stale clients
     new 4c0589431 test(integration): account for managed reconnects in stale clients
     new c53fff4e4 fix(connectors): reconnect stopped source links before retrying
     new c307d1433 fix(sdk): retry route discovery after a backup namespace miss
     new 208c3f057 test(node): stop both consumers before deleting the e2e stream
     new 1c95ff5a2 fix(swift): route polls and offsets through partition routes
     new d79bf5cea fix(sdk): resume group consumers after every replica link drops
     new 3504d9b50 test(gateways): accept either timeout in the black hole dial test

This update added new revisions after undoing existing revisions.
That is to say, some revisions that were in the old version of the
branch are not in the new version.  This situation occurs
when a user --force pushes a change and generates a repository
containing something like this:

 * -- * -- B -- O -- O -- O   (89500c468)
            \
             N -- N -- N   refs/heads/feat/sdk-partition-routing (3504d9b50)

You should already have received notification emails for all of the O
revisions, and so the following emails describe only the N revisions
from the common base, B.

Any revisions marked "omit" are not gone; other references still
refer to them.  Any revisions marked "discard" are gone forever.

The 7 revisions listed above as "new" are entirely new to this
repository and will be described in separate emails.  The revisions
listed as "add" were already present in the repository and have only
been added to this reference.


Summary of changes:
 .../stale_client_consumer_group_scenario.rs        | 40 ++++++++-----
 core/sdk/src/links/replicas.rs                     | 66 +++++++++++++++++++---
 .../kafka/tests/bridge_iggy_integration_tests.rs   | 34 ++++++-----
 3 files changed, 105 insertions(+), 35 deletions(-)


(iggy) 03/07: fix(sdk): retry route discovery after a backup namespace miss

Posted by hg...@apache.org.
This is an automated email from the ASF dual-hosted git repository.

hubcio pushed a commit to branch feat/sdk-partition-routing
in repository https://gitbox.apache.org/repos/asf/iggy.git

commit c307d14333cc5a705ffe7e6dc3005079872c06a0
Author: Hubert Gruszecki <h....@gmail.com>
AuthorDate: Thu Oct 15 23:58:05 2026 +0200

    fix(sdk): retry route discovery after a backup namespace miss
    
    A backup can lag a metadata create while the primary materializes
    the partition. Treat its namespace miss as transient in Rust, Go,
    Java, C#, and Node. Only the known metadata primary can confirm
    absence; preserve the original deadline and other error handling.
---
 core/sdk/src/driver.rs                             |  72 ++++++++-
 .../TcpMessageStream.PollRouting.cs                |  16 ++
 foreign/csharp/Iggy_SDK/Vsr/VsrError.cs            |   3 +
 .../Iggy_SDK_Tests/VsrTests/PrimaryPollingTests.cs |  99 +++++++++++++
 foreign/go/client/tcp/tcp_poll_routing.go          |   8 +
 foreign/go/client/tcp/tcp_poll_routing_test.go     |  57 ++++++++
 .../apache/iggy/client/async/tcp/PollRouter.java   |  54 ++++++-
 .../iggy/client/async/tcp/PollRouterTest.java      | 161 ++++++++++++++++++++-
 foreign/node/src/client/client.socket.test.ts      |  94 ++++++++++++
 foreign/node/src/client/client.socket.ts           |   8 +
 10 files changed, 561 insertions(+), 11 deletions(-)

diff --git a/core/sdk/src/driver.rs b/core/sdk/src/driver.rs
index ecf745217..7fca8205d 100644
--- a/core/sdk/src/driver.rs
+++ b/core/sdk/src/driver.rs
@@ -601,7 +601,8 @@ impl OperationDriver {
     ) -> Result<PartitionRouteResponse, IggyError> {
         let body = GetPartitionRouteRequest::try_from(key)?.to_bytes();
         let hinted = self.routes().ask_first(key);
-        let first = hinted.or_else(|| self.links.metadata_primary());
+        let metadata_primary = self.links.metadata_primary();
+        let first = hinted.or(metadata_primary);
         let mut replicas = self.links.ready_replicas();
         let start = first.map_or(0, |first| replicas.partition_point(|id| *id < first));
         replicas.rotate_left(start);
@@ -626,6 +627,17 @@ impl OperationDriver {
                     }
                 }
                 Err(error) if retries_lookup(&error) => refusal = error,
+                Err(
+                    IggyError::StreamIdNotFound(_)
+                    | IggyError::StreamNameNotFound(_)
+                    | IggyError::TopicIdNotFound(_, _)
+                    | IggyError::TopicNameNotFound(_, _)
+                    | IggyError::PartitionNotFound(_, _, _),
+                ) if Some(replica) != metadata_primary => {
+                    // A backup can miss metadata that another client just created.
+                    // Only the metadata primary can make this miss terminal.
+                    refusal = IggyError::TransientNotAccepted;
+                }
                 Err(error) => return Err(error),
             }
         }
@@ -1870,6 +1882,64 @@ mod tests {
         assert_eq!(reads[0].header.minimum_metadata_op, COMMIT);
     }
 
+    #[tokio::test(start_paused = true)]
+    async fn given_a_lagging_backup_when_the_metadata_primary_is_materialising_should_retry_the_route()
+     {
+        let fixture = Fixture::new().await;
+        let metadata_primary = fixture.driver.links.metadata_primary().unwrap();
+        fixture.cluster.script(
+            &endpoint(metadata_primary),
+            GET_PARTITION_ROUTE_CODE,
+            [Answer::Refuse(IggyError::TransientNotAccepted)],
+        );
+        for replica in 0..REPLICAS {
+            if replica != metadata_primary {
+                fixture.cluster.script(
+                    &endpoint(replica),
+                    GET_PARTITION_ROUTE_CODE,
+                    [Answer::Refuse(IggyError::TopicIdNotFound(
+                        fixture.topic_id.clone(),
+                        fixture.stream_id.clone(),
+                    ))],
+                );
+            }
+        }
+
+        fixture.send_messages().await.unwrap();
+
+        let mut queried: Vec<_> = (0..REPLICAS).map(endpoint).collect();
+        queried.push(endpoint(metadata_primary));
+        assert_eq!(
+            endpoints(&fixture.cluster.received(GET_PARTITION_ROUTE_CODE)),
+            queried
+        );
+        assert_eq!(fixture.sends().len(), 1);
+        assert_eq!(endpoints(&fixture.sends()), [endpoint(PRIMARY)]);
+    }
+
+    #[tokio::test(start_paused = true)]
+    async fn given_a_missing_topic_on_the_metadata_primary_when_looking_up_should_return_not_found()
+    {
+        let fixture = Fixture::new().await;
+        let metadata_primary = fixture.driver.links.metadata_primary().unwrap();
+        let missing =
+            IggyError::TopicIdNotFound(fixture.topic_id.clone(), fixture.stream_id.clone());
+        fixture.cluster.script(
+            &endpoint(metadata_primary),
+            GET_PARTITION_ROUTE_CODE,
+            [Answer::Refuse(missing.clone())],
+        );
+
+        let error = fixture.send_messages().await.unwrap_err();
+
+        assert_eq!(error.as_code(), missing.as_code());
+        assert_eq!(
+            endpoints(&fixture.cluster.received(GET_PARTITION_ROUTE_CODE)),
+            [endpoint(metadata_primary)]
+        );
+        assert!(fixture.sends().is_empty());
+    }
+
     #[tokio::test(start_paused = true)]
     async fn given_a_malformed_route_reply_when_looking_up_should_fail_without_a_frame() {
         let f = Fixture::new().await;
diff --git a/foreign/csharp/Iggy_SDK/IggyClient/Implementations/TcpMessageStream.PollRouting.cs b/foreign/csharp/Iggy_SDK/IggyClient/Implementations/TcpMessageStream.PollRouting.cs
index a9a4ff15f..f00c77bc5 100644
--- a/foreign/csharp/Iggy_SDK/IggyClient/Implementations/TcpMessageStream.PollRouting.cs
+++ b/foreign/csharp/Iggy_SDK/IggyClient/Implementations/TcpMessageStream.PollRouting.cs
@@ -592,6 +592,22 @@ public sealed partial class TcpMessageStream
                 {
                     continue;
                 }
+                if (attempt.Error is IggyInvalidStatusCodeException
+                    {
+                        StatusCode: VsrError.STREAM_ID_NOT_FOUND or VsrError.STREAM_NAME_NOT_FOUND
+                        or VsrError.TOPIC_ID_NOT_FOUND or VsrError.TOPIC_NAME_NOT_FOUND or VsrError.PARTITION_NOT_FOUND
+                    })
+                {
+                    lock (_pollRoutingGate)
+                    {
+                        if (_metadataReplica is not { } metadataPrimary
+                            || !_replicaLinks.TryGetValue(metadataPrimary, out var metadataSlot)
+                            || !ReferenceEquals(metadataSlot.Connection, connection))
+                        {
+                            continue;
+                        }
+                    }
+                }
                 ExceptionDispatchInfo.Throw(attempt.Error);
             }
             using var response = attempt.Response!;
diff --git a/foreign/csharp/Iggy_SDK/Vsr/VsrError.cs b/foreign/csharp/Iggy_SDK/Vsr/VsrError.cs
index 8cc3381b7..0e1d41dbd 100644
--- a/foreign/csharp/Iggy_SDK/Vsr/VsrError.cs
+++ b/foreign/csharp/Iggy_SDK/Vsr/VsrError.cs
@@ -46,7 +46,10 @@ internal static class VsrError
     internal const int LIFECYCLE_BUSY = 88;
     internal const int NOT_PRIMARY = 89;
     internal const int EMPTY_RESPONSE = 304;
+    internal const int STREAM_ID_NOT_FOUND = 1009;
+    internal const int STREAM_NAME_NOT_FOUND = 1010;
     internal const int TOPIC_ID_NOT_FOUND = 2010;
+    internal const int TOPIC_NAME_NOT_FOUND = 2011;
     internal const int CONSUMER_GROUP_MEMBER_NOT_FOUND = 5006;
     internal const int PARTITION_NOT_FOUND = 3007;
     internal const int CONSUMER_GROUP_PARTITION_NOT_OWNED = 5009;
diff --git a/foreign/csharp/Iggy_SDK_Tests/VsrTests/PrimaryPollingTests.cs b/foreign/csharp/Iggy_SDK_Tests/VsrTests/PrimaryPollingTests.cs
index ec7d63b55..aad7b26a2 100644
--- a/foreign/csharp/Iggy_SDK_Tests/VsrTests/PrimaryPollingTests.cs
+++ b/foreign/csharp/Iggy_SDK_Tests/VsrTests/PrimaryPollingTests.cs
@@ -1272,6 +1272,105 @@ public sealed class PrimaryPollingTests
         Assert.All(cluster.Primaries, node => Assert.Equal(0, node.Registrations));
     }
 
+    [Theory]
+    [InlineData(VsrError.STREAM_ID_NOT_FOUND, false)]
+    [InlineData(VsrError.STREAM_NAME_NOT_FOUND, false)]
+    [InlineData(VsrError.TOPIC_ID_NOT_FOUND, false)]
+    [InlineData(VsrError.TOPIC_NAME_NOT_FOUND, false)]
+    [InlineData(VsrError.PARTITION_NOT_FOUND, false)]
+    [InlineData(VsrError.STREAM_ID_NOT_FOUND, true)]
+    [InlineData(VsrError.STREAM_NAME_NOT_FOUND, true)]
+    [InlineData(VsrError.TOPIC_ID_NOT_FOUND, true)]
+    [InlineData(VsrError.TOPIC_NAME_NOT_FOUND, true)]
+    [InlineData(VsrError.PARTITION_NOT_FOUND, true)]
+    public async Task given_a_backup_route_lookup_miss_when_metadata_is_materializing_should_continue_discovery(
+        int status, bool remainingReplica)
+    {
+        using var cluster = new PollCluster(primaryCount: remainingReplica ? 2 : 1);
+        using var cancellation = CancellationTokenSource.CreateLinkedTokenSource(TestContext.Current.CancellationToken);
+        cancellation.CancelAfter(TimeSpan.FromSeconds(5));
+        var metadataLookups = 0;
+        var backupLookups = 0;
+        var resolved = 0;
+        cluster.OnCoordinator = request =>
+        {
+            if (request.Code != CommandCodes.GET_PARTITION_ROUTE_CODE)
+            {
+                return null;
+            }
+            if (Interlocked.Increment(ref metadataLookups) == 1 || remainingReplica)
+            {
+                return Reply(request.Operation, [], VsrError.TRANSIENT_NOT_ACCEPTED);
+            }
+            Volatile.Write(ref resolved, 1);
+            return RouteReply(request, cluster.RouteContext, 1, (uint)cluster.Primaries.Length);
+        };
+        cluster.OnPrimaryControl = request =>
+        {
+            if (request.Code != CommandCodes.GET_PARTITION_ROUTE_CODE)
+            {
+                return null;
+            }
+            if (Interlocked.Increment(ref backupLookups) == 1 || !remainingReplica)
+            {
+                return Reply(request.Operation, [], (uint)status);
+            }
+            Volatile.Write(ref resolved, 1);
+            return RouteReply(request, cluster.RouteContext, 1, (uint)cluster.Primaries.Length);
+        };
+        cluster.OnPrimarySend = request =>
+        {
+            Assert.Equal(1, Volatile.Read(ref resolved));
+            return Reply(request.Operation, new byte[4]);
+        };
+        using var client = await cluster.ConnectAsync();
+        for (byte replica = 1; replica <= cluster.Primaries.Length; replica++)
+        {
+            var connection = await (Task<VsrConnection?>)typeof(TcpMessageStream)
+                .GetMethod("FindReadyReplicaAsync", BindingFlags.Instance | BindingFlags.NonPublic)!
+                .Invoke(client, [replica, cancellation.Token])!;
+            Assert.NotNull(connection);
+        }
+
+        await client.SendMessagesAsync(Stream, Topic, Partitioning.PartitionId(0),
+            new Message(Guid.NewGuid(), "payload"u8.ToArray()), cancellation.Token);
+
+        Assert.False(cancellation.IsCancellationRequested);
+        Assert.Equal(remainingReplica ? 1 : 2, metadataLookups);
+        Assert.Equal(remainingReplica ? 2 : 1, backupLookups);
+        var routes = cluster.RouteRequests;
+        Assert.Equal(3, routes.Length);
+        var send = Assert.Single(cluster.PrimaryRequests, request => request.Operation == (byte)VsrOperation.SendMessages);
+        Assert.Equal(cluster.RouteContext, send.Context);
+        Assert.All(routes, route => Assert.True(route.RequestId < send.RequestId));
+    }
+
+    [Theory]
+    [InlineData(VsrError.STREAM_ID_NOT_FOUND)]
+    [InlineData(VsrError.STREAM_NAME_NOT_FOUND)]
+    [InlineData(VsrError.TOPIC_ID_NOT_FOUND)]
+    [InlineData(VsrError.TOPIC_NAME_NOT_FOUND)]
+    [InlineData(VsrError.PARTITION_NOT_FOUND)]
+    public async Task given_a_metadata_primary_route_lookup_miss_when_sending_should_surface_it_without_retrying(int status)
+    {
+        using var cluster = new PollCluster();
+        cluster.OnCoordinator = request => request.Code == CommandCodes.GET_PARTITION_ROUTE_CODE
+            ? Reply(request.Operation, [], (uint)status) : null;
+        using var client = await cluster.ConnectAsync();
+        using var cancellation = CancellationTokenSource.CreateLinkedTokenSource(TestContext.Current.CancellationToken);
+        cancellation.CancelAfter(TimeSpan.FromSeconds(5));
+
+        var error = await Assert.ThrowsAsync<IggyInvalidStatusCodeException>(() => client.SendMessagesAsync(
+            Stream, Topic, Partitioning.PartitionId(0), new Message(Guid.NewGuid(), "payload"u8.ToArray()),
+            cancellation.Token));
+
+        Assert.Equal(status, error.StatusCode);
+        Assert.True(error.FromServer);
+        Assert.False(cancellation.IsCancellationRequested);
+        Assert.Single(cluster.RouteRequests);
+        Assert.DoesNotContain(cluster.PrimaryRequests, request => request.Operation == (byte)VsrOperation.SendMessages);
+    }
+
     [Fact]
     public async Task given_a_malformed_write_reply_when_using_a_primary_should_report_an_unknown_outcome()
     {
diff --git a/foreign/go/client/tcp/tcp_poll_routing.go b/foreign/go/client/tcp/tcp_poll_routing.go
index 40dc45212..05c7ecde2 100644
--- a/foreign/go/client/tcp/tcp_poll_routing.go
+++ b/foreign/go/client/tcp/tcp_poll_routing.go
@@ -146,6 +146,7 @@ func (c *IggyTcpClient) consumerRoute(ctx context.Context, query []byte) (pollRo
 		}
 	}
 	c.polls.mu.Unlock()
+	metadataPrimary := c.links.metadata()
 	for _, link := range c.links.lookupCandidates(preferred, after) {
 		if err := c.bindLink(ctx, link); err != nil {
 			if isSessionError(err) {
@@ -168,6 +169,13 @@ func (c *IggyTcpClient) consumerRoute(ctx context.Context, query []byte) (pollRo
 				c.recordLookupFailure(fence, cached, found, link)
 				continue
 			}
+			// Only the metadata primary can confirm a miss; backups may lag a new namespace.
+			if link != metadataPrimary && (errors.Is(err, ierror.ErrStreamIdNotFound) ||
+				errors.Is(err, ierror.ErrStreamNameNotFound) || errors.Is(err, ierror.ErrTopicIdNotFound) ||
+				errors.Is(err, ierror.ErrTopicNameNotFound) || errors.Is(err, ierror.ErrPartitionNotFound)) {
+				c.recordLookupFailure(fence, cached, found, link)
+				continue
+			}
 			return pollRoute{}, err
 		}
 		var decoded iggcon.PartitionRoute
diff --git a/foreign/go/client/tcp/tcp_poll_routing_test.go b/foreign/go/client/tcp/tcp_poll_routing_test.go
index 9e9c2db15..b1d226f59 100644
--- a/foreign/go/client/tcp/tcp_poll_routing_test.go
+++ b/foreign/go/client/tcp/tcp_poll_routing_test.go
@@ -1512,6 +1512,63 @@ func TestPartitionLookupUsesReadyReplicaWhenMetadataCannotAnswer(t *testing.T) {
 	require.Equal(t, 1, requestCount(fixture.primaries[0].recorded(), command.PollMessagesCode))
 }
 
+func TestPartitionLookupDistinguishesLaggingReplicasFromMissingNamespaces(t *testing.T) {
+	for _, missing := range []ierror.IggyError{ierror.ErrStreamIdNotFound, ierror.ErrStreamNameNotFound,
+		ierror.ErrTopicIdNotFound, ierror.ErrTopicNameNotFound, ierror.ErrPartitionNotFound} {
+		t.Run(fmt.Sprint(missing.Code()), func(t *testing.T) {
+			t.Run("lagging_backup", func(t *testing.T) {
+				var primaryLookups atomic.Uint32
+				fixture := newPrimaryPollFixture(t, func(_, _ int, read request) ([]byte, bool) {
+					if read.code() == uint32(command.GetPartitionRouteCode) {
+						return statusReplyFrame(read.operation(), uint32(missing.Code()), nil), true
+					}
+					return nil, false
+				}, func(_ int, read request) ([]byte, bool) {
+					if read.code() == uint32(command.GetPartitionRouteCode) && primaryLookups.Add(1) == 1 {
+						return statusReplyFrame(read.operation(), uint32(ierror.TransientNotAcceptedCode), nil), true
+					}
+					return nil, false
+				})
+				require.Eventually(t, func() bool {
+					return fixture.client.links.replica(1) != nil && fixture.client.links.replica(2) != nil
+				}, managedLinkTestBudget, managedLinkPoll)
+				ctx, cancel := context.WithTimeout(context.Background(), managedLinkTestBudget)
+				defer cancel()
+
+				_, err := pollPrimaryPartition(ctx, fixture.client, 0)
+
+				require.NoError(t, err)
+				assert.Equal(t, uint32(2), primaryLookups.Load())
+				for _, replica := range fixture.primaries {
+					assert.Equal(t, 1, requestCount(replica.recorded(), command.GetPartitionRouteCode))
+				}
+				assert.Equal(t, 1, requestCount(fixture.primaries[0].recorded(), command.PollMessagesCode))
+				assert.Zero(t, requestCount(fixture.primaries[1].recorded(), command.PollMessagesCode))
+			})
+			t.Run("metadata_primary", func(t *testing.T) {
+				fixture := newPrimaryPollFixture(t, nil, func(_ int, read request) ([]byte, bool) {
+					if read.code() == uint32(command.GetPartitionRouteCode) {
+						return statusReplyFrame(read.operation(), uint32(missing.Code()), nil), true
+					}
+					return nil, false
+				})
+				ctx, cancel := context.WithTimeout(context.Background(), managedLinkTestBudget)
+				defer cancel()
+
+				_, err := pollPrimaryPartition(ctx, fixture.client, 0)
+
+				require.ErrorIs(t, err, missing)
+				assert.Equal(t, 1, requestCount(fixture.coordinator.recorded(), command.GetPartitionRouteCode))
+				assert.Zero(t, requestCount(fixture.coordinator.recorded(), command.PollMessagesCode))
+				for _, replica := range fixture.primaries {
+					assert.Zero(t, requestCount(replica.recorded(), command.GetPartitionRouteCode))
+					assert.Zero(t, requestCount(replica.recorded(), command.PollMessagesCode))
+				}
+			})
+		})
+	}
+}
+
 func TestPartitionRouteCannotReplaceANewerMetadataFloorOrPartitionCount(t *testing.T) {
 	client, peer := newPipeClient(t)
 	received, release := make(chan struct{}), make(chan struct{})
diff --git a/foreign/java/java-sdk/src/main/java/org/apache/iggy/client/async/tcp/PollRouter.java b/foreign/java/java-sdk/src/main/java/org/apache/iggy/client/async/tcp/PollRouter.java
index 2f2a3dcab..14ccbf40c 100644
--- a/foreign/java/java-sdk/src/main/java/org/apache/iggy/client/async/tcp/PollRouter.java
+++ b/foreign/java/java-sdk/src/main/java/org/apache/iggy/client/async/tcp/PollRouter.java
@@ -29,6 +29,7 @@ import org.apache.iggy.client.async.tcp.vsr.VsrHeaders;
 import org.apache.iggy.client.async.tcp.vsr.VsrOperation;
 import org.apache.iggy.client.async.tcp.vsr.VsrRequestEncoder;
 import org.apache.iggy.cluster.ClusterMetadata;
+import org.apache.iggy.cluster.ClusterNodeRole;
 import org.apache.iggy.exception.IggyClientException;
 import org.apache.iggy.exception.IggyConnectionException;
 import org.apache.iggy.exception.IggyErrorCode;
@@ -90,6 +91,7 @@ final class PollRouter {
     private final Set<Poll> pending = new HashSet<>();
     private volatile int rosterSize;
     private final Map<Integer, ConnectionInfo> replicas = new HashMap<>();
+    private ConnectionInfo metadataPrimary;
     private final Map<String, Long> partitionCounts = new HashMap<>();
 
     PollRouter(Supplier<AsyncTcpConnection> coordinator, Function<ConnectionInfo, AsyncTcpConnection> connectData) {
@@ -354,12 +356,16 @@ final class PollRouter {
     @SuppressWarnings({"checkstyle:CyclomaticComplexity", "checkstyle:NPathComplexity"})
     synchronized void observeTopology(ClusterMetadata metadata) {
         replicas.clear();
+        metadataPrimary = null;
         rosterSize = metadata.nodes().size();
         for (var node : metadata.nodes()) {
             if (node.endpoints().tcp() != 0) {
-                replicas.put(
-                        node.replicaId(),
-                        new ConnectionInfo(node.ip(), node.endpoints().tcp()));
+                ConnectionInfo endpoint =
+                        new ConnectionInfo(node.ip(), node.endpoints().tcp());
+                replicas.put(node.replicaId(), endpoint);
+                if (node.role() == ClusterNodeRole.Leader) {
+                    metadataPrimary = endpoint;
+                }
             }
         }
         if (connectData == null || !coordinator.get().isAuthenticated()) {
@@ -624,11 +630,12 @@ final class PollRouter {
                 : CompletableFuture.completedFuture(null);
         return roster.thenCompose(ignored -> lookupConnection(poll, cached))
                 .thenCompose(source -> source.sendRouted(
-                        CommandCode.Messages.GET_PARTITION_ROUTE.getValue(),
-                        Unpooled.wrappedBuffer(poll.routingBody),
-                        0,
-                        poll.deadline,
-                        new AsyncTcpConnection.TransientFailoverState()))
+                                CommandCode.Messages.GET_PARTITION_ROUTE.getValue(),
+                                Unpooled.wrappedBuffer(poll.routingBody),
+                                0,
+                                poll.deadline,
+                                new AsyncTcpConnection.TransientFailoverState())
+                        .exceptionallyCompose(error -> CompletableFuture.failedFuture(lookupFailure(source, error))))
                 .thenCompose(response -> {
                     PartitionRoute decoded;
                     try {
@@ -646,6 +653,37 @@ final class PollRouter {
                 });
     }
 
+    private Throwable lookupFailure(AsyncTcpConnection source, Throwable error) {
+        IggyServerException refusal = AsyncTcpConnection.findServerError(error);
+        boolean missing = refusal != null
+                && switch (refusal.getErrorCode()) {
+                    case STREAM_ID_NOT_FOUND,
+                            STREAM_NAME_NOT_FOUND,
+                            TOPIC_ID_NOT_FOUND,
+                            TOPIC_NAME_NOT_FOUND,
+                            PARTITION_NOT_FOUND -> true;
+                    default -> false;
+                };
+        // A backup can lack metadata that the leader is still materializing.
+        return missing && !isMetadataPrimary(source) ? notAccepted() : unwrap(error);
+    }
+
+    private synchronized boolean isMetadataPrimary(AsyncTcpConnection source) {
+        if (connectData == null) {
+            return true;
+        }
+        if (metadataPrimary == null) {
+            return false;
+        }
+        if (source == coordinator.get()
+                && coordinatorEndpoint != null
+                && LeaderAwareness.isSameSpelling(metadataPrimary, coordinatorEndpoint.get())) {
+            return true;
+        }
+        Slot primary = connections.get(metadataPrimary);
+        return primary != null && primary.connection == source;
+    }
+
     @SuppressWarnings({"checkstyle:CyclomaticComplexity", "checkstyle:NPathComplexity"})
     private CompletableFuture<AsyncTcpConnection> lookupConnection(Poll poll, Route stale) {
         AsyncTcpConnection current = coordinator.get();
diff --git a/foreign/java/java-sdk/src/test/java/org/apache/iggy/client/async/tcp/PollRouterTest.java b/foreign/java/java-sdk/src/test/java/org/apache/iggy/client/async/tcp/PollRouterTest.java
index 002e71199..266241dec 100644
--- a/foreign/java/java-sdk/src/test/java/org/apache/iggy/client/async/tcp/PollRouterTest.java
+++ b/foreign/java/java-sdk/src/test/java/org/apache/iggy/client/async/tcp/PollRouterTest.java
@@ -37,10 +37,17 @@ import org.apache.iggy.exception.IggyClientException;
 import org.apache.iggy.exception.IggyConnectionException;
 import org.apache.iggy.exception.IggyErrorCode;
 import org.apache.iggy.exception.IggyOperationException;
+import org.apache.iggy.exception.IggyServerException;
+import org.apache.iggy.identifier.StreamId;
+import org.apache.iggy.identifier.TopicId;
+import org.apache.iggy.message.Message;
+import org.apache.iggy.message.Partitioning;
+import org.apache.iggy.message.SendMessagesResponse;
 import org.apache.iggy.partition.PartitionContext;
 import org.apache.iggy.serde.CommandCode;
 import org.junit.jupiter.api.Test;
 import org.junit.jupiter.params.ParameterizedTest;
+import org.junit.jupiter.params.provider.EnumSource;
 import org.junit.jupiter.params.provider.ValueSource;
 
 import java.math.BigInteger;
@@ -79,6 +86,138 @@ class PollRouterTest {
     private static final Duration TIMEOUT = Duration.ofSeconds(5);
     private static final Duration NEVER = Duration.ofDays(1);
 
+    @ParameterizedTest
+    @EnumSource(
+            value = IggyErrorCode.class,
+            names = {
+                "STREAM_ID_NOT_FOUND",
+                "STREAM_NAME_NOT_FOUND",
+                "TOPIC_ID_NOT_FOUND",
+                "TOPIC_NAME_NOT_FOUND",
+                "PARTITION_NOT_FOUND"
+            })
+    void shouldRetryANamespaceMissFromALaggingBackup(IggyErrorCode missing) throws Exception {
+        IoEventLoopGroup group = new MultiThreadIoEventLoopGroup(1, NioIoHandler.newFactory());
+        ManualTimers timers = new ManualTimers();
+        Coordinator coordinator = new Coordinator(group, timers);
+        Primary primary = new Primary(group);
+        PollRouter router = new PollRouter(() -> coordinator, endpoint -> primary);
+        router.coordinatorEndpoint(
+                () -> new ConnectionInfo(InetAddress.getLoopbackAddress().getHostAddress(), PRIMARY_PORT + 1));
+        try {
+            coordinator.routeReady = CompletableFuture.failedFuture(
+                    IggyServerException.fromTcpResponse(AsyncTcpConnection.TRANSIENT_NOT_ACCEPTED, new byte[0]));
+            primary.routeReply.completeExceptionally(
+                    IggyServerException.fromTcpResponse(missing.getCode(), new byte[0]));
+            var sent = sendMessage(coordinator, router);
+            assertThat(sent).isNotDone();
+            assertThat(coordinator.routes).isEqualTo(1);
+            timers.runLast();
+            assertThat(primary.routes).isEqualTo(1);
+            assertThat(sent).isNotDone();
+            assertThat(primary.sentContexts).isEmpty();
+
+            coordinator.routeReady = CompletableFuture.completedFuture(null);
+            timers.runLast();
+            timers.runLast();
+            sent.get(TIMEOUT.toMillis(), TimeUnit.MILLISECONDS);
+            assertThat(coordinator.routes).isEqualTo(2);
+            assertThat(primary.routes).isEqualTo(1);
+            assertThat(primary.sentContexts).containsExactly(ROUTE_CONTEXT);
+        } finally {
+            router.clearSession().get(TIMEOUT.toMillis(), TimeUnit.MILLISECONDS);
+            timers.shutdownGracefully(0, 1, TimeUnit.SECONDS).get(5, TimeUnit.SECONDS);
+            group.shutdownGracefully(0, 1, TimeUnit.SECONDS).get(5, TimeUnit.SECONDS);
+        }
+    }
+
+    @ParameterizedTest
+    @ValueSource(booleans = {false, true})
+    void shouldTreatOnlyTheRosterLeaderNamespaceMissAsAuthoritative(boolean coordinatorIsLeader) throws Exception {
+        IoEventLoopGroup group = new MultiThreadIoEventLoopGroup(1, NioIoHandler.newFactory());
+        ManualTimers timers = new ManualTimers();
+        Coordinator coordinator = new Coordinator(group, timers);
+        Primary primary = new Primary(group);
+        PollRouter router = new PollRouter(() -> coordinator, endpoint -> primary);
+        router.coordinatorEndpoint(
+                () -> new ConnectionInfo(InetAddress.getLoopbackAddress().getHostAddress(), PRIMARY_PORT + 1));
+        try {
+            coordinator.metadataLeaderPort = coordinatorIsLeader ? PRIMARY_PORT + 1 : PRIMARY_PORT;
+            var missing = IggyServerException.fromTcpResponse(IggyErrorCode.TOPIC_ID_NOT_FOUND.getCode(), new byte[0]);
+            coordinator.routeReady = CompletableFuture.failedFuture(missing);
+            primary.routeReply.completeExceptionally(missing);
+            var sent = sendMessage(coordinator, router);
+            if (!coordinatorIsLeader) {
+                assertThat(sent).isNotDone();
+                timers.runLast();
+            }
+            assertServerError(sent, IggyErrorCode.TOPIC_ID_NOT_FOUND.getCode());
+            assertThat(coordinator.routes).isEqualTo(1);
+            assertThat(primary.routes).isEqualTo(coordinatorIsLeader ? 0 : 1);
+            assertThat(primary.sentContexts).isEmpty();
+        } finally {
+            router.clearSession().get(TIMEOUT.toMillis(), TimeUnit.MILLISECONDS);
+            timers.shutdownGracefully(0, 1, TimeUnit.SECONDS).get(5, TimeUnit.SECONDS);
+            group.shutdownGracefully(0, 1, TimeUnit.SECONDS).get(5, TimeUnit.SECONDS);
+        }
+    }
+
+    @ParameterizedTest
+    @EnumSource(
+            value = IggyErrorCode.class,
+            names = {"UNAUTHORIZED", "INVALID_CREDENTIALS", "INVALID_FORMAT"})
+    void shouldKeepOtherBackupLookupFailuresTerminal(IggyErrorCode error) throws Exception {
+        IoEventLoopGroup group = new MultiThreadIoEventLoopGroup(1, NioIoHandler.newFactory());
+        ManualTimers timers = new ManualTimers();
+        Coordinator coordinator = new Coordinator(group, timers);
+        Primary primary = new Primary(group);
+        PollRouter router = new PollRouter(() -> coordinator, endpoint -> primary);
+        router.coordinatorEndpoint(
+                () -> new ConnectionInfo(InetAddress.getLoopbackAddress().getHostAddress(), PRIMARY_PORT + 1));
+        try {
+            coordinator.routeReady = CompletableFuture.failedFuture(
+                    IggyServerException.fromTcpResponse(AsyncTcpConnection.TRANSIENT_NOT_ACCEPTED, new byte[0]));
+            primary.routeReply.completeExceptionally(IggyServerException.fromTcpResponse(error.getCode(), new byte[0]));
+            var sent = sendMessage(coordinator, router);
+            assertThat(sent).isNotDone();
+            timers.runLast();
+            assertServerError(sent, error.getCode());
+            assertThat(coordinator.routes).isEqualTo(1);
+            assertThat(primary.routes).isEqualTo(1);
+            assertThat(primary.sentContexts).isEmpty();
+        } finally {
+            router.clearSession().get(TIMEOUT.toMillis(), TimeUnit.MILLISECONDS);
+            timers.shutdownGracefully(0, 1, TimeUnit.SECONDS).get(5, TimeUnit.SECONDS);
+            group.shutdownGracefully(0, 1, TimeUnit.SECONDS).get(5, TimeUnit.SECONDS);
+        }
+    }
+
+    @Test
+    void shouldKeepAnUnknownLeaderNamespaceMissInsideTheOriginalDeadline() throws Exception {
+        IoEventLoopGroup group = new MultiThreadIoEventLoopGroup(1, NioIoHandler.newFactory());
+        ManualTimers timers = new ManualTimers();
+        Coordinator coordinator = new Coordinator(group, timers);
+        Primary primary = new Primary(group);
+        PollRouter router = new PollRouter(() -> coordinator, endpoint -> primary);
+        router.coordinatorEndpoint(
+                () -> new ConnectionInfo(InetAddress.getLoopbackAddress().getHostAddress(), PRIMARY_PORT + 1));
+        try {
+            coordinator.metadataLeaderPort = 0;
+            coordinator.routeReady = CompletableFuture.failedFuture(
+                    IggyServerException.fromTcpResponse(IggyErrorCode.TOPIC_ID_NOT_FOUND.getCode(), new byte[0]));
+            var sent = sendMessage(coordinator, router);
+            assertThat(sent).isNotDone();
+            assertThat(coordinator.routes).isEqualTo(1);
+            timers.scheduled.get(0).run();
+            assertServerError(sent, AsyncTcpConnection.TRANSIENT_NOT_ACCEPTED);
+            assertThat(primary.sentContexts).isEmpty();
+        } finally {
+            router.clearSession().get(TIMEOUT.toMillis(), TimeUnit.MILLISECONDS);
+            timers.shutdownGracefully(0, 1, TimeUnit.SECONDS).get(5, TimeUnit.SECONDS);
+            group.shutdownGracefully(0, 1, TimeUnit.SECONDS).get(5, TimeUnit.SECONDS);
+        }
+    }
+
     @ParameterizedTest
     @ValueSource(booleans = {false, true})
     void shouldAllowAnotherResolveAfterCancellationBeforeTheExchange(boolean duringBind) throws Exception {
@@ -283,6 +422,12 @@ class PollRouterTest {
         }
     }
 
+    private static CompletableFuture<SendMessagesResponse> sendMessage(Coordinator coordinator, PollRouter router) {
+        return new MessagesTcpClient(() -> coordinator, new ClientRoutingState(), router)
+                .sendMessages(
+                        StreamId.of(1L), TopicId.of(1L), Partitioning.partitionId(0L), List.of(Message.of("message")));
+    }
+
     private static ConsensusSession.Ticket retainOffset(Coordinator coordinator) {
         ByteBuf payload = pollPayload();
         payload.writerIndex(payload.writerIndex() - PollRouter.POLL_PARAMETERS_BYTES);
@@ -361,6 +506,10 @@ class PollRouterTest {
     private static final class ManualTimers extends DefaultEventLoop {
         private final List<Runnable> scheduled = new CopyOnWriteArrayList<>();
 
+        void runLast() {
+            scheduled.get(scheduled.size() - 1).run();
+        }
+
         @Override
         public ScheduledFuture<?> schedule(Runnable command, long delay, TimeUnit unit) {
             scheduled.add(command);
@@ -394,6 +543,7 @@ class PollRouterTest {
         private long watermark;
         private PartitionContext context = ROUTE_CONTEXT;
         private int routes;
+        private int metadataLeaderPort = PRIMARY_PORT + 1;
         private CompletableFuture<Void> routeReady = CompletableFuture.completedFuture(null);
 
         Coordinator(IoEventLoopGroup group, EventLoop timers) {
@@ -432,7 +582,7 @@ class PollRouterTest {
             payload.release();
             if (commandCode == CommandCode.System.GET_CLUSTER_METADATA.getValue()) {
                 return CompletableFuture.completedFuture(AsyncIggyTcpClientTransientFailoverTest.clusterMetadata(
-                        PRIMARY_PORT + 1, PRIMARY_PORT, PRIMARY_PORT + 1));
+                        PRIMARY_PORT + 1, PRIMARY_PORT, metadataLeaderPort));
             }
             assertThat(commandCode).isEqualTo(CommandCode.Messages.GET_PARTITION_ROUTE.getValue());
             routes++;
@@ -461,6 +611,8 @@ class PollRouterTest {
         private final List<PartitionContext> sentContexts = new CopyOnWriteArrayList<>();
         private final List<byte[]> sentFrames = new CopyOnWriteArrayList<>();
         private final CompletableFuture<ByteBuf> unanswered = new CompletableFuture<>();
+        private final CompletableFuture<ByteBuf> routeReply = new CompletableFuture<>();
+        private int routes;
         private CompletableFuture<ByteBuf> binding = CompletableFuture.completedFuture(Unpooled.EMPTY_BUFFER);
         private final AtomicInteger closes = new AtomicInteger();
         private boolean holdAfterFirst = true;
@@ -482,13 +634,18 @@ class PollRouterTest {
             if (commandCode == CommandCode.System.BIND_SESSION.getValue()) {
                 return binding;
             }
+            if (commandCode == GET_PARTITION_ROUTE_CODE) {
+                routes++;
+                return routeReply;
+            }
             sentContexts.add(state.context());
             if (state.ticket() != null) {
                 sentFrames.add(frozenFrame(state.ticket()));
             }
             beforeSend.run();
             return !holdAfterFirst || sentContexts.size() == 1
-                    ? CompletableFuture.completedFuture(emptyPoll(0))
+                    ? CompletableFuture.completedFuture(
+                            commandCode == CommandCode.Messages.SEND.getValue() ? Unpooled.EMPTY_BUFFER : emptyPoll(0))
                     : unanswered;
         }
 
diff --git a/foreign/node/src/client/client.socket.test.ts b/foreign/node/src/client/client.socket.test.ts
index 4d0fb4e49..d6ae897d3 100644
--- a/foreign/node/src/client/client.socket.test.ts
+++ b/foreign/node/src/client/client.socket.test.ts
@@ -3171,6 +3171,100 @@ describe('native replica resources and route floors', () => {
     } finally { client.destroy(); await server.close(); }
   });
 
+  for (const status of [1009, 1010, 2010, 2011, 3007]) {
+    it(`ignores a backup namespace miss ${status} while the primary materializes the route`, async (context) => {
+      const lookups: number[] = [];
+      let primaryLookups = 0;
+      const cluster = await startPollCluster((frame, socket) => {
+        if (frame.readUInt32LE(REQUEST_OFFSET.reserved) !== COMMAND_CODE.GetPartitionRoute) return false;
+        lookups.push(7);
+        socket.write(replyFrame(frame, Operation.NonReplicated, Buffer.alloc(0), status));
+        return true;
+      }, (frame, socket) => {
+        if (frame.readUInt32LE(REQUEST_OFFSET.reserved) !== COMMAND_CODE.GetPartitionRoute) return false;
+        lookups.push(0);
+        socket.write(++primaryLookups === 1
+          ? replyFrame(frame, Operation.NonReplicated, Buffer.alloc(0), TRANSIENT_NOT_ACCEPTED)
+          : replyFrame(frame, Operation.NonReplicated, routingBody(1n)));
+        return true;
+      });
+      try {
+        await cluster.client.authenticate(vsrConfig(cluster.coordinator.port).credentials);
+        await waitUntil(() => countCommand(cluster.primary, COMMAND_CODE.BindSession) === 1);
+        context.mock.timers.enable({ apis: ['Date', 'setTimeout'] });
+        let backoffStarted!: () => void;
+        const backoff = new Promise<void>((resolve) => { backoffStarted = resolve; });
+        context.mock.method(Math, 'random', () => { backoffStarted(); return 1 - Number.EPSILON; });
+        const pending = cluster.client.sendCommand(COMMAND_CODE.SendMessages, explicitSend, { deadline: Date.now() + 500 });
+        await Promise.race([backoff, pending]);
+        await new Promise<void>((resolve) => setImmediate(resolve));
+        assert.deepEqual(lookups, [0, 7]);
+        context.mock.timers.tick(50);
+        await pending;
+        assert.deepEqual(lookups, [0, 7, 0]);
+        assert.equal(framesOf(cluster.coordinator, Operation.SendMessages).length, 0);
+        assert.equal(framesOf(cluster.primary, Operation.SendMessages).length, 1);
+      } finally { context.mock.timers.reset(); await cluster.close(); }
+    });
+
+    it(`returns a known metadata primary namespace miss ${status} without sending`, async (context) => {
+      const cluster = await startPollCluster(undefined, (frame, socket) => {
+        if (frame.readUInt32LE(REQUEST_OFFSET.reserved) !== COMMAND_CODE.GetPartitionRoute) return false;
+        socket.write(replyFrame(frame, Operation.NonReplicated, Buffer.alloc(0), status));
+        return true;
+      });
+      try {
+        await cluster.client.authenticate(vsrConfig(cluster.coordinator.port).credentials);
+        await waitUntil(() => countCommand(cluster.primary, COMMAND_CODE.BindSession) === 1);
+        context.mock.timers.enable({ apis: ['Date', 'setTimeout'] });
+        await assert.rejects(
+          cluster.client.sendCommand(COMMAND_CODE.SendMessages, explicitSend, { deadline: Date.now() + 500 }),
+          (error: unknown) => error instanceof ResponseError && error.errorCode === status &&
+            error.commandCode === COMMAND_CODE.SendMessages
+        );
+        assert.equal(countCommand(cluster.coordinator, COMMAND_CODE.GetPartitionRoute), 1);
+        assert.equal(countCommand(cluster.primary, COMMAND_CODE.GetPartitionRoute), 0);
+        assert.equal(framesOf(cluster.coordinator, Operation.SendMessages).length, 0);
+        assert.equal(framesOf(cluster.primary, Operation.SendMessages).length, 0);
+      } finally { context.mock.timers.reset(); await cluster.close(); }
+    });
+  }
+
+  it('keeps backup namespace misses transient until the route deadline expires', async (context) => {
+    const cluster = await startPollCluster((frame, socket) => {
+      if (frame.readUInt32LE(REQUEST_OFFSET.reserved) !== COMMAND_CODE.GetPartitionRoute) return false;
+      socket.write(replyFrame(frame, Operation.NonReplicated, Buffer.alloc(0), 2010));
+      return true;
+    }, (frame, socket) => {
+      if (frame.readUInt32LE(REQUEST_OFFSET.reserved) !== COMMAND_CODE.GetPartitionRoute) return false;
+      socket.write(replyFrame(frame, Operation.NonReplicated, Buffer.alloc(0), TRANSIENT_NOT_ACCEPTED));
+      return true;
+    });
+    try {
+      await cluster.client.authenticate(vsrConfig(cluster.coordinator.port).credentials);
+      await waitUntil(() => countCommand(cluster.primary, COMMAND_CODE.BindSession) === 1);
+      context.mock.timers.enable({ apis: ['Date', 'setTimeout'] });
+      let backoffStarted!: () => void;
+      const backoff = new Promise<void>((resolve) => { backoffStarted = resolve; });
+      context.mock.method(Math, 'random', () => { backoffStarted(); return 1 - Number.EPSILON; });
+      const routeTimeout = 25;
+      const pending = cluster.client.sendCommand(COMMAND_CODE.SendMessages, explicitSend, { deadline: Date.now() + routeTimeout });
+      await Promise.race([backoff, pending]);
+      await new Promise<void>((resolve) => setImmediate(resolve));
+      assert.equal(countCommand(cluster.coordinator, COMMAND_CODE.GetPartitionRoute), 1);
+      assert.equal(countCommand(cluster.primary, COMMAND_CODE.GetPartitionRoute), 1);
+      const rejected = assert.rejects(pending,
+        (error: unknown) => error instanceof ResponseError && error.errorCode === TRANSIENT_NOT_ACCEPTED
+      );
+      context.mock.timers.tick(routeTimeout);
+      await rejected;
+      assert.equal(countCommand(cluster.coordinator, COMMAND_CODE.GetPartitionRoute), 1);
+      assert.equal(countCommand(cluster.primary, COMMAND_CODE.GetPartitionRoute), 1);
+      assert.equal(framesOf(cluster.coordinator, Operation.SendMessages).length, 0);
+      assert.equal(framesOf(cluster.primary, Operation.SendMessages).length, 0);
+    } finally { context.mock.timers.reset(); await cluster.close(); }
+  });
+
   for (const refusal of ['stale', 'conflicting', 'refused'] as const) {
     it(`visits every ready replica when earlier route replies are ${refusal}`, async () => {
       const incarnation = 17n;
diff --git a/foreign/node/src/client/client.socket.ts b/foreign/node/src/client/client.socket.ts
index fcab37d5f..83b464ca8 100644
--- a/foreign/node/src/client/client.socket.ts
+++ b/foreign/node/src/client/client.socket.ts
@@ -70,6 +70,7 @@ const NOT_PRIMARY = 89;
 const INVALID_COMMAND = 3;
 const FEATURE_UNAVAILABLE = 5;
 const INVALID_SESSION_BINDING = 14004;
+const ROUTE_NAMESPACE_MISSING = new Set([1009, 1010, 2010, 2011, 3007]);
 const POLL_OPTIONS_SIZE = 9 + 4 + 1;
 const IDENTIFIER_PREFIX_SIZE = 2;
 const SEND_METADATA_LENGTH_SIZE = 4;
@@ -467,6 +468,13 @@ export class CommandResponseStream extends EventEmitter {
           throw error;
         }
         this.ensureGeneration(generation, COMMAND_CODE.GetPartitionRoute);
+        if (error instanceof ResponseError && ROUTE_NAMESPACE_MISSING.has(error.errorCode) &&
+            (this.metadataReplica === undefined || this.replicas.get(this.metadataReplica)?.connection !== link)) {
+          // A backup can lag a metadata create while the primary materializes the route.
+          lastRefusal = responseError(COMMAND_CODE.GetPartitionRoute, TRANSIENT_NOT_ACCEPTED);
+          lastRefusal.fromServer = error.fromServer;
+          continue;
+        }
         if (error instanceof DeserializeError || (error instanceof ResponseError && !isTransient(error.errorCode))) throw error;
         if (error instanceof ResponseError) lastRefusal = error;
       }


(iggy) 05/07: fix(swift): route polls and offsets through partition routes

Posted by hg...@apache.org.
This is an automated email from the ASF dual-hosted git repository.

hubcio pushed a commit to branch feat/sdk-partition-routing
in repository https://gitbox.apache.org/repos/asf/iggy.git

commit 1c95ff5a209470b50c41e553bbee401deef3f3b2
Author: Hubert Gruszecki <h....@gmail.com>
AuthorDate: Fri Oct 16 17:26:17 2026 +0200

    fix(swift): route polls and offsets through partition routes
    
    The Swift messaging from #4553 polled and stored offsets through the
    routing commands 103, 104 and 123, which the server no longer serves.
    The package did not build. The server also serves an offset read
    only on the partition primary, under the context of its route.
    
    Polls and the three offset commands now look up GetPartitionRoute
    and send under its context. The reply names the primary by replica
    id, so the router maps the id through the cluster roster and reads
    the roster again when the id is missing. A data connection binds
    the client's session at the metadata op of the route. A group poll,
    a store or a delete without a partition fails with
    InvalidIdentifier before anything is sent.
    
    The golden fixture drops the poll routing vector and regenerates
    the committed reply vector, which no longer matched its generator.
---
 foreign/swift/Sources/Iggy/Client/ClientCore.swift |  18 +-
 .../Sources/Iggy/Client/IggyClient+Messages.swift  | 114 ++++++-----
 foreign/swift/Sources/Iggy/Client/IggyClient.swift |  13 +-
 foreign/swift/Sources/Iggy/Client/PollRouter.swift | 138 ++++++++-----
 .../swift/Sources/Iggy/Protocol/Responses.swift    |  43 ++--
 foreign/swift/Tests/IggyTests/Fixtures/golden.json |   3 +-
 foreign/swift/Tests/IggyTests/MessagingTests.swift | 220 +++++++++++++++------
 .../Tests/IggyTests/ResponseVectorTests.swift      |  14 +-
 .../Tests/IggyTests/Support/FakeVSRServer.swift    |  16 +-
 foreign/swift/Tools/golden-vectors/src/main.rs     |  31 +--
 10 files changed, 345 insertions(+), 265 deletions(-)

diff --git a/foreign/swift/Sources/Iggy/Client/ClientCore.swift b/foreign/swift/Sources/Iggy/Client/ClientCore.swift
index 3b06742d0..19a03b39f 100644
--- a/foreign/swift/Sources/Iggy/Client/ClientCore.swift
+++ b/foreign/swift/Sources/Iggy/Client/ClientCore.swift
@@ -272,6 +272,12 @@ actor ClientCore {
 
     var bindSecret: [UInt8] { session.bindSecret }
 
+    /// The bound session as a data connection binds to it, at the metadata
+    /// watermark `metadataOp`. Nil while no session is bound.
+    func sessionIdentity(at metadataOp: UInt64) -> Responses.SessionIdentity? {
+        session.session.map { Responses.SessionIdentity(clientID: session.clientID, session: $0, metadataWatermark: metadataOp) }
+    }
+
     /// Stamps a frame for a data connection from the shared session, for the
     /// session `identity` names. Replicated requests take the next id of the
     /// session's counter; reads carry its current value. A session that was
@@ -1164,7 +1170,7 @@ actor ClientCore {
         do {
             let body = try await exchange(code: CommandCode.getClusterMetadata.rawValue, payload: [])
             let metadata = try Responses.clusterMetadata(body[...])
-            learnRosterSize(metadata)
+            pollRouter.learnRoster(metadata)
             return Self.transportEndpoints(metadata)
         } catch {
             logger.debug("Failed to read the cluster roster: \(error)")
@@ -1172,14 +1178,6 @@ actor ClientCore {
         }
     }
 
-    /// Tells the router whether polls go to data connections. An empty
-    /// roster says nothing about the cluster, so the router keeps asking.
-    private func learnRosterSize(_ metadata: ClusterMetadata) {
-        if !metadata.nodes.isEmpty {
-            pollRouter.learnRosterSize(metadata.nodes.count)
-        }
-    }
-
     static func transportEndpoints(_ metadata: ClusterMetadata) -> [String] {
         metadata.nodes.filter { $0.endpoints.tcp != 0 }.map(\.tcpAddress)
     }
@@ -1224,7 +1222,7 @@ actor ClientCore {
                 logger.debug("Failed to get cluster metadata: \(error), continuing on \(currentAddress)")
                 return LeaderCheck(redirect: nil, endpoints: [])
             }
-            learnRosterSize(metadata)
+            pollRouter.learnRoster(metadata)
             let endpoints = Self.transportEndpoints(metadata)
             if metadata.nodes.count <= 1 {
                 return LeaderCheck(redirect: nil, endpoints: endpoints)
diff --git a/foreign/swift/Sources/Iggy/Client/IggyClient+Messages.swift b/foreign/swift/Sources/Iggy/Client/IggyClient+Messages.swift
index 903b53b9f..2dcb756d6 100644
--- a/foreign/swift/Sources/Iggy/Client/IggyClient+Messages.swift
+++ b/foreign/swift/Sources/Iggy/Client/IggyClient+Messages.swift
@@ -95,7 +95,7 @@ extension IggyClient {
         let strategy = strategyFor(partitionID ?? 0)
         let payload = try Requests.pollMessages(
             consumer: consumer, streamID: streamID, topicID: topicID, partitionID: partitionID, strategy: strategy, count: count, autoCommit: autoCommit)
-        return try Responses.polledMessages(try await routedPoll(payload, context: strategy.context)[...])
+        return try Responses.polledMessages(try await routedPartitionRequest(.pollMessages, payload: payload, context: strategy.context)[...])
     }
 
     // MARK: Partition contexts
@@ -114,7 +114,7 @@ extension IggyClient {
                 captured = context
             } else {
                 let body = try await send(.getPartitionRoute, Requests.partitionRoute(streamID: streamID, topicID: topicID, partitionID: partitionID))
-                captured = try Responses.partitionRoute(body[...])
+                captured = try Responses.partitionRoute(body[...]).context
                 state.setPartitionContext(key, partitionID: partitionID, captured)
             }
             do {
@@ -130,18 +130,22 @@ extension IggyClient {
         }
     }
 
-    /// A poll on its route. The route key is the poll without its strategy,
-    /// count, and auto-commit flag, which do not change where it goes.
-    func routedPoll(_ payload: [UInt8], context: PartitionContext?) async throws -> [UInt8] {
-        let key = PollRouter.RouteKey(code: .getPollRouting, prefix: payload.dropLast(RawRequest.pollParametersSize))
-        return try await core.pollRouter.send(.pollMessagesOnPrimary, payload: payload, key: key, routePayload: payload, context: context, coordinator: core)
-    }
-
-    /// An offset write on its route. `routePayload` is the consumer, stream,
-    /// topic, and partition the write names.
-    func routedOffsetWrite(_ code: CommandCode, payload: [UInt8], routePayload: [UInt8], context: PartitionContext?) async throws {
-        let key = PollRouter.RouteKey(code: .getConsumerOffsetRouting, prefix: routePayload[...])
-        _ = try await core.pollRouter.send(code, payload: payload, key: key, routePayload: routePayload, context: context, coordinator: core)
+    /// A poll or a consumer-offset request on the route of the partition its
+    /// payload names, as `OperationDriver::send_raw` in the Rust SDK picks
+    /// it. A plain consumer's poll and an offset read without a partition go
+    /// to partition 0. A group poll, a store, and a delete must name one.
+    func routedPartitionRequest(_ code: CommandCode, payload: [UInt8], context: PartitionContext?) async throws -> [UInt8] {
+        let target = try RawRequest.consumerTarget(payload)
+        let partitionID: UInt32
+        if let named = target.partitionID {
+            partitionID = named
+        } else if code == .getConsumerOffset || (code == .pollMessages && target.consumerKind == Consumer.Kind.consumer.rawValue) {
+            partitionID = 0
+        } else {
+            throw IggyError(.invalidIdentifier, context: "command \(code.rawValue) needs a partition id")
+        }
+        let key = PollRouter.RouteKey(stream: target.stream, topic: target.topic, partitionID: partitionID)
+        return try await core.pollRouter.send(code, payload: payload, key: key, context: context, coordinator: core)
     }
 
     // MARK: Client-side partitioning
@@ -232,7 +236,8 @@ extension IggyClient {
             let payload = try Requests.pollMessages(
                 consumer: consumer, streamID: streamID, topicID: topicID, partitionID: partitionID, strategy: strategy, count: count, autoCommit: autoCommit)
             do {
-                let polled = try Responses.polledMessages(try await routedPoll(payload, context: strategy.context)[...])
+                let polled = try Responses.polledMessages(
+                    try await routedPartitionRequest(.pollMessages, payload: payload, context: strategy.context)[...])
                 if polled.messages.isEmpty, polled.partitionID == PolledMessages.resyncRequiredPartition {
                     // The coordinator fences a stale assignment through the
                     // empty poll, for want of a typed error.
@@ -262,18 +267,19 @@ extension IggyClient {
 
 extension IggyClient {
     /// Stores the offset of a consumer on a partition. A consumer-group
-    /// consumer stores it for the group.
+    /// consumer stores it for the group. A nil `partitionID` fails with
+    /// ``IggyErrorCode/invalidIdentifier`` before anything is sent.
     public func storeConsumerOffset(
         consumer: Consumer = .default, streamID: Identifier, topicID: Identifier, partitionID: UInt32?, offset: UInt64
     )
         async throws
     {
         try await requireAuthenticated()
-        try await routedOffsetWrite(
+        _ = try await routedPartitionRequest(
             .storeConsumerOffset,
             payload: Requests.storeConsumerOffset(
                 consumer: consumer, streamID: streamID, topicID: topicID, partitionID: partitionID, offset: offset, ack: .quorum),
-            routePayload: Requests.getConsumerOffset(consumer: consumer, streamID: streamID, topicID: topicID, partitionID: partitionID), context: nil)
+            context: nil)
     }
 
     /// Stores a checkpoint under the partition context of the poll that
@@ -281,34 +287,36 @@ extension IggyClient {
     /// consumer group, reassigned since.
     public func storeConsumerPosition(consumer: Consumer = .default, streamID: Identifier, topicID: Identifier, position: ConsumerPosition) async throws {
         try await requireAuthenticated()
-        try await routedOffsetWrite(
+        _ = try await routedPartitionRequest(
             .storeConsumerOffset,
             payload: Requests.storeConsumerOffset(
                 consumer: consumer, streamID: streamID, topicID: topicID, partitionID: position.partitionID, offset: position.offset, ack: .quorum),
-            routePayload: Requests.getConsumerOffset(consumer: consumer, streamID: streamID, topicID: topicID, partitionID: position.partitionID),
             context: position.context)
     }
 
     /// The stored offset of a consumer on a partition, or nil when none is
-    /// stored.
+    /// stored. A nil `partitionID` reads partition 0.
     public func getConsumerOffset(
         consumer: Consumer = .default, streamID: Identifier, topicID: Identifier, partitionID: UInt32?
     ) async throws
         -> ConsumerOffsetInfo?
     {
         try await requireAuthenticated()
-        let body = try await send(
-            .getConsumerOffset, Requests.getConsumerOffset(consumer: consumer, streamID: streamID, topicID: topicID, partitionID: partitionID))
+        let body = try await routedPartitionRequest(
+            .getConsumerOffset, payload: Requests.getConsumerOffset(consumer: consumer, streamID: streamID, topicID: topicID, partitionID: partitionID),
+            context: nil)
         return body.isEmpty ? nil : try Responses.consumerOffset(body[...])
     }
 
-    /// Deletes the stored offset of a consumer on a partition.
+    /// Deletes the stored offset of a consumer on a partition. A nil
+    /// `partitionID` fails with ``IggyErrorCode/invalidIdentifier`` before
+    /// anything is sent.
     public func deleteConsumerOffset(consumer: Consumer = .default, streamID: Identifier, topicID: Identifier, partitionID: UInt32?) async throws {
         try await requireAuthenticated()
-        try await routedOffsetWrite(
+        _ = try await routedPartitionRequest(
             .deleteConsumerOffset,
             payload: Requests.deleteConsumerOffset(consumer: consumer, streamID: streamID, topicID: topicID, partitionID: partitionID, ack: .quorum),
-            routePayload: Requests.getConsumerOffset(consumer: consumer, streamID: streamID, topicID: topicID, partitionID: partitionID), context: nil)
+            context: nil)
     }
 }
 
@@ -319,24 +327,18 @@ extension IggyClient {
     /// carries the partition context the server requires. Nil for any other
     /// code.
     func sendRawPartitionRequest(code: UInt32, payload: [UInt8]) async throws -> [UInt8]? {
-        switch CommandCode(rawValue: code) {
+        guard let command = CommandCode(rawValue: code) else {
+            return nil
+        }
+        switch command {
         case .sendMessages:
             let target = try RawRequest.sendTarget(payload)
             return try await sendWithPartitionContext(streamID: target.stream, topicID: target.topic, partitionID: target.partitionID, payload: payload)
         case .pollMessages:
             try RawRequest.validatePoll(payload)
-            return try await routedPoll(payload, context: nil)
-        case .storeConsumerOffset, .deleteConsumerOffset:
-            let prefix = try RawRequest.consumerTargetPrefix(payload)
-            let command: CommandCode = code == CommandCode.storeConsumerOffset.rawValue ? .storeConsumerOffset : .deleteConsumerOffset
-            let key = PollRouter.RouteKey(code: .getConsumerOffsetRouting, prefix: prefix[...])
-            return try await core.pollRouter.send(command, payload: payload, key: key, routePayload: prefix, context: nil, coordinator: core)
-        case .getPollRouting, .pollMessagesOnPrimary, .getConsumerOffsetRouting:
-            // The routing protocol itself, sent once as the Rust client sends
-            // it: a replay after a reconnect could run under another session.
-            // A dropped client reconnects first, as for a typed call.
-            try await requireAuthenticated()
-            return try await core.exchangeOnce(code: code, payload: payload, context: .empty)
+            return try await routedPartitionRequest(.pollMessages, payload: payload, context: nil)
+        case .getConsumerOffset, .storeConsumerOffset, .deleteConsumerOffset:
+            return try await routedPartitionRequest(command, payload: payload, context: nil)
         default:
             return nil
         }
@@ -355,6 +357,14 @@ private enum RawRequest {
         let partitionID: UInt32
     }
 
+    struct ConsumerTarget {
+        let consumerKind: UInt8
+        let stream: Identifier
+        let topic: Identifier
+        /// Nil when the request names no partition.
+        let partitionID: UInt32?
+    }
+
     /// `[metadata_len:u32][stream][topic][partitioning][messages_count:u32]`
     /// leads the batch, and the fields must fit the declared length. Balanced
     /// and key partitioning are resolved by the typed send from its cache and
@@ -375,29 +385,27 @@ private enum RawRequest {
         return SendTarget(stream: stream, topic: topic, partitionID: partitionID)
     }
 
-    /// The consumer, stream, topic, and partition that lead a poll and an
-    /// offset request, which is the payload of the offset route lookup.
-    static func consumerTargetPrefix(_ payload: [UInt8]) throws -> [UInt8] {
-        let length = try decode(payload) { reader in
-            try skipConsumerTarget(&reader)
-            return reader.position
-        }
-        return Array(payload[..<length])
+    /// `[consumer kind:1][consumer][stream][topic][has partition:1][partition:4]`
+    /// leads a poll and every consumer-offset request.
+    static func consumerTarget(_ payload: [UInt8]) throws -> ConsumerTarget {
+        try decode(payload) { reader in try readConsumerTarget(&reader) }
     }
 
     static func validatePoll(_ payload: [UInt8]) throws {
         try decode(payload) { reader in
-            try skipConsumerTarget(&reader)
+            _ = try readConsumerTarget(&reader)
             try reader.skip(pollParametersSize)
         }
     }
 
-    private static func skipConsumerTarget(_ reader: inout ByteReader) throws {
-        _ = try reader.readUInt8()
-        _ = try Identifier.decode(from: &reader)
-        _ = try Identifier.decode(from: &reader)
+    private static func readConsumerTarget(_ reader: inout ByteReader) throws -> ConsumerTarget {
+        let consumerKind = try reader.readUInt8()
         _ = try Identifier.decode(from: &reader)
-        try reader.skip(1 + 4)
+        let stream = try Identifier.decode(from: &reader)
+        let topic = try Identifier.decode(from: &reader)
+        let hasPartition = try reader.readUInt8() != 0
+        let partitionID = try reader.readUInt32()
+        return ConsumerTarget(consumerKind: consumerKind, stream: stream, topic: topic, partitionID: hasPartition ? partitionID : nil)
     }
 
     private static func decode<T>(_ payload: [UInt8], _ body: (inout ByteReader) throws -> T) throws -> T {
diff --git a/foreign/swift/Sources/Iggy/Client/IggyClient.swift b/foreign/swift/Sources/Iggy/Client/IggyClient.swift
index 6f4e47905..39a31634d 100644
--- a/foreign/swift/Sources/Iggy/Client/IggyClient.swift
+++ b/foreign/swift/Sources/Iggy/Client/IggyClient.swift
@@ -176,15 +176,16 @@ public final class IggyClient: Sendable {
     ///
     /// Partition requests carry the partition context their typed call
     /// sends: `SendMessages` with an explicit partition id, `PollMessages`,
-    /// `StoreConsumerOffset`, and `DeleteConsumerOffset` take the route of
+    /// `GetConsumerOffset`, `StoreConsumerOffset`, and `DeleteConsumerOffset`
+    /// take the route of
     /// ``sendMessages(streamID:topicID:partitioning:messages:)``,
     /// ``pollMessages(streamID:topicID:partitionID:consumer:strategy:count:autoCommit:)``,
     /// and the offset calls. A raw send with balanced or key partitioning
-    /// fails with ``IggyErrorCode/featureUnavailable``, and a partition
-    /// payload that does not decode fails with ``IggyErrorCode/invalidCommand``,
-    /// before anything is sent. The routing codes `GetPollRouting`,
-    /// `PollMessagesOnPrimary`, and `GetConsumerOffsetRouting` are sent once
-    /// on the current connection, with no reconnect or replay.
+    /// fails with ``IggyErrorCode/featureUnavailable``. A group poll, a store,
+    /// or a delete that names no partition fails with
+    /// ``IggyErrorCode/invalidIdentifier``, and a partition payload that does
+    /// not decode fails with ``IggyErrorCode/invalidCommand``. Each fails
+    /// before anything is sent.
     public func sendRawRequest(code: UInt32, payload: [UInt8]) async throws -> [UInt8] {
         guard !CommandCode.isSessionControl(code) else {
             throw IggyError(.invalidCommand, context: "code \(code) controls the session; use login and logout")
diff --git a/foreign/swift/Sources/Iggy/Client/PollRouter.swift b/foreign/swift/Sources/Iggy/Client/PollRouter.swift
index 84a2daf80..86cba08c2 100644
--- a/foreign/swift/Sources/Iggy/Client/PollRouter.swift
+++ b/foreign/swift/Sources/Iggy/Client/PollRouter.swift
@@ -17,17 +17,19 @@
 
 import NIOConcurrencyHelpers
 
-/// Routes polls and consumer-offset writes to the primary of their
-/// partition, a port of `PollRouter` in `core/sdk/src/driver/poll_router.rs`.
+/// Routes polls and consumer-offset requests to the primary of their
+/// partition, as `OperationDriver` in `core/sdk/src/driver.rs` routes its
+/// partition calls.
 ///
 /// A request first asks the coordinator, the connection the client signed in
-/// on, for its route (`GetPollRouting` or `GetConsumerOffsetRouting`): the
-/// partition primary and the partition context the request carries. On a
-/// single node the request then goes over the coordinator connection. In a
-/// cluster it goes over a data connection to the primary, bound to the
-/// coordinator's session with `BindSession`, so consumer-group membership
-/// stays with the coordinator. Routes are cached until a request on them
-/// fails or the session is replaced.
+/// on, for the route of its partition (`GetPartitionRoute`): the partition
+/// context the request carries and the replica id of the partition primary,
+/// which the cluster roster maps to an endpoint. On a single node the request
+/// then goes over the coordinator connection. In a cluster it goes over a
+/// data connection to the primary, bound to the client's session with
+/// `BindSession`, so consumer-group membership stays with that session.
+/// Routes are cached until a request on them fails or the session is
+/// replaced.
 final class PollRouter: Sendable {
     /// Bounds one routed request across its lookups, attempts, and pauses.
     static let pollTimeout: Duration = .seconds(30)
@@ -37,17 +39,20 @@ final class PollRouter: Sendable {
     static let maxCachedRoutes = 4096
     static let maxDataConnections = 256
 
-    /// A route is cached per lookup code and the request prefix that names
-    /// the partition and the consumer.
+    /// A partition as its caller spelled it. A stream or topic named by
+    /// number and the same one named by name are two keys.
     struct RouteKey: Hashable, Sendable {
-        let code: CommandCode
-        let prefix: ArraySlice<UInt8>
+        let stream: Identifier
+        let topic: Identifier
+        let partitionID: UInt32
     }
 
     private struct Route: Sendable {
         /// The fence of the session the route was read under.
         let fence: UInt128Value
-        let endpoint: String
+        let primaryReplica: UInt8
+        /// The client's session, with the route's metadata op as the
+        /// watermark a data connection binds at.
         let consumerSession: Responses.SessionIdentity
         let context: PartitionContext
     }
@@ -70,8 +75,8 @@ final class PollRouter: Sendable {
         /// route or a connection of a replaced session is never published
         /// or used.
         var fence: UInt128Value
-        /// Nodes in the roster; zero until a roster read succeeded.
-        var rosterSize = 0
+        /// The roster by replica id; empty until a roster read succeeded.
+        var nodes: [UInt8: ClusterNode] = [:]
         var routes: [RouteKey: Route] = [:]
         var slots: [String: Slot] = [:]
         var nextHeartbeat: ContinuousClock.Instant?
@@ -83,9 +88,16 @@ final class PollRouter: Sendable {
         state = NIOLockedValueBox(State(fence: fence))
     }
 
-    /// Records the roster size a leader check or a roster read reported.
-    func learnRosterSize(_ size: Int) {
-        state.withLockedValue { $0.rosterSize = size }
+    /// Records the roster a leader check or a roster read reported, which
+    /// tells whether requests go to data connections and where each replica
+    /// listens. An empty roster says nothing about the cluster, so the router
+    /// keeps asking. A replica id the roster repeats keeps its first node.
+    func learnRoster(_ metadata: ClusterMetadata) {
+        guard !metadata.nodes.isEmpty else {
+            return
+        }
+        let nodes = Dictionary(metadata.nodes.map { ($0.replicaID, $0) }, uniquingKeysWith: { first, _ in first })
+        state.withLockedValue { $0.nodes = nodes }
     }
 
     /// Drops every route and data connection of the session that ended and
@@ -101,7 +113,7 @@ final class PollRouter: Sendable {
         }
     }
 
-    /// Sends a poll or an offset write on its route. `context` is the
+    /// Sends a poll or an offset request on its route. `context` is the
     /// partition context the caller captured, else the route's is taken and
     /// kept for every retry.
     ///
@@ -109,7 +121,7 @@ final class PollRouter: Sendable {
     /// of cancelling one in flight, which would take the coordinator
     /// connection, and the session's group membership, with it.
     func send(
-        _ code: CommandCode, payload: [UInt8], key: RouteKey, routePayload: [UInt8], context: PartitionContext?, coordinator: ClientCore
+        _ code: CommandCode, payload: [UInt8], key: RouteKey, context: PartitionContext?, coordinator: ClientCore
     ) async throws -> [UInt8] {
         let clock = ContinuousClock()
         let now = clock.now
@@ -120,7 +132,7 @@ final class PollRouter: Sendable {
             // pinged here once per heartbeat interval too.
             _ = try await control(.ping, [], coordinator: coordinator, deadline: deadline)
         }
-        let request = Request(code: code, payload: payload, key: key, routePayload: routePayload, deadline: deadline)
+        let request = Request(code: code, payload: payload, key: key, deadline: deadline)
         var captured = context
         var interval = Self.retryInterval
         while clock.now < deadline {
@@ -146,23 +158,44 @@ final class PollRouter: Sendable {
         let code: CommandCode
         let payload: [UInt8]
         let key: RouteKey
-        let routePayload: [UInt8]
         let deadline: ContinuousClock.Instant
     }
 
     /// Whether the roster has more than one node, reading it once when no
     /// leader check reported it yet.
     private func isClustered(_ coordinator: ClientCore, deadline: ContinuousClock.Instant) async throws -> Bool {
-        if state.withLockedValue({ $0.rosterSize }) == 0 {
-            let readDeadline = min(deadline, ContinuousClock.now + Self.rosterReadTimeout)
-            let body = try await control(.getClusterMetadata, [], coordinator: coordinator, deadline: readDeadline)
-            let metadata = try Responses.clusterMetadata(body[...])
-            guard !metadata.nodes.isEmpty else {
-                throw IggyError(.transientNotAccepted, context: "the cluster roster is empty")
-            }
-            learnRosterSize(metadata.nodes.count)
+        if state.withLockedValue({ $0.nodes.isEmpty }) {
+            try await readRoster(coordinator, deadline: deadline)
+        }
+        return state.withLockedValue { $0.nodes.count } > 1
+    }
+
+    private func readRoster(_ coordinator: ClientCore, deadline: ContinuousClock.Instant) async throws {
+        let readDeadline = min(deadline, ContinuousClock.now + Self.rosterReadTimeout)
+        let body = try await control(.getClusterMetadata, [], coordinator: coordinator, deadline: readDeadline)
+        let metadata = try Responses.clusterMetadata(body[...])
+        guard !metadata.nodes.isEmpty else {
+            throw IggyError(.transientNotAccepted, context: "the cluster roster is empty")
+        }
+        learnRoster(metadata)
+    }
+
+    /// The TCP address of `replica`. A roster that does not list it is read
+    /// once more before the route is refused.
+    private func endpoint(of replica: UInt8, coordinator: ClientCore, deadline: ContinuousClock.Instant) async throws -> String {
+        var node = state.withLockedValue { $0.nodes[replica] }
+        if node == nil {
+            try await readRoster(coordinator, deadline: deadline)
+            node = state.withLockedValue { $0.nodes[replica] }
+        }
+        guard let node else {
+            throw IggyError(.transientNotAccepted, context: "the cluster roster does not list replica \(replica)")
+        }
+        guard node.endpoints.tcp != 0 else {
+            coordinator.logger.error("The partition primary \(node.name) does not expose TCP")
+            throw IggyError(.featureUnavailable, context: "the partition primary \(node.name) does not expose TCP")
         }
-        return state.withLockedValue { $0.rosterSize } > 1
+        return node.tcpAddress
     }
 
     private func heartbeatDue(at now: ContinuousClock.Instant, interval: Duration) -> Bool {
@@ -190,11 +223,11 @@ final class PollRouter: Sendable {
     /// The single-node path: the request goes over the coordinator connection
     /// with the context of its route.
     private func sendOnCoordinator(_ request: Request, context: inout PartitionContext?, coordinator: ClientCore) async throws -> [UInt8] {
-        let route = try await route(request.key, routePayload: request.routePayload, coordinator: coordinator, deadline: request.deadline)
+        let route = try await route(request.key, coordinator: coordinator, deadline: request.deadline)
         let captured = context ?? route.context
         context = captured
         do {
-            if request.code == .pollMessagesOnPrimary {
+            if request.code == .pollMessages {
                 return try await coordinator.exchangeOnce(
                     code: request.code.rawValue, payload: request.payload, context: captured, deadline: request.deadline)
             }
@@ -206,14 +239,15 @@ final class PollRouter: Sendable {
     }
 
     /// The cluster path: the request goes over a data connection to the
-    /// partition primary, bound to the coordinator's session first. Every
+    /// partition primary, bound to the client's session first. Every
     /// frame is stamped under a check that the route's session is still the
     /// client's, so nothing is written for a session that was replaced.
     private func sendOnPrimary(_ request: Request, context: inout PartitionContext?, coordinator: ClientCore) async throws -> [UInt8] {
-        let route = try await route(request.key, routePayload: request.routePayload, coordinator: coordinator, deadline: request.deadline)
+        let route = try await route(request.key, coordinator: coordinator, deadline: request.deadline)
         let captured = context ?? route.context
         context = captured
-        let slot = try slot(for: route)
+        let endpoint = try await endpoint(of: route.primaryReplica, coordinator: coordinator, deadline: request.deadline)
+        let slot = try slot(for: route, at: endpoint)
         try await slot.lock.lock()
         defer { slot.lock.unlock() }
 
@@ -224,9 +258,9 @@ final class PollRouter: Sendable {
         if data == nil {
             let connection: any IggyConnection
             do {
-                connection = try await coordinator.dial(route.endpoint)
+                connection = try await coordinator.dial(endpoint)
             } catch let error as IggyError where error.isReconnectable {
-                throw IggyError(.transientNotAccepted, context: "cannot reach the partition primary at \(route.endpoint): \(error)")
+                throw IggyError(.transientNotAccepted, context: "cannot reach the partition primary at \(endpoint): \(error)")
             }
             data = DataConnection(connection: connection, consumerSession: nil, usable: true)
         }
@@ -242,7 +276,7 @@ final class PollRouter: Sendable {
             do {
                 try await bind(data.connection, to: route.consumerSession, coordinator: coordinator, deadline: request.deadline)
             } catch let error as IggyError where error.isReconnectable {
-                throw IggyError(.transientNotAccepted, context: "binding the session on \(route.endpoint) failed: \(error)")
+                throw IggyError(.transientNotAccepted, context: "binding the session on \(endpoint) failed: \(error)")
             }
             data.consumerSession = route.consumerSession
             slot.connection.withLockedValue { $0 = data }
@@ -262,7 +296,7 @@ final class PollRouter: Sendable {
             }
             slot.connection.withLockedValue { $0 = data }
             removeRoute(request.key)
-            throw Self.gradedLoss(error, on: route.endpoint)
+            throw Self.gradedLoss(error, on: endpoint)
         }
     }
 
@@ -331,20 +365,19 @@ final class PollRouter: Sendable {
 
     /// The cached route of `key` if the session still holds it, else a new
     /// lookup on the coordinator.
-    private func route(_ key: RouteKey, routePayload: [UInt8], coordinator: ClientCore, deadline: ContinuousClock.Instant) async throws -> Route {
+    private func route(_ key: RouteKey, coordinator: ClientCore, deadline: ContinuousClock.Instant) async throws -> Route {
         let watermark = await coordinator.metadataWatermark
         let (fence, cached) = state.withLockedValue { ($0.fence, $0.routes[key]) }
-        if let cached, cached.fence == fence, cached.consumerSession.metadataWatermark >= watermark {
+        if let cached, cached.fence == fence, cached.context.metadataOp >= watermark {
             return cached
         }
-        let body = try await control(key.code, routePayload, coordinator: coordinator, deadline: deadline)
-        var response = try Responses.pollRoute(body[...])
-        response.consumerSession.metadataWatermark = max(response.consumerSession.metadataWatermark, watermark)
-        guard response.primary.endpoints.tcp != 0 else {
-            coordinator.logger.error("The partition primary \(response.primary.name) does not expose TCP")
-            throw IggyError(.featureUnavailable, context: "the partition primary \(response.primary.name) does not expose TCP")
+        let payload = try Requests.partitionRoute(streamID: key.stream, topicID: key.topic, partitionID: key.partitionID)
+        let body = try await control(.getPartitionRoute, payload, coordinator: coordinator, deadline: deadline)
+        let response = try Responses.partitionRoute(body[...])
+        guard let session = await coordinator.sessionIdentity(at: response.context.metadataOp) else {
+            throw IggyError(.transientNotAccepted, context: "no session is bound to route partition \(key.partitionID)")
         }
-        let route = Route(fence: fence, endpoint: response.primary.tcpAddress, consumerSession: response.consumerSession, context: response.context)
+        let route = Route(fence: fence, primaryReplica: response.primaryReplica, consumerSession: session, context: response.context)
         try await validate(route, coordinator: coordinator)
         try state.withLockedValue { state in
             try Self.checkFence(of: route, in: state)
@@ -361,7 +394,7 @@ final class PollRouter: Sendable {
     private func validate(_ route: Route, coordinator: ClientCore) async throws {
         let watermark = await coordinator.metadataWatermark
         try state.withLockedValue { try Self.checkFence(of: route, in: $0) }
-        guard route.consumerSession.metadataWatermark >= watermark else {
+        guard route.context.metadataOp >= watermark else {
             throw IggyError(.transientNotAccepted, context: "the route predates metadata commit \(watermark)")
         }
     }
@@ -372,10 +405,9 @@ final class PollRouter: Sendable {
         }
     }
 
-    private func slot(for route: Route) throws -> Slot {
+    private func slot(for route: Route, at endpoint: String) throws -> Slot {
         try state.withLockedValue { state in
             try Self.checkFence(of: route, in: state)
-            let endpoint = route.endpoint
             if let slot = state.slots[endpoint] {
                 return slot
             }
diff --git a/foreign/swift/Sources/Iggy/Protocol/Responses.swift b/foreign/swift/Sources/Iggy/Protocol/Responses.swift
index c386254c6..91d4d88df 100644
--- a/foreign/swift/Sources/Iggy/Protocol/Responses.swift
+++ b/foreign/swift/Sources/Iggy/Protocol/Responses.swift
@@ -430,19 +430,29 @@ enum Responses {
 
     static let partitionRouteSize = 25
 
-    /// The context a request routed by a `GetPartitionRoute` reply carries:
-    /// `[incarnation:8][metadata_op:8][view:4][partitions_count:4][primary_replica:1]`.
+    /// One replica's route to a partition, the reply to `GetPartitionRoute`.
+    struct PartitionRoute: Equatable {
+        /// The context a request routed by the reply carries.
+        let context: PartitionContext
+        /// The configured replica id of the partition primary, as
+        /// `GetClusterMetadata` reports it, never a roster position.
+        let primaryReplica: UInt8
+    }
+
+    /// Decodes `[incarnation:8][metadata_op:8][view:4][partitions_count:4][primary_replica:1]`.
     /// A route names no consumer, so the context carries owner 0, as
-    /// `PartitionRouteResponse::context` in the Rust protocol crate. The view
-    /// and the primary pick a replica for a client that dials each one; this
-    /// one sends over its connection. A reply of any other length comes from
-    /// a mismatched build.
-    static func partitionRoute(_ body: ArraySlice<UInt8>) throws -> PartitionContext {
+    /// `PartitionRouteResponse::context` in the Rust protocol crate. A reply
+    /// of any other length comes from a mismatched build.
+    static func partitionRoute(_ body: ArraySlice<UInt8>) throws -> PartitionRoute {
         guard body.count == partitionRouteSize else {
             throw IggyError(.invalidCommand, context: "partition route is \(body.count) bytes, expected \(partitionRouteSize)")
         }
         return try decode(body) { reader in
-            PartitionContext(incarnation: try reader.readUInt64(), ownerGeneration: 0, metadataOp: try reader.readUInt64())
+            let context = PartitionContext(incarnation: try reader.readUInt64(), ownerGeneration: 0, metadataOp: try reader.readUInt64())
+            // The view and the partition count, which a client that asks only
+            // the coordinator for routes does not use.
+            try reader.skip(2 * MemoryLayout<UInt32>.size)
+            return PartitionRoute(context: context, primaryReplica: try reader.readUInt8())
         }
     }
 
@@ -451,22 +461,7 @@ enum Responses {
     struct SessionIdentity: Equatable {
         let clientID: UInt128Value
         let session: UInt64
-        var metadataWatermark: UInt64
-    }
-
-    /// Where a poll or an offset write goes: the reply to `GetPollRouting`
-    /// and `GetConsumerOffsetRouting`.
-    struct PollRoute: Equatable {
-        var consumerSession: SessionIdentity
-        let context: PartitionContext
-        let primary: ClusterNode
-    }
-
-    static func pollRoute(_ body: ArraySlice<UInt8>) throws -> PollRoute {
-        try decode(body) { reader in
-            let session = SessionIdentity(clientID: try reader.readUInt128(), session: try reader.readUInt64(), metadataWatermark: try reader.readUInt64())
-            return PollRoute(consumerSession: session, context: try PartitionContext.decode(from: &reader), primary: try clusterNode(from: &reader))
-        }
+        let metadataWatermark: UInt64
     }
 
     // MARK: Messages
diff --git a/foreign/swift/Tests/IggyTests/Fixtures/golden.json b/foreign/swift/Tests/IggyTests/Fixtures/golden.json
index 3d31d37ee..a5f24e7ed 100644
--- a/foreign/swift/Tests/IggyTests/Fixtures/golden.json
+++ b/foreign/swift/Tests/IggyTests/Fixtures/golden.json
@@ -994,7 +994,6 @@
     "response.partition_route": "07000000000000000a00000000000000030000000400000002",
     "response.poll_messages": "07000000660000000000000003000000000000000000000000000000000000000000000000000000070000000000000064000000000000008813000000000000e8030000000000006e01000000000000f576a2492e1328b3020000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000 [...]
     "response.poll_messages.empty": "00000000000000000000000000000000000000000000000000000000000000000000000000000000",
-    "response.poll_routing": "100f0e0d0c0b0a0908070605040302012a000000000000007800000000000000070000000000000003000000000000006e0000000000000002060000006e6f64652d330800000031302e302e302e339c1f0000ba0b00000100",
     "response.raw_personal_access_token": "167261772d7365637265742d746f6b656e2d76616c7565",
     "response.send_messages": "0200000001000000020000000300000004000000000000000100000002000000000000002a00000000000000",
     "response.send_messages.empty": "00000000",
@@ -1009,7 +1008,7 @@
     "version_info": "012c00000973776966742d73646b05302e312e30",
     "vsr.eviction.incompatible_protocol": "0000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000001000000000000000000000d000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000001032547698badcfeefcdab8967452301012c0000012c00000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000 [...]
     "vsr.eviction.stale_client": "0000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000001000000000000000000000d000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000001032547698badcfeefcdab896745230100000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000 [...]
-    "vsr.reply.committed": "0000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000c0100000000000000000000080000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000001032547698badcfeefcdab89674523010000000000000000000000000000000000000000000000000700000000000000800000000000000000000000010000000000000000000000 [...]
+    "vsr.reply.committed": "0000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000c0100000000000000000000080000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000001032547698badcfeefcdab896745230100000000000000000c0000000000000000000000000000000700000000000000800000000000000000000000010000000000000000000000 [...]
     "vsr.reply.denied": "00000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000010000000000000000000008000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000800000000000000020000000000000029000000000000000000000000000000000 [...]
     "vsr.reply.ok": "0000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000c0100000000000000000000080000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000001032547698badcfeefcdab896745230100000000000000000c00000000000000000000000000000007000000000000008000000000000000000000000000000000000000000000000000000 [...]
     "vsr.request.create_stream": "00000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000007010000000000000000000005000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000001032547698badcfeefcdab89674523013a9e6b43adf27bf20000000000000000000000000000000001000000000000008000000000000000630000000000000000000000000000000000000000000000000000000000000000000000000000000000000000 [...]
diff --git a/foreign/swift/Tests/IggyTests/MessagingTests.swift b/foreign/swift/Tests/IggyTests/MessagingTests.swift
index a5c25ca5b..1150bf664 100644
--- a/foreign/swift/Tests/IggyTests/MessagingTests.swift
+++ b/foreign/swift/Tests/IggyTests/MessagingTests.swift
@@ -211,12 +211,12 @@ struct MessagingTests {
         let continued = PollingStrategy.offset(3, context: otherContext)
         _ = try await client.pollMessages(streamID: 1, topicID: 2, partitionID: 1, consumer: .consumer(5), strategy: continued, count: 10, autoCommit: true)
 
-        let lookups = await requests(server, .getPollRouting)
+        let lookups = await requests(server, .getPartitionRoute)
         #expect(lookups.count == 1)
+        #expect(lookups.first?.payload == (try Requests.partitionRoute(streamID: 1, topicID: 2, partitionID: 1)))
         let payload = try Requests.pollMessages(
             consumer: .consumer(5), streamID: 1, topicID: 2, partitionID: 1, strategy: .next, count: 10, autoCommit: true)
-        #expect(lookups.first?.payload == payload)
-        let polls = await requests(server, .pollMessagesOnPrimary)
+        let polls = await requests(server, .pollMessages)
         #expect(polls.map(\.context) == [FakeVSRServer.routeContext, otherContext])
         #expect(polls.first?.payload == payload)
         // Every request went over the one coordinator connection.
@@ -229,7 +229,7 @@ struct MessagingTests {
         defer { Task { await server.stop() } }
         let refused = Locked(false)
         await server.respond { request in
-            if request.code == CommandCode.pollMessagesOnPrimary.rawValue,
+            if request.code == CommandCode.pollMessages.rawValue,
                 !refused.exchange(true)
             {
                 return .status(IggyErrorCode.transientNotAccepted.rawValue)
@@ -238,8 +238,8 @@ struct MessagingTests {
         }
         let client = try await connectedClient(server)
         _ = try await client.pollMessages(streamID: 1, topicID: 2, partitionID: 0, strategy: .first, count: 1, autoCommit: false)
-        #expect(await requests(server, .getPollRouting).count == 2)
-        #expect(await requests(server, .pollMessagesOnPrimary).count == 2)
+        #expect(await requests(server, .getPartitionRoute).count == 2)
+        #expect(await requests(server, .pollMessages).count == 2)
         await client.shutdown()
     }
 
@@ -250,7 +250,7 @@ struct MessagingTests {
         defer { Task { await server.stop() } }
         let dropped = Locked(false)
         await server.respond { request in
-            if request.code == CommandCode.pollMessagesOnPrimary.rawValue, !dropped.exchange(true) {
+            if request.code == CommandCode.pollMessages.rawValue, !dropped.exchange(true) {
                 return .close
             }
             return FakeVSRServer.defaultReply(request, address: server.address)
@@ -265,23 +265,59 @@ struct MessagingTests {
     @Test func aNewerMetadataCommitReadsTheRouteAgain() async throws {
         let server = try await FakeVSRServer.started()
         defer { Task { await server.stop() } }
+        let committed = PartitionContext(incarnation: 7, ownerGeneration: 0, metadataOp: 50)
+        let applied = Locked(FakeVSRServer.routeContext)
         await server.respond { request in
-            if request.operation == .deleteStream {
-                return .committed([], commit: 50)
+            switch request.code.flatMap(CommandCode.init(rawValue:)) {
+            case .deleteStream:
+                applied.withLock { $0 = committed }
+                return .committed([], commit: committed.metadataOp)
+            case .getPartitionRoute:
+                return .ok(FakeVSRServer.partitionRouteBody(applied.withLock { $0 }))
+            default:
+                return FakeVSRServer.defaultReply(request, address: server.address)
             }
-            return FakeVSRServer.defaultReply(request, address: server.address)
         }
         let client = try await connectedClient(server)
         let poll = { _ = try await client.pollMessages(streamID: 1, topicID: 2, partitionID: 0, strategy: .first, count: 1, autoCommit: false) }
         try await poll()
         try await poll()
-        #expect(await requests(server, .getPollRouting).count == 1)
+        #expect(await requests(server, .getPartitionRoute).count == 1)
         try await client.deleteStream(9)
         #expect(await client.core.metadataWatermark == 50)
         try await poll()
         try await poll()
         // The route read after the commit is as new as the commit.
-        #expect(await requests(server, .getPollRouting).count == 2)
+        #expect(await requests(server, .getPartitionRoute).count == 2)
+        #expect(await requests(server, .pollMessages).map(\.context) == [FakeVSRServer.routeContext, FakeVSRServer.routeContext, committed, committed])
+        await client.shutdown()
+    }
+
+    /// A route older than a metadata commit the client saw is never used: it
+    /// is read again until the coordinator applied the commit.
+    @Test func aRouteOlderThanTheWatermarkIsReadAgain() async throws {
+        let server = try await FakeVSRServer.started()
+        defer { Task { await server.stop() } }
+        let lagging = Locked(1)
+        await server.respond { request in
+            switch request.code.flatMap(CommandCode.init(rawValue:)) {
+            case .deleteStream:
+                return .committed([], commit: 50)
+            case .getPartitionRoute:
+                let behind = lagging.withLock {
+                    $0 -= 1; return $0 >= 0
+                }
+                let metadataOp: UInt64 = behind ? 49 : 50
+                return .ok(FakeVSRServer.partitionRouteBody(PartitionContext(incarnation: 7, ownerGeneration: 0, metadataOp: metadataOp)))
+            default:
+                return FakeVSRServer.defaultReply(request, address: server.address)
+            }
+        }
+        let client = try await connectedClient(server)
+        try await client.deleteStream(9)
+        _ = try await client.pollMessages(streamID: 1, topicID: 2, partitionID: 0, strategy: .first, count: 1, autoCommit: false)
+        #expect(await requests(server, .getPartitionRoute).count == 2)
+        #expect(await requests(server, .pollMessages).map(\.context.metadataOp) == [50])
         await client.shutdown()
     }
 
@@ -301,7 +337,7 @@ struct MessagingTests {
         _ = try await client.login(username: "iggy", password: "iggy")
         #expect(!client.core.groupState.isRegistered(.init(stream: 1, topic: 2, group: 3)))
         _ = try await client.pollMessages(streamID: 1, topicID: 2, partitionID: 0, strategy: .first, count: 1, autoCommit: false)
-        let lookups = await requests(server, .getPollRouting)
+        let lookups = await requests(server, .getPartitionRoute)
         #expect(lookups.count == 2)
         #expect(lookups[0].clientID != lookups[1].clientID)
         await client.shutdown()
@@ -333,7 +369,7 @@ struct MessagingTests {
         #expect(await server.requests.filter { $0.operation == .register }.count == 1)
         let binds = await requests(server, .bindSession)
         #expect(binds.count == 1)
-        let polls = await requests(server, .pollMessagesOnPrimary)
+        let polls = await requests(server, .pollMessages)
         #expect(polls.count == 2)
         #expect(Set(polls.map(\.clientID)).count == 1)
         #expect(polls.allSatisfy { $0.clientID == binds[0].clientID })
@@ -414,7 +450,7 @@ struct MessagingTests {
             switch request.code.flatMap(CommandCode.init(rawValue:)) {
             case .syncConsumerGroup:
                 return .ok(FakeVSRServer.assignmentBody(generation: 1, partitions: [1, 2]))
-            case .pollMessagesOnPrimary:
+            case .pollMessages:
                 return .ok(FakeVSRServer.polledBody(partitionID: polledPartition(request)))
             default:
                 return FakeVSRServer.defaultReply(request, address: server.address)
@@ -430,7 +466,10 @@ struct MessagingTests {
         #expect(polled == [1, 2, 1])
         #expect(await requests(server, .syncConsumerGroup).count == 1)
         // Each partition has its own route.
-        #expect(await requests(server, .getPollRouting).count == 2)
+        #expect(
+            await requests(server, .getPartitionRoute).map(\.payload) == [
+                try Requests.partitionRoute(streamID: 1, topicID: 2, partitionID: 1), try Requests.partitionRoute(streamID: 1, topicID: 2, partitionID: 2),
+            ])
         await client.shutdown()
     }
 
@@ -442,7 +481,7 @@ struct MessagingTests {
             switch request.code.flatMap(CommandCode.init(rawValue:)) {
             case .syncConsumerGroup:
                 return .ok(FakeVSRServer.assignmentBody(generation: fenced.withLock { $0 } ? 2 : 1, partitions: [1]))
-            case .pollMessagesOnPrimary:
+            case .pollMessages:
                 let first = !fenced.exchange(true)
                 return .ok(FakeVSRServer.polledBody(partitionID: first ? PolledMessages.resyncRequiredPartition : 1))
             default:
@@ -453,7 +492,7 @@ struct MessagingTests {
         let polled = try await client.pollMessages(streamID: 1, topicID: 2, partitionID: nil, consumer: .group(3), strategy: .next, count: 1, autoCommit: true)
         #expect(polled.partitionID == 1)
         #expect(await requests(server, .syncConsumerGroup).count == 2)
-        #expect(await requests(server, .pollMessagesOnPrimary).count == 2)
+        #expect(await requests(server, .pollMessages).count == 2)
         await client.shutdown()
     }
 
@@ -477,7 +516,7 @@ struct MessagingTests {
         member.withLock { $0 = false }
         await expectCode(.consumerGroupMemberNotFound) { _ = try await poll() }
         #expect(await requests(server, .syncConsumerGroup).count == 2)
-        #expect(await requests(server, .pollMessagesOnPrimary).isEmpty)
+        #expect(await requests(server, .pollMessages).isEmpty)
         await client.shutdown()
     }
 
@@ -492,9 +531,9 @@ struct MessagingTests {
                     $0 += 1; return $0
                 }
                 return .ok(FakeVSRServer.assignmentBody(generation: UInt64(count), partitions: count == 1 ? [1] : [2]))
-            case .pollMessagesOnPrimary where polledPartition(request) == 1:
+            case .pollMessages where polledPartition(request) == 1:
                 return .status(IggyErrorCode.consumerGroupPartitionNotOwned.rawValue)
-            case .pollMessagesOnPrimary:
+            case .pollMessages:
                 return .ok(FakeVSRServer.polledBody(partitionID: polledPartition(request)))
             default:
                 return FakeVSRServer.defaultReply(request, address: server.address)
@@ -534,27 +573,50 @@ struct MessagingTests {
 
     // MARK: Offsets
 
-    @Test func offsetWritesTakeTheOffsetRoute() async throws {
+    @Test func offsetRequestsTakeThePartitionRoute() async throws {
         let server = try await FakeVSRServer.started()
         defer { Task { await server.stop() } }
         let client = try await connectedClient(server)
         try await client.storeConsumerOffset(consumer: .consumer(5), streamID: 1, topicID: 2, partitionID: 3, offset: 40)
         let position = ConsumerPosition(partitionID: 3, offset: 41, context: otherContext)
         try await client.storeConsumerPosition(consumer: .consumer(5), streamID: 1, topicID: 2, position: position)
+        #expect(try await client.getConsumerOffset(consumer: .consumer(5), streamID: 1, topicID: 2, partitionID: 3) == nil)
         try await client.deleteConsumerOffset(consumer: .consumer(5), streamID: 1, topicID: 2, partitionID: 3)
 
-        let lookups = await requests(server, .getConsumerOffsetRouting)
+        let lookups = await requests(server, .getPartitionRoute)
         #expect(lookups.count == 1)
-        #expect(lookups.first?.payload == (try Requests.getConsumerOffset(consumer: .consumer(5), streamID: 1, topicID: 2, partitionID: 3)))
+        #expect(lookups.first?.payload == (try Requests.partitionRoute(streamID: 1, topicID: 2, partitionID: 3)))
         let stores = await requests(server, .storeConsumerOffset)
         #expect(stores.map(\.context) == [FakeVSRServer.routeContext, otherContext])
         #expect(
             stores.first?.payload
                 == (try Requests.storeConsumerOffset(consumer: .consumer(5), streamID: 1, topicID: 2, partitionID: 3, offset: 40, ack: .quorum)))
+        #expect(await requests(server, .getConsumerOffset).map(\.context) == [FakeVSRServer.routeContext])
         #expect(await requests(server, .deleteConsumerOffset).map(\.context) == [FakeVSRServer.routeContext])
         await client.shutdown()
     }
 
+    /// An offset read without a partition reads partition 0, as the server
+    /// does. A write without one names no partition to route.
+    @Test func offsetRequestsWithoutAPartition() async throws {
+        let server = try await FakeVSRServer.started()
+        defer { Task { await server.stop() } }
+        let client = try await connectedClient(server)
+        _ = try await client.getConsumerOffset(consumer: .group(3), streamID: 1, topicID: 2, partitionID: nil)
+        #expect(await requests(server, .getPartitionRoute).map(\.payload) == [try Requests.partitionRoute(streamID: 1, topicID: 2, partitionID: 0)])
+        #expect(
+            await requests(server, .getConsumerOffset).map(\.payload)
+                == [try Requests.getConsumerOffset(consumer: .group(3), streamID: 1, topicID: 2, partitionID: nil)])
+
+        let before = await server.requests.count
+        await expectCode(.invalidIdentifier) {
+            try await client.storeConsumerOffset(consumer: .group(3), streamID: 1, topicID: 2, partitionID: nil, offset: 1)
+        }
+        await expectCode(.invalidIdentifier) { try await client.deleteConsumerOffset(consumer: .group(3), streamID: 1, topicID: 2, partitionID: nil) }
+        #expect(await server.requests.count == before)
+        await client.shutdown()
+    }
+
     // MARK: Raw requests
 
     @Test func rawPartitionRequestsAreRoutedLikeTypedOnes() async throws {
@@ -569,13 +631,19 @@ struct MessagingTests {
 
         let poll = try Requests.pollMessages(consumer: .consumer(5), streamID: 1, topicID: 2, partitionID: 1, strategy: .first, count: 1, autoCommit: false)
         _ = try await client.sendRawRequest(code: CommandCode.pollMessages.rawValue, payload: poll)
-        #expect(await requests(server, .pollMessagesOnPrimary).map(\.context) == [FakeVSRServer.routeContext])
+        #expect(await requests(server, .pollMessages).map(\.context) == [FakeVSRServer.routeContext])
 
+        // The offset requests take the route the poll read.
         let store = try Requests.storeConsumerOffset(consumer: .consumer(5), streamID: 1, topicID: 2, partitionID: 1, offset: 9, ack: .quorum)
         _ = try await client.sendRawRequest(code: CommandCode.storeConsumerOffset.rawValue, payload: store)
-        #expect(
-            await requests(server, .getConsumerOffsetRouting).map(\.payload)
-                == [try Requests.getConsumerOffset(consumer: .consumer(5), streamID: 1, topicID: 2, partitionID: 1)])
+        let read = try Requests.getConsumerOffset(consumer: .consumer(5), streamID: 1, topicID: 2, partitionID: 1)
+        _ = try await client.sendRawRequest(code: CommandCode.getConsumerOffset.rawValue, payload: read)
+        let delete = try Requests.deleteConsumerOffset(consumer: .consumer(5), streamID: 1, topicID: 2, partitionID: 1, ack: .quorum)
+        _ = try await client.sendRawRequest(code: CommandCode.deleteConsumerOffset.rawValue, payload: delete)
+        for code in [CommandCode.storeConsumerOffset, .getConsumerOffset, .deleteConsumerOffset] {
+            #expect(await requests(server, code).map(\.context) == [FakeVSRServer.routeContext])
+        }
+        #expect(await requests(server, .getPartitionRoute).count == 2)
 
         let before = await server.requests.count
         let balanced = try Batch.encodeSend(streamID: 1, topicID: 2, partitioning: .balanced, messages: outgoing)
@@ -592,43 +660,29 @@ struct MessagingTests {
         await expectCode(.invalidCommand) { _ = try await client.sendRawRequest(code: CommandCode.pollMessages.rawValue, payload: Array(poll.dropLast())) }
         await expectCode(.invalidCommand) { _ = try await client.sendRawRequest(code: CommandCode.storeConsumerOffset.rawValue, payload: [1, 9]) }
         await expectCode(.invalidCommand) { _ = try await client.sendRawRequest(code: CommandCode.bindSession.rawValue, payload: []) }
-        #expect(await server.requests.count == before)
-        await client.shutdown()
-    }
-
-    /// The routing protocol goes once on the current connection, as the Rust
-    /// client sends it: a replay after a reconnect would run under another
-    /// connection's binding.
-    @Test func rawRoutingRequestsAreSentOnce() async throws {
-        let server = try await FakeVSRServer.started()
-        defer { Task { await server.stop() } }
-        let dropped = Locked(false)
-        await server.respond { request in
-            if request.code == CommandCode.getPollRouting.rawValue, !dropped.exchange(true) {
-                return .close
-            }
-            return FakeVSRServer.defaultReply(request, address: server.address)
+        // A group poll and an offset write must name their partition.
+        let groupPoll = try Requests.pollMessages(consumer: .group(3), streamID: 1, topicID: 2, partitionID: nil, strategy: .next, count: 1, autoCommit: true)
+        let unnamedStore = try Requests.storeConsumerOffset(consumer: .consumer(5), streamID: 1, topicID: 2, partitionID: nil, offset: 9, ack: .quorum)
+        let unnamedDelete = try Requests.deleteConsumerOffset(consumer: .consumer(5), streamID: 1, topicID: 2, partitionID: nil, ack: .quorum)
+        for (code, payload) in [(CommandCode.pollMessages, groupPoll), (.storeConsumerOffset, unnamedStore), (.deleteConsumerOffset, unnamedDelete)] {
+            await expectCode(.invalidIdentifier) { _ = try await client.sendRawRequest(code: code.rawValue, payload: payload) }
         }
-        let client = try await connectedClient(server)
-        let poll = try Requests.pollMessages(consumer: .consumer(5), streamID: 1, topicID: 2, partitionID: 1, strategy: .first, count: 1, autoCommit: false)
-        await expectCode(.disconnected) { _ = try await client.sendRawRequest(code: CommandCode.getPollRouting.rawValue, payload: poll) }
-        #expect(await requests(server, .getPollRouting).count == 1)
-        let body = try await client.sendRawRequest(code: CommandCode.getPollRouting.rawValue, payload: poll)
-        #expect(try Responses.pollRoute(body[...]).context == FakeVSRServer.routeContext)
+        #expect(await server.requests.count == before)
         await client.shutdown()
     }
 
     // MARK: Clusters
 
-    /// A coordinator that routes every poll and offset write to `primary`.
+    /// A coordinator, replica 0, that routes every partition to `primary`,
+    /// replica 1.
     private static func coordinator(routingTo primary: FakeVSRServer) async throws -> FakeVSRServer {
         let coordinator = try await FakeVSRServer.started()
         await coordinator.respond { request in
             switch request.code.flatMap(CommandCode.init(rawValue:)) {
             case .getClusterMetadata:
                 return .ok(FakeVSRServer.rosterBody([coordinator.address, primary.address]))
-            case .getPollRouting, .getConsumerOffsetRouting:
-                return .ok(FakeVSRServer.pollRouteBody(for: request, context: FakeVSRServer.routeContext, primary: primary.address, watermark: 3))
+            case .getPartitionRoute:
+                return .ok(FakeVSRServer.partitionRouteBody(FakeVSRServer.routeContext, primaryReplica: 1))
             default:
                 return FakeVSRServer.defaultReply(request, address: coordinator.address)
             }
@@ -653,15 +707,17 @@ struct MessagingTests {
         let session = await coordinator.requests.last!
         let binds = await requests(primary, .bindSession)
         #expect(binds.count == 1)
+        // The data connection binds at the metadata op of the route.
         #expect(
             binds.first?.payload
                 == (try Requests.bindSession(
-                    clientID: session.clientID, session: session.session, metadataWatermark: 3, bindSecret: await client.core.bindSecret)))
-        let polls = await requests(primary, .pollMessagesOnPrimary)
+                    clientID: session.clientID, session: session.session, metadataWatermark: FakeVSRServer.routeContext.metadataOp,
+                    bindSecret: await client.core.bindSecret)))
+        let polls = await requests(primary, .pollMessages)
         #expect(polls.count == 2)
         #expect(polls.allSatisfy { $0.context == FakeVSRServer.routeContext && $0.clientID == session.clientID && $0.session == session.session })
         #expect(await requests(primary, .storeConsumerOffset).count == 1)
-        #expect(await requests(coordinator, .pollMessagesOnPrimary).isEmpty)
+        #expect(await requests(coordinator, .pollMessages).isEmpty)
         #expect(await primary.connectionCount == 1)
         await client.shutdown()
     }
@@ -677,7 +733,7 @@ struct MessagingTests {
         }
         let dropped = Locked(false)
         await primary.respond { request in
-            if request.code == CommandCode.pollMessagesOnPrimary.rawValue,
+            if request.code == CommandCode.pollMessages.rawValue,
                 !dropped.exchange(true)
             {
                 return .close
@@ -707,15 +763,15 @@ struct MessagingTests {
         }
         let refused = Locked(false)
         await primary.respond { request in
-            if request.code == CommandCode.pollMessagesOnPrimary.rawValue, !refused.exchange(true) {
+            if request.code == CommandCode.pollMessages.rawValue, !refused.exchange(true) {
                 return .status(IggyErrorCode.notPrimary.rawValue)
             }
             return FakeVSRServer.defaultReply(request, address: primary.address)
         }
         let client = try await connectedClient(coordinator)
         _ = try await client.pollMessages(streamID: 1, topicID: 2, partitionID: 0, strategy: .first, count: 1, autoCommit: false)
-        #expect(await requests(coordinator, .getPollRouting).count == 2)
-        #expect(await requests(primary, .pollMessagesOnPrimary).count == 2)
+        #expect(await requests(coordinator, .getPartitionRoute).count == 2)
+        #expect(await requests(primary, .pollMessages).count == 2)
         // The refusal left the data connection at a frame boundary.
         #expect(await primary.connectionCount == 1)
         await client.shutdown()
@@ -737,12 +793,12 @@ struct MessagingTests {
         await coordinator.respond { request in
             switch request.code.flatMap(CommandCode.init(rawValue:)) {
             case .getClusterMetadata:
-                return .ok(FakeVSRServer.rosterBody([coordinator.address, primary.address]))
-            case .getPollRouting:
+                return .ok(FakeVSRServer.rosterBody([coordinator.address, goneAddress, primary.address]))
+            case .getPartitionRoute:
                 let first = lookups.withLock {
                     $0 += 1; return $0 == 1
                 }
-                return .ok(FakeVSRServer.pollRouteBody(for: request, context: FakeVSRServer.routeContext, primary: first ? goneAddress : primary.address))
+                return .ok(FakeVSRServer.partitionRouteBody(FakeVSRServer.routeContext, primaryReplica: first ? 1 : 2))
             default:
                 return FakeVSRServer.defaultReply(request, address: coordinator.address)
             }
@@ -750,7 +806,43 @@ struct MessagingTests {
         let client = try await connectedClient(coordinator)
         _ = try await client.pollMessages(streamID: 1, topicID: 2, partitionID: 0, strategy: .first, count: 1, autoCommit: false)
         #expect(lookups.withLock { $0 } == 2)
-        #expect(await requests(primary, .pollMessagesOnPrimary).count == 1)
+        #expect(await requests(primary, .pollMessages).count == 1)
+        await client.shutdown()
+    }
+
+    /// A route can name a replica that the roster the client holds does not
+    /// list. The roster is read again before the route is refused.
+    @Test func aPrimaryMissingFromTheRosterReadsTheRosterAgain() async throws {
+        let primary = try await FakeVSRServer.started()
+        let other = try await FakeVSRServer.started()
+        let coordinator = try await FakeVSRServer.started()
+        defer {
+            Task {
+                await coordinator.stop()
+                await other.stop()
+                await primary.stop()
+            }
+        }
+        let routed = Locked(false)
+        await coordinator.respond { request in
+            switch request.code.flatMap(CommandCode.init(rawValue:)) {
+            case .getClusterMetadata:
+                let addresses = [coordinator.address, other.address] + (routed.withLock { $0 } ? [primary.address] : [])
+                return .ok(FakeVSRServer.rosterBody(addresses))
+            case .getPartitionRoute:
+                routed.withLock { $0 = true }
+                return .ok(FakeVSRServer.partitionRouteBody(FakeVSRServer.routeContext, primaryReplica: 2))
+            default:
+                return FakeVSRServer.defaultReply(request, address: coordinator.address)
+            }
+        }
+        let client = try await connectedClient(coordinator)
+        let rosterReads = await requests(coordinator, .getClusterMetadata).count
+        _ = try await client.pollMessages(streamID: 1, topicID: 2, partitionID: 0, strategy: .first, count: 1, autoCommit: false)
+        #expect(await requests(coordinator, .getClusterMetadata).count == rosterReads + 1)
+        #expect(await requests(coordinator, .getPartitionRoute).count == 1)
+        #expect(await requests(primary, .pollMessages).count == 1)
+        #expect(await other.connectionCount == 0)
         await client.shutdown()
     }
 }
diff --git a/foreign/swift/Tests/IggyTests/ResponseVectorTests.swift b/foreign/swift/Tests/IggyTests/ResponseVectorTests.swift
index 8bf0fae85..9433c59af 100644
--- a/foreign/swift/Tests/IggyTests/ResponseVectorTests.swift
+++ b/foreign/swift/Tests/IggyTests/ResponseVectorTests.swift
@@ -196,17 +196,13 @@ struct ResponseVectorTests {
     }
 
     @Test func routes() async throws {
-        #expect(try Responses.partitionRoute(body("response.partition_route")) == PartitionContext(incarnation: 7, ownerGeneration: 0, metadataOp: 10))
+        let route = try Responses.partitionRoute(body("response.partition_route"))
+        #expect(route.context == PartitionContext(incarnation: 7, ownerGeneration: 0, metadataOp: 10))
+        // The view and the partition count sit between the context and the
+        // primary.
+        #expect(route.primaryReplica == 2)
         // A route of any other length comes from a mismatched build.
         await expectCode(.invalidCommand) { _ = try Responses.partitionRoute(body("response.partition_route") + [0]) }
-
-        let poll = try Responses.pollRoute(body("response.poll_routing"))
-        #expect(poll.consumerSession.clientID == UInt128Value(low: 0x090a_0b0c_0d0e_0f10, high: 0x0102_0304_0506_0708))
-        #expect(poll.consumerSession.session == 42)
-        #expect(poll.consumerSession.metadataWatermark == 120)
-        #expect(poll.context == PartitionContext(incarnation: 7, ownerGeneration: 3, metadataOp: 110))
-        #expect(poll.primary.replicaID == 2)
-        #expect(poll.primary.tcpAddress == "10.0.0.3:8092")
     }
 
     @Test func clusterMetadata() throws {
diff --git a/foreign/swift/Tests/IggyTests/Support/FakeVSRServer.swift b/foreign/swift/Tests/IggyTests/Support/FakeVSRServer.swift
index 8f42505e8..6e039f6e5 100644
--- a/foreign/swift/Tests/IggyTests/Support/FakeVSRServer.swift
+++ b/foreign/swift/Tests/IggyTests/Support/FakeVSRServer.swift
@@ -166,18 +166,6 @@ final class FakeVSRServer: @unchecked Sendable {
         return writer.bytes
     }
 
-    /// The reply to `GetPollRouting` and `GetConsumerOffsetRouting`: the
-    /// session of `request` and a primary at `primary`.
-    static func pollRouteBody(for request: Request, context: PartitionContext, primary: String, watermark: UInt64 = 0) -> [UInt8] {
-        var writer = ByteWriter()
-        writer.write(request.clientID)
-        writer.write(request.session)
-        writer.write(watermark)
-        context.encode(into: &writer)
-        writeNode(primary, replicaID: 0, leader: true, into: &writer)
-        return writer.bytes
-    }
-
     /// A poll reply without messages.
     static func polledBody(partitionID: UInt32, context: PartitionContext = .empty) -> [UInt8] {
         var writer = ByteWriter()
@@ -296,9 +284,7 @@ final class FakeVSRServer: @unchecked Sendable {
             return .ok(registerBody(session: request.session))
         case .getPartitionRoute:
             return .ok(partitionRouteBody(routeContext))
-        case .getPollRouting, .getConsumerOffsetRouting:
-            return .ok(pollRouteBody(for: request, context: routeContext, primary: address))
-        case .pollMessagesOnPrimary:
+        case .pollMessages:
             return .ok(polledBody(partitionID: 0, context: routeContext))
         default:
             return .ok([])
diff --git a/foreign/swift/Tools/golden-vectors/src/main.rs b/foreign/swift/Tools/golden-vectors/src/main.rs
index 75196c29a..d9f8e2ff6 100644
--- a/foreign/swift/Tools/golden-vectors/src/main.rs
+++ b/foreign/swift/Tools/golden-vectors/src/main.rs
@@ -67,8 +67,8 @@ use iggy_binary_protocol::responses::consumer_groups::{
 };
 use iggy_binary_protocol::responses::consumer_offsets::ConsumerOffsetResponse;
 use iggy_binary_protocol::responses::messages::{
-    PartitionRouteResponse, PollMessagesResponseHeader, PollRoutingResponse,
-    SendMessagesConfirmationResponse, SendMessagesResponse,
+    PartitionRouteResponse, PollMessagesResponseHeader, SendMessagesConfirmationResponse,
+    SendMessagesResponse,
 };
 use iggy_binary_protocol::responses::personal_access_tokens::{
     GetPersonalAccessTokensResponse, PersonalAccessTokenResponse, RawPersonalAccessTokenResponse,
@@ -1427,33 +1427,6 @@ fn main() {
             primary_replica: 2,
         },
     );
-    add(
-        &mut vectors,
-        "response.poll_routing",
-        &PollRoutingResponse {
-            consumer_session: SessionIdentity {
-                client_id: 0x0102_0304_0506_0708_090a_0b0c_0d0e_0f10,
-                session: 42,
-                metadata_watermark: 120,
-            },
-            context: PartitionContext {
-                incarnation: 7,
-                owner_generation: 3,
-                metadata_op: 110,
-            },
-            primary: ClusterNodeResponse {
-                replica_id: 2,
-                name: "node-3".to_owned(),
-                ip: "10.0.0.3".to_owned(),
-                tcp_port: 8092,
-                quic_port: 0,
-                http_port: 3002,
-                websocket_port: 0,
-                role: 1,
-                status: 0,
-            },
-        },
-    );
 
     // Domain option blocks.
     let create_options = TopicCreateOptions {


(iggy) 02/07: fix(connectors): reconnect stopped source links before retrying

Posted by hg...@apache.org.
This is an automated email from the ASF dual-hosted git repository.

hubcio pushed a commit to branch feat/sdk-partition-routing
in repository https://gitbox.apache.org/repos/asf/iggy.git

commit c53fff4e405842aa6d507fb73375b5b1773103a3
Author: Hubert Gruszecki <h....@gmail.com>
AuthorDate: Thu Oct 15 23:58:03 2026 +0200

    fix(connectors): reconnect stopped source links before retrying
    
    A source could not redeliver after the SDK exhausted its reconnect
    budget. Reconnect through the existing client for exact pre-send
    connection failures before retrying the failed tail. Bound that work
    and preserve the original failure if reconnect cannot complete.
---
 core/connectors/runtime/src/source.rs | 105 +++++++++++++++++++++++++++++-----
 1 file changed, 91 insertions(+), 14 deletions(-)

diff --git a/core/connectors/runtime/src/source.rs b/core/connectors/runtime/src/source.rs
index 36f4eb239..7e1c6c180 100644
--- a/core/connectors/runtime/src/source.rs
+++ b/core/connectors/runtime/src/source.rs
@@ -19,10 +19,10 @@ use dashmap::DashMap;
 use dlopen2::wrapper::Container;
 use flume::{Receiver, Sender};
 use iggy::prelude::{
-    DirectConfig, HeaderKey, HeaderValue, Identifier, IggyClient, IggyDuration, IggyError,
+    Client, DirectConfig, HeaderKey, HeaderValue, Identifier, IggyClient, IggyDuration, IggyError,
     IggyMessage, IggyProducer, StreamClient, TopicClient, TopicCreateOptions,
 };
-use iggy_common::{Durability, TopicRuntimeOptions};
+use iggy_common::{BINARY_OPERATION_TIMEOUT, Durability, TopicRuntimeOptions};
 use iggy_connector_sdk::encoders::avro::{AvroEncoderConfig, AvroStreamEncoder};
 use iggy_connector_sdk::{
     ConnectorState, DecodedMessage, Error as SdkError, ProducedMessages, Schema, StreamEncoder,
@@ -60,6 +60,7 @@ use prometheus_client::metrics::counter::Counter;
 use tokio::runtime::Handle;
 use tokio::sync::mpsc;
 use tokio::task::JoinHandle;
+use tokio::time::timeout;
 
 const MAX_FAILED_TAIL_RETRIES: u32 = 3;
 const SOURCE_TOPIC_MESSAGES_REQUIRED_TO_SAVE: u32 = 1;
@@ -692,9 +693,12 @@ pub(crate) async fn source_forwarding_loop(
         let send_result = if state_unavailable {
             Err(IggyError::Error)
         } else if processing_errors == 0 {
-            send_with_failed_tail_retries(processed.messages, plugin_id, |messages| {
-                producer.send(messages)
-            })
+            send_with_failed_tail_retries(
+                processed.messages,
+                plugin_id,
+                &context.iggy_clients.producer,
+                |messages| producer.send(messages),
+            )
             .await
         } else {
             Err(IggyError::Error)
@@ -1090,6 +1094,7 @@ fn process_messages(
 async fn send_with_failed_tail_retries<F, Fut, T>(
     mut messages: Vec<IggyMessage>,
     plugin_id: u32,
+    client: &IggyClient,
     mut send: F,
 ) -> Result<(), IggyError>
 where
@@ -1108,11 +1113,21 @@ where
                 topic_name,
             }) => {
                 warn!(
+                    cause_code = cause.as_code(),
                     "Source connector with ID: {plugin_id} send failed after {} chunks committed; {} messages remain",
                     committed.len(),
                     failed.len()
                 );
-                if retry >= MAX_FAILED_TAIL_RETRIES || failed.is_empty() {
+                // Exhausted SDK reconnect tasks need an explicit connect. A possibly
+                // submitted binary chunk returns OperationUncertain instead.
+                if retry >= MAX_FAILED_TAIL_RETRIES
+                    || failed.is_empty()
+                    || (matches!(*cause, IggyError::NotConnected | IggyError::Disconnected)
+                        && !matches!(
+                            timeout(BINARY_OPERATION_TIMEOUT, client.connect()).await,
+                            Ok(Ok(()))
+                        ))
+                {
                     return Err(IggyError::ProducerSendFailed {
                         cause,
                         failed,
@@ -1955,6 +1970,7 @@ mod tests {
             let result = send_with_failed_tail_retries(
                 vec![test_message(1), test_message(2), test_message(3)],
                 31,
+                &IggyClient::default(),
                 |messages| {
                     attempts.push(
                         messages
@@ -1983,10 +1999,15 @@ mod tests {
                     .collect::<Vec<_>>(),
             );
 
-            let result = send_with_failed_tail_retries(vec![test_message(1)], 37, |_| {
-                attempts += 1;
-                ready(responses.pop_front().expect("send response should exist"))
-            })
+            let result = send_with_failed_tail_retries(
+                vec![test_message(1)],
+                37,
+                &IggyClient::default(),
+                |_| {
+                    attempts += 1;
+                    ready(responses.pop_front().expect("send response should exist"))
+                },
+            )
             .await;
 
             assert!(matches!(result, Err(IggyError::ProducerSendFailed { .. })));
@@ -2009,16 +2030,72 @@ mod tests {
             }));
             let mut attempts = 0;
 
-            let result =
-                send_with_failed_tail_retries(vec![test_message(1), test_message(2)], 41, |_| {
+            let result = send_with_failed_tail_retries(
+                vec![test_message(1), test_message(2)],
+                41,
+                &IggyClient::default(),
+                |_| {
                     attempts += 1;
                     ready(response.take().expect("send response should exist"))
-                })
-                .await;
+                },
+            )
+            .await;
 
             assert!(matches!(result, Err(IggyError::ProducerSendFailed { .. })));
             assert_eq!(attempts, 1);
             assert_eq!(retained.len(), 1);
         });
     }
+
+    #[test]
+    fn given_unsent_tail_when_reconnect_fails_should_preserve_the_original_failure() {
+        let runtime = tokio::runtime::Runtime::new().expect("failed to create test runtime");
+        runtime.block_on(async {
+            for failure_cause in [IggyError::NotConnected, IggyError::Disconnected] {
+                let client = IggyClient::default();
+                client.shutdown().await.expect("client should shut down");
+                let mut failure = failed_send(vec![test_message(2), test_message(3)]);
+                let IggyError::ProducerSendFailed { cause, .. } = &mut failure else {
+                    panic!("expected producer failure");
+                };
+                **cause = failure_cause.clone();
+                let mut responses = VecDeque::from([Err(failure), Ok(())]);
+                let mut attempts = 0;
+
+                let result = send_with_failed_tail_retries(
+                    vec![test_message(1), test_message(2), test_message(3)],
+                    43,
+                    &client,
+                    |_| {
+                        attempts += 1;
+                        ready(responses.pop_front().expect("send response should exist"))
+                    },
+                )
+                .await;
+
+                let Err(IggyError::ProducerSendFailed {
+                    cause,
+                    failed,
+                    committed,
+                    stream_name,
+                    topic_name,
+                }) = result
+                else {
+                    panic!("reconnect failure must preserve the producer failure");
+                };
+                assert_eq!(*cause, failure_cause);
+                assert_eq!(
+                    failed
+                        .iter()
+                        .map(|message| message.payload[0])
+                        .collect::<Vec<_>>(),
+                    [2, 3]
+                );
+                assert!(committed.is_empty());
+                assert_eq!(stream_name, "test-stream");
+                assert_eq!(topic_name, "test-topic");
+                assert_eq!(attempts, 1, "reconnect failure must not resubmit the tail");
+            }
+        });
+    }
 }


(iggy) 06/07: fix(sdk): resume group consumers after every replica link drops

Posted by hg...@apache.org.
This is an automated email from the ASF dual-hosted git repository.

hubcio pushed a commit to branch feat/sdk-partition-routing
in repository https://gitbox.apache.org/repos/asf/iggy.git

commit d79bf5ceaac17d15b7790a0fe8ff5e28f5af7697
Author: Hubert Gruszecki <h....@gmail.com>
AuthorDate: Fri Oct 16 21:54:19 2026 +0200

    fix(sdk): resume group consumers after every replica link drops
    
    After every replica link closed, a link that bound the same session
    again published only Connected. A group IggyConsumer resumes only on
    SignedIn, so it never polled again. Publish SignedIn after Connected
    when that first link binds the session and the client is still
    signed in.
    
    Publish the events of a first install and a last close under the
    table lock. Otherwise a racing close can publish Disconnected after
    the SignedIn of a reconnect and stop the consumer again.
---
 core/sdk/src/links/replicas.rs | 66 +++++++++++++++++++++++++++++++++++++-----
 1 file changed, 58 insertions(+), 8 deletions(-)

diff --git a/core/sdk/src/links/replicas.rs b/core/sdk/src/links/replicas.rs
index 77703a25e..bce6423d4 100644
--- a/core/sdk/src/links/replicas.rs
+++ b/core/sdk/src/links/replicas.rs
@@ -470,7 +470,9 @@ impl LinksShared {
         self.table.lock().unwrap_or_else(PoisonError::into_inner)
     }
 
-    /// The channel runs in overflow mode, so a publish never waits.
+    /// The channel runs in overflow mode, so a publish never waits. A first
+    /// install and a last close publish under the table lock, so their events
+    /// keep the order of the table changes.
     fn publish(&self, event: DiagnosticEvent) {
         let _ = self.events.try_broadcast(event);
     }
@@ -698,7 +700,6 @@ impl LinksShared {
         table.bootstrap = None;
         let last = table.ready_count() == 0;
         table.settle();
-        drop(table);
         if last {
             self.publish(DiagnosticEvent::Disconnected);
         }
@@ -1091,11 +1092,16 @@ impl LinksShared {
         } else {
             None
         };
-        drop(table);
-        drop(retired);
         if first {
             self.publish(DiagnosticEvent::Connected);
+            // After every link closed, a link that binds the session again
+            // resumes it, as a sweep does.
+            if bound_fence.is_some() && table.state == ClientState::Authenticated {
+                self.publish(DiagnosticEvent::SignedIn);
+            }
         }
+        drop(table);
+        drop(retired);
         info!("The link to replica {id} is ready.");
         Some(link)
     }
@@ -1113,12 +1119,11 @@ impl LinksShared {
             return;
         }
         slot.link = None;
-        let last = table.ready_count() == 0;
-        drop(table);
-        warn!("The link to replica {id} closed.");
-        if last {
+        if table.ready_count() == 0 {
             self.publish(DiagnosticEvent::Disconnected);
         }
+        drop(table);
+        warn!("The link to replica {id} closed.");
     }
 
     fn slot_stopped(&self, id: u8) {
@@ -1552,6 +1557,40 @@ mod tests {
         assert!(events.try_recv().is_err());
     }
 
+    #[tokio::test(start_paused = true)]
+    async fn given_every_link_lost_when_a_slot_binds_the_session_again_should_publish_signed_in() {
+        let cluster = FakeCluster::new(3);
+        let links = connected(&cluster, 3).await;
+        let fence = links.shared.session.fence();
+        let mut events = links.subscribe();
+        while events.try_recv().is_ok() {}
+
+        // Refused dials keep every slot down until the last link closed.
+        cluster.down.lock().unwrap().extend((0..3).map(endpoint));
+        for id in 0..3 {
+            cluster.drop_connections(&endpoint(id));
+        }
+        eventually("every link is down", || links.ready_replicas().is_empty()).await;
+        assert_eq!(links.state(), ClientState::Authenticated);
+        cluster.down.lock().unwrap().clear();
+        eventually("every slot is ready again", || {
+            links.ready_replicas().len() == 3
+        })
+        .await;
+
+        let published: Vec<_> = std::iter::from_fn(|| events.try_recv().ok()).collect();
+        assert_eq!(
+            published,
+            [
+                DiagnosticEvent::Disconnected,
+                DiagnosticEvent::Connected,
+                DiagnosticEvent::SignedIn
+            ]
+        );
+        assert_eq!(links.shared.session.fence(), fence);
+        assert_eq!(cluster.count(LOGIN_REGISTER_CODE), 1);
+    }
+
     #[tokio::test(start_paused = true)]
     async fn given_a_session_reset_when_links_are_ready_should_close_all_but_the_sign_in_link() {
         let cluster = FakeCluster::new(3);
@@ -1703,6 +1742,8 @@ mod tests {
         let fence = links.shared.session.fence();
         // Each slot waits its initial jitter, then its bind finds the session gone.
         sleep(REESTABLISH_AFTER).await;
+        let mut events = links.subscribe();
+        while events.try_recv().is_ok() {}
 
         *cluster.session.lock().unwrap() = None;
         for id in 0..3 {
@@ -1716,6 +1757,15 @@ mod tests {
         assert_eq!(links.shared.session.fence(), fence + 1);
         assert_eq!(cluster.count(LOGIN_REGISTER_CODE), 2);
         assert_eq!(links.state(), ClientState::Authenticated);
+        let published: Vec<_> = std::iter::from_fn(|| events.try_recv().ok()).collect();
+        assert_eq!(
+            published,
+            [
+                DiagnosticEvent::Disconnected,
+                DiagnosticEvent::Connected,
+                DiagnosticEvent::SignedIn
+            ]
+        );
     }
 
     #[tokio::test(start_paused = true)]


(iggy) 04/07: test(node): stop both consumers before deleting the e2e stream

Posted by hg...@apache.org.
This is an automated email from the ASF dual-hosted git repository.

hubcio pushed a commit to branch feat/sdk-partition-routing
in repository https://gitbox.apache.org/repos/asf/iggy.git

commit 208c3f05769261d557c0878561aacd4fe6eb364b
Author: Hubert Gruszecki <h....@gmail.com>
AuthorDate: Fri Oct 16 16:36:29 2026 +0200

    test(node): stop both consumers before deleting the e2e stream
    
    consumer-stream::poll-stream finished when the first consumer stream
    ended, and its after hook then deleted the stream. The second
    consumer stops only on its next data event, so it was sometimes
    still polling. Its next poll or group re-join after the delete got
    1009, and with no error listener on that stream the test failed.
    
    Destroy both consumer streams before the delete. A destroyed stream
    drops the error of a later poll.
---
 foreign/node/src/e2e/tcp.consumer-stream.e2e.ts | 4 ++++
 1 file changed, 4 insertions(+)

diff --git a/foreign/node/src/e2e/tcp.consumer-stream.e2e.ts b/foreign/node/src/e2e/tcp.consumer-stream.e2e.ts
index b7026745e..32bf7ed5b 100644
--- a/foreign/node/src/e2e/tcp.consumer-stream.e2e.ts
+++ b/foreign/node/src/e2e/tcp.consumer-stream.e2e.ts
@@ -104,6 +104,10 @@ describe('e2e -> consumer-stream', async () => {
     });
 
     after(async () => {
+      // The member that did not get the last batch can still be polling,
+      // and a poll that fails after the delete has no error listener.
+      s.destroy();
+      s2.destroy();
       assert.ok(await c.stream.delete({ streamId: streamName }));
       assert.ok(await c.session.logout());
       await c.destroy();


(iggy) 01/07: test(integration): account for managed reconnects in stale clients

Posted by hg...@apache.org.
This is an automated email from the ASF dual-hosted git repository.

hubcio pushed a commit to branch feat/sdk-partition-routing
in repository https://gitbox.apache.org/repos/asf/iggy.git

commit 4c0589431ea5c51b704e00e3a2cd5b356b806ebf
Author: Hubert Gruszecki <h....@gmail.com>
AuthorDate: Thu Oct 15 23:58:01 2026 +0200

    test(integration): account for managed reconnects in stale clients
    
    Automatic replica reconnects renewed deliberately stale sessions and
    added a second client after restart. Disable reconnect only for the
    stale fixtures and explicitly disconnect the replaced stats client.
    Those fixtures keep their expiry, membership, and persistence
    assertions.
    
    The auto reconnection test keeps reconnect on, so each evicted link
    binds the same session again and renews its lease. Expect the
    consumer to keep its membership through the silent window. Run the
    test on one node, where every eviction takes the only link down, and
    on three.
---
 .../data_integrity/verify_after_server_restart.rs  |  8 +--
 .../verify_consumer_group_partition_assignment.rs  |  4 ++
 .../stale_client_consumer_group_scenario.rs        | 63 ++++++++++++++--------
 3 files changed, 48 insertions(+), 27 deletions(-)

diff --git a/core/integration/tests/data_integrity/verify_after_server_restart.rs b/core/integration/tests/data_integrity/verify_after_server_restart.rs
index a9dece200..9ed57b6b6 100644
--- a/core/integration/tests/data_integrity/verify_after_server_restart.rs
+++ b/core/integration/tests/data_integrity/verify_after_server_restart.rs
@@ -91,6 +91,9 @@ async fn should_fill_data_and_verify_after_restart() {
     let expected_clients_count = stats.clients_count;
     let expected_consumer_groups_count = stats.consumer_groups_count;
 
+    // Keep this handle from reconnecting alongside the replacement after restart.
+    client.disconnect().await.unwrap();
+
     // Restart server
     harness.restart_server().await.unwrap();
     let server_addr = harness.server().raw_tcp_addr().unwrap();
@@ -170,10 +173,7 @@ async fn should_fill_data_and_verify_after_restart() {
         "pinned-consumer",
         IggyByteSize::from(amount_of_data_to_process.as_bytes_u64() * 2),
     );
-    drop(client_after_restart);
-
-    // Connect and login to server
-    let client = harness.tcp_root_client().await.unwrap();
+    let client = client_after_restart;
 
     // Save stats from the second server (should have double the data)
     let stats = client.get_stats().await.unwrap();
diff --git a/core/integration/tests/data_integrity/verify_consumer_group_partition_assignment.rs b/core/integration/tests/data_integrity/verify_consumer_group_partition_assignment.rs
index cb660f026..fd42ee27b 100644
--- a/core/integration/tests/data_integrity/verify_consumer_group_partition_assignment.rs
+++ b/core/integration/tests/data_integrity/verify_consumer_group_partition_assignment.rs
@@ -71,6 +71,10 @@ async fn create_stale_tcp_client(server_addr: &str) -> IggyClient {
     let config = TcpClientConfig {
         server_address: server_addr.to_string(),
         heartbeat_interval: NonZeroIggyDuration::from_str("1h").unwrap(),
+        reconnection: TcpClientReconnectionConfig {
+            enabled: false,
+            ..TcpClientReconnectionConfig::default()
+        },
         nodelay: true,
         ..TcpClientConfig::default()
     };
diff --git a/core/integration/tests/server/scenarios/stale_client_consumer_group_scenario.rs b/core/integration/tests/server/scenarios/stale_client_consumer_group_scenario.rs
index e649ed757..6787665c5 100644
--- a/core/integration/tests/server/scenarios/stale_client_consumer_group_scenario.rs
+++ b/core/integration/tests/server/scenarios/stale_client_consumer_group_scenario.rs
@@ -125,7 +125,8 @@ async fn given_cluster_restart_when_member_is_replaced_should_resume_consumption
 async fn given_live_member_when_backup_restarts_should_preserve_membership(
     harness: &mut integration::harness::TestHarness,
 ) {
-    let consumer_client = create_client(&harness.server().raw_tcp_addr().unwrap(), "1h").await;
+    let consumer_client =
+        create_client(&harness.server().raw_tcp_addr().unwrap(), "1h", true).await;
     setup_resources(&consumer_client, Durability::Persisted).await;
     let stream = Identifier::named(STREAM_NAME).unwrap();
     let topic = Identifier::named(TOPIC_NAME).unwrap();
@@ -169,7 +170,7 @@ async fn verify_replacement_after_restart(
     restart: Restart,
 ) {
     let server_addr = harness.server().raw_tcp_addr().unwrap();
-    let original = create_client(&server_addr, "500ms").await;
+    let original = create_client(&server_addr, "500ms", true).await;
     setup_resources(&original, Durability::Persisted).await;
     let stream = Identifier::named(STREAM_NAME).unwrap();
     let topic = Identifier::named(TOPIC_NAME).unwrap();
@@ -232,7 +233,7 @@ async fn verify_replacement_after_restart(
         harness.restart_node(0).unwrap();
     }
 
-    let replacement = create_client(&server_addr, "500ms").await;
+    let replacement = create_client(&server_addr, "500ms", true).await;
     replacement
         .login_user(DEFAULT_ROOT_USERNAME, DEFAULT_ROOT_PASSWORD)
         .await
@@ -313,10 +314,14 @@ async fn verify_replacement_after_restart(
     }
 }
 
-async fn create_client(server_addr: &str, heartbeat_interval: &str) -> IggyClient {
+async fn create_client(server_addr: &str, heartbeat_interval: &str, reconnect: bool) -> IggyClient {
     let config = TcpClientConfig {
         server_address: server_addr.to_string(),
         heartbeat_interval: NonZeroIggyDuration::from_str(heartbeat_interval).unwrap(),
+        reconnection: TcpClientReconnectionConfig {
+            enabled: reconnect,
+            ..TcpClientReconnectionConfig::default()
+        },
         nodelay: true,
         ..TcpClientConfig::default()
     };
@@ -405,11 +410,11 @@ async fn should_handle_stale_client_with_manual_reconnection(
 ) {
     let server_addr = harness.server().raw_tcp_addr().unwrap();
 
-    let setup_client = create_client(&server_addr, "500ms").await;
+    let setup_client = create_client(&server_addr, "500ms", true).await;
     setup_resources(&setup_client, Durability::Persisted).await;
 
-    // Client with 1h heartbeat will become stale
-    let stale_client = create_client(&server_addr, "1h").await;
+    // Rebinding after eviction would renew the logical session instead of letting it expire.
+    let stale_client = create_client(&server_addr, "1h", false).await;
     stale_client
         .login_user(DEFAULT_ROOT_USERNAME, DEFAULT_ROOT_PASSWORD)
         .await
@@ -485,7 +490,7 @@ async fn should_handle_stale_client_with_manual_reconnection(
 
     // Reconnect with new client
     drop(stale_client);
-    let new_client = create_client(&server_addr, "500ms").await;
+    let new_client = create_client(&server_addr, "500ms", true).await;
     new_client
         .login_user(DEFAULT_ROOT_USERNAME, DEFAULT_ROOT_PASSWORD)
         .await
@@ -526,8 +531,9 @@ async fn should_handle_stale_client_with_manual_reconnection(
         .await;
 }
 
-/// Tests that IggyConsumer automatically recovers after stale disconnect.
-#[iggy_harness(server(
+/// Tests that IggyConsumer automatically recovers after stale disconnect. On one
+/// node every eviction takes the client's only link down.
+#[iggy_harness(cluster_nodes = [1, 3], server(
     heartbeat.enabled = true,
     heartbeat.interval = "7s",
     consumer_group.heartbeat_interval = "500ms",
@@ -537,7 +543,7 @@ async fn should_handle_stale_client_with_auto_reconnection(
 ) {
     let server_addr = harness.server().raw_tcp_addr().unwrap();
 
-    let setup_client = create_client(&server_addr, "500ms").await;
+    let setup_client = create_client(&server_addr, "500ms", true).await;
     setup_resources(&setup_client, Durability::Persisted).await;
 
     let consumer_client = create_reconnecting_client(&server_addr).await;
@@ -571,18 +577,29 @@ async fn should_handle_stale_client_with_auto_reconnection(
         if let Some(Ok(_)) = poll_result {
             messages_consumed += 1;
             if messages_consumed == 5 {
-                // Stay silent until the verifier evicts the connection and
-                // the server ends the session, so the consumer must
-                // reconnect, log in again and rejoin its group.
-                integration::harness::wait_for_consumer_group_assignment(
-                    &setup_client,
-                    &Identifier::named(STREAM_NAME).unwrap(),
-                    &Identifier::named(TOPIC_NAME).unwrap(),
-                    &Identifier::named(CONSUMER_GROUP_NAME).unwrap(),
-                    0,
-                    STALE_EVICTION_TIMEOUT,
-                )
-                .await;
+                // Stay silent past the bound in which a silent client loses
+                // its membership. The heartbeat verifier evicts the
+                // consumer's links, but each link reconnects and binds the
+                // same session again, which renews its lease. The setup
+                // client runs no heartbeat, so these reads also keep its own
+                // session alive.
+                let deadline = tokio::time::Instant::now() + STALE_EVICTION_TIMEOUT;
+                while tokio::time::Instant::now() < deadline {
+                    let group = setup_client
+                        .get_consumer_group(
+                            &Identifier::named(STREAM_NAME).unwrap(),
+                            &Identifier::named(TOPIC_NAME).unwrap(),
+                            &Identifier::named(CONSUMER_GROUP_NAME).unwrap(),
+                        )
+                        .await
+                        .unwrap()
+                        .expect("consumer group exists");
+                    assert_eq!(
+                        group.members_count, 1,
+                        "the rebound session must keep its membership: {group:?}"
+                    );
+                    sleep(STALE_EVICTION_RETRY_INTERVAL).await;
+                }
             }
         }
     }


(iggy) 07/07: test(gateways): accept either timeout in the black hole dial test

Posted by hg...@apache.org.
This is an automated email from the ASF dual-hosted git repository.

hubcio pushed a commit to branch feat/sdk-partition-routing
in repository https://gitbox.apache.org/repos/asf/iggy.git

commit 3504d9b50f910a420df0cd0eb64eac4faaf4721b
Author: Hubert Gruszecki <h....@gmail.com>
AuthorDate: Fri Oct 16 21:54:27 2026 +0200

    test(gateways): accept either timeout in the black hole dial test
    
    The SDK bounds every dial and returns CannotEstablishConnection after
    its last reconnect pass. Against a black hole address, this ends close
    to the bridge's 15 s request timeout, so either error can come first.
    Accept both, because no link came up in either case, and keep the
    bound on the elapsed time. The doc no longer names removed SDK items.
---
 .../kafka/tests/bridge_iggy_integration_tests.rs   | 34 +++++++++++++---------
 1 file changed, 21 insertions(+), 13 deletions(-)

diff --git a/gateways/kafka/tests/bridge_iggy_integration_tests.rs b/gateways/kafka/tests/bridge_iggy_integration_tests.rs
index 1456627ae..41587da44 100644
--- a/gateways/kafka/tests/bridge_iggy_integration_tests.rs
+++ b/gateways/kafka/tests/bridge_iggy_integration_tests.rs
@@ -24,7 +24,7 @@ use std::collections::HashMap;
 use std::time::Duration;
 
 use iggy::prelude::{
-    Identifier, IggyMessage, MessageClient, Partitioning, StreamClient, TopicClient,
+    Identifier, IggyError, IggyMessage, MessageClient, Partitioning, StreamClient, TopicClient,
 };
 use secrecy::SecretString;
 use serial_test::serial;
@@ -434,15 +434,14 @@ async fn connect_to_unreachable_iggy_returns_err_not_panic() {
     assert!(matches!(result, Err(BridgeError::Iggy(_))));
 }
 
-/// Regression test for the missing dial timeout: `TcpClient::establish_bounded` only applies its
-/// own `FAILOVER_DIAL_TIMEOUT` when at least two failover candidates are configured, which a
-/// bridge (always exactly one address) never has, so the underlying `TcpStream::connect` had no
-/// deadline at all against an address that drops packets instead of refusing them. 192.0.2.1 is
-/// RFC 5737 TEST-NET-1 - reserved for documentation, routed nowhere, so the connect attempt hangs
-/// on the kernel's own SYN-retry timeout (confirmed against this exact address before writing this
-/// test: over the sandbox's real network stack, a bare `connect()` past 3s had not yet failed).
-/// Before `REQUEST_TIMEOUT`, this test would have hung for minutes; now it must fail within a
-/// bounded window.
+/// Regression test for the missing dial timeout: the SDK once bounded a dial only when at least
+/// two failover candidates were configured, which a bridge (always exactly one address) never
+/// has, so the underlying `TcpStream::connect` had no deadline at all against an address that
+/// drops packets instead of refusing them. 192.0.2.1 is RFC 5737 TEST-NET-1 - reserved for
+/// documentation, routed nowhere, so the connect attempt hangs on the kernel's own SYN-retry
+/// timeout (confirmed against this exact address before writing this test: over the sandbox's
+/// real network stack, a bare `connect()` past 3s had not yet failed). Before `REQUEST_TIMEOUT`,
+/// this test would have hung for minutes; now it must fail within a bounded window.
 #[tokio::test]
 async fn connect_to_a_black_hole_address_times_out_instead_of_hanging() {
     let config = IggyBridgeConfig {
@@ -468,10 +467,19 @@ async fn connect_to_a_black_hole_address_times_out_instead_of_hanging() {
         "connect took {:?}, longer than REQUEST_TIMEOUT (15s) should allow",
         start.elapsed()
     );
-    // BridgeError::Timeout, not BridgeError::Iggy: with_request_timeout's own elapsed branch
-    // maps here (see that function's doc for why an unknown outcome must not borrow
+    // Either bound can end the attempt first. The SDK cuts every dial at its own timeout and
+    // returns CannotEstablishConnection after its last reconnect pass, which is safe because no
+    // link ever came up. Otherwise with_request_timeout's own elapsed branch maps to
+    // BridgeError::Timeout (see that function's doc for why an unknown outcome must not borrow
     // CannotEstablishConnection's known-safe code).
-    assert!(matches!(result, Err(BridgeError::Timeout)));
+    assert!(
+        matches!(
+            result,
+            Err(BridgeError::Timeout | BridgeError::Iggy(IggyError::CannotEstablishConnection))
+        ),
+        "unexpected connect result: {:?}",
+        result.as_ref().err()
+    );
 }
 
 /// Regression test: `IggyClient::disconnect` (what `close` used to call) never touches