[3.14 backport] feat: Add dynamic port binding to TCPSite (#12167) (#12184)

Co-authored-by: Tom Whittock <tom.whittock@disguise.one>
Co-authored-by: Sam Bull <git@sambull.org>
Co-authored-by: Tom Whittock <136440158+twhittock-disguise@users.noreply.github.com>
Co-authored-by: J. Nick Koston <nick+github@koston.org>
Co-authored-by: rodrigo.nogueira <rodrigo.nogueira@prf.gov.br>

Author: 5 people

CHANGES/10665.feature.rst

@@ -0,0 +1 @@
+Added :py:attr:`~aiohttp.web.TCPSite.port` accessor for dynamic port allocations in :class:`~aiohttp.web.TCPSite` -- by :user:`twhittock-disguise` and :user:`rodrigobnogueira`.

CONTRIBUTORS.txt

@@ -357,6 +357,7 @@ Thomas Forbes
 Thomas Grainger
 Tim Menninger
 Tolga Tezel
+Tom Whittock
 Tomasz Trebski
 Toshiaki Tanaka
 Trevor Gamblin

aiohttp/web_runner.py

@@ -7,8 +7,10 @@
 
 from yarl import URL
 
+from .abc import AbstractAccessLogger
 from .typedefs import PathLike
 from .web_app import Application
+from .web_log import AccessLogger
 from .web_server import Server
 
 if TYPE_CHECKING:
@@ -80,7 +82,7 @@ async def stop(self) -> None:
 
 
 class TCPSite(BaseSite):
-    __slots__ = ("_host", "_port", "_reuse_address", "_reuse_port")
+    __slots__ = ("_host", "_port", "_bound_port", "_reuse_address", "_reuse_port")
 
     def __init__(
         self,
@@ -104,14 +106,29 @@ def __init__(
         if port is None:
             port = 8443 if self._ssl_context else 8080
         self._port = port
+        self._bound_port: int | None = None
         self._reuse_address = reuse_address
         self._reuse_port = reuse_port
 
+    @property
+    def port(self) -> int:
+        """The port the server is listening on.
+
+        If the server hasn't been started yet, this returns the requested port
+        (which might be 0 for a dynamic port).
+        After the server starts, it returns the actual bound port. This is
+        especially useful when port=0 was requested, as it allows retrieving the
+        dynamically assigned port after the site has started.
+        """
+        if self._bound_port is not None:
+            return self._bound_port
+        return self._port
+
     @property
     def name(self) -> str:
         scheme = "https" if self._ssl_context else "http"
         host = "0.0.0.0" if not self._host else self._host
-        return str(URL.build(scheme=scheme, host=host, port=self._port))
+        return str(URL.build(scheme=scheme, host=host, port=self.port))
 
     async def start(self) -> None:
         await super().start()
@@ -127,6 +144,10 @@ async def start(self) -> None:
             reuse_address=self._reuse_address,
             reuse_port=self._reuse_port,
         )
+        if self._server.sockets:
+            self._bound_port = self._server.sockets[0].getsockname()[1]
+        else:
+            self._bound_port = self._port
 
 
 class UnixSite(BaseSite):
@@ -369,13 +390,19 @@ class AppRunner(BaseRunner):
     __slots__ = ("_app",)
 
     def __init__(
-        self, app: Application, *, handle_signals: bool = False, **kwargs: Any
+        self,
+        app: Application,
+        *,
+        handle_signals: bool = False,
+        access_log_class: type[AbstractAccessLogger] = AccessLogger,
+        **kwargs: Any,
     ) -> None:
         super().__init__(handle_signals=handle_signals, **kwargs)
         if not isinstance(app, Application):
             raise TypeError(
                 f"The first argument should be web.Application instance, got {app!r}"
             )
+        self._kwargs["access_log_class"] = access_log_class
         self._app = app
 
     @property

docs/web_reference.rst

@@ -2998,7 +2998,9 @@ application on specific TCP or Unix socket, e.g.::
 
    :param str host: HOST to listen on, all interfaces if ``None`` (default).
 
-   :param int port: PORT to listed on, ``8080`` if ``None`` (default).
+   :param int port: PORT to listen on, ``8080`` if ``None`` (default).
+                    Use ``0`` to let the OS assign a free ephemeral port
+                    (see :attr:`port`).
 
    :param float shutdown_timeout: a timeout used for both waiting on pending
                                   tasks before application shutdown and for
@@ -3026,6 +3028,12 @@ application on specific TCP or Unix socket, e.g.::
                            this flag when being created. This option is not
                            supported on Windows.
 
+   .. attribute:: port
+
+      Read-only. The actual port number the server is bound to, only
+      guaranteed to be correct after the site has been started.
+
+
 .. class:: UnixSite(runner, path, *, \
                    shutdown_timeout=60.0, ssl_context=None, \
                    backlog=128)

examples/fake_server.py

@@ -8,7 +8,6 @@
 from aiohttp import web
 from aiohttp.abc import AbstractResolver, ResolveResult
 from aiohttp.resolver import DefaultResolver
-from aiohttp.test_utils import unused_port
 
 
 class FakeResolver(AbstractResolver):
@@ -61,13 +60,13 @@ def __init__(self, *, loop):
         self.ssl_context = ssl.create_default_context(ssl.Purpose.CLIENT_AUTH)
         self.ssl_context.load_cert_chain(str(ssl_cert), str(ssl_key))
 
-    async def start(self):
-        port = unused_port()
-        self.runner = web.AppRunner(self.app)
+    async def start(self) -> dict[str, int]:
         await self.runner.setup()
-        site = web.TCPSite(self.runner, "127.0.0.1", port, ssl_context=self.ssl_context)
+        site = web.TCPSite(
+            self.runner, "127.0.0.1", port=0, ssl_context=self.ssl_context
+        )
         await site.start()
-        return {"graph.facebook.com": port}
+        return {"graph.facebook.com": site.port}
 
     async def stop(self):
         await self.runner.cleanup()

tests/test_run_app.py

@@ -61,8 +61,10 @@ def patched_loop(
 ) -> Iterator[asyncio.AbstractEventLoop]:
     server = mock.create_autospec(asyncio.Server, spec_set=True, instance=True)
     server.wait_closed.return_value = None
+    server.sockets = []
     unix_server = mock.create_autospec(asyncio.Server, spec_set=True, instance=True)
     unix_server.wait_closed.return_value = None
+    unix_server.sockets = []
     with mock.patch.object(
         loop, "create_server", autospec=True, spec_set=True, return_value=server
     ):

tests/test_web_runner.py

@@ -2,7 +2,7 @@
 import platform
 import signal
 from typing import Any
-from unittest.mock import patch
+from unittest import mock
 
 import pytest
 
@@ -167,20 +167,16 @@ async def test_tcpsite_default_host(make_runner: Any) -> None:
     site = web.TCPSite(runner)
     assert site.name == "http://0.0.0.0:8080"
 
-    calls = []
-
-    async def mock_create_server(*args, **kwargs):
-        calls.append((args, kwargs))
-
-    with patch("asyncio.get_event_loop") as mock_get_loop:
-        mock_get_loop.return_value.create_server = mock_create_server
+    m = mock.create_autospec(asyncio.AbstractEventLoop, spec_set=True, instance=True)
+    m.create_server.return_value = mock.create_autospec(asyncio.Server, spec_set=True)
+    with mock.patch(
+        "asyncio.get_event_loop", autospec=True, spec_set=True, return_value=m
+    ):
         await site.start()
 
-    assert len(calls) == 1
-    server, host, port = calls[0][0]
-    assert server is runner.server
-    assert host is None
-    assert port == 8080
+    m.create_server.assert_called_once()
+    args, kwargs = m.create_server.call_args
+    assert args == (runner.server, None, 8080)
 
 
 async def test_tcpsite_empty_str_host(make_runner: Any) -> None:
@@ -242,3 +238,15 @@ async def test_app_handler_args_ceil_threshold(value: Any, expected: Any) -> Non
     assert rh._timeout_ceil_threshold == expected
     await runner.cleanup()
     assert app
+
+
+async def test_tcpsite_ephemeral_port(make_runner: Any) -> None:
+    runner = make_runner()
+    await runner.setup()
+    site = web.TCPSite(runner, port=0)
+    assert site.port == 0
+
+    await site.start()
+    assert site.port != 0
+    assert site.name.startswith("http://0.0.0.0:")
+    await site.stop()