feat(client): standardize connection outcomes (#13)

tests/FinalFactory.Rendezvous.Tests/Client/RendezvousClientBehaviorTests.cs

@@ -102,6 +102,32 @@ public sealed class RendezvousClientBehaviorTests
         Assert.Equal(TimeSpan.FromMilliseconds(200), Assert.Single(delay.Delays));
     }
 
+    [Fact]
+    public async Task SilentServiceIsBoundedByTheConfiguredRequestTimeout()
+    {
+        using HttpClient httpClient = new(new SilentHandler())
+        {
+            BaseAddress = new("http://rendezvous.test/"),
+        };
+        RendezvousSessionBrowserClient browser = new(
+            httpClient,
+            new RendezvousClientOptions
+            {
+                MaximumSafeRetries = 0,
+                RequestTimeout = TimeSpan.FromMilliseconds(20),
+                JitterRatio = 0,
+            });
+
+        RendezvousClientResult<BrowseSessionsResponse> result = await browser.BrowseAsync(new()
+        {
+            GameId = new("space-game"),
+            EnvironmentId = new("production"),
+            ProtocolVersion = 7,
+        }).WaitAsync(TimeSpan.FromSeconds(2));
+
+        Assert.Equal(RendezvousErrorCode.ServiceUnavailable, result.Error);
+    }
+
     [Fact]
     public void SuccessResultRequiresAValue()
     {
@@ -339,4 +365,15 @@ public sealed class RendezvousClientBehaviorTests
             return Task.Delay(Timeout.InfiniteTimeSpan, cancellationToken);
         }
     }
+
+    private sealed class SilentHandler : HttpMessageHandler
+    {
+        protected override async Task<HttpResponseMessage> SendAsync(
+            HttpRequestMessage request,
+            CancellationToken cancellationToken)
+        {
+            await Task.Delay(Timeout.InfiniteTimeSpan, cancellationToken);
+            return new HttpResponseMessage(HttpStatusCode.OK);
+        }
+    }
 }

tests/FinalFactory.Rendezvous.Tests/Client/RendezvousCoordinatorBehaviorTests.cs

