reactor-runtime 3.2.7__tar.gz → 3.3.1__tar.gz

{reactor_runtime-3.2.7 → reactor_runtime-3.3.1}/PKG-INFO

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

{reactor_runtime-3.2.7 → reactor_runtime-3.3.1}/pyproject.toml

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

{reactor_runtime-3.2.7 → reactor_runtime-3.3.1}/pyproject.toml.orig

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

{reactor_runtime-3.2.7 → reactor_runtime-3.3.1}/src/reactor_runtime/core/typespec.py

@@ -218,6 +218,11 @@ class ListSpec(TypeSpec):
     def __init__(self, item: TypeSpec) -> None:
         self._item = item
 
+    @property
+    def item(self) -> TypeSpec:
+        """The type every element must fit."""
+        return self._item
+
     def check(self, value: Any) -> str | None:  # noqa: D102 — contract on the base
         if not isinstance(value, list):
             return f"expected array, got {type(value).__name__}"
@@ -240,6 +245,11 @@ class DictSpec(TypeSpec):
     def __init__(self, value: TypeSpec) -> None:
         self._value = value
 
+    @property
+    def value(self) -> TypeSpec:
+        """The type every value must fit."""
+        return self._value
+
     def check(self, value: Any) -> str | None:  # noqa: D102 — contract on the base
         if not isinstance(value, Mapping):
             return f"expected object, got {type(value).__name__}"
@@ -266,6 +276,11 @@ class DataclassSpec(TypeSpec):
         self._fields = fields
         self._required = required
 
+    @property
+    def fields(self) -> Mapping[str, TypeSpec]:
+        """Each field's type, by field name."""
+        return self._fields
+
     @classmethod
     def build(cls, dataclass_type: type) -> DataclassSpec:
         """Resolve a dataclass into a spec over its fields."""

{reactor_runtime-3.2.7 → reactor_runtime-3.3.1}/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.7 → reactor_runtime-3.3.1}/src/reactor_runtime/runner/runner.py

@@ -48,6 +48,8 @@ from reactor_runtime.core import (
     TrackDirection,
     Transition,
     TransitionEvent,
+    TypeSpec,
+    UploadedFile,
 )
 from reactor_runtime.event_stream import EventStream
 from reactor_runtime.interface.events.messages import ModelMessage
@@ -69,6 +71,7 @@ from reactor_runtime.recording import ClipResult, Recorder, RecorderError
 from reactor_runtime.runner.connection_manager import ConnectionManager
 from reactor_runtime.runner.offer_epochs import OfferEpochs
 from reactor_runtime.runner.state_machine import SessionStateMachine
