Add dynamic port binding

Fixes aio-libs#10665

Author: twhittock-disguise

CHANGES/10665.feature.rst

@@ -0,0 +1 @@
+Added `port` accessor for dynamic port allocations in `TCPSite` -- by :user:`twhittock-disguise`.

CONTRIBUTORS.txt

@@ -344,6 +344,7 @@ Thomas Forbes
 Thomas Grainger
 Tim Menninger
 Tolga Tezel
+Tom Whittock
 Tomasz Trebski
 Toshiaki Tanaka
 Trinh Hoang Nhu

aiohttp/web_runner.py

@@ -113,6 +113,11 @@ def name(self) -> str:
         host = "0.0.0.0" if not self._host else self._host
         return str(URL.build(scheme=scheme, host=host, port=self._port))
 
+    @property
+    def port(self) -> int:
+        """Return the port number the server is bound to, useful for the dynamically allocated port (0)."""
+        return self._port
+
     async def start(self) -> None:
         await super().start()
         loop = asyncio.get_event_loop()
@@ -127,6 +132,10 @@ async def start(self) -> None:
             reuse_address=self._reuse_address,
             reuse_port=self._reuse_port,
         )
+        if self._port == 0:
+            # Port 0 means bind to any port, so we need to set the attribute
+            # to the port the server was actually bound to.
+            self._port = self._server.sockets[0].getsockname()[1]
 
 
 class UnixSite(BaseSite):

docs/web_advanced.rst

@@ -1181,6 +1181,28 @@ the middleware might use :meth:`BaseRequest.clone`.
    for modifying *scheme*, *host* and *remote* attributes according
    to ``Forwarded`` and ``X-Forwarded-*`` HTTP headers.
 
+Deploying with a dynamic port
+-----------------------------
+
+When deploying aiohttp in a zeroconf environment, it may be useful
+to have the server bind to a dynamic port. This can be done by
+using the ``0`` port number. This will cause the OS to assign a
+free port to the server. The assigned port can be retrieved
+using the :attr:`TCPSite.port` property after the server has started.
+
+For example::
+
+    app = web.Application()
+    runner = web.AppRunner(app)
+    await runner.setup()
+    site = web.TCPSite(runner, 'localhost', 0)
+    await site.start()
+
+    print(f"Server started on port {site.port}")
+    while True:
+        await asyncio.sleep(3600)  # sleep forever
+
+
 Swagger support
 ---------------