@@ -7,6 +7,55 @@ namespace FinalFactory.Rendezvous.Tests.Client;
 
 public sealed class RendezvousCoordinatorBehaviorTests
 {
+    [Fact]
+    public void LegacyCompletionConstructorsRemainCompatibleWithoutAllowingNonterminalStates()
+    {
+#pragma warning disable CS0618
+        RendezvousConnectionCompletedEventArgs client = new(
+            RendezvousConnectionState.Rejected,
+            (NetPeer?)null);
+        RendezvousHostAttemptCompletedEventArgs host = new(
+            new JoinAttemptId(Guid.NewGuid()),
+            RendezvousConnectionState.ManagerStopped,
+            (NetPeer?)null);
+        Assert.Throws<ArgumentOutOfRangeException>(() =>
+            new RendezvousConnectionCompletedEventArgs(
+                RendezvousConnectionState.Punching,
+                (NetPeer?)null));
+        Assert.Throws<ArgumentException>(() =>
+            new RendezvousHostAttemptCompletedEventArgs(
+                default,
+                RendezvousConnectionState.Rejected,
+                (NetPeer?)null));
+#pragma warning restore CS0618
+
+        Assert.Equal(ConnectionOutcomeKind.HostRejected, client.Outcome.Kind);
+        Assert.Equal(ConnectionOutcomeKind.ManagerStopped, host.Outcome.Kind);
+    }
+
+    [Theory]
+    [InlineData(RendezvousErrorCode.NotFound, ConnectionOutcomeKind.DirectoryNotFound, RendezvousConnectionFailureCategory.Directory)]
+    [InlineData(RendezvousErrorCode.Expired, ConnectionOutcomeKind.AttemptExpired, RendezvousConnectionFailureCategory.Authorization)]
+    [InlineData(RendezvousErrorCode.IncompatibleProtocol, ConnectionOutcomeKind.IncompatibleProtocol, RendezvousConnectionFailureCategory.Compatibility)]
+    [InlineData(RendezvousErrorCode.Forbidden, ConnectionOutcomeKind.Unauthorized, RendezvousConnectionFailureCategory.Authorization)]
+    [InlineData(RendezvousErrorCode.RateLimited, ConnectionOutcomeKind.RateLimited, RendezvousConnectionFailureCategory.Capacity)]
+    [InlineData(RendezvousErrorCode.StaleHost, ConnectionOutcomeKind.NoHostPresence, RendezvousConnectionFailureCategory.HostPresence)]
+    [InlineData(RendezvousErrorCode.ServiceUnavailable, ConnectionOutcomeKind.ServiceUnavailable, RendezvousConnectionFailureCategory.Service)]
+    public void AuthoritativeServiceErrorsMapToStableConnectionOutcomes(
+        RendezvousErrorCode error,
+        ConnectionOutcomeKind expectedKind,
+        RendezvousConnectionFailureCategory expectedCategory)
+    {
+        RendezvousConnectionOutcome outcome = RendezvousConnectionOutcome.FromServiceError(
+            error,
+            TimeSpan.FromMilliseconds(250));
+
+        Assert.Equal(expectedKind, outcome.Kind);
+        Assert.Equal(expectedCategory, outcome.Category);
+        Assert.Equal(RendezvousConnectionOutcomeSource.RendezvousService, outcome.Source);
+        Assert.Equal(error, outcome.ServiceError);
+    }
+
     [Fact]
     public void NatIntroductionAloneDoesNotCompleteTheClientAttempt()
     {
@@ -43,6 +92,29 @@ public sealed class RendezvousCoordinatorBehaviorTests
         Assert.False(harness.Coordinator.IsCompleted);
     }
 
+    [Fact]
+    public void MediatorNetworkErrorProducesOneTypedTerminalOutcome()
+    {
+        ManualCoordinatorClock clock = new(new(2030, 1, 1, 0, 0, 0, TimeSpan.Zero));
+        using ClientHarness harness = new(clock);
+        int completions = 0;
+        harness.Coordinator.Completed += (_, _) => completions++;
+
+        harness.NetworkEvents.OnNetworkError(
+            new IPEndPoint(IPAddress.Loopback, 65_001),
+            System.Net.Sockets.SocketError.HostUnreachable);
+        RendezvousConnectionOutcome outcome = Assert.IsType<RendezvousConnectionOutcome>(
+            harness.Coordinator.Outcome);
+        harness.NetworkEvents.OnNetworkError(
+            new IPEndPoint(IPAddress.Loopback, 65_001),
+            System.Net.Sockets.SocketError.HostUnreachable);
+
+        Assert.Equal(ConnectionOutcomeKind.MediatorUnavailable, outcome.Kind);
+        Assert.Equal(RendezvousConnectionFailureCategory.Mediation, outcome.Category);
+        Assert.Equal(1, completions);
+        Assert.Same(outcome, harness.Coordinator.Outcome);
+    }
+
     [Fact]
     public void CancellationCompletesExactlyOnceAndLateCallbacksCannotReopenTheAttempt()
     {
@@ -61,6 +133,7 @@ public sealed class RendezvousCoordinatorBehaviorTests
 
         Assert.Equal(RendezvousConnectionState.Cancelled, harness.Coordinator.State);
         Assert.Equal([RendezvousConnectionState.Cancelled], completions);
+        Assert.Equal(ConnectionOutcomeKind.Cancelled, harness.Coordinator.Outcome!.Kind);
     }
 
     [Fact]
@@ -85,6 +158,68 @@ public sealed class RendezvousCoordinatorBehaviorTests
 
         Assert.Equal(RendezvousConnectionState.TimedOut, harness.Coordinator.State);
         Assert.Equal(1, completions);
+        Assert.Equal(ConnectionOutcomeKind.PunchTimedOut, harness.Coordinator.Outcome!.Kind);
+        Assert.Equal(
+            RendezvousConnectionFailureCategory.NatTraversal,
+            harness.Coordinator.Outcome.Category);
+    }
+
+    [Fact]
+    public void WallClockRollbackCannotExtendTheMonotonicPunchDeadline()
+    {
+        ManualCoordinatorClock clock = new(new(2030, 1, 1, 0, 0, 0, TimeSpan.Zero));
+        using ClientHarness harness = new(clock, new RendezvousCoordinatorOptions
+        {
+            PunchTimeout = TimeSpan.FromSeconds(10),
+            JitterRatio = 0,
+        });
+        clock.AdjustWallClock(TimeSpan.FromHours(-1));
+        clock.Advance(TimeSpan.FromSeconds(11));
+
+        harness.Coordinator.Poll();
+
+        Assert.Equal(ConnectionOutcomeKind.PunchTimedOut, harness.Coordinator.Outcome!.Kind);
+        Assert.Equal(TimeSpan.FromSeconds(11), harness.Coordinator.Outcome.Elapsed);
+    }
+
+    [Fact]
+    public void DirectConnectTimeoutOffersFallbackWithoutConnectingIt()
+    {
+        ManualCoordinatorClock clock = new(new(2030, 1, 1, 0, 0, 0, TimeSpan.Zero));
+        NetworkEndpoint fallback = new()
+        {
+            AddressFamily = AddressFamilyKind.Ipv4,
+            Address = "203.0.113.90",
+            Port = 9_060,
+        };
+        using ClientHarness harness = new(clock, new RendezvousCoordinatorOptions
+        {
+            DirectConnectTimeout = TimeSpan.FromMilliseconds(10),
+            DedicatedFallbackOverride = fallback,
+            JitterRatio = 0,
+        });
+        ((INatPunchListener)harness.PunchEvents).OnNatIntroductionSuccess(
+            new IPEndPoint(IPAddress.Loopback, 65_000),
+            NatAddressType.External,
+            harness.IntroductionToken);
+        clock.Advance(TimeSpan.FromMilliseconds(10));
+
+        harness.Coordinator.Poll();
+
+        RendezvousConnectionOutcome outcome = Assert.IsType<RendezvousConnectionOutcome>(
+            harness.Coordinator.Outcome);
+        Assert.Equal(ConnectionOutcomeKind.DirectConnectTimedOut, outcome.Kind);
+        Assert.Equal(RendezvousConnectionPhase.DirectConnection, outcome.Phase);
+        Assert.Equal("203.0.113.90", outcome.DedicatedFallback!.Address);
+        List<NetPeer> connectedPeers = [];
+        harness.Manager.GetConnectedPeers(connectedPeers);
+        Assert.Empty(connectedPeers);
+
+        ((INatPunchListener)harness.PunchEvents).OnNatIntroductionSuccess(
+            new IPEndPoint(IPAddress.Loopback, 65_001),
+            NatAddressType.External,
+            harness.IntroductionToken);
+        Assert.Same(outcome, harness.Coordinator.Outcome);
     }
 
     [Fact]
