reactor-runtime 3.2.6__tar.gz → 3.3.0__tar.gz

{reactor_runtime-3.2.6 → reactor_runtime-3.3.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: reactor-runtime
-Version: 3.2.6
+Version: 3.3.0
 Summary: A Python framework for building real-time, interactive video models
 Author: Reactor
 Author-email: Reactor <team@reactor.inc>

{reactor_runtime-3.2.6 → reactor_runtime-3.3.0}/pyproject.toml

@@ -92,7 +92,7 @@ pythonpath = ["."]
 
 [project]
 name = "reactor-runtime"
-version = "3.2.6"
+version = "3.3.0"
 description = "A Python framework for building real-time, interactive video models"
 readme = "README.md"
 license = "Apache-2.0"

{reactor_runtime-3.2.6 → reactor_runtime-3.3.0}/pyproject.toml.orig

@@ -20,7 +20,7 @@ version = "1.20260814.7"
 
 [project]
 name = "reactor-runtime"
-version = "3.2.6"
+version = "3.3.0"
 description = "A Python framework for building real-time, interactive video models"
 readme = "README.md"
 license = "Apache-2.0"

{reactor_runtime-3.2.6 → reactor_runtime-3.3.0}/src/reactor_runtime/recording/chunk_encoder.py

@@ -232,15 +232,10 @@ class ChunkEncoder:
                 "hls_segment_filename": str(self._output_dir / _SEGMENT_PATTERN),
             },
         )
