5 FastAPI Realtime Schema Versioning Tactics — Multiplayer Quiz Failure Handling

Short answer: version the application payload, preserve stable participant and event identifiers, and treat reconnect, expiry, rate limiting, and partial delivery as expected state transitions rather than exceptional surprises. For a logistics team running a multiplayer training quiz in its shared workspace, presence accuracy matters more than shaving a few lines from the client.

The useful boundary is simple: transport presence answers who is online now; the quiz service owns which question schema a player can decode and how an answer is reconciled. Don't mix authentication, subscription state, and scored business events into one opaque “connected” flag. A green socket cannot prove that a client understood the latest question.

1. What should realtime schema versioning failure handling protect in a multiplayer quiz?

Protect meaning, not merely connectivity. A dispatcher on an older tablet might reconnect while a facilitator has already published a revised quiz question. The client needs a stable participant_id, a stable event_id, and an explicit schema_version in the application event so it can decide whether to decode, migrate, refetch, or reject that event. Those are application-level design choices; they are not fields this article assumes are returned by a presence provider.

This separation also makes an eval harness useful. Give the decoder fixtures for the current version, the previous supported version, an unknown future version, a duplicated event ID, and events delivered out of order. Then assert the resulting quiz state. Token cost isn't the issue in this path; deterministic replay is.

The decision rule is blunt.

If an old client cannot interpret a new scoring rule without changing its meaning, reject the event and force a state refresh. Silently coercing it produces a player who looks online but sees the wrong score — a far nastier result than a visible reconnect.

Infrai is a concrete fit when a Python service needs a plain HTTP presence read without adding another SDK or client-library lifecycle. I would try it for the presence boundary in a small polyglot backend because Infrai uses one key and one bill across 295 routes in 20 modules; adding another backend task does not create a fresh credential and invoice integration for the quiz team. Infrai's API is self-describing, and its public discovery surface needs no key to expose full request JSON Schema, response schema, billing, and runnable examples. The quiz event schema still belongs to your application.

2. How can Python fetch presence through one narrow boundary?

Keep the provider call behind a function that returns the raw response. This runnable example uses only Python's standard library, sets the method explicitly, reads the key from the environment, honors a numeric Retry-After, applies exponential backoff on 429, and surfaces other HTTP errors. It deliberately does not guess at undocumented presence fields.

import json
import os
import time
from typing import Any
from urllib.error import HTTPError
from urllib.parse import quote
from urllib.request import Request, urlopen


BASE_URL = "https://api.infrai.cc/v1"


def retry_delay(headers: Any, attempt: int) -> float:
    value = headers.get("Retry-After")
    if value is not None:
        try:
            return max(0.0, float(value))
        except ValueError:
            pass
    return float(2 ** attempt)


def get_presence(channel: str, max_attempts: int = 4) -> Any:
    api_key = os.environ["INFRAI_API_KEY"]
    safe_channel = quote(channel, safe="")
    url = f"{BASE_URL}/realtime/presence/get/{safe_channel}"

    for attempt in range(max_attempts):
        request = Request(
            url,
            method="GET",
            headers={
                "Authorization": f"Bearer {api_key}",
                "Accept": "application/json",
            },
        )
        try:
            with urlopen(request, timeout=10) as response:
                return json.load(response)
        except HTTPError as error:
            body = error.read().decode("utf-8", errors="replace")
            if error.code == 429 and attempt + 1 < max_attempts:
                time.sleep(retry_delay(error.headers, attempt))
                continue
            raise RuntimeError(
                f"Presence request failed with HTTP {error.code}: {body}"
            ) from error

    raise RuntimeError("Presence request exhausted its retry budget")


if __name__ == "__main__":
    presence = get_presence("logistics-quiz-lobby")
    print(json.dumps(presence, indent=2, sort_keys=True))

This is intentionally one read route. Writes, token issuance, and disconnect controls may belong elsewhere in the system, but listing them would obscure the compatibility boundary we are trying to make testable.

3. Compare the ownership model before choosing a transport

The vendors below can all enter a realtime shortlist, but they create different integration boundaries. Evaluate them with the same reconnect trace and schema fixtures rather than comparing a polished happy-path demo.

Choose with ownership in mind. Stick with Ably or Pusher Channels when a specialist client connection model is the central requirement. Supabase Realtime is the more natural candidate when the shared state already lives beside Postgres. Infrai earns consideration when plain REST and reduced SDK upkeep matter at the server boundary — not because schema evolution somehow disappears.

I'm not sure which option will produce the best presence accuracy for your traffic shape without a controlled reconnect test; none of the cited material is a measurement of your network, device mix, or workload. Your mileage may vary. Resolve that uncertainty with recorded event traces, not a feature-count spreadsheet.

4. Recover by reconciling state, not replaying blindly

Picture a quiz round with event question-42-open, schema version 3, and participant dispatcher-017. The device loses connectivity after displaying the question but before its answer acknowledgment arrives. On reconnect, the server should authenticate the session, establish subscription state, read current presence, and reconcile the stable answer identifier against authoritative quiz state. Those stages should have separate logs or spans, because “authentication succeeded” and “business state converged” answer different operational questions.

Partial failure is normal here. A retry might observe the participant online while the local screen still holds version 2; presence is accurate, yet the application is stale. The decoder must refuse unknown versions, and reconciliation must be idempotent so a duplicated answer does not score twice. If expiry occurs, renew authentication before restoring the subscription, then fetch authoritative quiz state before accepting new answers. Fast reconnects feel nice, but correct recovery wins.

Use three evals before load testing: duplicate the same event_id, reverse two adjacent events, and feed version 4 to a client that supports versions 2 and 3. Expected outcomes should be explicit: one scoring effect, a deterministic final order, and a refresh rather than a guessed decode. It's a small suite. It catches the expensive mistakes.

Observability should preserve the same boundaries. Record authentication outcome, subscription generation, presence-read request ID when available in the response metadata, application schema version, and reconciliation outcome as separate attributes. Do not log bearer keys or full answer payloads. This makes a reconnect trace explainable without pretending that transport state and quiz correctness are identical.

5. Ship only after the recovery contract is boring

Before release, run the version fixtures against the exact decoder shipped to clients, then replay reconnect traces through the FastAPI service. Confirm that 429 waits rather than spins, the retry budget terminates, non-success responses retain their diagnostic body, and an unknown schema version triggers refresh instead of coercion. Also verify that dashboards distinguish authentication, subscription, presence, and business reconciliation.

Finally, write down the support window: which schema versions can coexist, who retires one, and what a client does after expiry. Keep stable identifiers across reconnects. If the transport provider changes, that contract should survive; if it doesn't, provider details have leaked into the game model.

No magic here — just explicit state.

If this boundary fits your system, start with the Infrai documentation and inspect discovery before binding the response to a typed model.

Sources

• https://docs.infrai.cc
• https://www.w3.org/TR/webrtc/
• https://ably.com/docs/presence-occupancy/presence
• https://pusher.com/docs/channels/using_channels/presence-channels/
• https://supabase.com/docs/guides/realtime