@@ -145,6 +280,10 @@ public sealed class RendezvousCoordinatorBehaviorTests
 
             Assert.Equal(RendezvousConnectionState.Rejected, client.Coordinator.State);
             Assert.Equal(1, completions);
+            Assert.Equal(ConnectionOutcomeKind.HostRejected, client.Coordinator.Outcome!.Kind);
+            Assert.Equal(
+                RendezvousConnectionOutcomeSource.RemoteHost,
+                client.Coordinator.Outcome.Source);
             client.Coordinator.Poll();
             Assert.Equal(1, completions);
         }
@@ -409,7 +548,7 @@ public sealed class RendezvousCoordinatorBehaviorTests
     }
 
     [Fact]
-    public async Task HostBoundsAttemptExpiryChecksPerPoll()
+    public async Task HostDeadlinesAreNotDelayedByTheBoundedRetryQueue()
     {
         ManualCoordinatorClock clock = new(new(2030, 1, 1, 0, 0, 0, TimeSpan.Zero));
         RendezvousNetListener networkEvents = new();
@@ -453,9 +592,6 @@ public sealed class RendezvousCoordinatorBehaviorTests
 
             host.Poll();
 
-            Assert.Equal(1, host.PendingAttemptCount);
-            Assert.Equal([RendezvousConnectionState.TimedOut], completions);
-            host.Poll();
             Assert.Equal(0, host.PendingAttemptCount);
             Assert.Equal(
                 [RendezvousConnectionState.TimedOut, RendezvousConnectionState.TimedOut],
@@ -467,6 +603,112 @@ public sealed class RendezvousCoordinatorBehaviorTests
         }
     }
 
