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
@@ -776,6 +776,16 @@
              }
            }
          },
+          "410": {
+            "description": "Gone",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/ApiError"
+                }
+              }
+            }
+          },
          "429": {
            "description": "Too Many Requests",
            "content": {
@@ -857,7 +867,12 @@
              }
            }
          }
-        }
+        },
+        "security": [
+          {
+            "JoinAttemptCapability": [ ]
+          }
+        ]
      }
    },
    "/v1/join-attempts/{attemptId}/outcome": {
@@ -874,6 +889,14 @@
            "schema": {
              "type": "string"
            }
+          },
+          {
+            "name": "X-Rendezvous-Client-Punch-Capability",
+            "in": "header",
+            "required": true,
+            "schema": {
+              "type": "string"
+            }
          }
        ],
        "requestBody": {
@@ -897,8 +920,38 @@
              }
            }
          },
-          "501": {
-            "description": "Not Implemented",
+          "400": {
+            "description": "Bad Request",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/ApiError"
+                }
+              }
+            }
+          },
+          "404": {
+            "description": "Not Found",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/ApiError"
+                }
+              }
+            }
+          },
+          "409": {
+            "description": "Conflict",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/ApiError"
+                }
+              }
+            }
+          },
+          "503": {
+            "description": "Service Unavailable",
            "content": {
              "application/json": {
                "schema": {
@@ -907,7 +960,12 @@
              }
            }
          }
-        }
+        },
+        "security": [
+          {
+            "JoinAttemptCapability": [ ]
+          }
+        ]
      }
    }
  },
@@ -1002,6 +1060,15 @@
          }
        }
      },
+      "ConnectionElapsedBucket": {
+        "enum": [
+          "underOneSecond",
+          "oneToFiveSeconds",
+          "fiveToFifteenSeconds",
+          "fifteenToThirtySeconds",
+          "thirtySecondsOrMore"
+        ]
+      },
      "ConnectionOutcomeKind": {
        "enum": [
          "connected",
@@ -1012,7 +1079,19 @@
          "serviceRejected",
          "hostRejected",
          "transportFailed",
-          "fallbackOffered"
+          "fallbackOffered",
+          "directoryNotFound",
+          "attemptExpired",
+          "unauthorized",
+          "rateLimited",
+          "noHostPresence",
+          "serviceUnavailable",
+          "mediatorUnavailable",
+          "punchTimedOut",
+          "directConnectTimedOut",
+          "transportError",
+          "managerStopped",
+          "disposed"
        ]
      },
      "CreateJoinAttemptRequest": {
@@ -1278,6 +1357,16 @@
            "additionalProperties": {
              "type": "string"
            }
+          },
+          "dedicatedFallback": {
+            "oneOf": [
+              {
+                "type": "null"
+              },
+              {
+                "$ref": "#/components/schemas/NetworkEndpoint"
+              }
+            ]
          }
        }
      },
@@ -1388,8 +1477,7 @@
      "ReportConnectionOutcomeRequest": {
        "required": [
          "contractVersion",
-          "outcome",
-          "elapsedMilliseconds"
+          "outcome"
        ],
        "type": "object",
        "properties": {
@@ -1400,6 +1488,9 @@
          "outcome": {
            "$ref": "#/components/schemas/ConnectionOutcomeKind"
          },
+          "elapsedBucket": {
+            "$ref": "#/components/schemas/ConnectionElapsedBucket"
+          },
          "elapsedMilliseconds": {
            "type": "integer",
            "format": "int32"
@@ -1415,7 +1506,8 @@
      "ReportConnectionOutcomeResponse": {
        "required": [
          "contractVersion",
-          "accepted"
+          "accepted",
+          "isDuplicate"
        ],
        "type": "object",
        "properties": {
@@ -1425,6 +1517,9 @@
          },
          "accepted": {
            "type": "boolean"
+          },
+          "isDuplicate": {
+            "type": "boolean"
          }
        }
      },
@@ -1502,6 +1597,16 @@
            "additionalProperties": {
              "type": "string"
            }
+          },
+          "dedicatedFallback": {
+            "oneOf": [
+              {
+                "type": "null"
+              },
+              {
+                "$ref": "#/components/schemas/NetworkEndpoint"
+              }
+            ]
          }
        }
      },
@@ -1541,6 +1646,16 @@
            "additionalProperties": {
              "type": "string"
            }
+          },
+          "dedicatedFallback": {
+            "oneOf": [
+              {
+                "type": "null"
+              },
+              {
+                "$ref": "#/components/schemas/NetworkEndpoint"
+              }
+            ]
          }
        }
      }
@@ -1551,6 +1666,12 @@
        "description": "Tenant-scoped publisher credential issued during game provisioning.",
        "scheme": "bearer",
        "bearerFormat": "rv1 publisher credential"
