Room Code API — Generate, Validate & Manage Game Room Codes for Ludo Multiplayer

import secrets
import string
import json
import redis
from datetime import datetime, timedelta
from enum import Enum
from typing import Optional, Dict, Any, List

# ── Alphabet Configuration ────────────────────────────────────
# Remove visually confusing characters to reduce mistyping.
BASE_ALPHABET = string.ascii_uppercase + string.digits
CLEAN_ALPHABET = (
    BASE_ALPHABET
    .replace('0', '')
    .replace('O', '')
    .replace('1', '')
    .replace('I', '')
    .replace('L', '')
)

# ── Room State Enum ──────────────────────────────────────────
class RoomState(Enum):
    WAITING   = "waiting"
    STARTING  = "starting"
    PLAYING   = "playing"
    ENDED     = "ended"
    EXPIRED   = "expired"

# ── Redis Client ─────────────────────────────────────────────
r = redis.Redis(host='localhost', port=6379, db=0, decode_responses=True)

# ── Room Code Generator ──────────────────────────────────────
def generate_room_code(
    length: int = 6,
    alphabet: str = CLEAN_ALPHABET,
    ttl_hours: float = 4,
    max_attempts: int = 10
) -> str:
    """
    Generate a unique room code using atomic Redis SET NX EX.

    The SET NX EX combination ensures that even under concurrent load,
    no two requests can claim the same code. SET returns True only if
    the key did not exist — making the check-and-insert atomic.
    """
    ttl_seconds = int(ttl_hours * 3600)

    for _ in range(max_attempts):
        code = ''.join(secrets.choice(alphabet) for _ in range(length))
        room_key = f"room:{code}"

        room_data = {
            "code": code,
            "status": RoomState.WAITING.value,
            "players": [],
            "max_players": 4,
            "host_id": None,
            "created_at": datetime.utcnow().isoformat(),
            "started_at": None,
            "ended_at": None,
            "privacy": "public",   # public | private | invite_only
            "spectator_code": None,
            "game_config": {
                "board_size": "standard",
                "time_limit_per_turn": None,
                "allow_bots": True
            }
        }

        # SET key json NX EX ttl — atomic set-if-not-exists with expiry
        was_set = r.set(
            room_key,
            json.dumps(room_data),
            nx=True,
            ex=ttl_seconds
        )
        if was_set:
            return code

    raise RuntimeError(
        f"Failed to generate unique room code after {max_attempts} attempts. "
        "Consider increasing the alphabet or reducing TTL."
    )

# ── Room Retrieval ──────────────────────────────────────────
def get_room(code: str) -> Optional[Dict[str, Any]]:
    """Retrieve a room by code, normalized to uppercase. Returns None if expired."""
    room_key = f"room:{code.upper().strip()}"
    raw = r.get(room_key)
    return json.loads(raw) if raw else None

# ── Player Join with Atomic Capacity Check ───────────────────
def join_room(
    code: str,
    player_id: str,
    player_name: str,
    is_host: bool = False
) -> Dict[str, Any]:
    """Add a player to a room with atomic capacity enforcement."""
    room = get_room(code)
    if not room:
        return {"success": False, "error": "ROOM_NOT_FOUND",
                "message": "Room not found or has expired."}

    state = room["status"]
    if state == RoomState.PLAYING.value:
        return {"success": False, "error": "GAME_IN_PROGRESS",
                "message": "This game is already in progress."}
    if state == RoomState.ENDED.value:
        return {"success": False, "error": "GAME_ENDED",
                "message": "This game has already ended."}
    if state == RoomState.EXPIRED.value:
        return {"success": False, "error": "ROOM_EXPIRED",
                "message": "This room has expired."}

    if len(room["players"]) >= room["max_players"]:
        return {"success": False, "error": "ROOM_FULL",
                "message": "This room is full."}

    # Atomic capacity check using Redis Lua script
    lua_script = """
    local room_key = KEYS[1]
    local max_players = tonumber(ARGV[1])
    local player_json = ARGV[2]
    local ttl = tonumber(ARGV[3])
    local room = redis.call('GET', room_key)
    if not room then return {-1, 'ROOM_NOT_FOUND'} end
    local data = cjson.decode(room)
    if #data.players >= max_players then return {0, 'ROOM_FULL'} end
    table.insert(data.players, cjson.decode(player_json))
    if data.status == 'waiting' and #data.players == data.max_players then
        data.status = 'starting'
    end
    redis.call('SET', room_key, cjson.encode(data), 'EX', ttl)
    return {1, 'OK'}
    """

    player = {
        "id": player_id,
        "name": player_name,
        "is_host": is_host,
        "joined_at": datetime.utcnow().isoformat()
    }
    remaining_ttl = r.ttl(f"room:{code.upper()}")
    result = r.eval(lua_script, 1,
                    f"room:{code.upper()}",
                    room["max_players"],
                    json.dumps(player),
                    remaining_ttl)

    if result[0] == 1:
        updated_room = get_room(code)
        return {"success": True, "room": updated_room,
                "state": updated_room["status"]}
    else:
        return {"success": False, "error": result[1],
                "message": result[1]}