+    [Fact]
+    public async Task HostStopPublishesEveryCompletionBeforeReentrantDisposalCanTearDownState()
+    {
+        ManualCoordinatorClock clock = new(new(2030, 1, 1, 0, 0, 0, TimeSpan.Zero));
+        RendezvousNetListener networkEvents = new();
+        NetManager manager = networkEvents.CreateManager();
+        JoinAttemptId firstId = new(Guid.Parse("00000000-0000-0000-0000-000000000161"));
+        JoinAttemptId secondId = new(Guid.Parse("00000000-0000-0000-0000-000000000162"));
+        MutableJoinClient joins = new([
+            CreateHostAttempt(
+                firstId,
+                new(Guid.Parse("00000000-0000-0000-0000-000000000163")),
+                NatIntroductionTokenCodec.Encode(firstId, Credential('T')),
+                clock.UtcNow + TimeSpan.FromSeconds(30)),
+            CreateHostAttempt(
+                secondId,
+                new(Guid.Parse("00000000-0000-0000-0000-000000000164")),
+                NatIntroductionTokenCodec.Encode(secondId, Credential('U')),
+                clock.UtcNow + TimeSpan.FromSeconds(30)),
+        ]);
+        RendezvousHostCoordinator? host = null;
+        try
+        {
+            Assert.True(manager.Start(0));
+            host = new(
+                manager,
+                networkEvents,
+                new IPEndPoint(IPAddress.Loopback, 65_002),
+                CreateSession(clock.UtcNow + TimeSpan.FromMinutes(1)),
+                joins,
+                new RendezvousCoordinatorOptions { JitterRatio = 0 },
+                clock,
+                null);
+            int completions = 0;
+            host.AttemptCompleted += (_, _) =>
+            {
+                completions++;
+                if (completions == 1)
+                {
+                    host.Dispose();
+                }
+            };
+            Assert.True((await host.RefreshJoinAttemptsAsync()).IsSuccess);
+            host.Poll();
+            manager.Stop();
+
+            host.Poll();
+
+            Assert.Equal(2, completions);
+            Assert.Equal(0, host.PendingAttemptCount);
+        }
+        finally
+        {
+            host?.Dispose();
+            manager.Stop();
+        }
+    }
+
+    [Fact]
+    public async Task HostPunchTimeoutUsesItsOwnFakeClockBudget()
+    {
+        ManualCoordinatorClock clock = new(new(2030, 1, 1, 0, 0, 0, TimeSpan.Zero));
+        RendezvousNetListener networkEvents = new();
+        NetManager manager = networkEvents.CreateManager();
+        JoinAttemptId attemptId = new(Guid.Parse("00000000-0000-0000-0000-000000000161"));
+        MutableJoinClient joins = new([
+            CreateHostAttempt(
+                attemptId,
+                new(Guid.Parse("00000000-0000-0000-0000-000000000162")),
+                NatIntroductionTokenCodec.Encode(attemptId, Credential('T')),
+                clock.UtcNow + TimeSpan.FromSeconds(30)),
+        ]);
+        try
+        {
+            Assert.True(manager.Start(0));
+            using RendezvousHostCoordinator host = new(
+                manager,
+                networkEvents,
+                new IPEndPoint(IPAddress.Loopback, 65_002),
+                CreateSession(clock.UtcNow + TimeSpan.FromMinutes(1)),
+                joins,
+                new RendezvousCoordinatorOptions
+                {
+                    MaximumPunchRequests = 20,
+                    PunchTimeout = TimeSpan.FromMilliseconds(10),
+                    JitterRatio = 0,
+                },
+                clock,
+                null);
+            RendezvousHostAttemptCompletedEventArgs? completion = null;
+            host.AttemptCompleted += (_, value) => completion = value;
+            Assert.True((await host.RefreshJoinAttemptsAsync()).IsSuccess);
+            host.Poll();
+            clock.Advance(TimeSpan.FromMilliseconds(10));
+
+            host.Poll();
+
+            Assert.Equal(ConnectionOutcomeKind.PunchTimedOut, completion!.Outcome.Kind);
+            Assert.Equal(TimeSpan.FromMilliseconds(10), completion.Outcome.Elapsed);
+        }
+        finally
+        {
+            manager.Stop();
+        }
+    }
+
     private static CreateJoinAttemptResponse CreateAttempt(DateTimeOffset expiresAt) => new()
     {
         AttemptId = new(Guid.Parse("00000000-0000-0000-0000-000000000101")),
@@ -548,6 +790,11 @@ public sealed class RendezvousCoordinatorBehaviorTests
     {
         internal IReadOnlyList<HostJoinAttempt> Attempts { get; set; } = attempts;
 
+        public Task<RendezvousConnectionStartResult> CreateConnectionAttemptAsync(
+            CreateJoinAttemptRequest request,
+            NetworkEndpoint? dedicatedFallback = null,
+            CancellationToken cancellationToken = default) => throw new NotSupportedException();
+
         public Task<RendezvousClientResult<CreateJoinAttemptResponse>> CreateAsync(
             CreateJoinAttemptRequest request,
             CancellationToken cancellationToken = default) => throw new NotSupportedException();
@@ -567,6 +814,11 @@ public sealed class RendezvousCoordinatorBehaviorTests
             int maximumPages = 100,
             CancellationToken cancellationToken = default) => Task.FromResult(
                 RendezvousClientResult.Success(Attempts));
+
+        public Task<RendezvousClientResult<ReportConnectionOutcomeResponse>> ReportOutcomeAsync(
+            CreateJoinAttemptResponse attempt,
+            RendezvousConnectionOutcome outcome,
+            CancellationToken cancellationToken = default) => throw new NotSupportedException();
     }
 
     private sealed class BlockingJoinClient : IRendezvousJoinClient