+      },
+      "JoinAttemptCapability": {
+        "type": "apiKey",
+        "description": "Attempt-scoped client capability returned only to the joining caller.",
+        "name": "X-Rendezvous-Client-Punch-Capability",
+        "in": "header"
      }
    }
  },
@@ -0,0 +1,117 @@
+# ADR 0010: typed connection outcomes, deadlines, and caller-owned fallback
+
+- Status: Accepted
+- Date: 2026-07-16
+- Tracking: #13
+
+## Context
+
+A connection can stop in the directory, authorization, mediation, NAT traversal,
+or direct-connection phase. Those failures have different authorities: an HTTP
+response can authoritatively reject a join, the SDK can observe a local timeout,
+and only the remote host can reject a direct connection. Treating all of them as
+one message or generic timeout would make player guidance, retry policy, tests,
+and operational measurements unreliable.
+
+UDP loss, service silence, cancellation, and late LiteNetLib callbacks also make
+completion races unavoidable. Games need one terminal result and bounded work,
+not a sequence of contradictory callbacks. Direct traversal cannot be guaranteed,
+but v1 has no gameplay relay and must not imply otherwise.
+
+## Decision
+
+### Closed typed outcome model
+
+`ConnectionOutcomeKind` is the stable wire-level terminal set: connected,
+cancelled, directory not found, attempt expired, incompatible protocol,
+unauthorized, rate limited, no host presence, service unavailable or rejected,
+mediator unavailable, punch timeout, direct-connect timeout, host rejection,
+transport error, manager stopped, and disposed.
+
+The already-frozen v1 members `TimedOut`, `StaleHost`, `TransportFailed`, and
+`FallbackOffered` retain their original numeric values for source and wire
+compatibility. New SDK code never emits them. The report service accepts them,
+normalizes the first three to their precise modern equivalents, and does not let
+legacy compatibility weaken the typed coordinator result.
+
+The client adds `RendezvousConnectionOutcomeSource`, failure category, and phase.
+These fields preserve authority instead of guessing from text:
+
+- `RendezvousService` is used only for an HTTP decision or bounded service
+  silence. Its optional `ServiceError` retains the stable service error code.
+- `LocalTraversal` reports local punch, direct-connect, and transport
+  observations.
+- `RemoteHost` reports an explicit direct-connection rejection.
+- `Caller` and `Lifecycle` distinguish cancellation from manager shutdown or
+  disposal.
+
+Messages remain diagnostic and are never parsed into outcomes. A successful NAT
+introduction is only a transition to direct connection; `Connected` is emitted
+only after LiteNetLib reports the authenticated peer connected.
+
+Join issuance is exposed as `RendezvousConnectionStartResult`, containing exactly
+one issued attempt or one terminal service outcome. Once an attempt is issued,
+the coordinator owns its local terminal outcome. Completion is exactly once;
+terminal paths release SDK subscriptions so late introductions, peer callbacks,
+network errors, cancellation, and polling are inert.
+
+### Bounded phases and retries
+
+Each HTTP try has a five-second default silence budget, configurable from above
+zero through thirty seconds. Only safe operations use the existing bounded retry
+policy, honoring caller cancellation and server retry guidance. Exhausting that
+budget returns `ServiceUnavailable`; it never waits indefinitely.
+
+Traversal has independent defaults: ten seconds for punch/mediation and five
+seconds for the direct connection. Both are configurable up to thirty seconds.
+Local budgets, retry schedules, and elapsed duration use monotonic time, so a
+wall-clock correction cannot extend them or produce a negative duration. The
+signed attempt expiry is converted to an additional monotonic upper bound when
+the attempt is received. Punch retries retain
+their bounded request count and exponential backoff; crossing a phase deadline
+completes exactly once even if a delayed packet later arrives. Tests use an
+injected clock and do not depend on wall-clock sleeps.
+
+### Explicit dedicated fallback handoff
+
+A publisher may attach one validated dedicated endpoint to registration or
+update only when the tenant's provisioned fallback policy allows it. The server
+copies that endpoint into browser and issued-attempt contracts.
+The client coordinator defensively copies it into every terminal outcome; a game
+may override it locally through `DedicatedFallbackOverride`.
+
+The SDK never opens, dials, reserves, probes, or authenticates the fallback. The
+game decides whether the outcome permits fallback, presents any player choice,
+and connects through its own gameplay transport and admission rules. Absence of
+an endpoint is an honest no-fallback result. Gameplay relay is absent from v1.
+
+### Privacy-safe optional reporting
+
+After an issued attempt completes, the game may explicitly report its outcome
+with the short-lived client punch capability. Reporting is authenticated and
+idempotent: an exact repeat succeeds as a duplicate, while a conflicting repeat
+is rejected. Reports contain only an allowlisted outcome enum and one coarse
+elapsed bucket (`<1s`, `1–5s`, `5–15s`, `15–30s`, or `30s+`). They contain no
+diagnostic message, exact duration, endpoint, metadata, player identifier, or
+credential.
+
+Frozen v1 DTOs still expose `elapsedMilliseconds` and `diagnosticCode`. They are
+deprecated compatibility inputs: the current SDK omits them, the service
+immediately buckets legacy elapsed time, and neither exact timing nor diagnostic
+text is retained, logged, or used as a metric dimension.
+
+The store retains a bounded capability-fingerprint tombstone long enough to
+accept a report after the live attempt expires. Metrics count the first accepted
+outcome only and use only outcome plus elapsed bucket as dimensions. Service
+issuance failures cannot be reported because no attempt capability was issued.
+
+## Consequences
+
+- Player-facing UI can map stable outcome/category pairs to localized guidance
+  without exposing diagnostic strings.
+- Service rejection, remote-host rejection, and local observation remain
+  distinguishable for retry and support decisions.
+- Games own fallback policy and gameplay admission; Rendezvous does not claim a
+  guaranteed connection path.
+- Outcome additions are contract changes and require OpenAPI, serialization,
+  public API, fake-clock, late-event, and idempotency coverage.
@@ -12,6 +12,7 @@ decision requires a superseding ADR and corresponding contract/test updates.
 - [ADR 0007: caller-owned .NET publisher and browser SDK](0007-caller-owned-dotnet-client-sdk.md)
 - [ADR 0008: scoped join attempts and one-time connection tickets](0008-scoped-join-attempts-and-tickets.md)
 - [ADR 0009: authenticated bounded LiteNetLib NAT mediator](0009-authenticated-litenet-nat-mediator.md)