+from reactor_runtime.runner.upload_resolution import declares_upload, resolve_uploads
 from reactor_runtime.transport.router import (
     SessionNotRunningError,
     SessionTransitionError,
@@ -109,6 +112,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 +235,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 +626,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 +637,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()
@@ -801,9 +817,17 @@ class Runner(ServiceComponent, ConnectionSink):
 
         Each upload the command references is resolved to its bytes through the
         store and merged into the arguments before validation, so the model
-        receives a file rather than a reference. A command that references an
-        upload the store cannot produce is journalled as an error and dropped
-        rather than submitted half-resolved. An accepted command is journalled on
+        receives a file rather than a reference. A reference arrives one of two
+        ways: beside the arguments, keyed by parameter name, which is how a
+        single top-level file travels; or inline in an argument as a mapping
+        with an ``upload_id``, which is the only way a file nested in a list,
+        dict, or dataclass can travel and is accepted for a single file too.
+        Inline references are found by
+        walking the command's declared types, never by inspecting values, so a
+        mapping of the model's own that carries an ``upload_id`` key is left
+        alone. A command that references an upload the store cannot produce,
+        in either form, is journalled as an error and dropped rather than
+        submitted half-resolved. An accepted command is journalled on
         the egress stream so a consumer can audit or moderate it; a command the
         contract rejects is journalled as an error instead and never reaches the
         model. The journalled argument record carries the scalar arguments, never
@@ -820,12 +844,13 @@ class Runner(ServiceComponent, ConnectionSink):
             return
         label = self._command_label(command.name)
         args = dict(command.args)
+        inline = self._inline_upload_fields(command.name, args)
         resolve_started = time.monotonic()
         try:
             for param, upload_id in command.uploads.items():
-                args[param] = await self._uploads.fetch(
-                    upload_id, wait_seconds=_UPLOAD_RESOLVE_TIMEOUT_SECONDS
-                )
+                args[param] = await self._fetch_upload(upload_id)
+            for param, spec in inline.items():
+                args[param] = await resolve_uploads(spec, args[param], self._fetch_upload)
         except UnknownUploadError:
             self._command_metrics.unresolved_upload(label)
             self._sm.send(
@@ -844,7 +869,7 @@ class Runner(ServiceComponent, ConnectionSink):
         # again where that wait ended. Counted whole, one command with a file
         # parameter reports the upload and hides the runtime's own cost.
         started_at = command.received_at
-        if command.uploads:
+        if command.uploads or inline:
             started_at += time.monotonic() - resolve_started
         outcome = await self._bridge.submit_command(
             command.name,
@@ -874,6 +899,29 @@ class Runner(ServiceComponent, ConnectionSink):
                     outcome.reason or "command rejected",
                 )
 
+    def _inline_upload_fields(self, name: str, args: Mapping[str, Any]) -> dict[str, TypeSpec]:
+        """Return the present arguments of command *name* whose type carries an upload.
+
+        The contract decides which fields to walk: a field typed as an upload,
+        or as a container holding one, may hold inline references and is
+        returned with its declared type; every other field is not. An unknown
+        command has no fields to walk and is left for the bridge to reject.
+        """
+        if self._bridge is None:
+            return {}
+        spec = self._bridge.contract.commands.get(name)
+        if spec is None:
+            return {}
+        return {
+            param: field.spec
+            for param, field in spec.command.__command_fields__.items()
+            if param in args and declares_upload(field.spec)
+        }
+
+    async def _fetch_upload(self, upload_id: str) -> UploadedFile:
+        """Read one upload from the store, waiting the standard grace for its bytes."""
+        return await self._uploads.fetch(upload_id, wait_seconds=_UPLOAD_RESOLVE_TIMEOUT_SECONDS)
+
     def _command_label(self, name: str) -> str:
         """Return a command name that is safe to label a metric with.
 
@@ -895,9 +943,7 @@ class Runner(ServiceComponent, ConnectionSink):
         if self._bridge is None:
             return
         try:
-            file = await self._uploads.fetch(
-                upload_id, wait_seconds=_UPLOAD_RESOLVE_TIMEOUT_SECONDS
-            )
+            file = await self._fetch_upload(upload_id)
         except UnknownUploadError:
             self._sm.send(
                 SessionEvent.ERROR, message=f"file upload {upload_id!r} could not be resolved"
@@ -1107,9 +1153,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 +1167,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.3.1/src/reactor_runtime/runner/upload_resolution.py

@@ -0,0 +1,118 @@
+"""Resolve the upload references a command's contract declares.
+
+A client refers to an uploaded file by its ``upload_id`` and the runtime swaps
+the reference for the bytes before the model sees the command. A single
+top-level file travels beside the arguments, keyed by parameter name; a file
+nested in a container has no such slot and travels inline, as a
+``{"upload_id": ...}`` mapping inside the argument itself. Both forms are
+resolved here.
+
+The walk follows the command's declared :class:`~reactor_runtime.core.TypeSpec`
+rather than the shape of the arguments: only a value the contract types as an
+upload is fetched, so a mapping field of the model's own that happens to carry
+an ``upload_id`` key is left exactly as the client sent it.
+"""
+
+from __future__ import annotations
+
+import asyncio
+from collections.abc import Awaitable, Callable, Mapping
+from typing import Any
+
+from reactor_runtime.core import UploadedFile
+from reactor_runtime.core.typespec import (
+    DataclassSpec,
+    DictSpec,
+    ListSpec,
+    OptionalSpec,
+    TypeSpec,
+    UploadSpec,
+)
+
+Fetch = Callable[[str], Awaitable[UploadedFile]]
+"""Turn an ``upload_id`` into the uploaded file, or raise when it cannot."""
+
+
+def declares_upload(spec: TypeSpec) -> bool:
+    """Return whether a value of *spec* can carry an upload reference.
+
+    True for an upload itself and for any container the contract supports
+    around one — optional, list, dict, or dataclass field — however deep they
+    nest. Every other type is False, so a caller can skip the walk for the
+    fields that never need it.
+    """
+    if isinstance(spec, UploadSpec):
+        return True
+    if isinstance(spec, OptionalSpec):
+        return declares_upload(spec.inner)
+    if isinstance(spec, ListSpec):
+        return declares_upload(spec.item)
+    if isinstance(spec, DictSpec):
+        return declares_upload(spec.value)
+    if isinstance(spec, DataclassSpec):
+        return any(declares_upload(field) for field in spec.fields.values())
+    return False
+
+
+async def resolve_uploads(spec: TypeSpec, value: Any, fetch: Fetch) -> Any:
+    """Return *value* with every upload reference *spec* declares fetched.
+
+    A reference is a mapping with a string ``upload_id`` in a position the spec
+    types as an upload. An :class:`~reactor_runtime.core.UploadedFile` already
+    in that position passes through, as does any value the spec does not type
+    as an upload, so contract validation still sees whatever the client sent
+    where it sent something else. The entries of a container are fetched
+    together and returned under their original positions and keys, so the
+    container as a whole waits no longer than its slowest entry.
+
+    Args:
+        spec: The declared type of the field holding *value*.
+        value: The field's raw argument, as decoded from the wire.
+        fetch: Resolves one ``upload_id`` to its file.
+
+    Returns:
+        The value with each declared reference replaced by its file.
+
+    Raises:
+        Exception: Whatever *fetch* raises for a reference it cannot resolve.
+    """
+    if isinstance(spec, OptionalSpec):
+        if value is None:
+            return None
+        return await resolve_uploads(spec.inner, value, fetch)
+    if isinstance(spec, ListSpec):
+        if not isinstance(value, list) or not declares_upload(spec.item):
+            return value
+        return list(
+            await asyncio.gather(*(resolve_uploads(spec.item, element, fetch) for element in value))
+        )
+    if isinstance(spec, DictSpec):
+        if not isinstance(value, Mapping) or not declares_upload(spec.value):
+            return value
+        return await _resolve_entries(value, dict.fromkeys(value, spec.value), fetch)
+    if isinstance(spec, DataclassSpec):
+        if not isinstance(value, Mapping):
+            return value
+        # Fields the dataclass does not declare are left as sent; the contract
+        # decides what to do with them.
+        specs = {name: field for name, field in spec.fields.items() if name in value}
+        if not any(declares_upload(field) for field in specs.values()):
+            return value
+        return await _resolve_entries(value, specs, fetch)
+    if isinstance(spec, UploadSpec):
+        if isinstance(value, Mapping) and isinstance(value.get("upload_id"), str):
+            return await fetch(value["upload_id"])
+        return value
+    return value
+
+
+async def _resolve_entries(
+    value: Mapping[Any, Any], specs: Mapping[Any, TypeSpec], fetch: Fetch
+) -> dict[Any, Any]:
+    """Resolve the entries of *value* named in *specs* together, keeping every key in place."""
+    resolved = dict(value)
+    keys = list(specs)
+    files = await asyncio.gather(*(resolve_uploads(specs[key], value[key], fetch) for key in keys))
+    for key, file in zip(keys, files, strict=True):
+        resolved[key] = file
+    return resolved

{reactor_runtime-3.2.7 → reactor_runtime-3.3.1}/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.7 → reactor_runtime-3.3.1}/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: