Atomic Matchmaking with Two-Phase Commit

Two-phase commit semantics for match creation that handles player disconnections gracefully.

When to Use This Skill

• Building real-time multiplayer matchmaking

• Need to handle player disconnections during match creation

• Want to avoid orphaned lobbies and stuck players

• Require reliable match notifications

Core Concepts

Matching two players is deceptively hard. Either player can disconnect between being matched and joining. The solution uses two-phase commit:

• Phase 1: Verify both connections are healthy via ping/pong

• Phase 2: Create lobby, send notifications, confirm delivery

• Rollback: On any failure, clean up lobby and re-queue the healthy player

Implementation

Python

from dataclasses import dataclass, field from datetime import datetime from typing import Optional, Tuple from enum import Enum import asyncio

class MatchStatus(str, Enum): SUCCESS = "success" PLAYER1_DISCONNECTED = "player1_disconnected" PLAYER2_DISCONNECTED = "player2_disconnected" BOTH_DISCONNECTED = "both_disconnected" NOTIFICATION_FAILED = "notification_failed"

@dataclass class MatchTicket: player_id: str category: str queued_at: datetime = field(default_factory=datetime.utcnow)

@dataclass class MatchResult: status: MatchStatus lobby_id: Optional[str] = None lobby_code: Optional[str] = None player1_healthy: bool = True player2_healthy: bool = True requeued_player: Optional[str] = None

class ConnectionHealthChecker: """Verifies player connections are healthy before matching."""

PING_TIMEOUT = 2.0
MAX_ACCEPTABLE_LATENCY = 500  # ms

def __init__(self, connection_manager):
    self._manager = connection_manager

async def check_health(self, player_id: str) -> Tuple[bool, Optional[float]]:
    if not self._manager.is_user_connected(player_id):
        return False, None
    
    success, latency = await self._manager.ping_user(
        player_id, timeout=self.PING_TIMEOUT
    )
    
    if not success:
        return False, None
    
    if latency and latency > self.MAX_ACCEPTABLE_LATENCY:
        return False, latency
    
    return True, latency

async def verify_both_healthy(
    self, player1_id: str, player2_id: str
) -> Tuple[bool, bool, bool]:
    results = await asyncio.gather(
        self.check_health(player1_id),
        self.check_health(player2_id),
    )
    
    health1, _ = results[0]
    health2, _ = results[1]
    
    return (health1 and health2), health1, health2

class AtomicMatchCreator: """Creates matches with two-phase commit semantics."""

NOTIFICATION_TIMEOUT = 2.0
NOTIFICATION_RETRIES = 3

def __init__(
    self,
    health_checker: ConnectionHealthChecker,
    lobby_service,
    queue_manager,
    notification_service,
):
    self._health_checker = health_checker
    self._lobby_service = lobby_service
    self._queue_manager = queue_manager
    self._notifications = notification_service

async def create_match(
    self, player1: MatchTicket, player2: MatchTicket
) -> MatchResult:
    # Phase 1: Health Check
    both_healthy, health1, health2 = await self._health_checker.verify_both_healthy(
        player1.player_id, player2.player_id
    )
    
    if not both_healthy:
        return await self._handle_health_failure(player1, player2, health1, health2)
    
    # Phase 2: Create Lobby & Notify
    lobby = None
    try:
        lobby = await self._lobby_service.create_lobby(
            host_id=player1.player_id,
            category=player1.category,
        )
        
        await self._lobby_service.add_player(lobby["id"], player2.player_id)
        
        # Notify both players in parallel
        notify_results = await asyncio.gather(
            self._notify_with_retry(player1.player_id, lobby["code"], player2.player_id),
            self._notify_with_retry(player2.player_id, lobby["code"], player1.player_id),
            return_exceptions=True,
        )
        
        if not all(r is True for r in notify_results):
            raise Exception("Notification failed")
        
        return MatchResult(
            status=MatchStatus.SUCCESS,
            lobby_id=lobby["id"],
            lobby_code=lobby["code"],
        )
        
    except Exception as e:
        # Rollback: delete lobby if created
        if lobby:
            await self._lobby_service.delete_lobby(lobby["id"])
        
        return await self._handle_phase2_failure(player1, player2, str(e))