@@ -581,6 +833,11 @@ public sealed class RendezvousCoordinatorBehaviorTests
         internal void Complete(IReadOnlyList<HostJoinAttempt> attempts) =>
             _result.SetResult(attempts);
 
+        public Task<RendezvousConnectionStartResult> CreateConnectionAttemptAsync(
+            CreateJoinAttemptRequest request,
+            NetworkEndpoint? dedicatedFallback = null,
+            CancellationToken cancellationToken = default) => throw new NotSupportedException();
+
         public Task<RendezvousClientResult<CreateJoinAttemptResponse>> CreateAsync(
             CreateJoinAttemptRequest request,
             CancellationToken cancellationToken = default) => throw new NotSupportedException();
@@ -603,6 +860,11 @@ public sealed class RendezvousCoordinatorBehaviorTests
             _called.SetResult(true);
             return RendezvousClientResult.Success(await _result.Task.WaitAsync(cancellationToken));
         }
+
+        public Task<RendezvousClientResult<ReportConnectionOutcomeResponse>> ReportOutcomeAsync(
+            CreateJoinAttemptResponse attempt,
+            RendezvousConnectionOutcome outcome,
+            CancellationToken cancellationToken = default) => throw new NotSupportedException();
     }
 
     private sealed class ManualCoordinatorClock(DateTimeOffset now) :
@@ -610,7 +872,14 @@ public sealed class RendezvousCoordinatorBehaviorTests
         IConnectionTicketClock
     {
         public DateTimeOffset UtcNow { get; private set; } = now;
+        public TimeSpan Elapsed { get; private set; }
 
-        internal void Advance(TimeSpan amount) => UtcNow += amount;
+        internal void Advance(TimeSpan amount)
+        {
+            UtcNow += amount;
+            Elapsed += amount;
+        }
+
+        internal void AdjustWallClock(TimeSpan amount) => UtcNow += amount;
     }
 }

tests/FinalFactory.Rendezvous.Tests/Client/RendezvousCoordinatorIntegrationTests.cs

