Skip to content

armgit / meet

Public Imported from GitHub
0

Open source video conferencing app powered by LiveKit. Built with Django and React.

13.9 KB
Raw Blame
"""Lobby Service"""

import logging
import uuid
from dataclasses import dataclass
from enum import Enum
from typing import Dict, FrozenSet, Optional, Sequence, Tuple
from uuid import UUID

from django.conf import settings
from django.core.cache import cache
from django.utils import timezone

from core import models, utils

logger = logging.getLogger(__name__)


class LobbyParticipantStatus(Enum):
    """Possible states of a participant in the lobby system.
    Values are lowercase strings for consistent serialization and API responses.
    """

    UNKNOWN = "unknown"
    WAITING = "waiting"
    ACCEPTED = "accepted"
    DENIED = "denied"


class LobbyError(Exception):
    """Base exception for lobby-related errors."""


class LobbyParticipantParsingError(LobbyError):
    """Raised when participant data parsing fails."""


class LobbyParticipantNotFound(LobbyError):
    """Raised when participant is not found."""


@dataclass
class LobbyParticipant:
    """Participant in a lobby system."""

    status: LobbyParticipantStatus
    username: str
    color: str
    id: str
    entered_at: str

    def to_dict(self) -> Dict[str, str]:
        """Serialize the participant object to a dict representation."""
        return {
            "status": self.status.value,
            "username": self.username,
            "id": self.id,
            "color": self.color,
            "entered_at": self.entered_at,
        }

    @classmethod
    def from_dict(cls, data: dict) -> "LobbyParticipant":
        """Create a LobbyParticipant instance from a dictionary."""
        try:
            status = LobbyParticipantStatus(
                data.get("status", LobbyParticipantStatus.UNKNOWN.value)
            )
            return cls(
                status=status,
                username=data["username"],
                id=data["id"],
                color=data["color"],
                entered_at=data["entered_at"],
            )
        except (KeyError, ValueError) as e:
            logger.exception("Error creating Participant from dict:")
            raise LobbyParticipantParsingError("Invalid participant data") from e


