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

2026-07-16 10:18:41 +02:00
parent b4b6072fe1
commit 94aba8a3bb
47 changed files with 2727 additions and 178 deletions
@@ -1,4 +1,5 @@
 using System.Net;
+using System.Net.Sockets;
 using FinalFactory.Rendezvous.Contracts;
 using LiteNetLib;

@@ -11,14 +12,37 @@ public enum RendezvousHostState
    Disposed = 3,
 }

-public sealed class RendezvousHostAttemptCompletedEventArgs(
-    JoinAttemptId attemptId,
-    RendezvousConnectionState state,
-    NetPeer? peer = null) : EventArgs
+public sealed class RendezvousHostAttemptCompletedEventArgs : EventArgs
 {
-    public JoinAttemptId AttemptId { get; } = attemptId;
-    public RendezvousConnectionState State { get; } = state;
-    public NetPeer? Peer { get; } = peer;
+    [Obsolete("Completion events now expose a typed Outcome. Construct these arguments only for legacy test doubles.")]
+    public RendezvousHostAttemptCompletedEventArgs(
+        JoinAttemptId attemptId,
+        RendezvousConnectionState state,
+        NetPeer? peer)
+        : this(attemptId, state, RendezvousCompletionInvariant.FromLegacy(state, peer))
+    {
+    }
+
+    internal RendezvousHostAttemptCompletedEventArgs(
+        JoinAttemptId attemptId,
+        RendezvousConnectionState state,
+        RendezvousConnectionOutcome outcome)
+    {
+        if (attemptId.Value == Guid.Empty)
+        {
+            throw new ArgumentException("The completed attempt ID is invalid.", nameof(attemptId));
+        }
+
+        RendezvousCompletionInvariant.Validate(state, outcome);
+        AttemptId = attemptId;
+        State = state;
+        Outcome = outcome;
+    }
+
+    public JoinAttemptId AttemptId { get; }
+    public RendezvousConnectionState State { get; }
+    public RendezvousConnectionOutcome Outcome { get; }
+    public NetPeer? Peer => Outcome.Peer;
 }

 public sealed class RendezvousHostCoordinator : IDisposable
@@ -37,6 +61,7 @@ public sealed class RendezvousHostCoordinator : IDisposable
    private readonly Dictionary<JoinAttemptId, DeferredConnectionRequest> _deferredRequests = [];
    private readonly Dictionary<JoinAttemptId, DateTimeOffset> _terminalAttempts = [];
    private readonly Queue<JoinAttemptId> _attemptSchedule = [];
+    private readonly SortedDictionary<long, Queue<HostAttemptDeadline>> _deadlines = [];
    private readonly List<JoinAttemptId> _cleanupScratch = [];
    private HostJoinAttempt[]? _latestSnapshot;
    private DateTimeOffset _nextPresenceAt = DateTimeOffset.MinValue;
@@ -90,6 +115,7 @@ public sealed class RendezvousHostCoordinator : IDisposable
        _networkEvents.RendezvousConnectionRequest += OnConnectionRequest;
        _networkEvents.RendezvousPeerConnected += OnPeerConnected;
        _networkEvents.RendezvousPeerDisconnected += OnPeerDisconnected;
+        _networkEvents.RendezvousNetworkError += OnNetworkError;
        _punchEvents.NatIntroductionSuccess += OnNatIntroductionSuccess;
    }

@@ -161,7 +187,10 @@ public sealed class RendezvousHostCoordinator : IDisposable
            ApplySnapshots();
            if (!_manager.IsRunning)
            {
-                Stop(RendezvousHostState.ManagerStopped, RendezvousConnectionState.ManagerStopped);
+                Stop(
+                    RendezvousHostState.ManagerStopped,
+                    RendezvousConnectionState.ManagerStopped,
+                    ConnectionOutcomeKind.ManagerStopped);
                return;
            }

@@ -174,13 +203,23 @@ public sealed class RendezvousHostCoordinator : IDisposable
            }

            DateTimeOffset now = _clock.UtcNow;