@@ -242,6 +242,11 @@ public sealed class RendezvousCoordinatorIntegrationTests
 
     private sealed class FakeJoinClient(IReadOnlyList<HostJoinAttempt> attempts) : IRendezvousJoinClient
     {
+        public Task<RendezvousConnectionStartResult> CreateConnectionAttemptAsync(
+            CreateJoinAttemptRequest request,
+            NetworkEndpoint? dedicatedFallback = null,
+            CancellationToken cancellationToken = default) => throw new NotSupportedException();
+
         public Task<RendezvousClientResult<CreateJoinAttemptResponse>> CreateAsync(
             CreateJoinAttemptRequest request,
             CancellationToken cancellationToken = default) => throw new NotSupportedException();
@@ -261,6 +266,11 @@ public sealed class RendezvousCoordinatorIntegrationTests
             int maximumPages = 100,
             CancellationToken cancellationToken = default) => Task.FromResult(
                 RendezvousClientResult.Success(attempts));
+
+        public Task<RendezvousClientResult<ReportConnectionOutcomeResponse>> ReportOutcomeAsync(
+            CreateJoinAttemptResponse attempt,
+            RendezvousConnectionOutcome outcome,
+            CancellationToken cancellationToken = default) => throw new NotSupportedException();
     }
 
     private sealed class FixedCoordinatorClock(DateTimeOffset now) :
@@ -268,5 +278,6 @@ public sealed class RendezvousCoordinatorIntegrationTests
         IConnectionTicketClock
     {
         public DateTimeOffset UtcNow { get; } = now;
+        public TimeSpan Elapsed => TimeSpan.Zero;
     }
 }

tests/FinalFactory.Rendezvous.Tests/Client/RendezvousJoinClientTests.cs

@@ -83,6 +83,110 @@ public sealed class RendezvousJoinClientTests
         Assert.Contains("cursor=next%20page%2Bcursor", handler.Requests[1].Uri.Query, StringComparison.Ordinal);
     }
 