async def _handle_health_failure(
    self, player1: MatchTicket, player2: MatchTicket,
    health1: bool, health2: bool
) -> MatchResult:
    if not health1 and not health2:
        return MatchResult(
            status=MatchStatus.BOTH_DISCONNECTED,
            player1_healthy=False,
            player2_healthy=False,
        )
    
    # Re-queue the healthy player with priority
    if health1 and not health2:
        await self._queue_manager.requeue_player(player1, priority=True)
        return MatchResult(
            status=MatchStatus.PLAYER2_DISCONNECTED,
            player1_healthy=True,
            player2_healthy=False,
            requeued_player=player1.player_id,
        )
    
    if health2 and not health1:
        await self._queue_manager.requeue_player(player2, priority=True)
        return MatchResult(
            status=MatchStatus.PLAYER1_DISCONNECTED,
            player1_healthy=False,
            player2_healthy=True,
            requeued_player=player2.player_id,
        )
    
    return MatchResult(status=MatchStatus.BOTH_DISCONNECTED)

async def _notify_with_retry(
    self, player_id: str, lobby_code: str, opponent_id: str
) -> bool:
    for attempt in range(self.NOTIFICATION_RETRIES):
        try:
            success = await asyncio.wait_for(
                self._notifications.notify_match_found(player_id, lobby_code, opponent_id),
                timeout=self.NOTIFICATION_TIMEOUT,
            )
            if success:
                return True
        except asyncio.TimeoutError:
            pass
        
        if attempt < self.NOTIFICATION_RETRIES - 1:
            await asyncio.sleep(0.1)
    
    return False

Queue Manager with Priority Re-queue

from collections import deque from typing import Dict, Optional, Set import asyncio

class MatchmakingQueue: """FIFO queue with priority re-queue support."""

def __init__(self):
    self._queues: Dict[str, deque] = {}
    self._player_tickets: Dict[str, MatchTicket] = {}
    self._lock = asyncio.Lock()

async def enqueue(self, ticket: MatchTicket, priority: bool = False) -> bool:
    async with self._lock:
        if ticket.player_id in self._player_tickets:
            return False
        
        if ticket.category not in self._queues:
            self._queues[ticket.category] = deque()
        
        queue = self._queues[ticket.category]
        
        if priority:
            queue.appendleft(ticket)
        else:
            queue.append(ticket)
        
        self._player_tickets[ticket.player_id] = ticket
        return True

async def dequeue_pair(self, category: str) -> Optional[tuple]:
    async with self._lock:
        queue = self._queues.get(category)
        if not queue or len(queue) < 2:
            return None
        
        ticket1 = queue.popleft()
        ticket2 = queue.popleft()
        
        self._player_tickets.pop(ticket1.player_id, None)
        self._player_tickets.pop(ticket2.player_id, None)
        
        return ticket1, ticket2

async def requeue_player(self, ticket: MatchTicket, priority: bool = True) -> None:
    await self.remove_player(ticket.player_id)
    await self.enqueue(ticket, priority=priority)

Usage Examples

Match Creation Flow

health_checker = ConnectionHealthChecker(connection_manager) match_creator = AtomicMatchCreator( health_checker, lobby_service, queue_manager, notification_service )

When two players are matched

result = await match_creator.create_match(ticket1, ticket2)

if result.status == MatchStatus.SUCCESS: print(f"Match created: {result.lobby_code}") elif result.requeued_player: print(f"Re-queued {result.requeued_player}")

Best Practices

• Always verify connections before creating lobby - prevents orphaned lobbies

• Re-queue healthy players with priority - they've already waited

• Use notification retries - network can be flaky

• Rollback on any failure - clean up partial state

• Log correlation IDs - essential for debugging match failures

Common Mistakes

• Creating lobby before verifying connections (orphaned lobbies)

• Not re-queuing healthy players (stuck in limbo)

• No notification retries (lost matches on network blips)

• Missing rollback logic (resource leaks)

• Not using priority re-queue (unfair to healthy players)

Related Patterns

• websocket-management - Connection health verification

• distributed-lock - Prevent race conditions in matching

• graceful-shutdown - Drain queue on shutdown