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"
      }
    }
  },