+            TimeSpan elapsed = _clock.Elapsed;
            if (!_manager.IsRunning)
            {
-                Stop(RendezvousHostState.ManagerStopped, RendezvousConnectionState.ManagerStopped);
+                Stop(
+                    RendezvousHostState.ManagerStopped,
+                    RendezvousConnectionState.ManagerStopped,
+                    ConnectionOutcomeKind.ManagerStopped);
                return;
            }

            RefreshPresence(now);
+            ProcessDueDeadlines(elapsed);
+            if (State != RendezvousHostState.Active)
+            {
+                return;
+            }
+
            int checks = Math.Min(
                _attemptSchedule.Count,
                _options.MaximumAttemptChecksPerPoll);
@@ -192,18 +231,22 @@ public sealed class RendezvousHostCoordinator : IDisposable
                    continue;
                }

-                if (now >= attempt.Invitation.ExpiresAt)
+                if (attempt.State != RendezvousConnectionState.Punching)
                {
-                    CompleteAttempt(attemptId, RendezvousConnectionState.TimedOut);
                    continue;
                }

-                if (attempt.State == RendezvousConnectionState.Punching
-                    && attempt.Retry.IsDue(now))
+                if (attempt.Retry.IsDue(elapsed))
                {
                    if (attempt.Retry.IsExhausted)
                    {
-                        CompleteAttempt(attemptId, RendezvousConnectionState.TimedOut);
+                        CompleteAttempt(
+                            attemptId,
+                            RendezvousConnectionState.TimedOut,
+                            ConnectionOutcomeKind.PunchTimedOut,
+                            RendezvousConnectionOutcomeSource.LocalTraversal,
+                            RendezvousConnectionFailureCategory.NatTraversal,
+                            RendezvousConnectionPhase.NatTraversal);
                        continue;
                    }

@@ -251,9 +294,13 @@ public sealed class RendezvousHostCoordinator : IDisposable
            return;
        }

-        Stop(RendezvousHostState.Disposed, RendezvousConnectionState.Disposed);
+        Stop(
+            RendezvousHostState.Disposed,
+            RendezvousConnectionState.Disposed,
+            ConnectionOutcomeKind.Disposed);
        Interlocked.Exchange(ref _latestSnapshot, null);
        _attemptSchedule.Clear();
+        _deadlines.Clear();
        _terminalAttempts.Clear();
        _cleanupScratch.Clear();
        _tickets.Dispose();
@@ -272,6 +319,7 @@ public sealed class RendezvousHostCoordinator : IDisposable
        }

        DateTimeOffset now = _clock.UtcNow;
+        TimeSpan elapsed = _clock.Elapsed;
        foreach (HostJoinAttempt invitation in latest)
        {
            if (invitation.AttemptId.Value == Guid.Empty
@@ -289,7 +337,11 @@ public sealed class RendezvousHostCoordinator : IDisposable
                {
                    CompleteAttempt(
                        invitation.AttemptId,
-                        RendezvousConnectionState.Cancelled);
+                        RendezvousConnectionState.Cancelled,
+                        ConnectionOutcomeKind.Cancelled,
+                        RendezvousConnectionOutcomeSource.RendezvousService,
+                        RendezvousConnectionFailureCategory.Lifecycle,
+                        RendezvousConnectionPhase.Authorization);
                }

                _terminalAttempts[invitation.AttemptId] = invitation.ExpiresAt;
@@ -303,11 +355,23 @@ public sealed class RendezvousHostCoordinator : IDisposable
                continue;
            }

+            TimeSpan attemptDeadline = elapsed + (invitation.ExpiresAt - now);
+            TimeSpan punchDeadline = Min(
+                attemptDeadline,
+                elapsed + _options.PunchTimeout);
            _attempts.Add(
                invitation.AttemptId,
                new PendingHostAttempt(
                    CopyAttempt(invitation),
-                    new RendezvousPunchRetrySchedule(_options, _clock)));
+                    new RendezvousPunchRetrySchedule(_options, _clock),
+                    elapsed,
+                    attemptDeadline,
+                    punchDeadline));
+            EnqueueDeadline(
+                new HostAttemptDeadline(
+                    invitation.AttemptId,
+                    RendezvousConnectionState.Punching,
+                    punchDeadline));
            _attemptSchedule.Enqueue(invitation.AttemptId);
        }
    }