class LobbyService:
    """Service for managing participant access through a lobby system.

    Handles participant entry requests, status management, and notifications
    using cache for state management and LiveKit for real-time updates.
    """

    @staticmethod
    def _get_cache_key(room_id: UUID, participant_id: str) -> str:
        """Generate cache key for participant(s) data."""
        return f"{settings.LOBBY_KEY_PREFIX}_{room_id!s}_{participant_id}"

    @staticmethod
    def _get_index_key(room_id: UUID) -> str:
        """Raw Redis key of the per-room participant index (a native SET)."""
        return cache.client.make_key(f"{settings.LOBBY_KEY_PREFIX}-index_{room_id!s}")

    @staticmethod
    def _redis(write: bool = True):
        """Raw redis-py client.

        SADD/SREM/SMEMBERS are not exposed by the Django cache API; this is
        the documented django-redis escape hatch.
        """
        return cache.client.get_client(write=write)

    def _index_add(self, room_id: UUID, participant_id: str) -> None:
        """Record a participant id in the room index."""
        index_key = self._get_index_key(room_id)
        pipe = self._redis().pipeline(transaction=False)
        pipe.sadd(index_key, participant_id)
        pipe.expire(index_key, settings.LOBBY_ACCEPTED_TIMEOUT)
        pipe.execute()

    def _index_members(self, room_id: UUID) -> FrozenSet[str]:
        """All participant ids currently indexed for the room."""
        members = self._redis(write=False).smembers(self._get_index_key(room_id))
        return frozenset(
            member.decode() if isinstance(member, bytes) else member
            for member in members
        )

    def _index_touch(self, room_id: UUID) -> None:
        """Re-arm the room index backstop TTL."""
        self._redis().expire(
            self._get_index_key(room_id), settings.LOBBY_ACCEPTED_TIMEOUT
        )

    def _index_remove(self, room_id: UUID, *participant_ids: str) -> None:
        """Drop participant ids from the room index."""
        if participant_ids:
            self._redis().srem(self._get_index_key(room_id), *participant_ids)

    @staticmethod
    def can_bypass_lobby(room, user, role) -> bool:
        """Determines if a user can bypass the waiting lobby and join a room directly.

        A user can bypass the lobby if:
        1. The room is public (open to everyone)
        2. The room has TRUSTED access level and the user is authenticated
        2. The room has RESTRICTED access level and the user has any role

        Note: Room access levels can change while participants are waiting in the lobby.
        This function only checks the current state and should be called each time
        a participant requests entry to ensure consistent access control, even for
        participants who have already begun waiting.
        """
        return (
            room.is_public
            or (
                room.access_level == models.RoomAccessLevel.TRUSTED
                and user.is_authenticated
            )
            or (
                room.access_level == models.RoomAccessLevel.RESTRICTED
                and user.is_authenticated
                and role is not None
            )
        )

    def request_entry(
        self,
        room: models.Room,
        user,
        username: str,
        participant_id: Optional[uuid.UUID] = None,
    ) -> Tuple[LobbyParticipant, Optional[Dict]]:
        """Request entry to a room for a participant.

        The usual status transitions are:
        UNKNOWN -> WAITING -> (ACCEPTED | DENIED)

        Flow:
        1. Check current status
        2. If waiting, refresh timeout to maintain position
        3. If unknown, add to waiting list
        4. If accepted, generate LiveKit config
        5. If denied, do nothing.
        """

        participant = None
        if participant_id:
            participant = self._get_participant(room.id, participant_id)

        is_new_participant = participant is None
        if is_new_participant:
            participant = self._create_participant(username)

        room_id = str(room.id)
        user_role = room.get_role(user)

        if self.can_bypass_lobby(room=room, user=user, role=user_role):
            if not is_new_participant:
                self.clear_participant_cache(room.id, participant.id)
            participant.status = LobbyParticipantStatus.ACCEPTED

            livekit_config = utils.generate_livekit_config(
                room_id=room_id,
                user=user,
                username=participant.username,
                color=participant.color,
                configuration=room.configuration,
                participant_id=participant.id,
                role=user_role,
            )
            return participant, livekit_config

        livekit_config = None

        if is_new_participant:
            self._save_participant(room.id, participant)
            self._notify_entry_request(room_id)

        elif participant.status == LobbyParticipantStatus.WAITING:
            self.refresh_waiting_status(room.id, participant.id)

        elif participant.status == LobbyParticipantStatus.ACCEPTED:
            # wrongly named, contains access token to join a room
            livekit_config = utils.generate_livekit_config(
                room_id=room_id,
                user=user,
                username=participant.username,
                color=participant.color,
                configuration=room.configuration,
                participant_id=participant.id,
                role=user_role,
            )

        return participant, livekit_config

    def refresh_waiting_status(self, room_id: UUID, participant_id: str):
        """Refresh timeout for waiting participant.

        Extends the waiting period for a participant to maintain their position
        in the lobby queue. Automatic removal if the participant is not
        actively checking their status.
        """
        cache.touch(
            self._get_cache_key(room_id, participant_id), settings.LOBBY_WAITING_TIMEOUT
        )
        self._index_touch(room_id)

    def _create_participant(self, username: str) -> LobbyParticipant:
        """Create a new waiting participant without persisting it.

        Participant identifiers are minted here, server-side, exclusively.
        """
        participant_id = str(uuid.uuid4())
        participant = LobbyParticipant(
            status=LobbyParticipantStatus.WAITING,
            username=username,
            id=participant_id,
            entered_at=timezone.now().isoformat(),
            color=utils.generate_color(participant_id),
        )
        return participant

    def _save_participant(self, room_id: UUID, participant: LobbyParticipant):
        """Persist a participant in the room's lobby."""
        cache.set(
            self._get_cache_key(room_id, participant.id),
            participant.to_dict(),
            timeout=settings.LOBBY_WAITING_TIMEOUT,
        )
        self._index_add(room_id, participant.id)

    def _notify_entry_request(self, room_id: str):
        """Notify room participants of a new entry request."""
        try:
            utils.notify_participants(
                room_name=room_id,
                notification_data={
                    "type": settings.LOBBY_NOTIFICATION_TYPE,
                },
            )
        except utils.NotificationError:
            # If room not created yet, there is no participants to notify
            logger.exception("Failed to notify room participants")

    def _get_participant(
        self, room_id: UUID, participant_id: str
    ) -> Optional[LobbyParticipant]:
        """Check participant's current status in the lobby."""

        cache_key = self._get_cache_key(room_id, participant_id)
        data = cache.get(cache_key)

        if not data:
            return None

        try:
            return LobbyParticipant.from_dict(data)
        except LobbyParticipantParsingError:
            logger.error("Corrupted participant data found and removed: %s", cache_key)
            cache.delete(cache_key)
            return None

    def list_waiting_participants(self, room_id: UUID) -> Sequence[dict]:
        """List all waiting participants for a room."""

        member_ids = self._index_members(room_id)

        if not member_ids:
            return ()

        keys_by_id = {
            participant_id: self._get_cache_key(room_id, participant_id)
            for participant_id in member_ids
        }
        data = cache.get_many(list(keys_by_id.values()))

        dead_ids = []
        waiting_participants = []

        for participant_id, cache_key in keys_by_id.items():
            raw_participant = data.get(cache_key)
            if raw_participant is None:
                dead_ids.append(participant_id)
                continue
            try:
                participant = LobbyParticipant.from_dict(raw_participant)
            except LobbyParticipantParsingError:
                cache.delete(cache_key)
                dead_ids.append(participant_id)
                continue
            if participant.status == LobbyParticipantStatus.WAITING:
                waiting_participants.append(participant.to_dict())

        self._index_remove(room_id, *dead_ids)

        waiting_participants.sort(key=lambda p: p["entered_at"], reverse=True)

        return tuple(waiting_participants)

    def handle_participant_entry(
        self,
        room_id: UUID,
        participant_id: str,
        allow_entry: bool,
    ) -> LobbyParticipant:
        """Handle decision on participant entry.

        Updates participant status based on allow_entry:
        - If accepted: ACCEPTED status with extended timeout matching LiveKit token
        - If denied: DENIED status with short timeout allowing status check and retry
        """
        if allow_entry:
            decision = {
                "status": LobbyParticipantStatus.ACCEPTED,
                "timeout": settings.LOBBY_ACCEPTED_TIMEOUT,
            }
        else:
            decision = {
                "status": LobbyParticipantStatus.DENIED,
                "timeout": settings.LOBBY_DENIED_TIMEOUT,
            }

        return self._update_participant_status(room_id, participant_id, **decision)

    def _update_participant_status(
        self,
        room_id: UUID,
        participant_id: str,
        status: LobbyParticipantStatus,
        timeout: int,
    ) -> LobbyParticipant:
        """Update participant status with appropriate timeout."""

        cache_key = self._get_cache_key(room_id, participant_id)

        data = cache.get(cache_key)
        if not data:
            logger.error("Participant %s not found", participant_id)
            raise LobbyParticipantNotFound("Participant not found")

        try:
            participant = LobbyParticipant.from_dict(data)
        except LobbyParticipantParsingError:
            logger.exception(
                "Removed corrupted data for participant %s:", participant_id
            )
            cache.delete(cache_key)
            raise

        participant.status = status
        cache.set(cache_key, participant.to_dict(), timeout=timeout)
        self._index_touch(room_id)

        return participant

    def clear_room_cache(self, room_id: UUID) -> None:
        """Clear all participant entries from the cache for a specific room."""

        member_ids = self._index_members(room_id)
        if member_ids:
            cache.delete_many(
                [
                    self._get_cache_key(room_id, participant_id)
                    for participant_id in member_ids
                ]
            )
        self._redis().delete(self._get_index_key(room_id))

    def clear_participant_cache(self, room_id: UUID, participant_id: str) -> None:
        """Clear a given participant entry from the cache for a specific room."""

        cache_key = self._get_cache_key(room_id, participant_id)
        cache.delete(cache_key)
        self._index_remove(room_id, participant_id)