feat(multiplayer): reject outdated clients with distinct messaging

Closes §8.43's 'version-mismatch-specific client messaging' gap. Per
the user's explicit go-ahead to design new server behavior for this
(rather than only wiring up something that already existed, the
pattern every other fix this session followed): before this, there
was no server-side protocol rejection at all. queue_create accepted
any protocol_version >= 1 unconditionally, so an outdated client could
only ever discover a mismatch by waiting in the queue forever
unmatched -- the matcher's own compatibility check requires every
formed player to share an identical protocol_version -- with no error
and no explanation given to the player.

Server: Service.MinProtocolVersion (opt-in, zero by default so every
existing caller keeps accepting protocol_version 1 unconditionally)
rejects a below-floor queue_create with 426 Upgrade Required /
client_outdated before the request ever reaches the candidate
provider. Wired via cmd/control-plane's new --min-protocol-version
flag (validated non-negative at startup).

Client: ControlPlaneClient recognises HTTPClient.RESPONSE_UPGRADE_REQUIRED
on queue_create specifically and sets a distinct 'Your client is out
of date -- please update to continue searching' message instead of
the server's raw generic error string, and clears _last_queue_create
so can_retry_queue_create() never offers 'Retry Search' for a failure
that retrying with the same build can never fix.

Verified: go build/vet/test -race clean across every server package.
TestQueueCreateEnforcesMinProtocolVersion covers below-floor rejection
(candidate provider never reached), exactly-at-floor acceptance, and
the error body naming client_outdated; TestQueueCreateMinProtocolVersionZeroIsDisabled
proves the opt-in default doesn't change behavior for every existing
caller. Godot: test_outdated_client_receives_a_distinct_message_and_no_retry_offer
proves the distinct message and suppressed retry offer. Full Godot
suite (217/217, 0 failed, no crash), full make verify-multiplayer-local
gate, zero new crash reports.
This commit is contained in:
Josh Creek
2026-09-04 18:07:29 +01:00
parent 24620be5c1
commit 7d50612abb
6 changed files with 137 additions and 1 deletions
+7
View File
@@ -502,6 +502,13 @@ func _on_request_completed(result: HTTPRequest.Result, response_code: int, _head
state.expire("Queue ticket expired")
elif response_code == HTTPClient.RESPONSE_SERVICE_UNAVAILABLE:
state.set_notice("Matchmaking is temporarily unavailable; retrying is safe")
elif response_code == HTTPClient.RESPONSE_UPGRADE_REQUIRED and operation == "queue_create":
# Distinct from the generic queue_create failure below: retrying
# with the same client build can never succeed, so the retry
# offer must not be shown (can_retry_queue_create() checks
# _last_queue_create; clearing it here suppresses "Retry Search").
_last_queue_create = {}
state.fail("Your client is out of date -- please update to continue searching")
elif operation == "ranked_profile":
ranked_profile.set_error(detail)
elif response_code == HTTPClient.RESPONSE_NOT_FOUND and (operation == "queue_recover" or operation == "proposal_recover"):
@@ -338,6 +338,24 @@ func test_queue_conflict_response_handler_defers_ticket_recovery() -> void:
client.free()
# Covers §8.43's "version-mismatch-specific client messaging": a 426 Upgrade
# Required on queue_create (the server-side floor added alongside this test)
# must surface a distinct, actionable message rather than the server's raw
# generic error string, and must not offer a futile "Retry Search" -- the
# same client build will fail again identically every time.
func test_outdated_client_receives_a_distinct_message_and_no_retry_offer() -> void:
var client := ControlPlaneClient.new()
client._ready()
assert_true(client.configure("https://match.example", "session-id:opaque-token"), "client configures")
client._operation = "queue_create"
client._last_queue_create = {"ticket_id": "ticket-outdated", "playlist": "casual", "client_build": "build-1", "protocol_version": 4, "key": "outdated-key-123456"}
client._on_request_completed(HTTPRequest.RESULT_SUCCESS, HTTPClient.RESPONSE_UPGRADE_REQUIRED, PackedStringArray(), JSON.stringify({"error": "client_outdated"}).to_utf8_buffer())
assert_eq(client.state.phase, MatchmakingState.FAILED, "outdated client fails the search")
assert_true(client.state.message.to_lower().contains("update"), "message tells the player to update rather than repeating the raw server error: %s" % client.state.message)
assert_true(not client.can_retry_queue_create(), "retrying with the same outdated client build is never offered")
client.free()
func test_rest_responses_reject_malformed_resource_identifiers() -> void:
var client := ControlPlaneClient.new()
client._ready()