Skip to content

armgit / meet

Public Imported from GitHub
0

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

🐛(recording) handle FAILED and ABORTED LiveKit egresses

leod89b01b68193
diff --git a/CHANGELOG.md b/CHANGELOG.md
index 0ec74f57..52b87bca 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -29,6 +29,7 @@ and this project adheres to
- ⬆️(frontend) upgrade humanize-duration from 3.33.2 to 3.34.1
- ⬆️(addons) upgrade i18next from 26.4.0 to 26.4.1
- 🔖(helm) release chart 0.0.28
+- ♻️(backend) decouple recording event handling from LiveKit egress statuses
### Fixed
@@ -43,6 +44,8 @@ and this project adheres to
- 🐛(frontend) fix file permissions in the Docker image
- 🚸(frontend) inform user that recording waits until a track is published
- 🔒(backend) upgrade base image to python:3.13.5-alpine3.24
+- 🐛(backend) handle failed and aborted egresses
+- 🩹(frontend) notify participants when a recording fails or is aborted
## [1.31.0] - 2026-09-08
diff --git a/src/backend/core/migrations/0023_alter_recording_status.py b/src/backend/core/migrations/0023_alter_recording_status.py
new file mode 100644
index 00000000..e8ae47b3
--- /dev/null
+++ b/src/backend/core/migrations/0023_alter_recording_status.py
@@ -0,0 +1,18 @@
+# Generated by Django 5.2.16 on 2026-09-23 16:49
+
+from django.db import migrations, models
+
+
+class Migration(migrations.Migration):
+
+ dependencies = [
+ ('core', '0022_user_default_room_access_level_and_more'),
+ ]
+
+ operations = [
+ migrations.AlterField(
+ model_name='recording',
+ name='status',
+ field=models.CharField(choices=[('initiated', 'Initiated'), ('active', 'Active'), ('stopped', 'Stopped'), ('saved', 'Saved'), ('aborted', 'Aborted'), ('failed', 'Failed'), ('failed_to_start', 'Failed to Start'), ('failed_to_stop', 'Failed to Stop'), ('notification_succeeded', 'Notification succeeded'), ('external_process_successful', 'External process successful'), ('external_process_failed', 'External process failed')], default='initiated', max_length=50),
+ ),
+ ]
diff --git a/src/backend/core/models.py b/src/backend/core/models.py
index 895deb1b..84471d80 100644
--- a/src/backend/core/models.py
+++ b/src/backend/core/models.py
@@ -58,6 +58,7 @@ class RecordingStatusChoices(models.TextChoices):
STOPPED = "stopped", _("Stopped")
SAVED = "saved", _("Saved")
ABORTED = "aborted", _("Aborted")
+ FAILED = "failed", _("Failed")
FAILED_TO_START = "failed_to_start", _("Failed to Start")
FAILED_TO_STOP = "failed_to_stop", _("Failed to Stop")
NOTIFICATION_SUCCEEDED = "notification_succeeded", _("Notification succeeded")
@@ -79,17 +80,13 @@ class RecordingStatusChoices(models.TextChoices):
cls.STOPPED,
cls.SAVED,
cls.ABORTED,
+ cls.FAILED,
cls.EXTERNAL_PROCESS_SUCCESSFUL,
cls.EXTERNAL_PROCESS_FAILED,
cls.FAILED_TO_START,
cls.FAILED_TO_STOP,
}
- @classmethod
- def is_unsuccessful(cls, status):
- """Determine if the recording status represents an unsuccessful state."""
- return status in {cls.ABORTED, cls.FAILED_TO_START, cls.FAILED_TO_STOP}
-
class RecordingModeChoices(models.TextChoices):
"""Recording mode choices."""
@@ -582,6 +579,7 @@ class Recording(BaseModel):
4. NOTIFICATION_SUCCEEDED: External service has been notified of this recording
Error States:
+ - FAILED: Egress failed mid-recording
- FAILED_TO_START: Worker failed to initialize recording
- FAILED_TO_STOP: Worker failed during stop operation
- ABORTED: Recording was terminated before completion
diff --git a/src/backend/core/recording/enums.py b/src/backend/core/recording/enums.py
index 7bc2c1f4..40aa54c7 100644
--- a/src/backend/core/recording/enums.py
+++ b/src/backend/core/recording/enums.py
@@ -8,3 +8,50 @@ class FileExtension(Enum):
OGG = "ogg"
MP4 = "mp4"
+
+
+class RecordingWorkerEvent(Enum):
+ """Lifecycle events a recording worker reports about a recording.
+
+ It is intended to be free of SFU-specific vocabulary.
+ """
+
+ # The worker accepted the request but is not recording yet.
+ STARTING = "starting"
+ # The worker is recording.
+ STARTED = "started"
+ # The worker stopped recording and is flushing the media file.
+ SAVING = "saving"
+
+ # The recording ended, its media file is available.
+ COMPLETED = "completed"
+ # The recording ended on its configured limit, its media file is available.
+ LIMIT_REACHED = "limit reached"
+ # The worker stopped before it ever started recording, there is no media file.
+ ABORTED = "aborted"
+ # The worker hit a runtime error once recording had started; its media file
+ # may be available.
+ FAILED = "failed"
+
+ @classmethod
+ def is_terminal(cls, event):
+ """Determine if the event ends the recording's lifecycle (successful or not)."""
+
+ return event in TERMINAL_EVENTS
+
+
+SUCCESSFUL_EVENTS = frozenset(
+ {
+ RecordingWorkerEvent.COMPLETED,
+ RecordingWorkerEvent.LIMIT_REACHED,
+ }
+)
+
+UNSUCCESSFUL_EVENTS = frozenset(
+ {
+ RecordingWorkerEvent.ABORTED,
+ RecordingWorkerEvent.FAILED,
+ }
+)
+
+TERMINAL_EVENTS = SUCCESSFUL_EVENTS | UNSUCCESSFUL_EVENTS
diff --git a/src/backend/core/recording/services/recording_events.py b/src/backend/core/recording/services/recording_events.py
index 0151c052..8093a02a 100644
--- a/src/backend/core/recording/services/recording_events.py
+++ b/src/backend/core/recording/services/recording_events.py
@@ -1,13 +1,13 @@
-"""Recording-related LiveKit Events Service"""
-
-# pylint: disable=no-member
+"""Recording-related Events Service"""
from logging import getLogger
-from livekit import api
-
from core import models, utils
from core.models import Recording
+from core.recording.enums import (
+ UNSUCCESSFUL_EVENTS,
+ RecordingWorkerEvent,
+)
from core.recording.event.notification import notification_service
from core.services.room_management import (
RoomManagement,
@@ -26,22 +26,110 @@ class RecordingNotSavableError(Exception):
"""Recording cannot be saved because it is either in an error state or has already been saved"""
+# Notification sent to the room's participants, per event and recording mode.
+NOTIFICATION_PREFIXES = {
+ models.RecordingModeChoices.SCREEN_RECORDING: "screenRecording",
+ models.RecordingModeChoices.TRANSCRIPT: "transcription",
+}
+NOTIFICATION_SUFFIXES = {
+ RecordingWorkerEvent.LIMIT_REACHED: "LimitReached",
+ RecordingWorkerEvent.FAILED: "Failed",
+ RecordingWorkerEvent.ABORTED: "Aborted",
+}
+
+
+def get_notification_type(recording_mode, event):
+ """Generate corresponding notification type string."""
+ try:
+ return f"{NOTIFICATION_PREFIXES[recording_mode]}{NOTIFICATION_SUFFIXES[event]}"
+ except KeyError:
+ return None
+
+
+# Recording status in the room's metadata, per event.
+ROOM_METADATA_RECORDING_STATUSES = {
+ RecordingWorkerEvent.STARTED: "started",
+ RecordingWorkerEvent.SAVING: "saving",
+}
+
+
class RecordingEventsService:
- """Handles recording-related LiveKit webhook events."""
+ """Handles recording-related worker events.
+
+ Two entry points: `handle_update` for the events a running recording
+ reports, and `handle_terminal_event` for the one ending it.
+ """
@staticmethod
- def handle_update(recording: Recording, egress_status):
- """Handle egress status updates and sync recording state to room metadata."""
+ def log_worker_error(recording, event, error=None, error_code=None):
+ """Log FAILED at error level and expected ABORTED outcomes at info level."""
- room_name = str(recording.room.id)
+ if event == RecordingWorkerEvent.FAILED:
+ log = logger.error
+ elif event == RecordingWorkerEvent.ABORTED:
+ log = logger.info
+ else:
+ return
+
+ log(
+ "Recording worker reported %s for recording %s (room=%s, mode=%s): %s (error_code=%s)",
+ event.value,
+ recording.id,
+ recording.room.id,
+ recording.mode,
+ error or "no error reported",
+ error_code or "no error_code reported",
+ )
+
+ @staticmethod
+ def _notify_participants(recording: Recording, event: RecordingWorkerEvent):
+ """Notify the room's participants that a recording ended on the given event."""
+ recording_mode = recording.options.get("original_mode", None) or recording.mode
- status_mapping = {
- api.EgressStatus.EGRESS_ACTIVE: "started",
- api.EgressStatus.EGRESS_ENDING: "saving",
- api.EgressStatus.EGRESS_ABORTED: "aborted",
- }
+ notification_type = get_notification_type(recording_mode, event)
+ if not notification_type:
+ logger.warning(
+ "Could not find notification type for: "
+ "room=%s, recording_id=%s, mode=%s, event=%s",
+ recording.room.id,
+ recording.id,
+ recording_mode,
+ event.value,
+ )
+ return
- recording_status = status_mapping.get(egress_status)
+ try:
+ utils.notify_participants(
+ room_name=str(recording.room.id),
+ notification_data={"type": notification_type},
+ )
+ except utils.NotificationError as e:
+ raise RecordingEventsError(
+ f"Failed to notify participants in room '{recording.room.id}' about "
+ f"recording {event.value} (recording_id={recording.id})"
+ ) from e
+
+ @staticmethod
+ def _log_notification_failure(recording, event: RecordingWorkerEvent):
+ """Log a participant notification error on an unsuccessful recording."""
+
+ logger.exception(
+ "Failed to notify participants that recording %s %s (room=%s)",
+ recording.id,
+ event.value,
+ recording.room.id,
+ )
+
+ @staticmethod
+ def handle_update(recording: Recording, event: RecordingWorkerEvent):
+ """Handle non-terminal worker events and sync recording state to room metadata.
+
+ Terminal events are dispatched through `handle_terminal_event` instead.
+ """
+
+ room_name = str(recording.room.id)
+
+ recording_status = ROOM_METADATA_RECORDING_STATUSES.get(event)
if recording_status:
try:
RoomManagement.update_metadata(
@@ -55,42 +143,113 @@ class RecordingEventsService:
except RoomManagementException as e:
logger.exception("Failed to update room's metadata: %s", e)
- @staticmethod
- def handle_limit_reached(recording: Recording):
- """Stop recording and notify participants when limit is reached."""
+ def handle_terminal_event(self, recording: Recording, event: RecordingWorkerEvent):
+ """Run the appropriate handlers for a terminal event, given the recording's state."""
- recording.status = models.RecordingStatusChoices.STOPPED
- recording.save()
+ if not RecordingWorkerEvent.is_terminal(event):
+ logger.warning(
+ "Ignoring non-terminal event %s dispatched as a terminal event "
+ "for recording %s.",
+ event.value,
+ recording.id,
+ )
+ return
- notification_mapping = {
- models.RecordingModeChoices.SCREEN_RECORDING: "screenRecordingLimitReached",
- models.RecordingModeChoices.TRANSCRIPT: "transcriptionLimitReached",
- }
+ if event in UNSUCCESSFUL_EVENTS:
+ self._flag_unsuccessful_recording(recording, event)
+ else:
+ self._save_successful_recording(recording, event)
- notification_type = notification_mapping.get(recording.mode)
- if not notification_type:
+ def _flag_unsuccessful_recording(
+ self, recording: Recording, event: RecordingWorkerEvent
+ ):
+ """Persist the outcome of a recording the worker announced as unsuccessful."""
+
+ # Aborted
+ if event == RecordingWorkerEvent.ABORTED:
+ if recording.status == models.RecordingStatusChoices.ACTIVE:
+ self._apply_outcome(recording, event, self._handle_aborted)
+ return
+
+ # Failed
+ if event == RecordingWorkerEvent.FAILED:
+ if recording.is_savable():
+ self._apply_outcome(recording, event, self._handle_failed)
return
+ logger.error(
+ "Unsuccessful event %s has no handler; recording %s keeps status '%s'.",
+ event.value,
+ recording.id,
+ recording.status,
+ )
+
+ def _save_successful_recording(
+ self, recording: Recording, event: RecordingWorkerEvent
+ ):
+ """Save a recording whose media file the worker made available."""
+
+ # Limit reached
+ if (
+ event == RecordingWorkerEvent.LIMIT_REACHED
+ and recording.status == models.RecordingStatusChoices.ACTIVE
+ ):
+ self._apply_outcome(recording, event, self._handle_limit_reached)
+
try:
- utils.notify_participants(
- room_name=str(recording.room.id),
- notification_data={"type": notification_type},
- )
- except utils.NotificationError as e:
- logger.exception(
- "Failed to notify participants about recording limit reached: "
- "room=%s, recording_id=%s, mode=%s",
- recording.room.id,
+ self._handle_successful(recording)
+ except RecordingNotSavableError:
+ logger.warning(
+ "Recording %s is not savable on a completed recording "
+ "(already saved or in an error state); ignoring.",
recording.id,
- recording.mode,
)
- raise RecordingEventsError(
- f"Failed to notify participants in room '{recording.room.id}' about "
- f"recording limit reached (recording_id={recording.id})"
- ) from e
+
+ def _apply_outcome(
+ self, recording: Recording, event: RecordingWorkerEvent, handler
+ ):
+ """Keep notification failure non-fatal."""
+
+ try:
+ handler(recording)
+ except RecordingEventsError:
+ self._log_notification_failure(recording, event)
+
+ @classmethod
+ def _handle_limit_reached(cls, recording: Recording):
+ """Stop recording and notify participants when limit is reached."""
+
+ recording.status = models.RecordingStatusChoices.STOPPED
+ recording.save()
+
+ cls._notify_participants(recording, RecordingWorkerEvent.LIMIT_REACHED)
+
+ @classmethod
+ def _handle_failed(cls, recording: Recording):
+ """Set recording status to failed, matching the worker event, and notify participants.
+
+ FAILED: used when an actual runtime/pipeline error occurs after the
+ recording has started
+ """
+ recording.status = models.RecordingStatusChoices.FAILED
+ recording.save()
+
+ cls._notify_participants(recording, RecordingWorkerEvent.FAILED)
+
+ @classmethod
+ def _handle_aborted(cls, recording: Recording):
+ """Set recording status to aborted, matching the worker event, and notify participants.
+
+ ABORTED: used when the worker stops before it ever became
+ active/recording
+ """
+ recording.status = models.RecordingStatusChoices.ABORTED
+ recording.save()
+
+ cls._notify_participants(recording, RecordingWorkerEvent.ABORTED)
@staticmethod
- def handle_complete(recording: Recording):
+ def _handle_successful(recording: Recording):
"""Notify external services and save recording."""
if not recording.is_savable():
diff --git a/src/backend/core/recording/worker/services.py b/src/backend/core/recording/worker/services.py
index 227e3bb0..d74f9f7e 100644
--- a/src/backend/core/recording/worker/services.py
+++ b/src/backend/core/recording/worker/services.py
@@ -2,6 +2,8 @@
# pylint: disable=no-member
+import logging
+
from asgiref.sync import async_to_sync
from livekit import api as livekit_api
@@ -10,6 +12,8 @@ from ..enums import FileExtension
from .exceptions import WorkerConnectionError, WorkerResponseError
from .factories import WorkerServiceConfig
+logger = logging.getLogger(__name__)
+
class BaseEgressService:
"""Base egress defining common methods to manage and interact with LiveKit egress processes."""
@@ -49,6 +53,22 @@ class BaseEgressService:
finally:
await lkapi.aclose()
+ @staticmethod
+ def _log_egress_error(response, event: str):
+ """Log the reason LiveKit reported an unsuccessful egress on stop.
+
+ Mirrors the logging done in the 'egress_ended' webhook. The
+ StopEgress response carries the same error fields.
+ """
+ logger.error(
+ "Egress %s on stop (egress_id=%s, status=%s): %s (error_code=%s)",
+ event,
+ response.egress_id,
+ livekit_api.EgressStatus.Name(response.status),
+ response.error or "no error reported",
+ response.error_code or "no error_code reported",
+ )
+
def stop(self, worker_id: str) -> str:
"""Stop an ongoing egress worker.
The StopEgressRequest is shared among all types of egress,
@@ -66,14 +86,26 @@ class BaseEgressService:
"LiveKit response is missing the recording status."
)
- # To avoid exposing EgressStatus values and coupling with LiveKit outside of this class,
- # the response status is mapped to simpler "ABORTED", "STOPPED" or "FAILED_TO_STOP" strings.
+ if response.status == livekit_api.EgressStatus.EGRESS_ENDING:
+ return "STOPPED"
+
+ if response.status == livekit_api.EgressStatus.EGRESS_LIMIT_REACHED:
+ return "STOPPED"
+
+ # Cases below should be very infrequent as status changes should be
+ # received and processed by `handle_ended`, thus `stop` would not
+ # be called (unless failure and stop are very close in time).
+ # We therefore accept not to notify the user in this code branch.
+ # This could be fixed in a future refactoring.
if response.status == livekit_api.EgressStatus.EGRESS_ABORTED:
+ self._log_egress_error(response, "aborted")
return "ABORTED"
- if response.status == livekit_api.EgressStatus.EGRESS_ENDING:
- return "STOPPED"
+ if response.status == livekit_api.EgressStatus.EGRESS_FAILED:
+ self._log_egress_error(response, "failed")
+ return "FAILED"
+ self._log_egress_error(response, "failed to stop")
return "FAILED_TO_STOP"
def start(self, room_name, recording_id):
diff --git a/src/backend/core/services/livekit_events.py b/src/backend/core/services/livekit_events.py
index a155b40c..cbeb0d47 100644
--- a/src/backend/core/services/livekit_events.py
+++ b/src/backend/core/services/livekit_events.py
@@ -12,15 +12,12 @@ from django.conf import settings
from livekit import api
from core import models
+from core.recording.enums import RecordingWorkerEvent
from core.recording.services.metadata_collector import (
MetadataCollectorException,
MetadataCollectorService,
)
-from core.recording.services.recording_events import (
- RecordingEventsError,
- RecordingEventsService,
- RecordingNotSavableError,
-)
+from core.recording.services.recording_events import RecordingEventsService
from .lobby import LobbyService
from .presence import PresenceCache
@@ -84,6 +81,30 @@ class LiveKitWebhookEventType(Enum):
INGRESS_ENDED = "ingress_ended"
+# LiveKit egress statuses mapped to recording worker event statuses
+EGRESS_STATUS_TO_RECORDING_EVENT = {
+ api.EgressStatus.EGRESS_STARTING: RecordingWorkerEvent.STARTING,
+ api.EgressStatus.EGRESS_ACTIVE: RecordingWorkerEvent.STARTED,
+ api.EgressStatus.EGRESS_ENDING: RecordingWorkerEvent.SAVING,
+ api.EgressStatus.EGRESS_COMPLETE: RecordingWorkerEvent.COMPLETED,
+ api.EgressStatus.EGRESS_LIMIT_REACHED: RecordingWorkerEvent.LIMIT_REACHED,
+ api.EgressStatus.EGRESS_ABORTED: RecordingWorkerEvent.ABORTED,
+ api.EgressStatus.EGRESS_FAILED: RecordingWorkerEvent.FAILED,
+}
+
+
+def to_recording_event(egress_status):
+ """Translate a LiveKit egress status into a recording worker event."""
+
+ event = EGRESS_STATUS_TO_RECORDING_EVENT.get(egress_status)
+ if event is None:
+ logger.warning(
+ "Unmapped LiveKit egress status '%s', ignoring the event.",
+ egress_status,
+ )
+ return event
+
+
class LiveKitEventsService:
"""Service for processing and handling LiveKit webhook events and notifications."""
@@ -173,12 +194,20 @@ class LiveKitEventsService:
f"Recording with worker ID {egress_id} does not exist"
) from err
- egress_status = data.egress_info.status
- self.recording_events.handle_update(recording, egress_status)
+ event = to_recording_event(data.egress_info.status)
+ if event is None:
+ return
+
+ self.recording_events.handle_update(recording, event)
def _handle_egress_ended(self, data):
- """Handle 'egress_ended' event."""
+ """Handle 'egress_ended' event.
+
+ Egress ended is sent with one of these statuses:
+ EGRESS_COMPLETE, EGRESS_FAILED, EGRESS_ABORTED, EGRESS_LIMIT_REACHED
+ """
+ # Fetch recording
try:
recording = models.Recording.objects.select_related("room").get(
worker_id=data.egress_info.egress_id
@@ -188,6 +217,17 @@ class LiveKitEventsService:
f"Recording with worker ID {data.egress_info.egress_id} does not exist"
) from err
+ event = to_recording_event(data.egress_info.status)
+
+ # Log if/why the recording failed
+ self.recording_events.log_worker_error(
+ recording,
+ event,
+ error=data.egress_info.error,
+ error_code=data.egress_info.error_code,
+ )
+
+ # Update room
try:
room_name = str(recording.room.id)
RoomManagement.update_metadata(
@@ -201,38 +241,17 @@ class LiveKitEventsService:
except RoomManagementException as e:
logger.exception("Failed to update room's metadata: %s", e)
+ # Stop metadata collector
if recording.options.get("metadata_collector_dispatch_id", None) is not None:
try:
MetadataCollectorService().stop(recording)
except MetadataCollectorException:
logger.warning("Failed to stop the MetadataCollectorService")
- if (
- data.egress_info.status == api.EgressStatus.EGRESS_LIMIT_REACHED
- and recording.status == models.RecordingStatusChoices.ACTIVE
- ):
- try:
- self.recording_events.handle_limit_reached(recording)
- except RecordingEventsError as e:
- raise ActionFailedError(
- f"Failed to process limit reached event for recording {recording}"
- ) from e
-
- # Finalize the recording, the egress has uploaded the file to the storage
- if data.egress_info.status in [
- api.EgressStatus.EGRESS_COMPLETE,
- api.EgressStatus.EGRESS_LIMIT_REACHED,
- ]:
- try:
- self.recording_events.handle_complete(recording)
- except RecordingNotSavableError:
- logger.warning(
- "Recording %s is not savable on egress complete "
- "(already saved or in an error state); ignoring.",
- recording.id,
- )
+ if event is None:
+ return
- # Silently ignoring EGRESS_ABORTED, EGRESS_FAILED
+ self.recording_events.handle_terminal_event(recording, event)
@staticmethod
def _is_connection_test_room(room_name: str) -> bool:
diff --git a/src/backend/core/tests/recording/service/test_recording_events.py b/src/backend/core/tests/recording/service/test_recording_events.py
index cfd2b28a..7c344b6c 100644
--- a/src/backend/core/tests/recording/service/test_recording_events.py
+++ b/src/backend/core/tests/recording/service/test_recording_events.py
@@ -2,18 +2,23 @@
Test RecordingEventsService service.
"""
-# pylint: disable=redefined-outer-name
+# pylint: disable=redefined-outer-name,protected-access
+import logging
from unittest import mock
import pytest
from core.factories import RecordingFactory
+from core.recording.enums import RecordingWorkerEvent
from core.recording.services.recording_events import (
RecordingEventsError,
RecordingEventsService,
RecordingNotSavableError,
)
+from core.services.room_management import (
+ RoomManagementException,
+)
from core.utils import NotificationError
pytestmark = pytest.mark.django_db
@@ -34,10 +39,10 @@ def service():
)
@mock.patch("core.utils.notify_participants")
def test_handle_limit_reached_success(mock_notify, mode, notification_type, service):
- """Test handle_limit_reached stops recording and notifies participants."""
+ """Test _handle_limit_reached stops recording and notifies participants."""
recording = RecordingFactory(status="active", mode=mode)
- service.handle_limit_reached(recording)
+ service._handle_limit_reached(recording)
assert recording.status == "stopped"
mock_notify.assert_called_once_with(
@@ -48,13 +53,69 @@ def test_handle_limit_reached_success(mock_notify, mode, notification_type, serv
@pytest.mark.parametrize(
("mode", "notification_type"),
(
- ("screen_recording", "screenRecordingLimitReached"),
- ("transcript", "transcriptionLimitReached"),
+ ("screen_recording", "screenRecordingFailed"),
+ ("transcript", "transcriptionFailed"),
),
)
@mock.patch("core.utils.notify_participants")
-def test_handle_limit_reached_error(mock_notify, mode, notification_type, service):
- """Test handle_limit_reached raises RecordingEventsError when notification fails."""
+def test_handle_failed_success(mock_notify, mode, notification_type, service):
+ """Test _handle_failed marks recording as failed and notifies participants."""
+
+ recording = RecordingFactory(status="active", mode=mode)
+ service._handle_failed(recording)
+
+ assert recording.status == "failed"
+ mock_notify.assert_called_once_with(
+ room_name=str(recording.room.id), notification_data={"type": notification_type}
+ )
+
+
+ ("mode", "notification_type"),
+ (
+ ("screen_recording", "screenRecordingAborted"),
+ ("transcript", "transcriptionAborted"),
+ ),
+)
[email protected]("core.utils.notify_participants")
+def test_handle_aborted_success(mock_notify, mode, notification_type, service):
+ """Test _handle_aborted marks recording as aborted and notifies participants."""
+
+ recording = RecordingFactory(status="active", mode=mode)
+ service._handle_aborted(recording)
+
+ assert recording.status == "aborted"
+ mock_notify.assert_called_once_with(
+ room_name=str(recording.room.id), notification_data={"type": notification_type}
+ )
+
+
+ ("mode", "notification_prefix"),
+ (("screen_recording", "screenRecording"), ("transcript", "transcription")),
+)
+ ("handler", "expected_status", "event", "notification_suffix"),
+ (
+ ("_handle_limit_reached", "stopped", "limit reached", "LimitReached"),
+ ("_handle_failed", "failed", "failed", "Failed"),
+ ("_handle_aborted", "aborted", "aborted", "Aborted"),
+ ),
+)
[email protected]("core.utils.notify_participants")
+def test_handle_event_notification_error( # noqa: PLR0913, PLR0917
+ mock_notify,
+ handler,
+ expected_status,
+ event,
+ notification_suffix,
+ mode,
+ notification_prefix,
+ service,
+): # pylint: disable=too-many-arguments,too-many-positional-arguments
+ """Test handlers raise RecordingEventsError when notifying participants fails,
+ while still applying the recording status of their event.
+ """
mock_notify.side_effect = NotificationError("Error notifying")
@@ -62,14 +123,15 @@ def test_handle_limit_reached_error(mock_notify, mode, notification_type, servic
with pytest.raises(
RecordingEventsError,
- match=r"Failed to notify participants in room '.+' "
- r"about recording limit reached \(recording_id=.+\)",
+ match=rf"Failed to notify participants in room '.+' "
+ rf"about recording {event} \(recording_id=.+\)",
):
- service.handle_limit_reached(recording)
+ getattr(service, handler)(recording)
- assert recording.status == "stopped"
+ assert recording.status == expected_status
mock_notify.assert_called_once_with(
- room_name=str(recording.room.id), notification_data={"type": notification_type}
+ room_name=str(recording.room.id),
+ notification_data={"type": f"{notification_prefix}{notification_suffix}"},
)
@@ -82,19 +144,19 @@ def test_handle_limit_reached_error(mock_notify, mode, notification_type, servic
"core.recording.services.recording_events.notification_service."
"notify_external_services"
)
-def test_handle_complete_saves_recording( # pylint: disable=too-many-arguments, too-many-positional-arguments
+def test_handle_successful_saves_recording( # pylint: disable=too-many-arguments, too-many-positional-arguments
mock_notify_external_services,
notify_return_value,
expected_status,
status,
service,
):
- """Test handle_complete notifies external services and saves a savable recording."""
+ """Test _handle_successful notifies external services and saves a savable recording."""
mock_notify_external_services.return_value = notify_return_value
recording = RecordingFactory(status=status)
- service.handle_complete(recording)
+ service._handle_successful(recording)
mock_notify_external_services.assert_called_once_with(recording)
@@ -104,23 +166,293 @@ def test_handle_complete_saves_recording( # pylint: disable=too-many-arguments,
@pytest.mark.parametrize(
"status",
- ["initiated", "saved", "notification_succeeded", "aborted", "failed_to_start"],
+ [
+ "initiated",
+ "saved",
+ "notification_succeeded",
+ "aborted",
+ "failed",
+ "failed_to_start",
+ ],
)
@mock.patch(
"core.recording.services.recording_events.notification_service."
"notify_external_services"
)
-def test_handle_complete_non_savable_recording(
+def test_handle_successful_non_savable_recording(
mock_notify_external_services, status, service
):
- """Test handle_complete refuses recordings that are already saved or in error."""
+ """Test _handle_successful refuses recordings that are already saved or in error."""
recording = RecordingFactory(status=status)
with pytest.raises(RecordingNotSavableError):
- service.handle_complete(recording)
+ service._handle_successful(recording)
mock_notify_external_services.assert_not_called()
recording.refresh_from_db()
assert recording.status == status
+
+
+ ("event", "recording_status"),
+ (
+ (RecordingWorkerEvent.STARTED, "started"),
+ (RecordingWorkerEvent.SAVING, "saving"),
+ ),
+)
[email protected]("core.services.room_management.RoomManagement.update_metadata")
+def test_handle_update_syncs_room_metadata(
+ mock_update_metadata, event, recording_status, service
+):
+ """Test handle_update updates the room's metadata."""
+
+ recording = RecordingFactory(status="active")
+ service.handle_update(recording, event)
+
+ mock_update_metadata.assert_called_once_with(
+ str(recording.room.id), {"recording_status": recording_status}
+ )
+
+
+ "event",
+ (
+ RecordingWorkerEvent.STARTING,
+ RecordingWorkerEvent.COMPLETED,
+ RecordingWorkerEvent.LIMIT_REACHED,
+ RecordingWorkerEvent.ABORTED,
+ RecordingWorkerEvent.FAILED,
+ ),
+)
[email protected]("core.services.room_management.RoomManagement.update_metadata")
+def test_handle_update_ignores_events_without_a_metadata_status(
+ mock_update_metadata, event, service
+):
+ """Test handle_update doesn't update metadata for events it doesn't match."""
+
+ recording = RecordingFactory(status="active")
+ service.handle_update(recording, event)
+
+ mock_update_metadata.assert_not_called()
+
+
+ ("event", "initial_status", "expected_status", "notification_type"),
+ (
+ (RecordingWorkerEvent.LIMIT_REACHED, "active", "saved", "LimitReached"),
+ (RecordingWorkerEvent.LIMIT_REACHED, "stopped", "saved", None),
+ (RecordingWorkerEvent.LIMIT_REACHED, "saved", "saved", None),
+ (RecordingWorkerEvent.ABORTED, "active", "aborted", "Aborted"),
+ (RecordingWorkerEvent.ABORTED, "failed_to_stop", "failed_to_stop", None),
+ (RecordingWorkerEvent.FAILED, "active", "failed", "Failed"),
+ (RecordingWorkerEvent.FAILED, "stopped", "failed", "Failed"),
+ (RecordingWorkerEvent.FAILED, "aborted", "aborted", None),
+ (RecordingWorkerEvent.COMPLETED, "active", "saved", None),
+ (RecordingWorkerEvent.COMPLETED, "saved", "saved", None),
+ ),
+)
+ "core.recording.services.recording_events.notification_service."
+ "notify_external_services"
+)
[email protected]("core.utils.notify_participants")
+def test_handle_terminal_event_dispatches_on_event_and_status( # noqa: PLR0913, PLR0917
+ mock_notify,
+ mock_notify_external_services,
+ event,
+ initial_status,
+ expected_status,
+ notification_type,
+ service,
+): # pylint: disable=too-many-arguments,too-many-positional-arguments
+ """Test handle_terminal_event chooses the right handler from the event and status."""
+
+ mock_notify_external_services.return_value = False
+
+ recording = RecordingFactory(status=initial_status, mode="screen_recording")
+ service.handle_terminal_event(recording, event)
+
+ recording.refresh_from_db()
+ assert recording.status == expected_status
+
+ if notification_type is None:
+ mock_notify.assert_not_called()
+ else:
+ mock_notify.assert_called_once_with(
+ room_name=str(recording.room.id),
+ notification_data={"type": f"screenRecording{notification_type}"},
+ )
+
+
+ "event",
+ (
+ RecordingWorkerEvent.STARTING,
+ RecordingWorkerEvent.STARTED,
+ RecordingWorkerEvent.SAVING,
+ ),
+)
+ "core.recording.services.recording_events.notification_service."
+ "notify_external_services"
+)
[email protected]("core.utils.notify_participants")
+def test_handle_terminal_event_ignores_non_terminal_events(
+ mock_notify, mock_notify_external_services, event, service, caplog
+):
+ """Test handle_terminal_event refuses non-terminal events."""
+
+ recording = RecordingFactory(status="active")
+
+ with caplog.at_level(logging.WARNING):
+ service.handle_terminal_event(recording, event)
+
+ assert f"Ignoring non-terminal event {event.value}" in caplog.text
+ mock_notify.assert_not_called()
+ mock_notify_external_services.assert_not_called()
+
+ recording.refresh_from_db()
+ assert recording.status == "active"
+
+
+ ("event", "expected_status"),
+ (
+ (RecordingWorkerEvent.LIMIT_REACHED, "saved"),
+ (RecordingWorkerEvent.ABORTED, "aborted"),
+ (RecordingWorkerEvent.FAILED, "failed"),
+ ),
+)
+ "core.recording.services.recording_events.notification_service."
+ "notify_external_services"
+)
[email protected]("core.utils.notify_participants")
+def test_handle_terminal_event_survives_a_notification_failure( # noqa: PLR0913, PLR0917
+ mock_notify,
+ mock_notify_external_services,
+ event,
+ expected_status,
+ service,
+ caplog,
+): # pylint: disable=too-many-arguments,too-many-positional-arguments
+ """Test handle_terminal_event logs a notification failure instead of raising.
+
+ The recording status must still be persisted: participants missing their
+ notification should not disturb recording.
+ """
+
+ mock_notify_external_services.return_value = False
+ mock_notify.side_effect = NotificationError("Error notifying")
+
+ recording = RecordingFactory(status="active")
+
+ with caplog.at_level(logging.ERROR):
+ service.handle_terminal_event(recording, event)
+
+ assert f"Failed to notify participants that recording {recording.id}" in caplog.text
+
+ recording.refresh_from_db()
+ assert recording.status == expected_status
+
+
+ "status",
+ ["failed_to_start", "aborted", "failed", "failed_to_stop", "saved", "initiated"],
+)
+ "core.recording.services.recording_events.notification_service."
+ "notify_external_services"
+)
+def test_handle_terminal_event_ignores_a_non_savable_recording(
+ mock_notify_external_services, status, service, caplog
+):
+ """Test handle_terminal_event handles a redelivered event idempotently.
+
+ A terminal event may be redelivered for an already finalized recording;
+ this must not raise, otherwise the webhook would 500 and be retried.
+ """
+
+ recording = RecordingFactory(status=status)
+
+ with caplog.at_level(logging.WARNING):
+ service.handle_terminal_event(recording, RecordingWorkerEvent.COMPLETED)
+
+ assert f"Recording {recording.id} is not savable" in caplog.text
+ mock_notify_external_services.assert_not_called()
+
+ recording.refresh_from_db()
+ assert recording.status == status
+
+
[email protected]("core.services.room_management.RoomManagement.update_metadata")
+def test_handle_update_survives_a_metadata_failure(
+ mock_update_metadata, service, caplog
+):
+ """Test handle_update logs a metadata failure instead of raising."""
+
+ mock_update_metadata.side_effect = RoomManagementException("Error updating")
+
+ recording = RecordingFactory(status="active")
+
+ with caplog.at_level(logging.ERROR):
+ service.handle_update(recording, RecordingWorkerEvent.SAVING)
+
+ assert "Failed to update room's metadata" in caplog.text
+
+
+ ("event", "expected_level"),
+ (
+ (RecordingWorkerEvent.ABORTED, logging.INFO),
+ (RecordingWorkerEvent.FAILED, logging.ERROR),
+ ),
+)
+def test_log_worker_error_reports_an_unsuccessful_event(
+ event, expected_level, service, caplog
+):
+ """Test log_worker_error records the reason the recording did not succeed."""
+
+ recording = RecordingFactory(status="active", mode="screen_recording")
+
+ with caplog.at_level(logging.INFO):
+ service.log_worker_error(
+ recording, event, error="could not connect to the room", error_code=500
+ )
+
+ assert (
+ f"Recording worker reported {event.value} for recording {recording.id}"
+ in caplog.text
+ )
+ assert "could not connect to the room" in caplog.text
+ assert "error_code=500" in caplog.text
+ worker_logs = [
+ record
+ for record in caplog.records
+ if record.name == "core.recording.services.recording_events"
+ ]
+ assert [record.levelno for record in worker_logs] == [expected_level]
+
+
+ "event",
+ (
+ RecordingWorkerEvent.STARTING,
+ RecordingWorkerEvent.STARTED,
+ RecordingWorkerEvent.SAVING,
+ RecordingWorkerEvent.COMPLETED,
+ RecordingWorkerEvent.LIMIT_REACHED,
+ None,
+ ),
+)
+def test_log_worker_error_stays_quiet_on_anything_else(event, service, caplog):
+ """Test log_worker_error ignores events other than FAILED and ABORTED."""
+
+ recording = RecordingFactory(status="active")
+
+ with caplog.at_level(logging.INFO):
+ service.log_worker_error(recording, event, error="some error", error_code=500)
+
+ assert "Recording worker reported" not in caplog.text
diff --git a/src/backend/core/tests/recording/test_api_recordings_retrieve.py b/src/backend/core/tests/recording/test_api_recordings_retrieve.py
index 827bdd09..9f186749 100644
--- a/src/backend/core/tests/recording/test_api_recordings_retrieve.py
+++ b/src/backend/core/tests/recording/test_api_recordings_retrieve.py
@@ -224,6 +224,7 @@ def test_api_recording_retrieve_expired(settings):
RecordingStatusChoices.INITIATED,
RecordingStatusChoices.ACTIVE,
RecordingStatusChoices.SAVED,
+ RecordingStatusChoices.FAILED,
RecordingStatusChoices.FAILED_TO_START,
RecordingStatusChoices.FAILED_TO_STOP,
RecordingStatusChoices.ABORTED,
diff --git a/src/backend/core/tests/recording/worker/test_services.py b/src/backend/core/tests/recording/worker/test_services.py
index 1c0b2c9d..b53175c3 100644
--- a/src/backend/core/tests/recording/worker/test_services.py
+++ b/src/backend/core/tests/recording/worker/test_services.py
@@ -4,6 +4,7 @@ Test worker service classes.
# pylint: disable=protected-access,redefined-outer-name,unused-argument,no-member
+import logging
from unittest.mock import AsyncMock, Mock, patch
import pytest
@@ -154,9 +155,9 @@ def test_base_egress_filepath_construction(service, filename, extension, expecte
"response_status,expected_result",
[
(livekit_api.EgressStatus.EGRESS_ABORTED, "ABORTED"),
+ (livekit_api.EgressStatus.EGRESS_FAILED, "FAILED"),
(livekit_api.EgressStatus.EGRESS_COMPLETE, "FAILED_TO_STOP"),
(livekit_api.EgressStatus.EGRESS_ENDING, "STOPPED"),
- (livekit_api.EgressStatus.EGRESS_FAILED, "FAILED_TO_STOP"),
],
)
def test_base_egress_stop_with_status(service, response_status, expected_result):
@@ -175,6 +176,32 @@ def test_base_egress_stop_with_status(service, response_status, expected_result)
assert result == expected_result
+ "response_status,event",
+ [
+ (livekit_api.EgressStatus.EGRESS_ABORTED, "aborted"),
+ (livekit_api.EgressStatus.EGRESS_FAILED, "failed"),
+ (livekit_api.EgressStatus.EGRESS_COMPLETE, "failed to stop"),
+ ],
+)
+def test_base_egress_stop_logs_livekit_error(service, response_status, event, caplog):
+ """Should log the reason LiveKit reported for an unsuccessful stop."""
+ mock_response = Mock(
+ status=response_status,
+ egress_id="test_worker_id",
+ error="could not connect to the room",
+ error_code=500,
+ )
+ service._handle_request = Mock(return_value=mock_response)
+
+ with caplog.at_level(logging.ERROR):
+ service.stop("test_worker_id")
+
+ assert f"Egress {event} on stop (egress_id=test_worker_id" in caplog.text
+ assert "could not connect to the room" in caplog.text
+ assert "error_code=500" in caplog.text
+
+
def test_base_egress_stop_missing_status(service):
"""Test stop method when response is missing status"""
# Mock _handle_request with missing status
diff --git a/src/backend/core/tests/services/test_livekit_events.py b/src/backend/core/tests/services/test_livekit_events.py
index 601e317b..9aa49a56 100644
--- a/src/backend/core/tests/services/test_livekit_events.py
+++ b/src/backend/core/tests/services/test_livekit_events.py
@@ -3,6 +3,7 @@ Test LiveKitEvents service.
"""
# pylint: disable=W0621,W0613, W0212, E0611
+import logging
import uuid
from unittest import mock
@@ -10,13 +11,16 @@ import pytest
from livekit.api import EgressStatus
from core.factories import RecordingFactory, RoomFactory
+from core.recording.enums import RecordingWorkerEvent
from core.recording.services.recording_events import RecordingEventsService
from core.services.livekit_events import (
+ EGRESS_STATUS_TO_RECORDING_EVENT,
ActionFailedError,
AuthenticationError,
InvalidPayloadError,
LiveKitEventsService,
api,
+ to_recording_event,
)
from core.services.lobby import LobbyService
from core.services.room_management import RoomManagementException
@@ -77,7 +81,7 @@ def test_initialization(
def test_handle_egress_ended_success( # pylint: disable=too-many-arguments, too-many-positional-arguments
mock_update_metadata, mock_notify, mode, notification_type, service
):
- """Should successfully stop recording and notifies all participant."""
+ """Should successfully stop recording and notify all participant."""
recording = RecordingFactory(worker_id="worker-1", mode=mode, status="active")
mock_data = mock.MagicMock()
@@ -104,7 +108,6 @@ def test_handle_egress_ended_success( # pylint: disable=too-many-arguments, too
(
(EgressStatus.EGRESS_ACTIVE, "started"),
(EgressStatus.EGRESS_ENDING, "saving"),
- (EgressStatus.EGRESS_ABORTED, "aborted"),
),
)
@mock.patch("core.services.room_management.RoomManagement.update_metadata")
@@ -125,29 +128,6 @@ def test_handle_egress_updated_success(
)
- "egress_status",
- (
- EgressStatus.EGRESS_FAILED,
- EgressStatus.EGRESS_LIMIT_REACHED,
- ),
-)
[email protected]("core.services.room_management.RoomManagement.update_metadata")
-def test_handle_egress_updated_non_handled(
- mock_update_metadata, egress_status, service
-):
- """Should ignore certain egress status and don't trigger metadata updates."""
-
- recording = RecordingFactory(worker_id="worker-1", status="initiated")
- mock_data = mock.MagicMock()
- mock_data.egress_info.egress_id = recording.worker_id
- mock_data.egress_info.status = egress_status
-
- service._handle_egress_updated(mock_data)
-
- mock_update_metadata.assert_not_called()
-
-
@pytest.mark.parametrize(
("mode", "notification_type"),
(
@@ -180,33 +160,38 @@ def test_handle_egress_ended_metadata_update_fails( # pylint: disable=too-many-
assert recording.status == "saved"
+ "core.recording.services.recording_events.notification_service."
+ "notify_external_services"
+)
@mock.patch("core.utils.notify_participants")
@mock.patch("core.services.room_management.RoomManagement.update_metadata")
def test_handle_egress_ended_notification_fails(
- mock_update_metadata, mock_notify, service
+ mock_update_metadata, mock_notify, mock_notify_external_services, service
):
- """Should raise ActionFailedError when notification fails but still stop recording."""
+ """Should still stop and save the recording when notifying participants fails."""
+
+ mock_notify_external_services.return_value = False
+ mock_notify.side_effect = NotificationError("Error notifying")
recording = RecordingFactory(worker_id="worker-1", status="active")
mock_data = mock.MagicMock()
mock_data.egress_info.egress_id = recording.worker_id
mock_data.egress_info.status = EgressStatus.EGRESS_LIMIT_REACHED
- mock_notify.side_effect = NotificationError("Error notifying")
-
- with pytest.raises(
- ActionFailedError,
- match=r"Failed to process limit reached event for recording .+",
- ):
- service._handle_egress_ended(mock_data)
-
- recording.refresh_from_db()
- assert recording.status == "stopped"
+ service._handle_egress_ended(mock_data)
+ mock_notify.assert_called_once_with(
+ room_name=str(recording.room.id),
+ notification_data={"type": "screenRecordingLimitReached"},
+ )
mock_update_metadata.assert_called_once_with(
str(recording.room.id), remove_keys=["recording_mode", "recording_status"]
)
+ recording.refresh_from_db()
+ assert recording.status == "saved"
+
@mock.patch("core.utils.notify_participants")
@mock.patch("core.services.room_management.RoomManagement.update_metadata")
@@ -232,17 +217,25 @@ def test_handle_egress_ended_recording_not_found(
assert recording.status == "active"
+ "egress_status",
+ (
+ EgressStatus.EGRESS_FAILED,
+ EgressStatus.EGRESS_ABORTED,
+ EgressStatus.EGRESS_LIMIT_REACHED,
+ ),
+)
@mock.patch("core.utils.notify_participants")
@mock.patch("core.services.room_management.RoomManagement.update_metadata")
-def test_handle_egress_ended_recording_not_active(
- mock_update_metadata, mock_notify, service
+def test_handle_egress_ended_recording_should_not_be_saved(
+ mock_update_metadata, mock_notify, egress_status, service
):
- """Should ignore non-active recordings."""
+ """Don't update status for recordings that must not be saved."""
recording = RecordingFactory(worker_id="worker-1", status="failed_to_stop")
mock_data = mock.MagicMock()
mock_data.egress_info.egress_id = "worker-1"
- mock_data.egress_info.status = EgressStatus.EGRESS_LIMIT_REACHED
+ mock_data.egress_info.status = egress_status
service._handle_egress_ended(mock_data)
@@ -255,12 +248,24 @@ def test_handle_egress_ended_recording_not_active(
assert recording.status == "failed_to_stop"
+ "core.recording.services.recording_events.notification_service."
+ "notify_external_services"
+)
@mock.patch("core.utils.notify_participants")
@mock.patch("core.services.room_management.RoomManagement.update_metadata")
-def test_handle_egress_ended_recording_not_limit_reached(
- mock_update_metadata, mock_notify, service
+def test_handle_egress_ended_complete_does_not_notify_participants(
+ mock_update_metadata, mock_notify, mock_notify_external_services, service
):
- """Should ignore egress non-limit-reached statuses."""
+ """Shouldn't notify participants on a successful egress.
+
+ EGRESS_COMPLETE is the only ended status that notifies no one: limit
+ reached, aborted and failed egresses each send their own notification.
+ A stopped recording is simply finalized, which is the nominal flow once
+ the egress uploaded the file of a user-initiated stop.
+ """
+
+ mock_notify_external_services.return_value = False
recording = RecordingFactory(worker_id="worker-1", status="stopped")
mock_data = mock.MagicMock()
@@ -273,7 +278,10 @@ def test_handle_egress_ended_recording_not_limit_reached(
mock_update_metadata.assert_called_once_with(
str(recording.room.id), remove_keys=["recording_mode", "recording_status"]
)
- assert recording.status == "stopped"
+ mock_notify_external_services.assert_called_once_with(recording)
+
+ recording.refresh_from_db()
+ assert recording.status == "saved"
@mock.patch("core.services.livekit_events.MetadataCollectorService")
@@ -333,96 +341,163 @@ def test_handle_egress_ended_does_not_call_metadata_collector_stop_when_conditio
mock_collector.stop.assert_not_called()
- "core.recording.services.recording_events.notification_service."
- "notify_external_services"
+ ("egress_status", "recording_status", "event", "expected_level"),
+ (
+ (EgressStatus.EGRESS_ABORTED, "active", "aborted", logging.INFO),
+ (EgressStatus.EGRESS_FAILED, "active", "failed", logging.ERROR),
+ # The synchronous stop may already have persisted the terminal status,
+ # and the error details exist only in the webhook payload.
+ (EgressStatus.EGRESS_ABORTED, "aborted", "aborted", logging.INFO),
+ (EgressStatus.EGRESS_FAILED, "failed", "failed", logging.ERROR),
+ ),
)
@mock.patch("core.utils.notify_participants")
@mock.patch("core.services.room_management.RoomManagement.update_metadata")
+def test_handle_egress_ended_logs_livekit_error( # noqa: PLR0913, PLR0917
+ mock_update_metadata,
+ mock_notify,
+ egress_status,
+ recording_status,
+ event,
+ expected_level,
+ service,
+ caplog,
+): # pylint: disable=too-many-arguments,too-many-positional-arguments
+ """Should log the reason LiveKit reported an unsuccessful egress."""
+
+ recording = RecordingFactory(worker_id="worker-1", status=recording_status)
+ mock_data = mock.MagicMock()
+ mock_data.egress_info.egress_id = recording.worker_id
+ mock_data.egress_info.status = egress_status
+ mock_data.egress_info.error = "could not connect to the room"
+ mock_data.egress_info.error_code = 500
+
+ with caplog.at_level(logging.INFO):
+ service._handle_egress_ended(mock_data)
+
+ assert (
+ f"Recording worker reported {event} for recording {recording.id}" in caplog.text
+ )
+ assert "could not connect to the room" in caplog.text
+ assert "error_code=500" in caplog.text
+
+ worker_logs = [
+ record
+ for record in caplog.records
+ if record.name == "core.recording.services.recording_events"
+ ]
+ assert [record.levelno for record in worker_logs] == [expected_level]
+
+
@pytest.mark.parametrize(
"egress_status",
- [EgressStatus.EGRESS_COMPLETE, EgressStatus.EGRESS_LIMIT_REACHED],
+ (EgressStatus.EGRESS_COMPLETE, EgressStatus.EGRESS_LIMIT_REACHED),
)
- "notify_return_value, recording_status",
- [(True, "notification_succeeded"), (False, "saved")],
+ "core.recording.services.recording_events.notification_service."
+ "notify_external_services"
)
-def test_handle_egress_ended_finalizes_recording( # noqa: PLR0913, PLR0917
[email protected]("core.utils.notify_participants")
[email protected]("core.services.room_management.RoomManagement.update_metadata")
+def test_handle_egress_ended_does_not_log_error_on_successful_egress( # noqa: PLR0913, PLR0917
mock_update_metadata,
mock_notify,
mock_notify_external_services,
- notify_return_value,
- recording_status,
egress_status,
service,
+ caplog,
): # pylint: disable=too-many-arguments,too-many-positional-arguments
- """Should notify external services and save the recording on egress completion
- (EGRESS_COMPLETE or EGRESS_LIMIT_REACHED).
- """
- mock_notify_external_services.return_value = notify_return_value
+ """Shouldn't log an egress error when LiveKit reports a successful egress."""
recording = RecordingFactory(worker_id="worker-1", status="active")
mock_data = mock.MagicMock()
mock_data.egress_info.egress_id = recording.worker_id
mock_data.egress_info.status = egress_status
- service._handle_egress_ended(mock_data)
-
- mock_notify_external_services.assert_called_once_with(recording)
+ with caplog.at_level(logging.ERROR):
+ service._handle_egress_ended(mock_data)
- recording.refresh_from_db()
- assert recording.status == recording_status
+ assert "Recording worker reported" not in caplog.text
- "egress_status",
- [
- EgressStatus.EGRESS_STARTING,
- EgressStatus.EGRESS_ACTIVE,
- EgressStatus.EGRESS_ENDING,
- EgressStatus.EGRESS_FAILED,
- EgressStatus.EGRESS_ABORTED,
- ],
-)
[email protected]("core.utils.notify_participants")
@mock.patch("core.services.room_management.RoomManagement.update_metadata")
-def test_handle_egress_ended_does_not_save_on_wrong_status(
- mock_update_metadata, egress_status, service
+def test_handle_egress_ended_logs_livekit_error_before_cleaning_up(
+ mock_update_metadata, mock_notify, service, caplog
):
- """Shouldn't save on invalid status."""
+ """Should log the failure reason even when the cleanup fails afterwards."""
+
+ mock_update_metadata.side_effect = RuntimeError("LiveKit is unreachable")
recording = RecordingFactory(worker_id="worker-1", status="active")
mock_data = mock.MagicMock()
mock_data.egress_info.egress_id = recording.worker_id
- mock_data.egress_info.status = egress_status
+ mock_data.egress_info.status = EgressStatus.EGRESS_FAILED
+ mock_data.egress_info.error = "could not connect to the room"
+ mock_data.egress_info.error_code = 500
- service._handle_egress_ended(mock_data)
+ with caplog.at_level(logging.ERROR), pytest.raises(RuntimeError):
+ service._handle_egress_ended(mock_data)
- recording.refresh_from_db()
- assert recording.status == "active"
+ assert (
+ f"Recording worker reported failed for recording {recording.id}" in caplog.text
+ )
+ assert "could not connect to the room" in caplog.text
+
+
+def test_egress_status_mapping_covers_every_livekit_status():
+ """Every egress status LiveKit can report must translate to a recording event."""
+
+ unmapped = [
+ name
+ for name in EgressStatus.keys()
+ if getattr(EgressStatus, name) not in EGRESS_STATUS_TO_RECORDING_EVENT
+ ]
+
+ assert not unmapped
@pytest.mark.parametrize(
- "status", ["failed_to_start", "aborted", "failed_to_stop", "saved", "initiated"]
+ ("egress_status", "expected_event"),
+ (
+ (EgressStatus.EGRESS_STARTING, RecordingWorkerEvent.STARTING),
+ (EgressStatus.EGRESS_ACTIVE, RecordingWorkerEvent.STARTED),
+ (EgressStatus.EGRESS_ENDING, RecordingWorkerEvent.SAVING),
+ (EgressStatus.EGRESS_COMPLETE, RecordingWorkerEvent.COMPLETED),
+ (EgressStatus.EGRESS_LIMIT_REACHED, RecordingWorkerEvent.LIMIT_REACHED),
+ (EgressStatus.EGRESS_ABORTED, RecordingWorkerEvent.ABORTED),
+ (EgressStatus.EGRESS_FAILED, RecordingWorkerEvent.FAILED),
+ ),
)
[email protected]("core.services.room_management.RoomManagement.update_metadata")
-def test_handle_egress_ended_ignores_non_savable_recording(
- mock_update_metadata, status, service
-):
- """Should handle non-savable recordings idempotently without raising.
+def test_to_recording_event_translates_egress_status(egress_status, expected_event):
+ """Should translate a LiveKit egress status into a recording worker event."""
- 'egress_ended' may be redelivered (e.g. for an already-saved recording);
- this must not raise, otherwise the webhook would 500 and LiveKit would retry.
- """
+ assert to_recording_event(egress_status) == expected_event
+
+
+def test_to_recording_event_returns_none_on_unmapped_status(caplog):
+ """Should warn and return None when LiveKit reports an unknown status."""
- recording = RecordingFactory(worker_id="worker-1", status=status)
+ with caplog.at_level(logging.WARNING):
+ event = to_recording_event(999)
+
+ assert event is None
+ assert "Unmapped LiveKit egress status" in caplog.text
+
+
[email protected]("core.services.room_management.RoomManagement.update_metadata")
+def test_handle_egress_updated_ignores_unmapped_status(mock_update_metadata, service):
+ """Shouldn't touch the room's metadata when the egress status is unknown."""
+
+ RecordingFactory(worker_id="worker-1", status="active")
mock_data = mock.MagicMock()
- mock_data.egress_info.egress_id = recording.worker_id
- mock_data.egress_info.status = EgressStatus.EGRESS_COMPLETE
+ mock_data.egress_info.egress_id = "worker-1"
+ mock_data.egress_info.status = 999
- service._handle_egress_ended(mock_data)
+ service._handle_egress_updated(mock_data)
- recording.refresh_from_db()
- assert recording.status == status
+ mock_update_metadata.assert_not_called()
@mock.patch.object(LobbyService, "clear_room_cache")
diff --git a/src/backend/core/tests/test_models_recording.py b/src/backend/core/tests/test_models_recording.py
index 4b6ec38d..6c7c3e75 100644
--- a/src/backend/core/tests/test_models_recording.py
+++ b/src/backend/core/tests/test_models_recording.py
@@ -157,6 +157,7 @@ def test_models_recording_is_savable_normal():
@pytest.mark.parametrize(
"status",
[
+ RecordingStatusChoices.FAILED,
RecordingStatusChoices.FAILED_TO_STOP,
RecordingStatusChoices.FAILED_TO_START,
RecordingStatusChoices.ABORTED,
@@ -279,6 +280,7 @@ def test_models_recording_is_saved_false_initiated():
@pytest.mark.parametrize(
"status",
[
+ RecordingStatusChoices.FAILED,
RecordingStatusChoices.FAILED_TO_STOP,
RecordingStatusChoices.FAILED_TO_START,
RecordingStatusChoices.ABORTED,
diff --git a/src/frontend/src/features/notifications/MainNotificationToast.tsx b/src/frontend/src/features/notifications/MainNotificationToast.tsx
index ff80f40c..fe3aa2ff 100644
--- a/src/frontend/src/features/notifications/MainNotificationToast.tsx
+++ b/src/frontend/src/features/notifications/MainNotificationToast.tsx
@@ -96,6 +96,10 @@ export const MainNotificationToast = () => {
case NotificationType.ScreenRecordingStopped:
case NotificationType.TranscriptionLimitReached:
case NotificationType.ScreenRecordingLimitReached:
+ case NotificationType.TranscriptionFailed:
+ case NotificationType.ScreenRecordingFailed:
+ case NotificationType.TranscriptionAborted:
+ case NotificationType.ScreenRecordingAborted:
toastQueue.add(
{
participant,
diff --git a/src/frontend/src/features/notifications/NotificationType.ts b/src/frontend/src/features/notifications/NotificationType.ts
index e42fe7c3..e1a49030 100644
--- a/src/frontend/src/features/notifications/NotificationType.ts
+++ b/src/frontend/src/features/notifications/NotificationType.ts
@@ -10,11 +10,15 @@ export enum NotificationType {
TranscriptionStarted = 'transcriptionStarted',
TranscriptionStopped = 'transcriptionStopped',
TranscriptionLimitReached = 'transcriptionLimitReached',
+ TranscriptionFailed = 'transcriptionFailed',
+ TranscriptionAborted = 'transcriptionAborted',
TranscriptionRequested = 'transcriptionRequested',
ScreenRecordingStarted = 'screenRecordingStarted',
ScreenRecordingStopped = 'screenRecordingStopped',
ScreenRecordingRequested = 'screenRecordingRequested',
ScreenRecordingLimitReached = 'screenRecordingLimitReached',
+ ScreenRecordingFailed = 'screenRecordingFailed',
+ ScreenRecordingAborted = 'screenRecordingAborted',
RecordingSaving = 'recordingSaving',
PermissionsRemoved = 'permissionsRemoved',
RoleChanged = 'roleChanged',
diff --git a/src/frontend/src/features/notifications/components/ToastAnyRecording.tsx b/src/frontend/src/features/notifications/components/ToastAnyRecording.tsx
index b3063ac2..6200882b 100644
--- a/src/frontend/src/features/notifications/components/ToastAnyRecording.tsx
+++ b/src/frontend/src/features/notifications/components/ToastAnyRecording.tsx
@@ -22,12 +22,20 @@ export function ToastAnyRecording({ state, ...props }: Readonly<ToastProps>) {
return 'transcript.stopped'
case NotificationType.TranscriptionLimitReached:
return 'transcript.limitReached'
+ case NotificationType.TranscriptionFailed:
+ return 'transcript.failed'
+ case NotificationType.TranscriptionAborted:
+ return 'transcript.aborted'
case NotificationType.ScreenRecordingStarted:
return 'screenRecording.started'
case NotificationType.ScreenRecordingStopped:
return 'screenRecording.stopped'
case NotificationType.ScreenRecordingLimitReached:
return 'screenRecording.limitReached'
+ case NotificationType.ScreenRecordingFailed:
+ return 'screenRecording.failed'
+ case NotificationType.ScreenRecordingAborted:
+ return 'screenRecording.aborted'
default:
return
}
diff --git a/src/frontend/src/features/notifications/components/ToastRegion.tsx b/src/frontend/src/features/notifications/components/ToastRegion.tsx
index f39c667b..ee9bb205 100644
--- a/src/frontend/src/features/notifications/components/ToastRegion.tsx
+++ b/src/frontend/src/features/notifications/components/ToastRegion.tsx
@@ -58,6 +58,10 @@ const renderToast = (
case NotificationType.ScreenRecordingStarted:
case NotificationType.ScreenRecordingStopped:
case NotificationType.ScreenRecordingLimitReached:
+ case NotificationType.TranscriptionFailed:
+ case NotificationType.ScreenRecordingFailed:
+ case NotificationType.TranscriptionAborted:
+ case NotificationType.ScreenRecordingAborted:
return <ToastAnyRecording key={toast.key} toast={toast} state={state} />
case NotificationType.TranscriptionRequested:
diff --git a/src/frontend/src/features/recording/types.ts b/src/frontend/src/features/recording/types.ts
index fc450bfe..3f2aa875 100644
--- a/src/frontend/src/features/recording/types.ts
+++ b/src/frontend/src/features/recording/types.ts
@@ -9,8 +9,9 @@ export enum RecordingStatus {
Stopped = 'stopped',
Saved = 'saved',
Aborted = 'aborted',
- FailedToStart = 'failedToStart',
- FailedToStop = 'failedToStop',
+ Failed = 'failed',
+ FailedToStart = 'failed_to_start',
+ FailedToStop = 'failed_to_stop',
NotificationSucceed = 'notification_succeeded',
ExternalProcessSuccessful = 'external_process_successful',
ExternalProcessFailed = 'external_process_failed',
diff --git a/src/frontend/src/locales/de/notifications.json b/src/frontend/src/locales/de/notifications.json
index 59e79f46..3b48dde0 100644
--- a/src/frontend/src/locales/de/notifications.json
+++ b/src/frontend/src/locales/de/notifications.json
@@ -37,6 +37,8 @@
"started": "{{name}} hat die Meeting-Transkription gestartet.",
"stopped": "{{name}} hat die Meeting-Transkription gestoppt.",
"limitReached": "Die Transkription hat die maximal zulässige Dauer überschritten und wird automatisch gespeichert.",
+ "failed": "Die Transkription wurde unerwartet beendet und konnte nicht gespeichert werden.",
+ "aborted": "Die Transkription konnte nicht gestartet werden.",
"requested": "{{name}} möchte die Meeting-Transkription starten."
},
"screenRecording": {
@@ -44,6 +46,8 @@
"started": "{{name}} hat die Meeting-Aufzeichnung gestartet.",
"stopped": "{{name}} hat die Meeting-Aufzeichnung gestoppt.",
"limitReached": "Die Aufzeichnung hat die maximal zulässige Dauer überschritten und wird automatisch gespeichert.",
+ "failed": "Die Aufzeichnung wurde unerwartet beendet und konnte nicht gespeichert werden.",
+ "aborted": "Die Aufzeichnung konnte nicht gestartet werden.",
"requested": "{{name}} möchte die Meeting-Aufzeichnung starten."
},
"recordingSave": {
diff --git a/src/frontend/src/locales/en/notifications.json b/src/frontend/src/locales/en/notifications.json
index cdac5a79..380503ed 100644
--- a/src/frontend/src/locales/en/notifications.json
+++ b/src/frontend/src/locales/en/notifications.json
@@ -37,6 +37,8 @@
"started": "{{name}} started the meeting transcription.",
"stopped": "{{name}} stopped the meeting transcription.",
"limitReached": "The transcription has exceeded the maximum allowed duration and will be automatically saved.",
+ "failed": "The transcription stopped unexpectedly and could not be saved.",
+ "aborted": "The transcription could not be started.",
"requested": "{{name}} wants to start the meeting transcription."
},
"screenRecording": {
@@ -44,6 +46,8 @@
"started": "{{name}} started the meeting recording.",
"stopped": "{{name}} stopped the meeting recording.",
"limitReached": "The recording has exceeded the maximum allowed duration and will be automatically saved.",
+ "failed": "The recording stopped unexpectedly and could not be saved.",
+ "aborted": "The recording could not be started.",
"requested": "{{name}} wants to start the meeting recording."
},
"recordingSave": {
diff --git a/src/frontend/src/locales/es/notifications.json b/src/frontend/src/locales/es/notifications.json
index f6c4d74e..d3f5fe38 100644
--- a/src/frontend/src/locales/es/notifications.json
+++ b/src/frontend/src/locales/es/notifications.json
@@ -37,6 +37,8 @@
"started": "{{name}} ha iniciado la transcripción de la reunión.",
"stopped": "{{name}} ha detenido la transcripción de la reunión.",
"limitReached": "La transcripción ha superado la duración máxima permitida, se va a guardar automáticamente.",
+ "failed": "La transcripción se ha interrumpido de forma inesperada y no se ha podido guardar.",
+ "aborted": "No se ha podido iniciar la transcripción.",
"requested": "{{name}} ha solicitado iniciar la transcripción."
},
"screenRecording": {
@@ -44,6 +46,8 @@
"started": "{{name}} ha iniciado la grabación de la reunión.",
"stopped": "{{name}} ha detenido la grabación de la reunión.",
"limitReached": "La grabación ha superado la duración máxima permitida, se va a guardar automáticamente.",
+ "failed": "La grabación se ha interrumpido de forma inesperada y no se ha podido guardar.",
+ "aborted": "No se ha podido iniciar la grabación.",
"requested": "{{name}} ha solicitado iniciar la grabación."
},
"recordingSave": {
diff --git a/src/frontend/src/locales/fr/notifications.json b/src/frontend/src/locales/fr/notifications.json
index 3d753f19..0d948cbd 100644
--- a/src/frontend/src/locales/fr/notifications.json
+++ b/src/frontend/src/locales/fr/notifications.json
@@ -37,6 +37,8 @@
"started": "{{name}} a démarré la transcription de la réunion.",
"stopped": "{{name}} a arrêté la transcription de la réunion.",
"limitReached": "La transcription a dépassé la durée maximale autorisée, elle va être automatiquement sauvegardée.",
+ "failed": "La transcription s'est interrompue de façon inattendue et n'a pas pu être sauvegardée.",
+ "aborted": "La transcription n'a pas pu être démarrée.",
"requested": "{{name}} a demandé à démarrer la transcription."
},
"screenRecording": {
@@ -44,6 +46,8 @@
"started": "{{name}} a démarré l'enregistrement de la réunion.",
"stopped": "{{name}} a arrêté l'enregistrement de la réunion.",
"limitReached": "L'enregistrement a dépassé la durée maximale autorisée, il va être automatiquement sauvegardé.",
+ "failed": "L'enregistrement s'est interrompu de façon inattendue et n'a pas pu être sauvegardé.",
+ "aborted": "L'enregistrement n'a pas pu être démarré.",
"requested": "{{name}} a demandé à démarrer l'enregistrement."
},
"recordingSave": {
diff --git a/src/frontend/src/locales/nl/notifications.json b/src/frontend/src/locales/nl/notifications.json
index 114b741a..01fb757f 100644
--- a/src/frontend/src/locales/nl/notifications.json
+++ b/src/frontend/src/locales/nl/notifications.json
@@ -37,6 +37,8 @@
"started": "{{name}} is de transcriptie van de vergadering gestart.",
"stopped": "{{name}} heeft de transcriptie van de vergadering gestopt.",
"limitReached": "De transcriptie heeft de maximaal toegestane duur overschreden en wordt automatisch opgeslagen.",
+ "failed": "De transcriptie is onverwacht gestopt en kon niet worden opgeslagen.",
+ "aborted": "De transcriptie kon niet worden gestart.",
"requested": "{{name}} wil graag de transcriptie starten."
},
"screenRecording": {
@@ -44,6 +46,8 @@
"started": "{{name}} is begonnen met het opnemen van de vergadering.",
"stopped": "{{name}} is gestopt met het opnemen van de vergadering.",
"limitReached": "De opname heeft de maximaal toegestane duur overschreden en wordt automatisch opgeslagen.",
+ "failed": "De opname is onverwacht gestopt en kon niet worden opgeslagen.",
+ "aborted": "De opname kon niet worden gestart.",
"requested": "{{name}} wil graag de opname starten."
},
"recordingSave": {