jrtc 3.1.0__py3-none-any.whl

jrtc/__init__.py

@@ -0,0 +1,40 @@
+"""Janus Core: plugin-agnostic Python bindings for Janus Gateway."""
+
+from importlib.metadata import PackageNotFoundError, version
+
+from jrtc.auth import JanusCredentialProvider, JanusCredentials
+from jrtc.lib import Plugin
+from jrtc.manager import JanusSessionManager
+from jrtc.messaging import (
+    JanusEventPublisher,
+    JanusResponseDispatcher,
+    LogVistaMetrics,
+    create_broker,
+)
+from jrtc.models import JanusRequest, JanusResponse
+from jrtc.session import JanusSession, SessionState, WebsocketSession
+from jrtc.transport import JanusTransport, WebsocketTransportClient
+
+try:
+    __version__ = version("jrtc")
+except PackageNotFoundError:  # source checkout
+    __version__ = "3.1.0"
+
+
+__all__ = (
+    "JanusCredentialProvider",
+    "JanusCredentials",
+    "JanusEventPublisher",
+    "JanusRequest",
+    "JanusResponse",
+    "JanusResponseDispatcher",
+    "JanusSession",
+    "JanusSessionManager",
+    "JanusTransport",
+    "LogVistaMetrics",
+    "Plugin",
+    "SessionState",
+    "WebsocketSession",
+    "WebsocketTransportClient",
+    "create_broker",
+)

jrtc/auth.py

@@ -0,0 +1,60 @@
+"""Credential providers for authenticated Janus API sessions."""
+
+from __future__ import annotations
+
+from collections.abc import Callable
+from dataclasses import dataclass
+from typing import Protocol, runtime_checkable
+
+from jrtc.models.request import BaseJanusRequest
+
+
+@dataclass(frozen=True, slots=True, repr=False)
+class JanusCredentials:
+    """Outer-envelope credentials required by an authenticated Janus server.
+
+    Values are deliberately redacted from ``repr`` and are applied immediately
+    before transport serialization.  Both mechanisms may be configured by a
+    server, although most deployments use one or the other.
+    """
+
+    token: str | None = None
+    api_secret: str | None = None
+
+    def __post_init__(self) -> None:
+        if self.token is not None and not self.token:
+            raise ValueError("token cannot be empty")
+        if self.api_secret is not None and not self.api_secret:
+            raise ValueError("api_secret cannot be empty")
+
+    def __repr__(self) -> str:
+        return (
+            "JanusCredentials("
+            f"token={'<redacted>' if self.token else None}, "
+            f"api_secret={'<redacted>' if self.api_secret else None})"
+        )
+
+    def apply(self, request: BaseJanusRequest) -> None:
+        if request.token is None:
+            request.token = self.token
+        if request.apisecret is None:
+            request.apisecret = self.api_secret
+
+
+@runtime_checkable
+class JanusCredentialProvider(Protocol):
+    """Provider used when credentials need rotation between requests."""
+
+    def __call__(self) -> JanusCredentials: ...
+
+
+type CredentialSource = JanusCredentials | Callable[[], JanusCredentials] | None
+
+
+def resolve_credentials(source: CredentialSource) -> JanusCredentials | None:
+    if source is None or isinstance(source, JanusCredentials):
+        return source
+    value = source()
+    if not isinstance(value, JanusCredentials):
+        raise TypeError("credential provider must return JanusCredentials")
+    return value

jrtc/conf/__init__.py

@@ -0,0 +1,4 @@
+from jrtc.conf._config import configure, settings
+from jrtc.conf._janus import Janus
+
+__all__ = ["Janus", "configure", "settings"]

jrtc/conf/_config.py