@@ -354,6 +418,13 @@ public sealed class RendezvousHostCoordinator : IDisposable
        }

        attempt.State = RendezvousConnectionState.Connecting;
+        attempt.DirectDeadline = Min(
+            attempt.AttemptDeadline,
+            _clock.Elapsed + _options.DirectConnectTimeout);
+        EnqueueDeadline(new HostAttemptDeadline(
+            introduction.AttemptId,
+            RendezvousConnectionState.Connecting,
+            attempt.DirectDeadline.Value));
        if (_deferredRequests.Remove(
                introduction.AttemptId,
                out DeferredConnectionRequest? deferred))
@@ -410,7 +481,14 @@ public sealed class RendezvousHostCoordinator : IDisposable
    {
        if (_acceptedPeers.TryGetValue(peer, out JoinAttemptId attemptId))
        {
-            CompleteAttempt(attemptId, RendezvousConnectionState.Connected, peer);
+            CompleteAttempt(
+                attemptId,
+                RendezvousConnectionState.Connected,
+                ConnectionOutcomeKind.Connected,
+                RendezvousConnectionOutcomeSource.LocalTraversal,
+                RendezvousConnectionFailureCategory.None,
+                RendezvousConnectionPhase.Complete,
+                peer);
        }
    }

@@ -419,32 +497,113 @@ public sealed class RendezvousHostCoordinator : IDisposable
        _ = disconnectInfo;
        if (_acceptedPeers.TryGetValue(peer, out JoinAttemptId attemptId))
        {
-            CompleteAttempt(attemptId, RendezvousConnectionState.Rejected);
+            ConnectionOutcomeKind kind = disconnectInfo.Reason == DisconnectReason.Timeout
+                ? ConnectionOutcomeKind.DirectConnectTimedOut
+                : ConnectionOutcomeKind.TransportError;
+            CompleteAttempt(
+                attemptId,
+                kind == ConnectionOutcomeKind.DirectConnectTimedOut
+                    ? RendezvousConnectionState.TimedOut
+                    : RendezvousConnectionState.Rejected,
+                kind,
+                RendezvousConnectionOutcomeSource.LocalTraversal,
+                RendezvousConnectionFailureCategory.DirectConnection,
+                RendezvousConnectionPhase.DirectConnection);
+        }
+    }
+
+    private void OnNetworkError(IPEndPoint endpoint, SocketError socketError)
+    {
+        _ = socketError;
+        if (!endpoint.Equals(_mediator))
+        {
+            return;
+        }
+
+        foreach (JoinAttemptId attemptId in _attempts
+                     .Where(static item => item.Value.State == RendezvousConnectionState.Punching)
+                     .Select(static item => item.Key)
+                     .ToArray())
+        {
+            CompleteAttempt(
+                attemptId,
+                RendezvousConnectionState.Rejected,
+                ConnectionOutcomeKind.MediatorUnavailable,
+                RendezvousConnectionOutcomeSource.LocalTraversal,
+                RendezvousConnectionFailureCategory.Mediation,
+                RendezvousConnectionPhase.Mediation);
        }
    }

    private void CompleteAttempt(
        JoinAttemptId attemptId,
        RendezvousConnectionState state,
+        ConnectionOutcomeKind kind,
+        RendezvousConnectionOutcomeSource source,
+        RendezvousConnectionFailureCategory category,
+        RendezvousConnectionPhase phase,
        NetPeer? peer = null)
    {
+        if (TryCompleteAttempt(
+                attemptId,
+                state,
+                kind,
+                source,
+                category,
+                phase,
+                peer,
+                out RendezvousHostAttemptCompletedEventArgs? completion))
+        {
+            AttemptCompleted?.Invoke(this, completion!);
+        }
+    }
+
+    private bool TryCompleteAttempt(
+        JoinAttemptId attemptId,
+        RendezvousConnectionState state,
+        ConnectionOutcomeKind kind,
+        RendezvousConnectionOutcomeSource source,
+        RendezvousConnectionFailureCategory category,
+        RendezvousConnectionPhase phase,
+        NetPeer? peer,
+        out RendezvousHostAttemptCompletedEventArgs? completion)
+    {
+        completion = null;
        if (!_attempts.Remove(attemptId, out PendingHostAttempt? attempt))
        {
-            return;
+            return false;
        }

        if (attempt.AcceptedPeer is not null)
        {
            _acceptedPeers.Remove(attempt.AcceptedPeer);
+            if (kind != ConnectionOutcomeKind.Connected)
+            {
+                attempt.AcceptedPeer.Disconnect();
+            }
        }

-        _deferredRequests.Remove(attemptId);
+        if (_deferredRequests.Remove(attemptId, out DeferredConnectionRequest? deferred))
+        {
+            deferred.Request.RejectForce([]);
+        }
        _tickets.Revoke(attemptId);
        _terminalAttempts[attemptId] = attempt.Invitation.ExpiresAt;
-        AttemptCompleted?.Invoke(this, new(attemptId, state, peer));
+        RendezvousConnectionOutcome outcome = RendezvousConnectionOutcome.Create(
+            kind,
+            source,
+            category,
+            phase,
+            _clock.Elapsed - attempt.StartedAt,
+            peer: peer);
+        completion = new(attemptId, state, outcome);
+        return true;
    }