-        # ``add_stream`` is overloaded on a literal set of codec names, so the
-        # configured codec resolves to the catch-all return type.
-        video = cast(
-            "av.VideoStream",
-            container.add_stream(
-                "libx264" if config.video_codec == "h264" else "libx265",
-                rate=Fraction(self._frame_rate, 1),
-                options=_video_options(config, self._frame_rate * config.chunk_seconds),
-            ),
+        video = container.add_stream(
+            "libx264" if config.video_codec == "h264" else "libx265",
+            rate=Fraction(self._frame_rate, 1),
+            options=_video_options(config, self._frame_rate * config.chunk_seconds),
         )
         video.width = width
         video.height = height
@@ -248,6 +243,8 @@ class ChunkEncoder:
         video.profile = _PROFILE
         video.time_base = Fraction(1, self._frame_rate)
 
+        # ``add_stream`` is overloaded on a literal set of codec names, so the
+        # configured codec resolves to the catch-all return type.
         audio = cast(
             "av.AudioStream",
             container.add_stream(config.audio_codec, rate=self._audio_sample_rate, layout="mono"),

{reactor_runtime-3.2.6 → reactor_runtime-3.3.0}/src/reactor_runtime/recording/recorder.py

@@ -59,6 +59,14 @@ _FEED_WAIT_SECONDS = 1.0
 # frames on every emission, so the count is carried on every recording's summary
 # and only the periodic warning is rate-limited.
 _DROP_LOG_INTERVAL_SECONDS = 5.0
+# How much audio may sit in the jitter buffer on top of the emission just handed
+# over, in grid slots. A model's audio is framed on its own boundaries rather
+# than the video's, so an emission carries a little more or less than its slots
+# drain; two slots absorb that wobble without the buffer running dry on the
+# short ones. Past that the audio belongs to frames the encoder was too far
+# behind to take — their video is not in the recording, so pairing it with later
+# video would hold the rest of the session that far out of sync.
+_AUDIO_BACKLOG_FRAMES = 2
 
 _INIT_FILENAME = "init.mp4"
 # Written into a recording's directory once it is finished, so its final segment
@@ -669,11 +677,20 @@ class Recorder:
                 return
 
     def _buffer_audio(self, bundle: MediaBundle) -> None:
-        """Append a chunk's audio to the jitter buffer, capped at one second.
+        """Append a chunk's audio to the jitter buffer, keeping the newest samples.
 
         The whole chunk's audio is buffered once; :meth:`_take_audio` then pulls a
         grid slot's worth per recorded frame, so the audio DTS tracks the video
         PTS regardless of how the chunk's frames map onto the grid.
+
+        The bound is one authoritative limit, never applied below the emission
+        just appended, so however much audio a model hands over at once, all of
+        it is kept and the grid slots that drain it find real samples rather than
+        silence. Above the emission sits :data:`_AUDIO_BACKLOG_FRAMES` of slack
+        and no more, which keeps each emission's video paired with its own audio:
+        trimming takes the oldest samples, so audio orphaned by frames the
+        encoder never took is discarded with them instead of displacing the
+        audio that belongs to the video still to be fed.
         """
         if self._audio_track is None:
             return
@@ -683,7 +700,8 @@ class Recorder:
         flat = np.ascontiguousarray(track.data, dtype=np.int16).reshape(-1)
         self._audio_jitter_buf.append(flat)
         self._audio_buffered_samples += int(flat.size)
-        cap = self._audio_sample_rate
+        slack = _AUDIO_BACKLOG_FRAMES * round(self._audio_sample_rate / RECORDING_FPS)
+        cap = int(flat.size) + slack
         while self._audio_buffered_samples > cap:
             head = self._audio_jitter_buf[0]
             drop = self._audio_buffered_samples - cap

{reactor_runtime-3.2.6 → reactor_runtime-3.3.0}/src/reactor_runtime/runner/runner.py

@@ -109,6 +109,17 @@ def _stamp_log_state(state: SessionState) -> None:
     set_state(state.name.lower(), _RUNTIME_STATES[state].value)
 
 
+def _recording_id_from(params: Mapping[str, Any]) -> str:
+    """Resolve a session's recording id from its start parameters.
+
+    A ``session_id`` in *params* is adopted as the recording id, so a caller can
+    align both clips and logs with the id it knows the session by. Absent one, a
+    fresh id is minted per session so sequential recordings in a reused process
+    never overwrite each other.
+    """
+    return str(params.get("session_id") or uuid.uuid4())
+
+
 # How long to wait for an upload's bytes to arrive when a command or notification
 # references it before they are written. A client references an upload over the
 # data channel while its bytes are still being delivered on a separate request,
@@ -221,9 +232,10 @@ class Runner(ServiceComponent, ConnectionSink):
         self._teardown: set[asyncio.Task[None]] = set()
         self._orphan_task: asyncio.Task[None] | None = None
         self._session_id = SESSION_ID
-        # The session's own id, set per session in start_session: the id a
-        # recording is stored and addressed under, and the id stamped on the
-        # session's log records. Separate from the fixed transport session id so a
+        # The session's own id, resolved per session as the start transition is
+        # applied (see _dispatch_transition): the id a recording is stored and
+        # addressed under, and the id stamped on the session's log records.
+        # Separate from the fixed transport session id so a
         # caller can align both with the id it knows the session by; a session
         # started without one mints a fresh id, so sequential recordings in a
         # reused process never share a directory and the logs of one session are
@@ -611,8 +623,10 @@ class Runner(ServiceComponent, ConnectionSink):
         its recording is stored and addressed under, and the id stamped on every
         log record the session writes. A caller can therefore align both clips and
         logs with the id it knows the session by. Absent one, a fresh id is minted
-        per session so sequential recordings never overwrite each other. The
-        transport session id is unaffected — it is always :data:`SESSION_ID`.
+        per session so sequential recordings never overwrite each other. The id is
+        resolved as the machine accepts the start, so a rejected request leaves a
+        live session's id untouched. The transport session id is unaffected: it is
+        always :data:`SESSION_ID`.
 
         Args:
             params: The initial session parameters supplied by the caller.
@@ -620,7 +634,6 @@ class Runner(ServiceComponent, ConnectionSink):
         Raises:
             SessionTransitionError: If the session is not in a startable state.
         """
-        self._recording_id = str(params.get("session_id") or uuid.uuid4())
         if not self._sm.send(SessionEvent.START_SESSION, params=dict(params)):
             raise SessionTransitionError("start", self._sm.current_state)
         self._offer_epochs.session_started()
@@ -1107,9 +1120,12 @@ class Runner(ServiceComponent, ConnectionSink):
         self-loops log at debug so a per-segment ``chunk_ready`` does not flood
         the log.
 
-        The session boundary is also where the log's session context binds, so
-        every record written while a session is live names it, the opening move
-        included. The release travels differently: it rides the ``SessionEnded``
+        The session boundary is where the session's recording id resolves, off
+        the start parameters, so a rejected start cannot touch it; both the log's
+        session context and the recorder's directory read it from there. Binding
+        the log context is also part of this boundary, so every record written
+        while a session is live names it, the opening move included. The release
+        travels differently: it rides the ``SessionEnded``
         event into the model, whose dispatch retires the binding once the
         ``@session_ended`` hook has returned. A terminal move dispatches no
         ``SessionEnded`` and releases nothing — the process is exiting, and its
@@ -1118,6 +1134,7 @@ class Runner(ServiceComponent, ConnectionSink):
         reads the state the process was in when it was written.
         """
         if transition.is_session_start:
+            self._recording_id = _recording_id_from(transition.detail.get("params", {}))
             self._log_binding = set_session_id(self._recording_id)
         if transition.from_state is not transition.to_state:
             _stamp_log_state(transition.to_state)

{reactor_runtime-3.2.6 → reactor_runtime-3.3.0}/src/reactor_runtime/transport/webrtc/__init__.py

@@ -7,8 +7,13 @@ WebRTC reshaped as a connection: :class:`WebRTCConnection` is the wire,
 during offer negotiation by a :data:`WebRtcPeerFactory`.
 """
 
-from reactor_runtime.transport.webrtc.acceptor import WebRTCAcceptor
-from reactor_runtime.transport.webrtc.config import IceServer, IceTransportPolicy, WebRtcConfig
+from reactor_runtime.transport.webrtc.acceptor import PortRangeUnavailableError, WebRTCAcceptor
+from reactor_runtime.transport.webrtc.config import (
+    IceCredentials,
+    IceServer,
+    IceTransportPolicy,
+    WebRtcConfig,
+)
 from reactor_runtime.transport.webrtc.connection import WebRTCConnection
 from reactor_runtime.transport.webrtc.peer import WebRTCPeer, WebRtcPeerFactory
 from reactor_runtime.transport.webrtc.router import WebRtcRouter
@@ -23,11 +28,13 @@ from reactor_runtime.transport.webrtc.stats import OutboundMediaHealth, PeerStat
 
 __all__ = [
     "IceCandidate",
+    "IceCredentials",
     "IceServer",
     "IceTransportPolicy",
     "MappedTrack",
     "OutboundMediaHealth",
     "PeerStats",
+    "PortRangeUnavailableError",
     "SdpAnswer",
     "SdpOffer",
     "TrackMap",

{reactor_runtime-3.2.6 → reactor_runtime-3.3.0}/src/reactor_runtime/transport/webrtc/acceptor.py

@@ -28,7 +28,7 @@ from reactor_runtime.metrics import WebRtcMetrics
 from reactor_runtime.protocol import ProtocolVersion
 from reactor_runtime.transport.acceptor import ConnectionAcceptor
 from reactor_runtime.transport.router import TooManyConnectionsError
-from reactor_runtime.transport.webrtc.config import IceServer, WebRtcConfig
+from reactor_runtime.transport.webrtc.config import IceCredentials, IceServer, WebRtcConfig
 from reactor_runtime.transport.webrtc.connection import WebRTCConnection
 from reactor_runtime.transport.webrtc.peer import WebRtcPeerFactory
 from reactor_runtime.transport.webrtc.signaling import IceCandidate, SdpAnswer, SdpOffer, TrackMap
@@ -47,6 +47,46 @@ _MAX_PENDING_ICE_CONNS = 128
 _MAX_PENDING_ICE_PER_CONN = 256
 
 
+class PortRangeUnavailableError(RuntimeError):
+    """Raised when a single-port ``port_range`` override names a port already held.
+
+    A caller pinning a connection to one port has no second port to fall back
+    on. Two connections pinned to the same one both try to bind it: the second
+    finds nothing free in its range, gathers no host candidate, and its
+    negotiation is logged and dropped — which reaches the caller only as its
+    answer poll timing out. Refused at the offer instead, it is an error the
+    caller can act on by pinning a different port.
+
+    Only a single-port range is measured. A wider range still has ports left to
+    pick, and two wide ranges overlapping is the ordinary case: the acceptor
+    knows which range a connection gathers in, never which port inside it the
+    ICE agent took.
+
+    Attributes:
+        port: The pinned port that is already held.
+        held_by: The connection holding it.
+    """
+
+    def __init__(self, port: int, held_by: ConnId) -> None:
+        """Record the pinned port and the connection already holding it."""
+        self.port = port
+        self.held_by = held_by
+        super().__init__(f"port {port} is already held by connection {held_by}")
+
+
+def _pinned_port(port_range: tuple[int, int] | None) -> int | None:
+    """Return the single port a range pins a connection to, or ``None``.
+
+    A range wider than one port leaves the ICE agent a choice, so there is
+    nothing to reserve; only ``min == max`` names a port the connection must
+    have.
+    """
+    if port_range is None:
+        return None
+    low, high = port_range
+    return low if low == high else None
+
+
 class WebRTCAcceptor(ConnectionAcceptor):
     """Negotiate WebRTC handshakes and register connections once they are live.
 
@@ -100,6 +140,12 @@ class WebRTCAcceptor(ConnectionAcceptor):
         # teardown of the superseded connection runs while the new offer's
         # deadline is already armed and must not carry it off.
         self._deadlines: dict[ConnId, tuple[float, asyncio.Task[None]]] = {}
+        # The port each connection offering a single-port range is pinned to,
+        # keyed with the offer generation that claimed it: a reconnect claims
+        # its port and only then tears the superseded connection down, so a
+        # release by id alone would carry the new claim off. Wider ranges are
+        # absent — there is nothing to reserve when the agent has a choice.
+        self._pinned_ports: dict[ConnId, tuple[float, int]] = {}
 
     def start_offer(
         self,
@@ -108,6 +154,8 @@ class WebRTCAcceptor(ConnectionAcceptor):
         tracks: TrackMap,
         version: ProtocolVersion,
         ice_servers: tuple[IceServer, ...] | None = None,
+        ice_credentials: IceCredentials | None = None,
+        port_range: tuple[int, int] | None = None,
     ) -> None:
         """Begin negotiating *sdp_offer* in the background.
 
@@ -123,13 +171,30 @@ class WebRTCAcceptor(ConnectionAcceptor):
         ``None`` falls back to the acceptor's configuration. Supplied per offer,
         so a reconnect can carry fresh credentials.
 
+        *ice_credentials* and *port_range* override the same fields for this
+        connection only, on the same terms: ``None`` — the default for both —
+        uses the acceptor's configuration, which for credentials means the media
+        engine generates its own. They are here for a deployment that fronts the
+        runtime with a relaying layer and must know a connection's ICE
+        credentials and media port before the connection exists; a runtime
+        driven directly never sets them.
+
+        *port_range* replaces the configured range rather than narrowing it, so
+        a caller can name a port outside it. A single-port range is reserved for
+        the connection: a second connection pinned to the same port is refused
+        here rather than left to fail gathering in the background.
+
         Raises:
             TooManyConnectionsError: If *conn_id* is a new connection and the
                 acceptor already holds its configured maximum. A re-offer on a
                 connection already negotiating or live is a reconnect and is
                 admitted regardless of the ceiling.
+            PortRangeUnavailableError: If *port_range* pins a single port that
+                another connection is already pinned to. A re-offer on this same
+                connection keeps its own port.
         """
         self._guard_capacity(conn_id)
+        self._guard_pinned_port(conn_id, port_range)
         in_flight = self._negotiating.pop(conn_id, None)
         if in_flight is not None:
             in_flight.cancel()
@@ -137,8 +202,18 @@ class WebRTCAcceptor(ConnectionAcceptor):
         self._answers.pop(conn_id, None)
         offered_at = time.monotonic()
         self._offered_at[conn_id] = offered_at
+        self._claim_pinned_port(conn_id, port_range, offered_at)
         self._negotiating[conn_id] = asyncio.create_task(
-            self._negotiate(conn_id, sdp_offer, tracks, version, ice_servers, offered_at=offered_at)
+            self._negotiate(
+                conn_id,
+                sdp_offer,
+                tracks,
+                version,
+                ice_servers,
+                ice_credentials,
+                port_range,
+                offered_at=offered_at,
+            )
         )
         self._arm_deadline(conn_id, offered_at)
 
@@ -156,6 +231,48 @@ class WebRTCAcceptor(ConnectionAcceptor):
         if not known and len(set(self._conns) | set(self._negotiating)) >= limit:
             raise TooManyConnectionsError(limit)
 
+    def _guard_pinned_port(self, conn_id: ConnId, port_range: tuple[int, int] | None) -> None:
+        """Refuse an offer pinned to a port another connection already holds.
+
+        The one bad ``port_range`` the request boundary cannot catch: it is
+        structurally valid and only conflicts with what this acceptor is
+        currently negotiating. A re-offer on the connection already holding the
+        port is a reconnect — its own peer is closed before the new one is
+        built, so the port is free for it.
+        """
+        port = _pinned_port(port_range)
+        if port is None:
+            return
+        for other, (_, held) in self._pinned_ports.items():
+            if other != conn_id and held == port:
+                raise PortRangeUnavailableError(port, other)
+
+    def _claim_pinned_port(
+        self, conn_id: ConnId, port_range: tuple[int, int] | None, offered_at: float
+    ) -> None:
+        """Record the port this offer pins the connection to, if it pins one.
+
+        A re-offer that supplies a wider range, or none at all, releases the
+        port its predecessor claimed: the new peer gathers wherever its range
+        allows, so the old claim describes nothing.
+        """
+        port = _pinned_port(port_range)
+        if port is None:
+            self._pinned_ports.pop(conn_id, None)
+            return
+        self._pinned_ports[conn_id] = (offered_at, port)
+
+    def _release_pinned_port(self, conn_id: ConnId, offered_at: float) -> None:
+        """Free a claimed port, unless a newer offer on the id already holds it.
+
+        The ordering :meth:`_drop_offer` guards against: a reconnect claims its
+        port and then tears the superseded connection down, and that teardown
+        must not release the claim the reconnect is negotiating with.
+        """
+        entry = self._pinned_ports.get(conn_id)
+        if entry is not None and entry[0] == offered_at:
+            del self._pinned_ports[conn_id]
+
     def _arm_deadline(self, conn_id: ConnId, offered_at: float) -> None:
         """Start the reaper that frees this connection's slot if it never goes live."""
         if self._config.negotiation_timeout <= 0:
@@ -222,6 +339,7 @@ class WebRTCAcceptor(ConnectionAcceptor):
             self._pending_ice.pop(conn_id, None)
             self._answers.pop(conn_id, None)
             self._drop_offer(conn_id, offered_at)
+            self._release_pinned_port(conn_id, offered_at)
         finally:
             entry = self._deadlines.get(conn_id)
             if entry is not None and entry[1] is asyncio.current_task():
@@ -238,6 +356,8 @@ class WebRTCAcceptor(ConnectionAcceptor):
         tracks: TrackMap,
         version: ProtocolVersion,
         ice_servers: tuple[IceServer, ...] | None = None,
+        ice_credentials: IceCredentials | None = None,
+        port_range: tuple[int, int] | None = None,
         *,
         offered_at: float,
     ) -> None:
@@ -250,14 +370,18 @@ class WebRTCAcceptor(ConnectionAcceptor):
         in the gap. A negotiation that fails is logged and dropped — the client's
         poll for the answer times out — rather than left as an unhandled task.
 
-        *ice_servers* override the configured STUN/TURN servers for this
-        connection when given; ``None`` uses the acceptor's configuration.
+        *ice_servers*, *ice_credentials* and *port_range* override the
+        corresponding configured values for this connection when given; ``None``
+        uses the acceptor's configuration for each independently.
         """
-        config = (
-            self._config
-            if ice_servers is None
-            else dataclasses.replace(self._config, ice_servers=ice_servers)
-        )
+        overrides: dict[str, object] = {}
+        if ice_servers is not None:
+            overrides["ice_servers"] = ice_servers
+        if ice_credentials is not None:
+            overrides["ice_credentials"] = ice_credentials
+        if port_range is not None:
+            overrides["port_range"] = port_range
+        config = self._config if not overrides else dataclasses.replace(self._config, **overrides)
         try:
             previous = self._conns.pop(conn_id, None)
             if previous is not None:
@@ -295,6 +419,7 @@ class WebRTCAcceptor(ConnectionAcceptor):
             # its deadline has nothing left to guard either.
             self._drop_offer(conn_id, offered_at)
             self._cancel_deadline(conn_id, offered_at)
+            self._release_pinned_port(conn_id, offered_at)
             logger.exception("WebRTC negotiation failed for connection %s", conn_id)
         finally:
             # Only clear our own entry: a superseding offer may have already
@@ -361,6 +486,7 @@ class WebRTCAcceptor(ConnectionAcceptor):
         self._pending_ice.pop(conn_id, None)
         self._answers.pop(conn_id, None)
         self._drop_offer(conn_id, offered_at)
+        self._release_pinned_port(conn_id, offered_at)
         if conn_id in self._live:
             self._live.discard(conn_id)
             self._sink.connection_closed(conn_id)
@@ -379,6 +505,7 @@ class WebRTCAcceptor(ConnectionAcceptor):
         self._pending_ice.pop(conn_id, None)
         self._answers.pop(conn_id, None)
         self._drop_offer(conn_id, offered_at)
+        self._release_pinned_port(conn_id, offered_at)
         self._live.discard(conn_id)
 
     def _drop_offer(self, conn_id: ConnId, offered_at: float) -> None:

{reactor_runtime-3.2.6 → reactor_runtime-3.3.0}/src/reactor_runtime/transport/webrtc/config.py

@@ -40,6 +40,30 @@ class IceServer:
     credential: str | None = None
 
 
+@dataclass(frozen=True)
+class IceCredentials:
+    """The ICE username fragment and password a connection answers with.
+
+    Normally the media engine generates these itself, and nothing needs to
+    supply them. They exist as a configurable value for deployments that front
+    the runtime with a relaying layer that has to recognise a connection from
+    its ICE credentials alone — the credentials are the only field an ICE agent
+    echoes on every connectivity check, so a fronting layer can route on them
+    without inspecting media.
+
+    Both values must satisfy RFC 8445's ``ice-char`` alphabet and length
+    ranges; :meth:`reactor_webrtc.SessionDescription.with_ice_credentials`
+    rejects anything outside them.
+
+    Attributes:
+        ufrag: The ``a=ice-ufrag`` value to answer with.
+        pwd: The ``a=ice-pwd`` value to answer with.
+    """
+
+    ufrag: str
+    pwd: str
+
+
 class CodecEntry(TypedDict):
     """A supported codec for SDP negotiation and encoder/decoder selection.
 
@@ -81,8 +105,14 @@ class WebRtcConfig:
 
     Attributes:
         ice_servers: The STUN/TURN servers offered for candidate gathering.
+        ice_credentials: The ICE credentials to answer with, or ``None`` — the
+            default — to let the media engine generate its own. Setting these
+            is only useful to a deployment whose fronting layer routes on them;
+            see :class:`IceCredentials`.
         port_range: An inclusive ``(min, max)`` UDP port range to confine ICE
-            to, or ``None`` to let the stack choose.
+            to, or ``None`` to let the stack choose. A single-port range pins
+            the connection to one port, which is what a fronting layer needs if
+            it must know the media address before the connection exists.
         transport_policy: Which candidate types to gather.
         ping_timeout: Seconds without a client ping before the connection's
             watchdog declares it lost. ``0`` or less disables the watchdog.
@@ -139,6 +169,7 @@ class WebRtcConfig:
     """
 
     ice_servers: tuple[IceServer, ...] = ()
+    ice_credentials: IceCredentials | None = None
     port_range: tuple[int, int] | None = None
     transport_policy: IceTransportPolicy = IceTransportPolicy.ALL
     ping_timeout: float = 20.0

{reactor_runtime-3.2.6 → reactor_runtime-3.3.0}/src/reactor_runtime/transport/webrtc/peer.py

@@ -479,6 +479,14 @@ class WebRTCPeer:
         await self._attach_out_tracks(pc, factory)
 
         answer = await pc.create_answer()
+        # Substituting the ICE credentials has to happen HERE: setting the local
+        # description is what creates the transport and starts gathering, so a
+        # substitution after it has nothing left to act on. Nothing is
+        # substituted unless the configuration asks for it, which is the usual
+        # case -- the media engine's own credentials are used.
+        credentials = self._config.ice_credentials
+        if credentials is not None:
+            answer = answer.with_ice_credentials(credentials.ufrag, credentials.pwd)
         self._answer_sdp = answer.sdp
         await pc.set_local_description(answer)
         # The answer describes every outbound track as sending, which is the

{reactor_runtime-3.2.6 → reactor_runtime-3.3.0}/src/reactor_runtime/transport/webrtc/router.py

@@ -15,9 +15,9 @@ from __future__ import annotations
 
 from typing import Annotated, Any
 
-from fastapi import FastAPI, Header, Request, Response
+from fastapi import FastAPI, Header, HTTPException, Request, Response
 from fastapi.responses import JSONResponse
-from pydantic import BaseModel, Field
+from pydantic import BaseModel, Field, model_validator
 
 from reactor_runtime.core import ConnId
 from reactor_runtime.metrics import RuntimeMetrics, WebRtcMetrics
@@ -30,8 +30,8 @@ from reactor_runtime.transport.router import (
     TransportRouter,
     UnknownSessionError,
 )
-from reactor_runtime.transport.webrtc.acceptor import WebRTCAcceptor
-from reactor_runtime.transport.webrtc.config import IceServer, WebRtcConfig
+from reactor_runtime.transport.webrtc.acceptor import PortRangeUnavailableError, WebRTCAcceptor
+from reactor_runtime.transport.webrtc.config import IceCredentials, IceServer, WebRtcConfig
 from reactor_runtime.transport.webrtc.peer import WebRtcPeerFactory
 from reactor_runtime.transport.webrtc.signaling import IceCandidate, SdpOffer, TrackMap
 from reactor_runtime.transport.webrtc.version import protocol_for_transport
@@ -55,6 +55,16 @@ _CONNECT_RESPONSES: dict[int | str, dict[str, Any]] = {
     503: {"model": ErrorDetail},
 }
 
+# Offering adds a 409 on top: a ``port_range`` pinned to a single port another
+# connection already holds is refused, since a pinned caller has no second port
+# to fall back on. Unlike the 503s this is not transient — retrying the same
+# port changes nothing, so it is a distinct code the caller branches on to pin
+# another port.
+_OFFER_RESPONSES: dict[int | str, dict[str, Any]] = {
+    **_CONNECT_RESPONSES,
+    409: {"model": ErrorDetail},
+}
+
 
 class RegisterConnectionResponse(BaseModel):
     """A minted connection id and the model's track manifest for transceiver setup."""
@@ -104,18 +114,78 @@ class IceServerEntry(BaseModel):
     credentials: TurnCredentials | None = None
 
 
+# RFC 8445 §15.4: ice-char = ALPHA / DIGIT / "+" / "/". Anchored, so a value
+# is rejected for containing anything else rather than for merely starting with
+# something valid.
+_ICE_CHAR = r"^[A-Za-z0-9+/]+$"
+
+
+class IceCredentialsEntry(BaseModel):
+    """The ICE credentials a connection should answer with.
+
+    The constraints are RFC 8445 §15.4: both values are ``ice-char``
+    (ALPHA / DIGIT / "+" / "/"), a ufrag is 4..256 of them and a password
+    22..256.
+
+    They are enforced here rather than left to the media engine because of where
+    each failure surfaces. Registering an offer answers 202 and the negotiation
+    runs in the background, so a malformed value rejected downstream reaches the
+    caller only as its answer poll timing out, with the reason in the runtime's
+    logs. Checked here it is a 422 naming the field.
+    """
+
+    ufrag: str = Field(min_length=4, max_length=256, pattern=_ICE_CHAR)
+    pwd: str = Field(min_length=22, max_length=256, pattern=_ICE_CHAR)
+
+
+# A UDP port. Zero is excluded: it asks the kernel for an ephemeral port, which
+# is the one thing a caller pinning a range cannot mean.
+_Port = Annotated[int, Field(ge=1, le=65535)]
+
+
 class SdpParamsRequest(BaseModel):
-    """A client's SDP offer, the tracks it declares, and optional ICE servers.
+    """A client's SDP offer, the tracks it declares, and optional overrides.
 
     ``ice_servers`` lets the caller supply the STUN/TURN servers this connection
     gathers against. Absent, the runtime uses its own configured servers; present
     (even empty), it is authoritative for the connection — so a reconnect can
     carry fresh credentials.
+
+    ``ice_credentials`` and ``port_range`` follow the same rule and are likewise
+    optional: absent — the usual case — the media engine generates its own
+    credentials and the configured port range applies. They exist for a
+    deployment that fronts the runtime with a relaying layer, which must know a
+    connection's ICE credentials and media address before the connection exists.
+    ``port_range`` is an inclusive ``[min, max]``; a single-port range pins the
+    connection to one port. It replaces the configured range rather than
+    narrowing it, so a caller can name a port outside what the runtime is
+    configured with — an operator who set a range for an environmental reason (a
+    firewall rule, a container's published ports) cannot rely on it to bound a
+    caller. A port pinned this way is reserved for the connection: pinning one
+    another live connection already holds is a 409 rather than a negotiation
+    that fails out of sight.
     """
 
     sdp_offer: str
     track_mapping: list[TrackMappingEntry] = Field(default_factory=list)
     ice_servers: list[IceServerEntry] | None = None
+    ice_credentials: IceCredentialsEntry | None = None
+    port_range: tuple[_Port, _Port] | None = None
+
+    @model_validator(mode="after")
+    def _port_range_is_ordered(self) -> SdpParamsRequest:
+        """Reject an inverted range here rather than at gathering.
+
+        ``(50000, 40000)`` is accepted by the type and then fails when the
+        engine gathers, which reaches the caller as an answer poll that times
+        out. This makes it a 422 that names the field.
+        """
+        if self.port_range is not None:
+            low, high = self.port_range
+            if low > high:
+                msg = f"port_range min {low} is above max {high}"
+                raise ValueError(msg)
+        return self
 
 
 class IceCandidateEntry(BaseModel):
@@ -133,6 +203,19 @@ class IceCandidatesRequest(BaseModel):
     is_final: bool = False
 
 
+def _ice_credentials_from_request(
+    entry: IceCredentialsEntry | None,
+) -> IceCredentials | None:
+    """Convert a connect request's ICE credentials to the transport's form.
+
+    ``None`` (the field absent) means the media engine generates its own, which
+    is the ordinary case.
+    """
+    if entry is None:
+        return None
+    return IceCredentials(ufrag=entry.ufrag, pwd=entry.pwd)
+
+
 def _ice_servers_from_request(
     entries: list[IceServerEntry] | None,
 ) -> tuple[IceServer, ...] | None:
@@ -245,18 +328,26 @@ class WebRtcRouter(TransportRouter):
             tracks = TrackMap.from_client(entry.model_dump() for entry in req.track_mapping)
             conn_id = ConnId(cid)
             runner.offer_admitted(conn_id)
-            acceptor.start_offer(
-                conn_id,
-                SdpOffer(req.sdp_offer),
-                tracks,
-                protocol_for_transport(webrtc_version),
-                ice_servers=_ice_servers_from_request(req.ice_servers),
-            )
+            try:
+                acceptor.start_offer(
+                    conn_id,
+                    SdpOffer(req.sdp_offer),
+                    tracks,
+                    protocol_for_transport(webrtc_version),
+                    ice_servers=_ice_servers_from_request(req.ice_servers),
+                    ice_credentials=_ice_credentials_from_request(req.ice_credentials),
+                    port_range=req.port_range,
+                )
+            except PortRangeUnavailableError as taken:
+                raise HTTPException(
+                    status_code=409,
+                    detail=f"port {taken.port} is already held by another connection",
+                ) from None
             return OfferAccepted(connection_id=cid)
 
         offer_path = f"{_PREFIX}/connections/{{cid}}/sdp_params"
-        app.post(offer_path, status_code=202, responses=_CONNECT_RESPONSES)(offer)
-        app.put(offer_path, status_code=202, responses=_CONNECT_RESPONSES)(offer)
+        app.post(offer_path, status_code=202, responses=_OFFER_RESPONSES)(offer)
+        app.put(offer_path, status_code=202, responses=_OFFER_RESPONSES)(offer)
 
         @app.get(
             f"{_PREFIX}/connections/{{cid}}/sdp_params",