@@ -0,0 +1,173 @@
+"""Small, deterministic settings proxy.
+
+Applications may point ``JANUS_SETTINGS_MODULE`` at their own typed module.
+Environment parsing belongs in that module, avoiding the old heuristic that
+could turn numeric secrets into integers or comma-containing URLs into lists.
+"""
+
+from __future__ import annotations
+
+import importlib
+import os
+import threading
+from collections.abc import Mapping
+from types import ModuleType
+from typing import Any
+from urllib.parse import SplitResult, urlsplit, urlunsplit
+
+_DEFAULT_MODULE = "jrtc.conf.settings"
+_SENSITIVE_PARTS = ("SECRET", "TOKEN", "PASSWORD", "PASS", "CREDENTIAL", "API_KEY", "DSN")
+
+
+def _sensitive(name: str) -> bool:
+    normalized = name.upper().replace("-", "_")
+    return any(part in normalized for part in _SENSITIVE_PARTS)
+
+
+def _redact_url(value: str) -> str:
+    try:
+        parsed = urlsplit(value)
+        if not parsed.scheme or parsed.hostname is None or parsed.username is None:
+            return value
+        host = parsed.hostname
+        if ":" in host and not host.startswith("["):
+            host = f"[{host}]"
+        if parsed.port is not None:
+            host = f"{host}:{parsed.port}"
+        return urlunsplit(
+            SplitResult(
+                parsed.scheme, f"<redacted>@{host}", parsed.path, parsed.query, parsed.fragment
+            )
+        )
+    except ValueError:
+        return "<redacted-url>" if "://" in value and "@" in value else value
+
+
+def _redact_value(value: Any, *, name: str = "") -> Any:
+    if _sensitive(name) and value not in (None, ""):
+        return "<redacted>"
+    if isinstance(value, Mapping):
+        return {str(key): _redact_value(item, name=str(key)) for key, item in value.items()}
+    if isinstance(value, (list, tuple)):
+        return [_redact_value(item) for item in value]
+    return _redact_url(value) if isinstance(value, str) else value
+
+
+class SettingsLoadError(RuntimeError):
+    """Raised when a configured settings module cannot be loaded."""
+
+
+class Settings:
+    def __init__(self) -> None:
+        self._lock = threading.RLock()
+        self._module_name = os.getenv("JANUS_SETTINGS_MODULE", _DEFAULT_MODULE)
+        self._module: ModuleType | None = None
+        self._defaults: dict[str, Any] = {}
+        self._overrides: dict[str, Any] = {}
+        self._frozen = False
+
+    def configure(
+        self,
+        *,
+        module: str | None = None,
+        defaults: dict[str, Any] | None = None,
+        overrides: dict[str, Any] | None = None,
+        freeze: bool = False,
+    ) -> None:
+        """Select a settings module and explicit programmatic values.
+
+        Precedence is ``overrides > module > defaults``.  The operation resets
+        prior overrides so test/application lifecycles do not retain stale
+        configuration.
+        """
+
+        with self._lock:
+            if module is not None:
+                self._module_name = module
+            self._module = None
+            self._defaults = dict(defaults or {})
+            self._overrides = dict(overrides or {})
+            self._frozen = freeze
+
+    def reload(self) -> None:
+        with self._lock:
+            self._module = None
+
+    def _load(self) -> ModuleType:
+        with self._lock:
+            if self._module is not None:
+                return self._module
+            try:
+                module = importlib.import_module(self._module_name)
+            except Exception as exc:
+                raise SettingsLoadError(
+                    f"Could not import Janus settings module {self._module_name!r}"
+                ) from exc
+            self._module = module
+            return module
+
+    def __getattr__(self, name: str) -> Any:
+        if not name.isupper():
+            raise AttributeError(name)
+        with self._lock:
+            if name in self._overrides:
+                return self._overrides[name]
+            module = self._load()
+            if hasattr(module, name):
+                return getattr(module, name)
+            if name in self._defaults:
+                return self._defaults[name]
+        raise AttributeError(f"Janus setting {name!r} is not defined")
+
+    def __setattr__(self, name: str, value: Any) -> None:
+        if name.startswith("_"):
+            object.__setattr__(self, name, value)
+            return
+        if not name.isupper():
+            raise AttributeError("settings names must be uppercase")
+        with self._lock:
+            if self._frozen:
+                raise RuntimeError("settings are frozen")
+            self._overrides[name] = value
+
+    def as_dict(self, *, redact: bool = True) -> dict[str, Any]:
+        module = self._load()
+        values = {name: value for name, value in vars(module).items() if name.isupper()}
+        values = {**self._defaults, **values, **self._overrides}
+        if redact:
+            values = {name: _redact_value(value, name=name) for name, value in values.items()}
+        return values
+
+    def inspect_settings(self) -> dict[str, dict[str, Any]]:
+        module = self._load()
+        keys = set(self._defaults) | set(self._overrides)
+        keys.update(name for name in vars(module) if name.isupper())
+        result: dict[str, dict[str, Any]] = {}
+        for name in sorted(keys):
+            if name in self._overrides:
+                source = "override"
+            elif hasattr(module, name):
+                source = "module"
+            else:
+                source = "default"
+            value = _redact_value(getattr(self, name), name=name)
+            result[name] = {"value": value, "source": source}
+        return result
+
+
+settings = Settings()
+
+
+def configure(
+    *,
+    module: str | None = None,
+    defaults: dict[str, Any] | None = None,
+    overrides: dict[str, Any] | None = None,
+    freeze: bool = False,
+) -> None:
+    settings.configure(
+        module=module,
+        defaults=defaults,
+        overrides=overrides,
+        freeze=freeze,
+    )