# ── State Transition ─────────────────────────────────────────
def transition_room_state(code: str, new_state: RoomState) -> Dict[str, Any]:
    """Transition a room to a new state, enforcing valid transitions."""
    valid_transitions = {
        RoomState.WAITING:  {RoomState.STARTING, RoomState.EXPIRED},
        RoomState.STARTING: {RoomState.PLAYING,  RoomState.WAITING, RoomState.EXPIRED},
        RoomState.PLAYING:  {RoomState.ENDED,    RoomState.EXPIRED},
        RoomState.ENDED:    {RoomState.EXPIRED},
        RoomState.EXPIRED:   {RoomState.EXPIRED},
    }

    room = get_room(code)
    if not room:
        return {"success": False, "error": "ROOM_NOT_FOUND"}

    current = RoomState(room["status"])
    if new_state not in valid_transitions.get(current, set()):
        return {"success": False,
                "error": "INVALID_TRANSITION",
                "message": f"Cannot transition from {current.value} to {new_state.value}."}

    room["status"] = new_state.value
    if new_state == RoomState.PLAYING:
        room["started_at"] = datetime.utcnow().isoformat()
    elif new_state in {RoomState.ENDED, RoomState.EXPIRED}:
        room["ended_at"] = datetime.utcnow().isoformat()

    remaining_ttl = r.ttl(f"room:{code.upper()}")
    r.setex(f"room:{code.upper()}", remaining_ttl, json.dumps(room))
    return {"success": True, "room": room}

# ── Spectator Code Generator ────────────────────────────────
def generate_spectator_code(room_code: str) -> Optional[str]:
    """Generate a read-only spectator code for a room."""
    room = get_room(room_code)
    if not room:
        return None
    # Spectator codes use a different alphabet (lower case) to visually distinguish
    spec_alphabet = string.ascii_lowercase + string.digits
    spec_code = ''.join(secrets.choice(spec_alphabet) for _ in range(4))
    room["spectator_code"] = spec_code
    remaining_ttl = r.ttl(f"room:{room_code.upper()}")
    r.setex(f"room:{room_code.upper()}", remaining_ttl, json.dumps(room))
    return spec_code

# ── Demo Usage ───────────────────────────────────────────────
if __name__ == "__main__":
    code = generate_room_code(length=6, ttl_hours=4)
    print(f"Created room: {code}")

    result = join_room(code, "player_001", "Rahul", is_host=True)
    print(f"Join result: {result}")

    result = transition_room_state(code, RoomState.STARTING)
    print(f"State transition: {result}")

    spec = generate_spectator_code(code)
    print(f"Spectator code: {spec}")

const express = require('express');
const { body, param, query, validationResult } = require('express-validator');
const rateLimit = require('express-rate-limit');
const router = express.Router();

// ── Rate Limiter for Room Operations ────────────────────────
const roomLimiter = rateLimit({
  windowMs: 60 * 1000,   // 1 minute
  max: 30,               // 30 requests per minute per IP
  message: { success: false, error: 'RATE_LIMIT_EXCEEDED',
             message: 'Too many room requests. Slow down.' },
  standardHeaders: true,
  legacyHeaders: false,
});

// ── Validation Middleware ────────────────────────────────────
const validateRoomCode = [
  param('code')
    .trim()
    .toUpperCase()
    .isLength({ min: 4, max: 8 })
    .matches(/^[A-Z0-9]+$/)
    .withMessage('Room code must be 4-8 alphanumeric characters')
];

// ── POST /api/rooms — Create a New Room ─────────────────────
router.post('/', roomLimiter, async (req, res) => {
  const { maxPlayers = 4, privacy = 'public', gameConfig = {} } = req.body;

  try {
    const code = await RoomService.generateRoomCode({
      length: 6,
      ttlHours: 4,
      maxPlayers,
      privacy,
      gameConfig
    });

    res.status(201).json({
      success: true,
      room: { code, status: 'waiting', expiresIn: 4 * 3600 },
      joinUrl: `ludogame://join/{code}`
    });
  } catch (err) {
    console.error('Room creation failed:', err);
    res.status(500).json({ success: false, error: 'INTERNAL_ERROR',
                              message: 'Failed to create room.' });
  }
});

