✨(backend) add roomkit viewset to start a room without WebRTC join

Introduce a new viewset that lets the roomkit start a room even when
no WebRTC participant has joined yet.

This is a first entry point that will be extended over time with
more actions a roomkit needs to be able to trigger.

Known limitations:

* The responsibility around SIP rules is currently split between
  the telephony feature and the roomkit one. This may need a
  refactor later on to consolidate ownership in a single place.
* The default throttle might be too low for production usage and
  will likely need to be revisited.

src/backend/core/tests/roomkit/__init__.py

@@ -0,0 +1 @@
+"""Tests for the roomkit API of the Meet core app."""

src/backend/core/tests/roomkit/test_api_roomkit_join.py

@@ -0,0 +1,266 @@
+"""
+Test the roomkit join server-to-server API endpoint.
+"""
+
+# pylint: disable=redefined-outer-name,unused-argument
+
+from unittest import mock
+
+import pytest
+
+from ...factories import RoomFactory
+from ...services.telephony import TelephonyException
+
+pytestmark = pytest.mark.django_db
+
+
+@pytest.fixture
+def mock_telephony_service():
+    """Mock the TelephonyService used by the roomkit viewset."""
+    with mock.patch("core.roomkit.viewsets.TelephonyService") as mock_service_class:
+        yield mock_service_class.return_value
+
+
+def test_join_anonymous(settings, mock_telephony_service, client):
+    """Requests without an Authorization header should be rejected."""
+    settings.ROOMKIT_ENABLED = True
+    settings.ROOMKIT_SERVER_TO_SERVER_API_TOKEN = "testAuthToken"
+
+    room = RoomFactory(pin_code="1234567890")
+
+    response = client.post("/api/v1.0/roomkit/join/", {"pin_code": room.pin_code})
+
+    assert response.status_code == 401
+    assert response.json() == {"detail": "Authorization header is missing."}
+    mock_telephony_service.ensure_dispatch_rule.assert_not_called()
+
+
+def test_join_malformed_authorization_header(settings, mock_telephony_service, client):
+    """Requests with a malformed Authorization header should be rejected."""
+    settings.ROOMKIT_ENABLED = True
+    settings.ROOMKIT_SERVER_TO_SERVER_API_TOKEN = "testAuthToken"
+
+    room = RoomFactory(pin_code="1234567890")
+
+    response = client.post(
+        "/api/v1.0/roomkit/join/",
+        {"pin_code": room.pin_code},
+        HTTP_AUTHORIZATION="testAuthToken",
+    )
+
+    assert response.status_code == 401
+    assert response.json() == {"detail": "Invalid authorization header."}
+    mock_telephony_service.ensure_dispatch_rule.assert_not_called()
+
+
+def test_join_wrong_bearer(settings, mock_telephony_service, client):
+    """Requests with an incorrect bearer token should be rejected."""
+    settings.ROOMKIT_ENABLED = True
+    settings.ROOMKIT_SERVER_TO_SERVER_API_TOKEN = "testAuthToken"
+
+    room = RoomFactory(pin_code="1234567890")
+
+    response = client.post(
+        "/api/v1.0/roomkit/join/",
+        {"pin_code": room.pin_code},
+        HTTP_AUTHORIZATION="Bearer wrongAuthToken",
+    )
+
+    assert response.status_code == 401
+    assert response.json() == {"detail": "Invalid server-to-server token."}
+    mock_telephony_service.ensure_dispatch_rule.assert_not_called()
+
+
+def test_join_token_not_configured(settings, mock_telephony_service, client):
+    """Requests should be rejected when no server-to-server token is configured."""
+
+    settings.ROOMKIT_ENABLED = True
+    settings.ROOMKIT_SERVER_TO_SERVER_API_TOKEN = None
+
+    room = RoomFactory(pin_code="1234567890")
+
+    response = client.post(
+        "/api/v1.0/roomkit/join/",
+        {"pin_code": room.pin_code},
+        HTTP_AUTHORIZATION="Bearer testAuthToken",
+    )
+
+    assert response.status_code == 401
+    mock_telephony_service.ensure_dispatch_rule.assert_not_called()
+
+
+def test_join_roomkit_disabled(settings, mock_telephony_service, client):
+    """The endpoint should not be exposed when the roomkit integration is disabled."""
+
+    settings.ROOMKIT_ENABLED = False
+    settings.ROOMKIT_SERVER_TO_SERVER_API_TOKEN = "testAuthToken"
+
+    room = RoomFactory(pin_code="1234567890")
+
+    response = client.post(
+        "/api/v1.0/roomkit/join/",
+        {"pin_code": room.pin_code},
+        HTTP_AUTHORIZATION="Bearer testAuthToken",
+    )
+
+    assert response.status_code == 404
+    mock_telephony_service.ensure_dispatch_rule.assert_not_called()
+
+
+def test_join_missing_pin(settings, mock_telephony_service, client):
+    """Requests without a PIN code should be rejected."""
+
+    settings.ROOMKIT_ENABLED = True
+    settings.ROOMKIT_SERVER_TO_SERVER_API_TOKEN = "testAuthToken"
+
+    response = client.post(
+        "/api/v1.0/roomkit/join/",
+        {},
+        HTTP_AUTHORIZATION="Bearer testAuthToken",
+    )
+
+    assert response.status_code == 400
+    assert response.json() == {"pin_code": ["This field is required."]}
+    mock_telephony_service.ensure_dispatch_rule.assert_not_called()
+
+
+def test_join_blank_pin(settings, mock_telephony_service, client):
+    """Requests with a blank PIN code should be rejected."""
+
+    settings.ROOMKIT_ENABLED = True
+    settings.ROOMKIT_SERVER_TO_SERVER_API_TOKEN = "testAuthToken"
+
+    response = client.post(
+        "/api/v1.0/roomkit/join/",
+        {"pin_code": ""},
+        HTTP_AUTHORIZATION="Bearer testAuthToken",
+    )
+
+    assert response.status_code == 400
+    assert response.json() == {"pin_code": ["This field may not be blank."]}
+    mock_telephony_service.ensure_dispatch_rule.assert_not_called()
+
+
+def test_join_wrong_pin_length(settings, mock_telephony_service, client):
+    """Requests with a PIN code of unexpected length should be rejected."""
+
+    settings.ROOMKIT_ENABLED = True
+    settings.ROOMKIT_SERVER_TO_SERVER_API_TOKEN = "testAuthToken"
+    settings.ROOM_TELEPHONY_PIN_LENGTH = 10
+
+    response = client.post(
+        "/api/v1.0/roomkit/join/",
+        {"pin_code": "123"},
+        HTTP_AUTHORIZATION="Bearer testAuthToken",
+    )
+
+    assert response.status_code == 400
+    assert response.json() == {"pin_code": ["PIN code length is invalid."]}
+    mock_telephony_service.ensure_dispatch_rule.assert_not_called()
+
+
+def test_join_unknown_pin(settings, mock_telephony_service, client):
+    """Requests with a PIN matching no room should return 404 and create no rule."""
+    settings.ROOMKIT_ENABLED = True
+    settings.ROOMKIT_SERVER_TO_SERVER_API_TOKEN = "testAuthToken"
+
+    RoomFactory(pin_code="1234567890")
+
+    response = client.post(
+        "/api/v1.0/roomkit/join/",
+        {"pin_code": "0987654321"},
+        HTTP_AUTHORIZATION="Bearer testAuthToken",
+    )
+
+    assert response.status_code == 404
+    assert response.json() == {"detail": "No room found for this PIN code."}
+    mock_telephony_service.ensure_dispatch_rule.assert_not_called()
+
+
+def test_join_success(settings, mock_telephony_service, client):
+    """Requests with a valid PIN should create the dispatch rule."""
+    settings.ROOMKIT_ENABLED = True
+    settings.ROOMKIT_SERVER_TO_SERVER_API_TOKEN = "testAuthToken"
+
+    room = RoomFactory(pin_code="1234567890")
+    mock_telephony_service.ensure_dispatch_rule.return_value = True
+
+    response = client.post(
+        "/api/v1.0/roomkit/join/",
+        {"pin_code": room.pin_code},
+        HTTP_AUTHORIZATION="Bearer testAuthToken",
+    )
+
+    assert response.status_code == 200
+    assert response.json() == {"status": "success"}
+    mock_telephony_service.ensure_dispatch_rule.assert_called_once_with(room)
+
+
+def test_join_dispatch_rule_already_exists(settings, mock_telephony_service, client):
+    """Requests should succeed when the dispatch rule already exists (idempotency)."""
+
+    settings.ROOMKIT_ENABLED = True
+    settings.ROOMKIT_SERVER_TO_SERVER_API_TOKEN = "testAuthToken"
+
+    room = RoomFactory(pin_code="1234567890")
+    mock_telephony_service.ensure_dispatch_rule.return_value = False
+
+    response = client.post(
+        "/api/v1.0/roomkit/join/",
+        {"pin_code": room.pin_code},
+        HTTP_AUTHORIZATION="Bearer testAuthToken",
+    )
+
+    assert response.status_code == 200
+    assert response.json() == {"status": "success"}
+    mock_telephony_service.ensure_dispatch_rule.assert_called_once_with(room)
+
+
+def test_join_tracks_analytics_event(settings, mock_telephony_service, client):
+    """Successful joins should be tracked with an analytics event."""
+
+    settings.ROOMKIT_ENABLED = True
+    settings.ROOMKIT_SERVER_TO_SERVER_API_TOKEN = "testAuthToken"
+
+    room = RoomFactory(pin_code="1234567890")
+    mock_telephony_service.ensure_dispatch_rule.return_value = True
+
+    with mock.patch("core.roomkit.viewsets.analytics.capture") as mock_capture:
+        response = client.post(
+            "/api/v1.0/roomkit/join/",
+            {"pin_code": room.pin_code},
+            HTTP_AUTHORIZATION="Bearer testAuthToken",
+        )
+
+    assert response.status_code == 200
+    mock_capture.assert_called_once()
+    _user, event, properties = mock_capture.call_args[0]
+    assert str(event) == "roomkit_joined"
+    assert properties == {
+        "room_id": str(room.pk),
+        "dispatch_rule_created": True,
+    }
+
+
+def test_join_telephony_failure(settings, mock_telephony_service, client):
+    """Requests should fail with a server error when the telephony service fails."""
+
+    settings.ROOMKIT_ENABLED = True
+    settings.ROOMKIT_SERVER_TO_SERVER_API_TOKEN = "testAuthToken"
+
+    room = RoomFactory(pin_code="1234567890")
+    mock_telephony_service.ensure_dispatch_rule.side_effect = TelephonyException(
+        "Could not create dispatch rule"
+    )
+
+    with mock.patch("core.roomkit.viewsets.analytics.capture") as mock_capture:
+        response = client.post(
+            "/api/v1.0/roomkit/join/",
+            {"pin_code": room.pin_code},
+            HTTP_AUTHORIZATION="Bearer testAuthToken",
+            raise_request_exception=False,
+        )
+
+    assert response.status_code == 500
+    mock_telephony_service.ensure_dispatch_rule.assert_called_once_with(room)
+    mock_capture.assert_not_called()