jrtc/conf/_janus.py

@@ -0,0 +1,70 @@
+"""Explicit application-level access to an installed session manager."""
+
+from __future__ import annotations
+
+from typing import Any
+
+
+class Janus:
+    """Compatibility accessor populated explicitly by a host application.
+
+    The manager lifecycle remains explicit; importing this module starts no
+    thread, event loop, network connection, or background task.
+    """
+
+    _manager: Any | None = None
+    _manager_owner: object | None = None
+
+    @classmethod
+    def set_manager(cls, manager: Any | None) -> None:
+        """Install a manager for compatibility with single-app hosts.
+
+        Multi-lifecycle hosts should use :meth:`install_manager`, which prevents
+        one owner from clearing another owner's manager.
+        """
+
+        if manager is not None and cls._manager is not None and cls._manager is not manager:
+            raise RuntimeError("a Janus session manager is already installed in this process")
+        cls._manager = manager
+        cls._manager_owner = None
+
+    @classmethod
+    def install_manager(cls, manager: Any) -> object:
+        """Install one process-global compatibility manager and return its lease."""
+
+        if cls._manager is not None and cls._manager is not manager:
+            raise RuntimeError("a Janus session manager is already installed in this process")
+        owner = object()
+        cls._manager = manager
+        cls._manager_owner = owner
+        return owner
+
+    @classmethod
+    def remove_manager(cls, owner: object) -> None:
+        """Remove a manager only when ``owner`` holds the current lease."""
+
+        if cls._manager_owner is owner:
+            cls._manager = None
+            cls._manager_owner = None
+
+    @classmethod
+    def get_manager(cls) -> Any | None:
+        return cls._manager
+
+    @classmethod
+    def get_session(cls, key: str | int | None = None) -> Any | None:
+        manager = cls._manager
+        return None if manager is None else manager.get_session(key)
+
+    @classmethod
+    async def setup(cls) -> None:
+        if cls._manager is None:
+            raise RuntimeError("configure a JanusSessionManager before setup()")
+        await cls._manager.start()
+
+    @classmethod
+    async def teardown(cls) -> None:
+        manager, cls._manager = cls._manager, None
+        cls._manager_owner = None
+        if manager is not None:
+            await manager.stop()

jrtc/conf/settings/__init__.py

@@ -0,0 +1,45 @@
+"""Default environment-backed Janus Core settings."""
+
+from jrtc.conf.settings.global_settings import (
+    DEBUG,
+    jrtc_SECRET,
+    JANUS_BROKER_ADMISSION_TIMEOUT,
+    JANUS_BROKER_DRAIN_TIMEOUT,
+    JANUS_BROKER_ENGINE,
+    JANUS_BROKER_ENGINE_OPTIONS,
+    JANUS_BROKER_OPTIONS,
+    JANUS_BROKER_PUBLISH_TIMEOUT,
+    JANUS_BROKER_PUBLISH_WORKERS,
+    JANUS_BROKER_QUEUE_CAPACITY,
+    JANUS_BROKER_ROUTE,
+    JANUS_DETACH_CONCURRENCY,
+    JANUS_KEEPALIVE_FAILURES,
+    JANUS_KEEPALIVE_INTERVAL,
+    JANUS_REQUEST_TIMEOUT,
+    JANUS_SESSION_POOL_SIZE,
+    JANUS_SESSION_URL,
+    JANUS_SHUTDOWN_TIMEOUT,
+    JANUS_TOKEN,
+)
+
+__all__ = [
+    "DEBUG",
+    "jrtc_SECRET",
+    "JANUS_BROKER_ADMISSION_TIMEOUT",
+    "JANUS_BROKER_DRAIN_TIMEOUT",
+    "JANUS_BROKER_ENGINE",
+    "JANUS_BROKER_ENGINE_OPTIONS",
+    "JANUS_BROKER_OPTIONS",
+    "JANUS_BROKER_PUBLISH_TIMEOUT",
+    "JANUS_BROKER_PUBLISH_WORKERS",
+    "JANUS_BROKER_QUEUE_CAPACITY",
+    "JANUS_BROKER_ROUTE",
+    "JANUS_DETACH_CONCURRENCY",
+    "JANUS_KEEPALIVE_FAILURES",
+    "JANUS_KEEPALIVE_INTERVAL",
+    "JANUS_REQUEST_TIMEOUT",
+    "JANUS_SESSION_POOL_SIZE",
+    "JANUS_SESSION_URL",
+    "JANUS_SHUTDOWN_TIMEOUT",
+    "JANUS_TOKEN",
+]

