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

src/FinalFactory.Rendezvous.Client/JoinAttempts/RendezvousJoinClient.cs

@@ -1,3 +1,4 @@
+using System.Diagnostics;
 using FinalFactory.Rendezvous.Contracts;
 
 namespace FinalFactory.Rendezvous.Client;
@@ -39,6 +40,45 @@ public sealed class RendezvousJoinClient : IRendezvousJoinClient
             cancellationToken);
     }
 
+    public async Task<RendezvousConnectionStartResult> CreateConnectionAttemptAsync(
+        CreateJoinAttemptRequest request,
+        NetworkEndpoint? dedicatedFallback = null,
+        CancellationToken cancellationToken = default)
+    {
+        if (dedicatedFallback is not null
+            && !ContractValidation.IsNetworkEndpointValid(dedicatedFallback))
+        {
+            throw new ArgumentException("The dedicated fallback endpoint is invalid.", nameof(dedicatedFallback));
+        }
+
+        Stopwatch elapsed = Stopwatch.StartNew();
+        try
+        {
+            RendezvousClientResult<CreateJoinAttemptResponse> result = await CreateAsync(
+                request,
+                cancellationToken).ConfigureAwait(false);
+            elapsed.Stop();
+            return result.IsSuccess && result.Value is not null
+                ? RendezvousConnectionStartResult.ReadyForTraversal(result.Value)
+                : RendezvousConnectionStartResult.Completed(
+                    RendezvousConnectionOutcome.FromServiceError(
+                        result.Error,
+                        elapsed.Elapsed,
+                        dedicatedFallback));
+        }
+        catch (OperationCanceledException) when (cancellationToken.IsCancellationRequested)
+        {
+            elapsed.Stop();
+            return RendezvousConnectionStartResult.Completed(
+                RendezvousConnectionOutcome.Create(
+                    ConnectionOutcomeKind.Cancelled,
+                    RendezvousConnectionOutcomeSource.Caller,
+                    RendezvousConnectionFailureCategory.Lifecycle,
+                    RendezvousConnectionPhase.Authorization,
+                    elapsed.Elapsed));
+        }
+    }
+
     public Task<RendezvousClientResult<bool>> CancelAsync(
         CreateJoinAttemptResponse attempt,
         CancellationToken cancellationToken = default)
@@ -130,6 +170,41 @@ public sealed class RendezvousJoinClient : IRendezvousJoinClient
             $"Host invitation polling exceeded the configured {maximumPages}-page limit.");
     }
 
+    public Task<RendezvousClientResult<ReportConnectionOutcomeResponse>> ReportOutcomeAsync(
+        CreateJoinAttemptResponse attempt,
+        RendezvousConnectionOutcome outcome,
+        CancellationToken cancellationToken = default)
+    {
+        if (attempt is null)
+        {
+            throw new ArgumentNullException(nameof(attempt));
+        }
+        if (outcome is null)
+        {
+            throw new ArgumentNullException(nameof(outcome));
+        }
+        if (!ContractValidation.IsReportableConnectionOutcome(outcome.Kind))
+        {
+            throw new ArgumentException(
+                "This outcome cannot be reported for an issued join attempt.",
+                nameof(outcome));
+        }
+
+        ReportConnectionOutcomeRequest body = new()
+        {
+            Outcome = outcome.Kind,
+            ElapsedBucket = RendezvousConnectionOutcome.BucketElapsed(outcome.Elapsed),
+        };
+        return _transport.SendSafeAsync<ReportConnectionOutcomeResponse>(
+            () => HeaderJsonRequest(
+                HttpMethod.Post,
+                $"v1/join-attempts/{attempt.AttemptId}/outcome",
+                ClientPunchCapabilityHeader,
+                RequireHeaderValue(attempt.ClientPunchCapability, nameof(attempt)),
+                body),
+            cancellationToken);
+    }
+
     private static HttpRequestMessage HeaderRequest(
         HttpMethod method,
         string uri,
@@ -141,6 +216,18 @@ public sealed class RendezvousJoinClient : IRendezvousJoinClient
         return request;
     }
 
+    private static HttpRequestMessage HeaderJsonRequest<T>(
+        HttpMethod method,
+        string uri,
+        string header,
+        string value,
+        T body)
+    {
+        HttpRequestMessage request = RendezvousHttpTransport.JsonRequest(method, uri, body);
+        request.Headers.TryAddWithoutValidation(header, value);
+        return request;
+    }
+
     private static string RequireHeaderValue(string value, string parameterName) =>
         !string.IsNullOrWhiteSpace(value)
             ? value