-    private void Stop(RendezvousHostState hostState, RendezvousConnectionState attemptState)
+    private void Stop(
+        RendezvousHostState hostState,
+        RendezvousConnectionState attemptState,
+        ConnectionOutcomeKind outcomeKind)
    {
        if (State != RendezvousHostState.Active)
        {
@@ -452,12 +611,32 @@ public sealed class RendezvousHostCoordinator : IDisposable
        }

        State = hostState;
+        List<RendezvousHostAttemptCompletedEventArgs> completions = [];
        foreach (JoinAttemptId attemptId in _attempts.Keys.ToArray())
        {
-            CompleteAttempt(attemptId, attemptState);
+            RendezvousConnectionPhase phase = _attempts[attemptId].State
+                == RendezvousConnectionState.Connecting
+                    ? RendezvousConnectionPhase.DirectConnection
+                    : RendezvousConnectionPhase.NatTraversal;
+            if (TryCompleteAttempt(
+                    attemptId,
+                    attemptState,
+                    outcomeKind,
+                    RendezvousConnectionOutcomeSource.Lifecycle,
+                    RendezvousConnectionFailureCategory.Lifecycle,
+                    phase,
+                    null,
+                    out RendezvousHostAttemptCompletedEventArgs? completion))
+            {
+                completions.Add(completion!);
+            }
        }

        ReleaseSubscriptions();
+        foreach (RendezvousHostAttemptCompletedEventArgs completion in completions)
+        {
+            AttemptCompleted?.Invoke(this, completion);
+        }
    }

    private void ReleaseSubscriptions()
@@ -470,6 +649,7 @@ public sealed class RendezvousHostCoordinator : IDisposable
        _networkEvents.RendezvousConnectionRequest -= OnConnectionRequest;
        _networkEvents.RendezvousPeerConnected -= OnPeerConnected;
        _networkEvents.RendezvousPeerDisconnected -= OnPeerDisconnected;
+        _networkEvents.RendezvousNetworkError -= OnNetworkError;
        _punchEvents.NatIntroductionSuccess -= OnNatIntroductionSuccess;
        _subscriptionsReleased = true;
    }
@@ -496,9 +676,78 @@ public sealed class RendezvousHostCoordinator : IDisposable
        ExpiresAt = attempt.ExpiresAt,
    };

+    private static TimeSpan Min(TimeSpan left, TimeSpan right) =>
+        left <= right ? left : right;
+
    private static DateTimeOffset Min(DateTimeOffset left, DateTimeOffset right) =>
        left <= right ? left : right;

