HeiKyu/Rendezvous
2
0
Fork 0
Code Issues 27 Pull Requests Actions Packages Projects Releases Wiki Activity

Define versioned v1 HTTP, UDP, error, and compatibility contracts #4

New Issue
Open
opened 2026-07-15 10:04:13 +02:00 by Kyuubi · 2 comments
Kyuubi commented 2026-07-15 10:04:13 +02:00
Owner
Copy Link
Copy Source

Parent: #1
Depends on: #2, #3

Outcome

Freeze a transport-neutral v1 contract that both games can consume without importing server internals.

Scope

  • Define strongly typed IDs, game/environment scopes, listing fields, capacity, region, visibility, build/protocol versions, leases, attempts, and typed errors.
  • Specify the HTTP surface for register/renew/update/delete, browse/get, join, optional outcome reporting, liveness, and readiness.
  • Specify bounded UDP envelopes/handles for host presence, client presence, and mediation correlation.
  • Define exact v1 network-protocol compatibility and display-only build-version behavior unless #2 chooses otherwise.
  • Define cursor pagination, idempotency, cancellation, unknown-field/version behavior, payload/token/metadata limits, and stable error mapping.
  • Generate OpenAPI for HTTP and a concise binary/semantic specification for UDP.
  • Keep raw endpoints and reusable credentials out of browser contracts.

Acceptance criteria

  • Contract serialization round trips and golden vectors are committed.
  • Unknown or incompatible versions fail predictably.
  • Limits are constants/policy, documented, and tested at boundary ±1.
  • Contracts are address-family aware even if v1 punches IPv4 first.
  • No canonical game/player/entity identity or gameplay state enters Rendezvous contracts.
  • The LiteNetLib NAT token remains comfortably below its 256-character ceiling.
  • An API compatibility test detects accidental breaking changes.
Parent: #1 Depends on: #2, #3 ## Outcome Freeze a transport-neutral v1 contract that both games can consume without importing server internals. ## Scope - Define strongly typed IDs, game/environment scopes, listing fields, capacity, region, visibility, build/protocol versions, leases, attempts, and typed errors. - Specify the HTTP surface for register/renew/update/delete, browse/get, join, optional outcome reporting, liveness, and readiness. - Specify bounded UDP envelopes/handles for host presence, client presence, and mediation correlation. - Define exact v1 network-protocol compatibility and display-only build-version behavior unless #2 chooses otherwise. - Define cursor pagination, idempotency, cancellation, unknown-field/version behavior, payload/token/metadata limits, and stable error mapping. - Generate OpenAPI for HTTP and a concise binary/semantic specification for UDP. - Keep raw endpoints and reusable credentials out of browser contracts. ## Acceptance criteria - Contract serialization round trips and golden vectors are committed. - Unknown or incompatible versions fail predictably. - Limits are constants/policy, documented, and tested at boundary ±1. - Contracts are address-family aware even if v1 punches IPv4 first. - No canonical game/player/entity identity or gameplay state enters Rendezvous contracts. - The LiteNetLib NAT token remains comfortably below its 256-character ceiling. - An API compatibility test detects accidental breaking changes.
Kyuubi self-assigned this 2026-07-16 04:26:24 +02:00
Kyuubi commented 2026-07-16 04:26:25 +02:00
Author
Owner
Copy Link
Copy Source

Starting the v1 contract freeze on top of the completed architecture/bootstrap checkpoints. Scope includes transport-neutral typed contracts, bounded HTTP/UDP semantics, deterministic serialization/golden vectors, OpenAPI, limit boundary tests, and an API compatibility guard.

Starting the v1 contract freeze on top of the completed architecture/bootstrap checkpoints. Scope includes transport-neutral typed contracts, bounded HTTP/UDP semantics, deterministic serialization/golden vectors, OpenAPI, limit boundary tests, and an API compatibility guard.
Kyuubi commented 2026-07-16 04:53:08 +02:00
Author
Owner
Copy Link
Copy Source

Implemented and pushed on codex/issue-4-v1-contracts at 69c8b2d.

Delivered:

  • strongly typed v1 scopes and opaque IDs, canonical JSON rules, required-field/version semantics, exact gameplay protocol compatibility, and bounded validation helpers;
  • complete register/renew/update/delete, browse/get, join-attempt/outcome, health, and host-polling HTTP contract surface;
  • generated OpenAPI 3.1 document with CI drift detection;
  • bounded, address-family-aware host/client UDP presence codec with stable decode errors and canonical UUID/network byte order;
  • HTTP/UDP specifications covering idempotency, cursors, cancellation, unknown fields/versions, error mapping, credential exposure, and limits;
  • JSON and UDP golden vectors, boundary ±1 coverage, unknown-version/enum tests, browser privacy assertions, OpenAPI compatibility checks, and a public .NET API snapshot.

Verification:

  • locked restore passed;
  • formatter verification passed;
  • Release solution build passed;
  • 36/36 tests passed;
  • generated OpenAPI regenerated with no drift;
  • real server smoke passed for liveness, readiness, runtime OpenAPI, UDP bind, and expected 501 contract stub;
  • completion and branch audits found no remaining actionable issues.

A high-severity advisory in the generator's transitive Microsoft.OpenApi 2.0.0 was caught by restore; the patched compatible 2.7.5 line is centrally pinned. The issue remains open until this stacked branch is landed.

Implemented and pushed on `codex/issue-4-v1-contracts` at `69c8b2d`. Delivered: - strongly typed v1 scopes and opaque IDs, canonical JSON rules, required-field/version semantics, exact gameplay protocol compatibility, and bounded validation helpers; - complete register/renew/update/delete, browse/get, join-attempt/outcome, health, and host-polling HTTP contract surface; - generated OpenAPI 3.1 document with CI drift detection; - bounded, address-family-aware host/client UDP presence codec with stable decode errors and canonical UUID/network byte order; - HTTP/UDP specifications covering idempotency, cursors, cancellation, unknown fields/versions, error mapping, credential exposure, and limits; - JSON and UDP golden vectors, boundary ±1 coverage, unknown-version/enum tests, browser privacy assertions, OpenAPI compatibility checks, and a public .NET API snapshot. Verification: - locked restore passed; - formatter verification passed; - Release solution build passed; - 36/36 tests passed; - generated OpenAPI regenerated with no drift; - real server smoke passed for liveness, readiness, runtime OpenAPI, UDP bind, and expected 501 contract stub; - completion and branch audits found no remaining actionable issues. A high-severity advisory in the generator's transitive `Microsoft.OpenApi` 2.0.0 was caught by restore; the patched compatible 2.7.5 line is centrally pinned. The issue remains open until this stacked branch is landed.
Sign in to join this conversation.
No Branch/Tag Specified
Branches Tags
Labels
No items
No Label
Milestone
No items
No Milestone
Projects
Clear projects
No project
Assignees
Clear assignees
Kyuubi schmidt.florian (Florian Schmidt)
No Assignees Kyuubi
1 Participants
Notifications
Due Date
No due date set.
Dependencies

No dependencies set.

Reference: HeiKyu/Rendezvous#4
Delete Branch "%!s()"

Deleting a branch is permanent. Although the deleted branch may continue to exist for a short time before it actually gets removed, it CANNOT be undone in most cases. Continue?