+- [ADR 0010: typed connection outcomes, deadlines, and caller-owned fallback](0010-typed-connection-outcomes-and-fallback.md)
 - [Threat model](../security/threat-model.md)
 - [Security promise and test matrix](../security/control-matrix.md)
 - [Versioned HTTP and UDP contracts](../contracts/README.md)
@@ -40,9 +40,7 @@ the same value as a required query parameter.
 | `GET` | `/health/ready` | Report whether the UDP mediator is bound and ready. |

 The generated [OpenAPI document](../api/rendezvous-v1.json) is the normative
-shape reference for parameters, bodies, and responses. Contract-only endpoints
-return `501` until their behavior is implemented by the subsequent directory,
-lease, and join-orchestration issues.
+shape reference for parameters, bodies, and responses.

 Host polling sends its reusable lease credential in
 `X-Rendezvous-Lease-Token`; it must never be placed in a URL. Lease credentials
@@ -55,6 +53,24 @@ Attempt cancellation sends the short-lived client punch capability in
 source only for a process-keyed, short-lived idempotency/abuse scope; this is not
 player authentication and is never returned to callers.

+Outcome reporting uses that same short-lived capability. It accepts only outcomes
+for an issued attempt and carries one stable outcome enum plus one coarse elapsed
+bucket. Exact duplicate reports are idempotent; conflicting repeats fail. Reports
+never carry exact timing, diagnostics, endpoints, metadata, player identifiers,
+or credentials.
+
+The frozen v1 .NET request also retains deprecated `elapsedMilliseconds` and
+`diagnosticCode` properties for source/wire compatibility. Current clients omit
+them. If a legacy client supplies them, the server immediately converts elapsed
+milliseconds to the coarse bucket and discards diagnostic text; neither value is
+retained or used as a metric dimension.
+
+Registration and update may include one validated `dedicatedFallback`. The
+endpoint must be enabled by the tenant's provisioned fallback policy, is visible
+browser data, and is copied into subsequently issued attempts.
+It is a handoff for caller-owned policy: neither the HTTP service nor the SDK
+automatically connects to it. V1 provides no gameplay relay.
+
 ## Idempotency, cursors, and retries

 Registration and join creation require a caller-generated visible-ASCII
@@ -101,9 +117,9 @@ must not be parsed. Secrets and raw credentials are never echoed.
 | 401 | `authenticationRequired` |
 | 403 | `forbidden` |
 | 404 | `notFound` |
-| 409 | `conflict`, `incompatibleProtocol`, `replayRejected`, `capacityExceeded` |
+| 409 | `conflict`, `incompatibleProtocol`, `replayRejected` |
 | 410 | `expired`, `staleHost` |
-| 429 | `rateLimited` (with retry guidance when known) |
+| 429 | `rateLimited`, `capacityExceeded` (with retry guidance when known) |
 | 503 | `serviceUnavailable` (with retry guidance when known) |
 | 500 | `internalError` |