Vixen
dd8b0a81

Live · concept

Transfer tickets

A player's signed, expiring permission to be admitted to a shard — and why the client can only carry it.

Edit this page on GitHub

Documents

What it is

A TransferTicket says: *this character may enter that shard, at that lease epoch, until that moment*. It is signed with a key every realm in a cluster holds and no client ever does, so the client that carries it is a courier — it can neither read anything it did not already know nor forge one.

TransferTicketSigner mints them and is the only thing that can tell a real one from a made-up one. TicketStatus is what it decided.

What it is for

This is NetworkSession's reconnect token with a different issuer. Doc 16 already established server-issued, opaque, expiring tokens that let a PlayerId survive a dropped ConnectionId; a transfer ticket is the same object minted by the orchestrator instead of by the source session.

Two properties make the transfer protocol work:

  • Admission costs an HMAC, not a round trip. The ticket is self-contained and the key is already in the realm's process, so the second session a transfer opens is admitted in the time it takes to hash a hundred bytes. That is what lets it overlap with the player still playing on the first realm, which is the whole reason a map change is a preload rather than a reconnect.
  • A replayed ticket is harmless. It names a lease epoch, and an epoch already superseded is a no-op rather than a second grant. The expiry is a second, cruder bound on the same window.

Using it

csharp
using var signer = new TransferTicketSigner(clusterKey);       // ≥ 32 bytes, or it refusesvar ticket = signer.Sign(new TransferTicket {    Player     = player,    Target     = shard,    Endpoint   = endpoint,    LeaseEpoch = epoch + 1,    Expires    = DateTimeOffset.UtcNow + TimeSpan.FromSeconds(30)});var carried = ticket.Encode();     // what the client is handed, and all it is handed

and on the realm being entered:

csharp
if (!TransferTicket.TryDecode(presented, out var ticket, out var why)) {    return AuthenticationDecision.Refuse("A ticket is required.");}var status = signer.Validate(ticket, myShard, DateTimeOffset.UtcNow);

⚠ Decoding is not validating. TryDecode answers whether the bytes were a ticket, which is a question about a stranger's input. Whether it is this cluster's ticket, not yet expired, for the shard being entered is Validate, and that is the only check that means anything.

Validate checks signature, then expiry, then shard, in that order — so everything after the first check is a statement about a ticket this cluster actually issued.

Examples

Every refusal has a name, and the names are told to the client on purpose: expired is something it can act on by asking the gate for another, and wrong shard by asking where it should have gone. Neither tells an attacker anything the ticket did not.

csharp
signer.Validate(unsigned,          shard, now);   // TicketStatus.Unsignedsigner.Validate(anotherClusters,   shard, now);   // TicketStatus.Forgedsigner.Validate(lastWeeks,         shard, now);   // TicketStatus.Expiredsigner.Validate(forTheShardNextDoor, shard, now); // TicketStatus.WrongShard

The key

⚠ The cluster key is the whole of the security of admission. Anyone holding it can admit anyone to anything. It belongs in whatever the deployment already uses for secrets, and never in a RealmSpec — a spec travels on a command line, and a command line is visible to every other process on the machine.

A realm nobody handed a key to derives one from its own spec (RealmHost.DevelopmentSigner). That is a development convenience and is not meant to look like a security mechanism: what it buys is that a deployment which forgot to configure a key gets a fleet that refuses everybody — which is loud — rather than one that admits anybody, which is not.

Readiness is the other half

TransferReadiness is what a draining shard asks about each player before moving them: Ready, Soon, or Blocked. The engine ships a default that says everybody, always, and does not pretend to know better — "in a scripted encounter" is a sentence only the game can finish. Nothing is force-disconnected by a drain; Blocked escalates to a live-ops alert at the hard deadline, and that path ends in a human rather than in a kick.

See also

Next

  • Admission, health and the control plane — The door a ticketed player comes through, the two-second sample a fleet is watched by, and the one place a realm ever calls an orchestrator.
  • Shards, keys and specs — What a shard is, what makes two of them interchangeable, and the one string a realm process boots from.
  • The service plane — The gate — sign in, characters, the catalog check, and the one call that turns "I want to play" into an endpoint and a signed ticket.
  • Transferring players — The overlap — a second session opened while the player is still playing on the first, and the lease epoch that makes the switch atomic.