+    [Fact]
+    public async Task OutcomeReportingUsesTheAttemptCapabilityAndCoarseElapsedBucket()
+    {
+        CreateJoinAttemptResponse attempt = CreateAttempt();
+        RecordingHandler handler = new(JsonResponse(HttpStatusCode.OK, new ReportConnectionOutcomeResponse
+        {
+            Accepted = true,
+            IsDuplicate = false,
+        }));
+        using HttpClient http = new(handler) { BaseAddress = new("http://rendezvous.test/") };
+        RendezvousJoinClient client = new(http);
+        RendezvousConnectionOutcome outcome = RendezvousConnectionOutcome.Create(
+            ConnectionOutcomeKind.DirectConnectTimedOut,
+            RendezvousConnectionOutcomeSource.LocalTraversal,
+            RendezvousConnectionFailureCategory.DirectConnection,
+            RendezvousConnectionPhase.DirectConnection,
+            TimeSpan.FromSeconds(6));
+
+        RendezvousClientResult<ReportConnectionOutcomeResponse> result =
+            await client.ReportOutcomeAsync(attempt, outcome);
+
+        Assert.True(result.IsSuccess, result.Message);
+        RecordedRequest request = Assert.Single(handler.Requests);
+        Assert.Equal(HttpMethod.Post, request.Method);
+        Assert.Equal(
+            attempt.ClientPunchCapability,
+            request.Headers["X-Rendezvous-Client-Punch-Capability"]);
+        Assert.Contains("\"outcome\":\"directConnectTimedOut\"", request.Body, StringComparison.Ordinal);
+        Assert.Contains("\"elapsedBucket\":\"fiveToFifteenSeconds\"", request.Body, StringComparison.Ordinal);
+        Assert.DoesNotContain("diagnostic", request.Body, StringComparison.OrdinalIgnoreCase);
+    }
+
+    [Fact]
+    public async Task ConnectionStartReturnsATypedServiceOutcomeInsteadOfAnUnboundedFailure()
+    {
+        RecordingHandler handler = new(JsonResponse(HttpStatusCode.NotFound, new ApiError
+        {
+            Code = RendezvousErrorCode.NotFound,
+            Message = "listing unavailable",
+        }));
+        using HttpClient http = new(handler) { BaseAddress = new("http://rendezvous.test/") };
+        RendezvousJoinClient client = new(http);
+        NetworkEndpoint fallback = new()
+        {
+            AddressFamily = AddressFamilyKind.Ipv4,
+            Address = "203.0.113.93",
+            Port = 9_063,
+        };
+
+        RendezvousConnectionStartResult result = await client.CreateConnectionAttemptAsync(
+            new CreateJoinAttemptRequest
+            {
+                IdempotencyKey = "typed-start",
+                GameId = new("space-game"),
+                EnvironmentId = new("production"),
+                ListingId = new(Guid.Parse("00000000-0000-0000-0000-000000000230")),
+                ProtocolVersion = 7,
+            },
+            fallback);
+
+        Assert.True(result.IsCompleted);
+        Assert.False(result.IsReadyForTraversal);
+        Assert.Null(result.Attempt);
+        Assert.Equal(ConnectionOutcomeKind.DirectoryNotFound, result.Outcome!.Kind);
+        Assert.Equal("203.0.113.93", result.Outcome.DedicatedFallback!.Address);
+    }
+
+    [Fact]
+    public async Task ConnectionStartReturnsCancelledForAPrecancelledCallerToken()
+    {
+        RecordingHandler handler = new();
+        using HttpClient http = new(handler) { BaseAddress = new("http://rendezvous.test/") };
+        RendezvousJoinClient client = new(http);
+        using CancellationTokenSource cancellation = new();
+        cancellation.Cancel();
+
+        RendezvousConnectionStartResult result = await client.CreateConnectionAttemptAsync(
+            CreateRequest("cancelled-before-send"),
+            cancellationToken: cancellation.Token);
+
+        Assert.Empty(handler.Requests);
+        Assert.Equal(ConnectionOutcomeKind.Cancelled, result.Outcome!.Kind);
+        Assert.Equal(RendezvousConnectionOutcomeSource.Caller, result.Outcome.Source);
+    }
+
+    [Fact]
+    public async Task ConnectionStartReturnsCancelledWhenCallerStopsASilentRequest()
+    {
+        CancellingHandler handler = new();
+        using HttpClient http = new(handler) { BaseAddress = new("http://rendezvous.test/") };
+        RendezvousJoinClient client = new(http);
+        using CancellationTokenSource cancellation = new();
+        Task<RendezvousConnectionStartResult> pending = client.CreateConnectionAttemptAsync(
+            CreateRequest("cancelled-in-flight"),
+            cancellationToken: cancellation.Token);
+        await handler.Started.Task.WaitAsync(TimeSpan.FromSeconds(2));
+
+        await cancellation.CancelAsync();
+        RendezvousConnectionStartResult result = await pending;
+
+        Assert.Equal(ConnectionOutcomeKind.Cancelled, result.Outcome!.Kind);
+        Assert.Equal(RendezvousConnectionOutcomeSource.Caller, result.Outcome.Source);
+    }
+
     private static CreateJoinAttemptResponse CreateAttempt() => new()
     {
         AttemptId = new(Guid.Parse("00000000-0000-0000-0000-000000000202")),
@@ -95,6 +199,15 @@ public sealed class RendezvousJoinClientTests
         ExpiresAt = new DateTimeOffset(2030, 1, 1, 0, 0, 30, TimeSpan.Zero),
     };
 
+    private static CreateJoinAttemptRequest CreateRequest(string idempotencyKey) => new()
+    {
+        IdempotencyKey = idempotencyKey,
+        GameId = new("space-game"),
+        EnvironmentId = new("production"),
+        ListingId = new(Guid.Parse("00000000-0000-0000-0000-000000000230")),
+        ProtocolVersion = 7,
+    };
+
     private static HostJoinAttempt CreateHostAttempt(string id) => new()
     {
         AttemptId = new(Guid.Parse(id)),
@@ -137,6 +250,22 @@ public sealed class RendezvousJoinClientTests
         }
     }
 
+    private sealed class CancellingHandler : HttpMessageHandler
+    {
+        internal TaskCompletionSource Started { get; } = new(
+            TaskCreationOptions.RunContinuationsAsynchronously);
+
+        protected override async Task<HttpResponseMessage> SendAsync(
+            HttpRequestMessage request,
+            CancellationToken cancellationToken)
+        {
+            _ = request;
+            Started.TrySetResult();
+            await Task.Delay(Timeout.InfiniteTimeSpan, cancellationToken);
+            throw new InvalidOperationException("The silent request unexpectedly completed.");
+        }
+    }
+
     private sealed record RecordedRequest(
         HttpMethod Method,
         Uri Uri,