jrtc/conf/settings/global_settings.py

@@ -0,0 +1,81 @@
+"""Secure environment-backed defaults for the Janus client core."""
+
+from __future__ import annotations
+
+import json
+import math
+import os
+from typing import Any
+
+
+def _boolean(name: str, default: bool = False) -> bool:
+    value = os.getenv(name)
+    if value is None:
+        return default
+    normalized = value.strip().lower()
+    if normalized in {"1", "true", "yes", "on"}:
+        return True
+    if normalized in {"0", "false", "no", "off"}:
+        return False
+    raise ValueError(f"{name} must be a boolean value")
+
+
+def _integer(name: str, default: int, *, minimum: int = 0) -> int:
+    value = int(os.getenv(name, str(default)))
+    if value < minimum:
+        raise ValueError(f"{name} must be at least {minimum}")
+    return value
+
+
+def _number(name: str, default: float, *, minimum: float = 0.0) -> float:
+    value = float(os.getenv(name, str(default)))
+    if not math.isfinite(value) or value < minimum:
+        raise ValueError(f"{name} must be finite and at least {minimum}")
+    return value
+
+
+def _optional(name: str) -> str | None:
+    value = os.getenv(name)
+    return value if value else None
+
+
+def _json_object(name: str) -> dict[str, Any]:
+    raw = os.getenv(name, "{}")
+    try:
+        value = json.loads(raw)
+    except json.JSONDecodeError as exc:
+        raise ValueError(f"{name} must contain valid JSON") from exc
+    if not isinstance(value, dict):
+        raise ValueError(f"{name} must contain a JSON object")
+    return value
+
+
+DEBUG = _boolean("JANUS_DEBUG", False)
+
+# Client runtime
+JANUS_SESSION_URL = os.getenv("JANUS_SESSION_URL", "ws://localhost:8188/janus")
+JANUS_REQUEST_TIMEOUT = _number("JANUS_REQUEST_TIMEOUT", 15.0, minimum=0.001)
+JANUS_SESSION_POOL_SIZE = _integer("JANUS_SESSION_POOL_SIZE", 1, minimum=1)
+JANUS_KEEPALIVE_INTERVAL = _number("JANUS_KEEPALIVE_INTERVAL", 25.0, minimum=0.001)
+JANUS_KEEPALIVE_FAILURES = _integer("JANUS_KEEPALIVE_FAILURES", 3, minimum=1)
+JANUS_SHUTDOWN_TIMEOUT = _number("JANUS_SHUTDOWN_TIMEOUT", 10.0, minimum=0.001)
+JANUS_DETACH_CONCURRENCY = _integer("JANUS_DETACH_CONCURRENCY", 16, minimum=1)
+JANUS_TOKEN = _optional("JANUS_TOKEN")
+jrtc_SECRET = _optional("jrtc_SECRET")
+
+# Transport-originated WebRTC events.  All logical ``janus.*`` event types are
+# mapped to one portable physical destination so Redis Streams, RabbitMQ and
+# Kafka subscribers share the same contract.
+JANUS_BROKER_ENGINE = os.getenv("JANUS_BROKER_ENGINE", "memory").strip().lower()
+if JANUS_BROKER_ENGINE not in {"memory", "local", "redis", "rabbitmq", "kafka"}:
+    raise ValueError("JANUS_BROKER_ENGINE is invalid")
+JANUS_BROKER_ROUTE = os.getenv("JANUS_BROKER_ROUTE", "janus.events").strip()
+if not JANUS_BROKER_ROUTE or any(character.isspace() for character in JANUS_BROKER_ROUTE):
+    raise ValueError("JANUS_BROKER_ROUTE must be a non-empty route without whitespace")
+JANUS_BROKER_ENGINE_OPTIONS = _json_object("JANUS_BROKER_ENGINE_OPTIONS")
+JANUS_BROKER_OPTIONS = _json_object("JANUS_BROKER_OPTIONS")
+JANUS_BROKER_PUBLISH_WORKERS = _integer("JANUS_BROKER_PUBLISH_WORKERS", 4, minimum=1)
+JANUS_BROKER_QUEUE_CAPACITY = _integer("JANUS_BROKER_QUEUE_CAPACITY", 4096, minimum=1)
+JANUS_BROKER_ADMISSION_TIMEOUT = _number("JANUS_BROKER_ADMISSION_TIMEOUT", 0.05, minimum=0.001)
+JANUS_BROKER_PUBLISH_TIMEOUT = _number("JANUS_BROKER_PUBLISH_TIMEOUT", 5.0, minimum=0.001)
+JANUS_BROKER_DRAIN_TIMEOUT = _number("JANUS_BROKER_DRAIN_TIMEOUT", 10.0, minimum=0.001)

