Open source video conferencing app powered by LiveKit. Built with Django and React.
✨(backend) expose livekit reconnect settings in the config
briquetb9748983acef
diff --git a/CHANGELOG.md b/CHANGELOG.mdindex 8cb8afbe..c74c0ee9 100644--- a/CHANGELOG.md+++ b/CHANGELOG.md@@ -11,6 +11,7 @@ and this project adheres to### Changed- ⬆️(frontend) upgrade livekit-client to 2.23.0+- ✨(backend) expose LiveKit reconnection settings in the config### Fixeddiff --git a/docs/features/signaling.md b/docs/features/signaling.mdindex 6d04ce90..59399115 100644--- a/docs/features/signaling.md+++ b/docs/features/signaling.md@@ -11,14 +11,23 @@ We do not cover internal signaling behavior. For full reference, see the [LiveKi> [!IMPORTANT]> The WebSocket is the backbone of LiveKit signaling. All signaling messages rely on it, and without it, ICE candidate exchange and peer connection setup cannot occur. If the WebSocket connection is lost, the client automatically attempts to resume the RTC session once connectivity is restored.+## Reconnection+When the WebSocket drops, for instance after a LiveKit node crash or during a Redis outage, every client in every room loses it at the same time. To keep them from all reconnecting at once, each client waits a random delay before every attempt. The first delay is at most `LIVEKIT_RECONNECT_BASE_DELAY_MS`. That ceiling then doubles after each failed attempt, capped at `LIVEKIT_RECONNECT_MAX_DELAY_MS`, and each later delay falls between half the ceiling and the ceiling. The first attempt always starts within 5 seconds of the drop.++A client gives up once its reconnection has lasted longer than `LIVEKIT_RECONNECT_GIVE_UP_AFTER_MS`, and then shows a "connection lost" page. While only signaling is down and its media still flows, it keeps trying instead. A client that loses the connection again less than `LIVEKIT_RECONNECT_BACKOFF_RESET_MS` after reconnecting resumes the backoff one step above where it stopped.## Environment Variables-| Variable | Type | Default | Purpose |-| ----------------------------------------- | ------- | ------- | --------------------------------------------------------------------------------------------------------------------------------------------------------- |-| `LIVEKIT_FORCE_WSS_PROTOCOL` | Boolean | `True` | Forces the WebSocket URL to use `wss://`. Required for legacy browsers (Firefox <124, Chrome <125, Edge <125) where HTTPS URLs in `WebSocket()` may fail. |-| `LIVEKIT_ENABLE_FIREFOX_PROXY_WORKAROUND` | Boolean | `True` | Workaround for Firefox clients behind proxies that fail to establish WebSocket connections. Pre-establishes a dummy connection to “prime” the WebSocket. |+| Variable | Type | Default | Purpose |+| ----------------------------------------- | ------- | -------- | --------------------------------------------------------------------------------------------------------------------------------------------------------- |+| `LIVEKIT_FORCE_WSS_PROTOCOL` | Boolean | `False` | Forces the WebSocket URL to use `wss://`. Required for legacy browsers (Firefox <124, Chrome <125, Edge <125) where HTTPS URLs in `WebSocket()` may fail. |+| `LIVEKIT_ENABLE_FIREFOX_PROXY_WORKAROUND` | Boolean | `False` | Workaround for Firefox clients behind proxies that fail to establish WebSocket connections. Pre-establishes a dummy connection to “prime” the WebSocket. |+| `LIVEKIT_RECONNECT_BACKOFF_ENABLED` | Boolean | `True` | Enables the reconnection backoff described above. When `False`, clients use LiveKit's default reconnection policy. |+| `LIVEKIT_RECONNECT_BASE_DELAY_MS` | Integer | `1000` | Longest wait before the first reconnection attempt, in milliseconds. It doubles after each failed attempt. Must be greater than 0. |+| `LIVEKIT_RECONNECT_MAX_DELAY_MS` | Integer | `10000` | Longest wait between two reconnection attempts, in milliseconds. Must be greater than 0. |+| `LIVEKIT_RECONNECT_GIVE_UP_AFTER_MS` | Integer | `180000` | How long a client keeps trying to reconnect, in milliseconds. Not applied while its media still flows. Must be greater than 0. |+| `LIVEKIT_RECONNECT_BACKOFF_RESET_MS` | Integer | `120000` | How long a connection must stay up, in milliseconds, for the next reconnection to start from the shortest delay again. With `0`, every reconnection does. |> [!NOTE]> Questions? Open an issue on [GitHub](https://github.com/suitenumerique/meet/issues/new?assignees=&labels=bug&template=Bug_report.md) or join our [Matrix community](https://matrix.to/#/#meet-official:matrix.org).diff --git a/docs/installation/kubernetes.md b/docs/installation/kubernetes.mdindex ef0735e2..5fef9827 100644--- a/docs/installation/kubernetes.md+++ b/docs/installation/kubernetes.md@@ -413,6 +413,11 @@ These are the environmental options available on meet backend.| LIVEKIT_API_TIMEOUT_SECONDS | Seconds before a call to the LiveKit API gives up | 10 || LIVEKIT_FORCE_WSS_PROTOCOL | Enables WSS protocol conversion for legacy browser compatibility (Firefox <124, Chrome <125, Edge <125) where HTTPS URLs fail in WebSocket() constructor. | false || LIVEKIT_ENABLE_FIREFOX_PROXY_WORKAROUND | Firefox-only connection warmup: pre-calls WebSocket endpoint (expecting 401) to initialize cache, resolving proxy/network connectivity issues. | false |+| LIVEKIT_RECONNECT_BACKOFF_ENABLED | Spread client reconnections with a random exponential backoff. When false, clients use LiveKit's default reconnection policy | true |+| LIVEKIT_RECONNECT_BASE_DELAY_MS | Longest wait before the first reconnection attempt, in milliseconds. It doubles after each failed attempt. Must be greater than 0 | 1000 |+| LIVEKIT_RECONNECT_MAX_DELAY_MS | Longest wait between two reconnection attempts, in milliseconds. Must be greater than 0 | 10000 |+| LIVEKIT_RECONNECT_GIVE_UP_AFTER_MS | How long a client keeps trying to reconnect, in milliseconds. Not applied while its media still flows. Must be greater than 0 | 180000 |+| LIVEKIT_RECONNECT_BACKOFF_RESET_MS | How long a connection must stay up, in milliseconds, for the next reconnection to start from the shortest delay again. With 0, every reconnection does | 120000 || RESOURCE_DEFAULT_ACCESS_LEVEL | Default resource access level for rooms | public || ALLOW_UNREGISTERED_ROOMS | Allow usage of unregistered rooms | true || ROOM_INACTIVITY_DELETION_DAYS | Days without being started after which a room is purged. Unset to never purge | |diff --git a/src/backend/core/api/__init__.py b/src/backend/core/api/__init__.pyindex c7b57b62..d60a7823 100644--- a/src/backend/core/api/__init__.py+++ b/src/backend/core/api/__init__.py@@ -86,6 +86,13 @@ def get_frontend_configuration(request):"enable_firefox_proxy_workaround": settings.LIVEKIT_ENABLE_FIREFOX_PROXY_WORKAROUND,"default_sources": settings.LIVEKIT_DEFAULT_SOURCES,"default_video_codec": settings.LIVEKIT_DEFAULT_VIDEO_CODEC,+ "reconnect": {+ "backoff_enabled": settings.LIVEKIT_RECONNECT_BACKOFF_ENABLED,+ "base_delay_ms": settings.LIVEKIT_RECONNECT_BASE_DELAY_MS,+ "max_delay_ms": settings.LIVEKIT_RECONNECT_MAX_DELAY_MS,+ "give_up_after_ms": settings.LIVEKIT_RECONNECT_GIVE_UP_AFTER_MS,+ "backoff_reset_ms": settings.LIVEKIT_RECONNECT_BACKOFF_RESET_MS,+ },},"allow_unregistered_rooms": settings.ALLOW_UNREGISTERED_ROOMS,"authenticated_users_can_edit_display_name": (diff --git a/src/backend/core/tests/test_api_config_retrieve.py b/src/backend/core/tests/test_api_config_retrieve.pynew file mode 100644index 00000000..1e486340--- /dev/null+++ b/src/backend/core/tests/test_api_config_retrieve.py@@ -0,0 +1,40 @@+"""Test the LiveKit reconnection settings exposed by the config endpoint."""++import pytest+from rest_framework.test import APIClient++pytestmark = pytest.mark.django_db+++def test_api_config_retrieve_livekit_reconnect_defaults():+ """Without any override, the frontend gets the default backoff."""+ response = APIClient().get("/api/v1.0/config/")++ assert response.status_code == 200+ assert response.json()["livekit"]["reconnect"] == {+ "backoff_enabled": True,+ "base_delay_ms": 1000,+ "max_delay_ms": 10000,+ "give_up_after_ms": 180000,+ "backoff_reset_ms": 120000,+ }+++def test_api_config_retrieve_livekit_reconnect_settings(settings):+ """Each reconnection setting reaches the frontend unchanged."""+ settings.LIVEKIT_RECONNECT_BACKOFF_ENABLED = False+ settings.LIVEKIT_RECONNECT_BASE_DELAY_MS = 500+ settings.LIVEKIT_RECONNECT_MAX_DELAY_MS = 30000+ settings.LIVEKIT_RECONNECT_GIVE_UP_AFTER_MS = 600000+ settings.LIVEKIT_RECONNECT_BACKOFF_RESET_MS = 60000++ response = APIClient().get("/api/v1.0/config/")++ assert response.status_code == 200+ assert response.json()["livekit"]["reconnect"] == {+ "backoff_enabled": False,+ "base_delay_ms": 500,+ "max_delay_ms": 30000,+ "give_up_after_ms": 600000,+ "backoff_reset_ms": 60000,+ }diff --git a/src/backend/core/tests/test_settings_livekit_reconnect.py b/src/backend/core/tests/test_settings_livekit_reconnect.pynew file mode 100644index 00000000..5ab2cfcd--- /dev/null+++ b/src/backend/core/tests/test_settings_livekit_reconnect.py@@ -0,0 +1,24 @@+"""Unit tests for the value of the LiveKit reconnection delay settings."""++import pytest++from meet.settings import StrictlyPositiveIntegerValue++[email protected]("raw,expected", [("1", 1), (" 15000 ", 15000)])+def test_strictly_positive_integer_value_parses(raw, expected):+ """A delay above 0 is read as an integer."""+ assert StrictlyPositiveIntegerValue(environ=False).to_python(raw) == expected+++def test_strictly_positive_integer_value_rejects_zero():+ """0 stops the settings module loading, unlike with PositiveIntegerValue."""+ with pytest.raises(ValueError, match="greater than 0"):+ StrictlyPositiveIntegerValue(environ=False).to_python("0")++[email protected]("raw", ["-1", "1e3", "1000ms", ""])+def test_strictly_positive_integer_value_rejects_invalid(raw):+ """A negative or non-integer value stops the settings module loading."""+ with pytest.raises(ValueError):+ StrictlyPositiveIntegerValue(environ=False).to_python(raw)diff --git a/src/backend/meet/settings.py b/src/backend/meet/settings.pyindex ced1df39..0bdeca74 100755--- a/src/backend/meet/settings.py+++ b/src/backend/meet/settings.py@@ -68,6 +68,17 @@ class VideoCodecValue(values.Value):return codec+class StrictlyPositiveIntegerValue(values.PositiveIntegerValue):+ """An integer greater than 0"""++ def to_python(self, value):+ """Ensure the integer is greater than 0."""+ int_value = super().to_python(value)+ if int_value == 0:+ raise ValueError(f"Expected an integer greater than 0, got {value!r}.")+ return int_value++class ResolutionSpec(BaseModel):"""An value of RECORDING_ENCODING_AVAILABLE_RESOLUTIONS."""@@ -787,6 +798,28 @@ class Base(Configuration):LIVEKIT_DEFAULT_VIDEO_CODEC = VideoCodecValue("vp9", environ_name="LIVEKIT_DEFAULT_VIDEO_CODEC", environ_prefix=None)+ # Livekit websocket reconnection exponential backoff config sent to the frontend.+ # Before its first reconnection attempt, a client waits a random delay up to the base+ # delay. That ceiling doubles after every failed attempt, capped at the max delay, and+ # later delays fall between half the ceiling and the ceiling.+ # It gives up after the give-up delay unless the media still flows.+ # After a successful reconnection, a new disconnection starting sooner than the reset+ # delay after the last one resumes the backoff one step above where that one stopped.+ LIVEKIT_RECONNECT_BACKOFF_ENABLED = values.BooleanValue(+ True, environ_name="LIVEKIT_RECONNECT_BACKOFF_ENABLED", environ_prefix=None+ )+ LIVEKIT_RECONNECT_BASE_DELAY_MS = StrictlyPositiveIntegerValue(+ 1000, environ_name="LIVEKIT_RECONNECT_BASE_DELAY_MS", environ_prefix=None+ )+ LIVEKIT_RECONNECT_MAX_DELAY_MS = StrictlyPositiveIntegerValue(+ 10000, environ_name="LIVEKIT_RECONNECT_MAX_DELAY_MS", environ_prefix=None+ )+ LIVEKIT_RECONNECT_GIVE_UP_AFTER_MS = StrictlyPositiveIntegerValue(+ 180000, environ_name="LIVEKIT_RECONNECT_GIVE_UP_AFTER_MS", environ_prefix=None+ )+ LIVEKIT_RECONNECT_BACKOFF_RESET_MS = values.PositiveIntegerValue(+ 120000, environ_name="LIVEKIT_RECONNECT_BACKOFF_RESET_MS", environ_prefix=None+ )CONNECTION_TEST_ENABLED = values.BooleanValue(environ_name="CONNECTION_TEST_ENABLED",environ_prefix=None,