// ── GET /api/rooms/:code — Get Room Info ────────────────────
router.get('/:code', validateRoomCode, async (req, res) => {
  const errors = validationResult(req);
  if (!errors.isEmpty()) {
    return res.status(400).json({ success: false, errors: errors.array() });
  }

  const { code } = req.params;
  const room = await RoomService.getRoom(code);

  if (!room) {
    return res.status(404).json({
      success: false, error: 'ROOM_NOT_FOUND',
      message: 'Room not found or has expired. Check the code and try again.'
    });
  }

  // Sanitized response — hide internal IDs
  res.json({
    success: true,
    room: {
      code: room.code,
      status: room.status,
      playerCount: room.players.length,
      maxPlayers: room.maxPlayers,
      privacy: room.privacy,
      gameConfig: room.gameConfig,
      createdAt: room.createdAt,
      hasSpectatorCode: Boolean(room.spectatorCode)
    }
  });
});

// ── POST /api/rooms/:code/join — Join a Room ────────────────
router.post('/:code/join', roomLimiter, [
  validateRoomCode,
  body('playerId').isString().notEmpty().isLength({ max: 64 }),
  body('playerName').isString().isLength({ min: 1, max: 20 })
], async (req, res) => {
  const errors = validationResult(req);
  if (!errors.isEmpty()) {
    return res.status(400).json({ success: false, errors: errors.array() });
  }

  const { code } = req.params;
  const { playerId, playerName } = req.body;

  try {
    const result = await RoomService.joinRoom(code, playerId, playerName);
    if (!result.success) {
      const statusMap = {
        'ROOM_NOT_FOUND': 404,
        'ROOM_FULL': 409,
        'GAME_IN_PROGRESS': 409,
        'GAME_ENDED': 410,
        'ROOM_EXPIRED': 410
      };
      return res.status(statusMap[result.error] || 400).json(result);
    }
    res.json(result);
  } catch (err) {
    console.error('Join room failed:', err);
    res.status(500json({ success: false, error: 'INTERNAL_ERROR' });
  }
});

// ── POST /api/rooms/:code/start — Start the Game ────────────
router.post('/:code/start', [
  validateRoomCode
], async (req, res) => {
  const { code } = req.params;
  const result = await RoomService.transitionRoomState(code, 'playing');
  if (!result.success) {
    return res.status(400).json(result);
  }
  // Emit WebSocket event to notify all connected clients
  io.to(code).emit('room:game-start', { roomCode: code, state: 'playing' });
  res.json(result);
});

// ── DELETE /api/rooms/:code — Close a Room (Host Only) ──────
router.delete('/:code', validateRoomCode, async (req, res) => {
  const { code } = req.params;
  const result = await RoomService.transitionRoomState(code, 'expired');
  if (!result.success) {
    return res.status(400).json(result);
  }
  io.to(code).emit('room:closed', { roomCode: code, reason: 'host_closed' });
  res.json({ success: true, message: 'Room closed successfully.' });
});

module.exports = router;

// ── WebSocket Room Subscription (Client-Side) ───────────────
const socket = new WebSocket('wss://api.ludokingapi.site/v1/game');

socket.onopen = () => {
  // Authenticate and subscribe to the room channel
  socket.send(JSON.stringify({
    type: 'room:subscribe',
    roomCode: 'ABCD12',
    playerId: 'player_001',
    token: jwtToken
  }));
};

socket.onmessage = (event) => {
  const msg = JSON.parse(event.data);

  switch (msg.type) {
    case 'room:player-joined':
      appendLog(`{msg.playerName} joined the room ({msg.playerCount}/{msg.maxPlayers})`);
      break;
    case 'room:player-left':
      appendLog(`{msg.playerName} left the room`);
      break;
    case 'room:game-start':
      appendLog('Game started!');
      setGamePhase('playing');
      break;
    case 'game:dice-roll':
      animateDiceRoll(msg.value, msg.playerId);
      break;
    case 'game:piece-move':
      animatePieceMove(msg.pieceId, msg.from, msg.to);
      break;
    case 'game:turn-update':
      highlightCurrentPlayer(msg.currentPlayerId);
      startTurnTimer(msg.turnTimeoutSeconds);
      break;
    case 'room:closed':
      showGameOver(msg.reason, msg.results);
      socket.close();
      break;
    default:
      console.log('Unknown event type:', msg.type);
  }
};

socket.onclose = (event) => {
  if (event.code !== 1000) {
    console.warn('WebSocket disconnected unexpectedly. Reconnecting...');
    setTimeout(reconnect, 2000);
  }
};