jrtc/core/__init__.py

@@ -0,0 +1,29 @@
+"""Plugin-agnostic Janus Core exceptions."""
+
+from jrtc.core.exceptions import (
+    JanusConfigurationError,
+    JanusConnectionClosed,
+    JanusErrorResponse,
+    JanusException,
+    JanusProtocolError,
+    JanusRequestTimeout,
+    JanusTransportError,
+    PluginAlreadyRegistered,
+    PluginLoadError,
+    PluginManagerError,
+    PluginNotRegistered,
+)
+
+__all__ = [
+    "JanusConfigurationError",
+    "JanusConnectionClosed",
+    "JanusErrorResponse",
+    "JanusException",
+    "JanusProtocolError",
+    "JanusRequestTimeout",
+    "JanusTransportError",
+    "PluginAlreadyRegistered",
+    "PluginLoadError",
+    "PluginManagerError",
+    "PluginNotRegistered",
+]

jrtc/core/exceptions.py

@@ -0,0 +1,73 @@
+"""Exception hierarchy for the Janus client runtime.
+
+The exceptions in this module are intentionally plugin agnostic.  Named plugin
+packages should translate their own ``error_code`` payloads into package-local
+exceptions while preserving :class:`JanusErrorResponse` as the cause.
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+
+class JanusException(Exception):
+    """Base class for errors raised by the toolkit."""
+
+
+class JanusConfigurationError(JanusException):
+    """Raised when required runtime configuration is invalid or missing."""
+
+
+class JanusProtocolError(JanusException):
+    """Raised when a peer sends a malformed Janus protocol message."""
+
+
+class JanusTransportError(JanusException):
+    """Raised when a transport cannot send, receive, or maintain a connection."""
+
+
+class JanusConnectionClosed(JanusTransportError):
+    """Raised when an operation is interrupted because its transport closed."""
+
+
+class JanusRequestTimeout(JanusTransportError, TimeoutError):
+    """Raised when a Janus transaction does not complete before its deadline."""
+
+    def __init__(self, transaction: str, timeout: float) -> None:
+        self.transaction = transaction
+        self.timeout = timeout
+        super().__init__(f"Janus transaction {transaction!r} timed out after {timeout:g}s")
+
+
+class JanusErrorResponse(JanusException):
+    """A structured ``janus: error`` response returned by the gateway."""
+
+    def __init__(
+        self,
+        code: int,
+        reason: str,
+        *,
+        transaction: str | None = None,
+        response: Any | None = None,
+    ) -> None:
+        self.code = code
+        self.reason = reason
+        self.transaction = transaction
+        self.response = response
+        super().__init__(f"Janus error {code}: {reason}")
+
+
+class PluginManagerError(JanusException):
+    """Base class for plugin registration and handle ownership errors."""
+
+
+class PluginAlreadyRegistered(PluginManagerError):
+    """Raised when a handle or plugin identifier is registered twice."""
+
+
+class PluginNotRegistered(PluginManagerError, KeyError):
+    """Raised when a plugin identifier or handle cannot be resolved."""
+
+
+class PluginLoadError(PluginManagerError):
+    """Raised when an installed plugin entry point cannot be imported safely."""

jrtc/core/logging/__init__.py

@@ -0,0 +1,19 @@
+"""Opt-in logging utilities; importing Janus Core never configures logging."""
+
+from jrtc.core.logging._json import JsonFormatter
+from jrtc.core.logging.formatting import ColoredFormatter
+from jrtc.core.logging.utils import (
+    get_colored_stream_handler,
+    get_json_file_handler,
+    get_plain_file_handler,
+    install_colored_logging,
+)
+
+__all__ = [
+    "ColoredFormatter",
+    "JsonFormatter",
+    "get_colored_stream_handler",
+    "get_json_file_handler",
+    "get_plain_file_handler",
+    "install_colored_logging",
+]