src/backend/core/tests/services/test_livekit_events.py

@@ -487,6 +487,24 @@ def test_handle_room_finished_clears_cache_and_deletes_dispatch_rule(
     mock_clear_cache.assert_called_once_with(mock_room_name)
 
 
+@mock.patch.object(LobbyService, "clear_room_cache")
+@mock.patch.object(TelephonyService, "delete_dispatch_rule")
+def test_handle_room_finished_deletes_dispatch_rule_when_only_roomkit_enabled(
+    mock_delete_dispatch_rule, mock_clear_cache, service, settings
+):
+    """Should delete dispatch rule when only roomkit is enabled when room finishes."""
+    settings.ROOM_TELEPHONY_ENABLED = False
+    settings.ROOMKIT_ENABLED = True
+    mock_room_name = uuid.uuid4()
+    mock_data = mock.MagicMock()
+    mock_data.room.name = str(mock_room_name)
+
+    service._handle_room_finished(mock_data)
+
+    mock_delete_dispatch_rule.assert_called_once_with(mock_room_name)
+    mock_clear_cache.assert_called_once_with(mock_room_name)
+
+
 @mock.patch.object(LobbyService, "clear_room_cache")
 @mock.patch.object(TelephonyService, "delete_dispatch_rule")
 def test_handle_room_finished_skips_telephony_when_disabled(
@@ -494,6 +512,7 @@ def test_handle_room_finished_skips_telephony_when_disabled(
 ):
     """Should clear lobby cache but skip dispatch rule deletion when telephony is disabled."""
     settings.ROOM_TELEPHONY_ENABLED = False
+    settings.ROOMKIT_ENABLED = False
     mock_room_name = uuid.uuid4()
     mock_data = mock.MagicMock()
     mock_data.room.name = str(mock_room_name)
@@ -543,7 +562,7 @@ def test_handle_room_finished_raises_error_when_telephony_deletion_fails(
     mock_data.room.name = "00000000-0000-0000-0000-000000000000"
 
     expected_error = (
-        "Failed to delete telephony dispatch rule for room "
+        "Failed to delete sip dispatch rule for room "
         "00000000-0000-0000-0000-000000000000"
     )
 
@@ -579,12 +598,29 @@ def test_handle_room_started_creates_dispatch_rule_successfully(
     mock_create_dispatch_rule.assert_called_once_with(room)
 
 
+@mock.patch.object(TelephonyService, "create_dispatch_rule")
+def test_handle_room_started_creates_dispatch_rule_when_only_roomkit_enabled(
+    mock_create_dispatch_rule, service, settings
+):
+    """Should create dispatch rule when only roomkit is enabled during room start."""
+    settings.ROOM_TELEPHONY_ENABLED = False
+    settings.ROOMKIT_ENABLED = True
+    room = RoomFactory()
+    mock_data = mock.MagicMock()
+    mock_data.room.name = str(room.id)
+
+    service._handle_room_started(mock_data)
+
+    mock_create_dispatch_rule.assert_called_once_with(room)
+
+
 @mock.patch.object(TelephonyService, "create_dispatch_rule")
 def test_handle_room_started_skips_dispatch_rule_when_telephony_disabled(
     mock_create_dispatch_rule, service, settings
 ):
     """Should skip creating telephony dispatch rule when telephony is disabled during room start."""
     settings.ROOM_TELEPHONY_ENABLED = False
+    settings.ROOMKIT_ENABLED = False
     room = RoomFactory()
     mock_data = mock.MagicMock()
     mock_data.room.name = str(room.id)

src/backend/core/tests/services/test_telephony_service.py

@@ -20,7 +20,11 @@ from livekit.protocol.sip import (
 
 from core.factories import RoomFactory
 from core.models import RoomAccessLevel
-from core.services.telephony import TelephonyException, TelephonyService
+from core.services.telephony import (
+    DispatchRuleConflictError,
+    TelephonyException,
+    TelephonyService,
+)
 
 pytestmark = pytest.mark.django_db
 
@@ -303,3 +307,126 @@ def test_delete_dispatch_rule_api_failure(mock_client_factory, mock_list_rules):
 
     mock_api.sip.delete_sip_dispatch_rule.assert_called_once()
     mock_api.aclose.assert_called_once()
+
+
+@mock.patch("core.utils.create_livekit_client")
+def test_create_dispatch_rule_conflict_raises_dedicated_error(mock_client_factory):
+    """Test that a LiveKit conflict error raises DispatchRuleConflictError."""
+    telephony_service = TelephonyService()
+    room = RoomFactory(access_level=RoomAccessLevel.RESTRICTED, pin_code="1234")
+
+    mock_api = create_mock_livekit_client()
+    mock_api.sip.create_sip_dispatch_rule = mock.AsyncMock(
+        side_effect=TwirpError(
+            msg=(
+                "Dispatch rule for the same trunk, inbound number, number, and "
+                "PIN combination already exists in dispatch rule"
+            ),
+            code="already_exists",
+            status=409,
+        )
+    )
+    mock_client_factory.return_value = mock_api
+
+    with pytest.raises(DispatchRuleConflictError):
+        telephony_service.create_dispatch_rule(room)
+
+    mock_api.aclose.assert_called_once()
+
+
+@mock.patch("core.utils.create_livekit_client")
+def test_ensure_dispatch_rule_creates_when_missing(mock_client_factory):
+    """Test that ensure_dispatch_rule creates the rule when none exists."""
+    telephony_service = TelephonyService()
+    room = RoomFactory(access_level=RoomAccessLevel.RESTRICTED, pin_code="1234")
+
+    mock_api = create_mock_livekit_client()
+    mock_api.sip.list_sip_dispatch_rule = mock.AsyncMock(
+        return_value=ListSIPDispatchRuleResponse(items=[])
+    )
+    mock_api.sip.create_sip_dispatch_rule = mock.AsyncMock()
+    mock_client_factory.return_value = mock_api
+
+    created = telephony_service.ensure_dispatch_rule(room)
+
+    assert created is True
+    mock_api.sip.create_sip_dispatch_rule.assert_called_once()
+    create_request = mock_api.sip.create_sip_dispatch_rule.call_args[1]["create"]
+
+    assert isinstance(create_request, CreateSIPDispatchRuleRequest)
+    assert create_request.name == f"SIP_{str(room.id)}"
+    assert create_request.rule.dispatch_rule_direct.room_name == str(room.id)
+    assert create_request.rule.dispatch_rule_direct.pin == str(room.pin_code)
+
+
+@mock.patch("core.utils.create_livekit_client")
+def test_ensure_dispatch_rule_skips_when_existing(mock_client_factory):
+    """Test that ensure_dispatch_rule is idempotent when the rule already exists."""
+    telephony_service = TelephonyService()
+    room = RoomFactory(access_level=RoomAccessLevel.RESTRICTED, pin_code="1234")
+
+    existing_rule = SIPDispatchRuleInfo(
+        sip_dispatch_rule_id="rule-1", name=f"SIP_{str(room.id)}"
+    )
+    mock_api = create_mock_livekit_client()
+    mock_api.sip.list_sip_dispatch_rule = mock.AsyncMock(
+        return_value=ListSIPDispatchRuleResponse(items=[existing_rule])
+    )
+    mock_api.sip.create_sip_dispatch_rule = mock.AsyncMock()
+    mock_client_factory.return_value = mock_api
+
+    created = telephony_service.ensure_dispatch_rule(room)
+
+    assert created is False
+    mock_api.sip.create_sip_dispatch_rule.assert_not_called()
+
+
+@mock.patch("core.utils.create_livekit_client")
+def test_ensure_dispatch_rule_returns_false_on_conflict(mock_client_factory):
+    """Test that ensure_dispatch_rule tolerates a concurrent rule creation.
+
+    If the rule is created by a concurrent caller (e.g. the LiveKit webhook)
+    between the existence check and the creation, LiveKit rejects the
+    duplicate and ensure_dispatch_rule reports the rule as already existing.
+    """
+    telephony_service = TelephonyService()
+    room = RoomFactory(access_level=RoomAccessLevel.RESTRICTED, pin_code="1234")
+
+    mock_api = create_mock_livekit_client()
+    mock_api.sip.list_sip_dispatch_rule = mock.AsyncMock(
+        return_value=ListSIPDispatchRuleResponse(items=[])
+    )
+    mock_api.sip.create_sip_dispatch_rule = mock.AsyncMock(
+        side_effect=TwirpError(
+            msg=(
+                "Dispatch rule for the same trunk, inbound number, number, and "
+                "PIN combination already exists in dispatch rule"
+            ),
+            code="already_exists",
+            status=409,
+        )
+    )
+    mock_client_factory.return_value = mock_api
+
+    created = telephony_service.ensure_dispatch_rule(room)
+
+    assert created is False
+
+
+@mock.patch("core.utils.create_livekit_client")
+def test_ensure_dispatch_rule_raises_on_other_failures(mock_client_factory):
+    """Test that ensure_dispatch_rule propagates unexpected LiveKit failures."""
+    telephony_service = TelephonyService()
+    room = RoomFactory(access_level=RoomAccessLevel.RESTRICTED, pin_code="1234")
+
+    mock_api = create_mock_livekit_client()
+    mock_api.sip.list_sip_dispatch_rule = mock.AsyncMock(
+        return_value=ListSIPDispatchRuleResponse(items=[])
+    )
+    mock_api.sip.create_sip_dispatch_rule = mock.AsyncMock(
+        side_effect=TwirpError(msg="Internal server error", code="unknown", status=500)
+    )
+    mock_client_factory.return_value = mock_api
+
+    with pytest.raises(TelephonyException, match="Could not create dispatch rule"):
+        telephony_service.ensure_dispatch_rule(room)

src/backend/core/tests/test_models_rooms.py

@@ -184,12 +184,13 @@ def test_models_rooms_is_public_property():
 
 
 @mock.patch.object(Room, "generate_unique_pin_code")
-def test_telephony_disabled_skips_pin_generation(
+def test_telephony_and_roomkit_disabled_skips_pin_generation(
     mock_generate_unique_pin_code, settings
 ):
-    """Telephony disabled should not generate pin codes."""
+    """Telephony and roomkit both disabled should not generate pin codes."""
 
     settings.ROOM_TELEPHONY_ENABLED = False
+    settings.ROOMKIT_ENABLED = False
 
     room = RoomFactory()
 
@@ -197,6 +198,18 @@ def test_telephony_disabled_skips_pin_generation(
     assert room.pin_code is None
 
 
+def test_roomkit_enabled_generates_pin_code(settings):
+    """Roomkit enabled alone should generate pin codes, even without telephony."""
+
+    settings.ROOM_TELEPHONY_ENABLED = False
+    settings.ROOMKIT_ENABLED = True
+
+    room = RoomFactory()
+
+    assert room.pin_code is not None
+    assert len(room.pin_code) == settings.ROOM_TELEPHONY_PIN_LENGTH
+
+
 def test_default_and_custom_pin_length(settings):
     """Pin codes should be created with correct configured length."""