+    private void EnqueueDeadline(HostAttemptDeadline deadline)
+    {
+        if (!_deadlines.TryGetValue(deadline.Deadline.Ticks, out Queue<HostAttemptDeadline>? bucket))
+        {
+            bucket = new Queue<HostAttemptDeadline>();
+            _deadlines.Add(deadline.Deadline.Ticks, bucket);
+        }
+
+        bucket.Enqueue(deadline);
+    }
+
+    private void ProcessDueDeadlines(TimeSpan elapsed)
+    {
+        while (_deadlines.Count > 0)
+        {
+            KeyValuePair<long, Queue<HostAttemptDeadline>> first = _deadlines.First();
+            if (first.Key > elapsed.Ticks)
+            {
+                return;
+            }
+
+            HostAttemptDeadline deadline = first.Value.Dequeue();
+            if (first.Value.Count == 0)
+            {
+                _deadlines.Remove(first.Key);
+            }
+
+            if (!_attempts.TryGetValue(deadline.AttemptId, out PendingHostAttempt? attempt)
+                || attempt.State != deadline.ExpectedState
+                || (deadline.ExpectedState == RendezvousConnectionState.Punching
+                    ? attempt.PunchDeadline
+                    : attempt.DirectDeadline) != deadline.Deadline)
+            {
+                continue;
+            }
+
+            bool expired = elapsed >= attempt.AttemptDeadline;
+            CompleteAttempt(
+                deadline.AttemptId,
+                RendezvousConnectionState.TimedOut,
+                expired
+                    ? ConnectionOutcomeKind.AttemptExpired
+                    : deadline.ExpectedState == RendezvousConnectionState.Punching
+                        ? ConnectionOutcomeKind.PunchTimedOut
+                        : ConnectionOutcomeKind.DirectConnectTimedOut,
+                expired
+                    ? RendezvousConnectionOutcomeSource.RendezvousService
+                    : RendezvousConnectionOutcomeSource.LocalTraversal,
+                expired
+                    ? RendezvousConnectionFailureCategory.Authorization
+                    : deadline.ExpectedState == RendezvousConnectionState.Punching
+                        ? RendezvousConnectionFailureCategory.NatTraversal
+                        : RendezvousConnectionFailureCategory.DirectConnection,
+                expired
+                    ? RendezvousConnectionPhase.Authorization
+                    : deadline.ExpectedState == RendezvousConnectionState.Punching
+                        ? RendezvousConnectionPhase.NatTraversal
+                        : RendezvousConnectionPhase.DirectConnection);
+
+            if (State != RendezvousHostState.Active)
+            {
+                return;
+            }
+        }
+    }
+
    private void AcceptAuthorizedRequest(
        JoinAttemptId attemptId,
        PendingHostAttempt attempt,
@@ -529,14 +778,31 @@ public sealed class RendezvousHostCoordinator : IDisposable

    private sealed class PendingHostAttempt(
        HostJoinAttempt invitation,
-        RendezvousPunchRetrySchedule retry)
+        RendezvousPunchRetrySchedule retry,
+        TimeSpan startedAt,
+        TimeSpan attemptDeadline,
+        TimeSpan punchDeadline)
    {
        internal HostJoinAttempt Invitation { get; } = invitation;
        internal RendezvousPunchRetrySchedule Retry { get; } = retry;
+        internal TimeSpan StartedAt { get; } = startedAt;
+        internal TimeSpan AttemptDeadline { get; } = attemptDeadline;
+        internal TimeSpan PunchDeadline { get; } = punchDeadline;
+        internal TimeSpan? DirectDeadline { get; set; }
        internal RendezvousConnectionState State { get; set; } = RendezvousConnectionState.Punching;
        internal NetPeer? AcceptedPeer { get; set; }
    }

+    private sealed class HostAttemptDeadline(
+        JoinAttemptId attemptId,
+        RendezvousConnectionState expectedState,
+        TimeSpan deadline)
+    {
+        internal JoinAttemptId AttemptId { get; } = attemptId;
+        internal RendezvousConnectionState ExpectedState { get; } = expectedState;
+        internal TimeSpan Deadline { get; } = deadline;
+    }
+
    private sealed class DeferredConnectionRequest(
        ConnectionRequest request,
        string connectionTicket)