P2P Connectivity and TURN Relay

P2P Connectivity and TURN Relay

ggscale's peer-to-peer modes let players connect straight to each other, with ggscale out of the data path. The optional TURN relay covers players who cannot reach each other directly through NAT.

The recommended handshake (game_session)

1. Every player queues a game_session matchmaking ticket.
2. The match delivers session_id, join_code, host_player_id, and the roster.
3. The host joins the session and registers its endpoint through the normal join and heartbeat flow. Peers read the host's endpoint from the session.
4. Peers connect directly.

Bring your own signaling (match_only)

match_only gives you the same match and host without a session. Peers exchange connect info through the roster attributes, for example a platform lobby id, or through your own signaling. Attributes are visible to every matched peer and capped at 4 KiB per ticket.

TURN relay

When a direct connection fails, a relay forwards traffic between peers. Ask for short-lived credentials with POST /v1/relay/credentials, optionally scoped to a match_id. The response holds a username, password, ttl, realm, and the urls and stun_urls to feed into your ICE configuration.

The relay is off unless the operator enables it. It turns on with FEATURE_P2P_RELAY_ENABLED plus the relay URLs and shared secret. See the Configuration Reference for the full set.

Example

curl -s -X POST "http://localhost:8080/v1/relay/credentials?match_id=abc123" \
  -H "Authorization: Bearer <api_key>" \
  -H "X-Session-Token: <access_token>"

Full reference: the /v1/relay/credentials operation. See also Matchmaking and Game Sessions and Invites.