Merge pull request #329 from rstudio/launch-browser-2

Add --launch-browser option to shiny run, and random port

Author: jcheng5

shiny/_autoreload.py

@@ -6,6 +6,7 @@
 import secrets
 from typing import Optional, Tuple
 import threading
+import webbrowser
 
 from asgiref.typing import (
     ASGI3Application,
@@ -149,7 +150,7 @@ async def rewrite_send(event: ASGISendEvent) -> None:
 # PARENT PROCESS ------------------------------------------------------------
 
 
-def start_server(port: int, app_port: int):
+def start_server(port: int, app_port: int, launch_browser: bool):
     """Starts a websocket server that listens on its own port (separate from the main
     Shiny listener).
 
@@ -173,18 +174,25 @@ def start_server(port: int, app_port: int):
     # Run on a background thread so our event loop doesn't interfere with uvicorn.
     # Set daemon=True because we don't want to keep the process alive with this thread.
     threading.Thread(
-        None, _thread_main, args=[port, app_url, secret], daemon=True
+        None, _thread_main, args=[port, app_url, secret, launch_browser], daemon=True
     ).start()
 
 
-def _thread_main(port: int, app_url: str, secret: str):
-    asyncio.run(_coro_main(port, app_url, secret))
+def _thread_main(port: int, app_url: str, secret: str, launch_browser: bool):
+    asyncio.run(_coro_main(port, app_url, secret, launch_browser))
 
 
-async def _coro_main(port: int, app_url: str, secret: str) -> None:
+async def _coro_main(
+    port: int, app_url: str, secret: str, launch_browser: bool
+) -> None:
     reload_now: asyncio.Event = asyncio.Event()
 
     def nudge():
+        nonlocal launch_browser
+        if launch_browser:
+            # Only launch the browser once, not every time autoreload occurs
+            launch_browser = False
+            webbrowser.open(app_url, 1)
         reload_now.set()
         reload_now.clear()
 

shiny/_launchbrowser.py

@@ -0,0 +1,40 @@
+import logging
+import os
+import webbrowser
+
+from ._hostenv import get_proxy_url
+
+
+class LaunchBrowserHandler(logging.Handler):
+    """Uvicorn log reader, detects successful app startup so we can launch a browser.
+
+    This class is ONLY used when reload mode is turned off; in the case of reload, the
+    launching of the browser must be tightly coupled to the HotReloadHandler as that is
+    the only way to ensure the browser is only launched at startup, not on every reload.
+    """
+
+    def __init__(self):
+        logging.Handler.__init__(self)
+        self._launched = False
+
+    def emit(self, record: logging.LogRecord) -> None:
+        if self._launched:
+            # Ensure that we never launch a browser window twice. In non-reload
+            # scenarios it probably would never happen anyway, as we're unlikely to get
+            # "Application startup complete." in the logs more than once, but just in
+            # case someone does choose to log that string...
+            return
+
+        if "Application startup complete." in record.getMessage():
+            self._launched = True
+            port = os.environ["SHINY_PORT"]
+            if not port.isnumeric():
+                print(
+                    "SHINY_PORT environment variable not set or unusable; "
+                    "--launch-browser will be ignored"
+                )
+                # For some reason the shiny port isn't set correctly!?
+                return
+            host = os.environ["SHINY_HOST"]
+            url = get_proxy_url(f"http://{host}:{port}/")
+            webbrowser.open(url, 1)

shiny/_main.py

@@ -2,7 +2,6 @@
 import importlib
 import importlib.util
 import os
-import re
 import shutil
 import sys
 import types
@@ -15,7 +14,7 @@
 
 import shiny
 
-from . import _autoreload, _hostenv, _static
+from . import _autoreload, _hostenv, _static, _utils
 
 
 @click.group()  # pyright: ignore[reportUnknownMemberType]
@@ -54,14 +53,14 @@ def main() -> None:
     "--port",
     type=int,
     default=8000,
-    help="Bind socket to this port.",
+    help="Bind socket to this port. If 0, a random port will be used.",
     show_default=True,
 )
 @click.option(
     "--autoreload-port",
-    type=str,
-    default="+123",
-    help="Bind autoreload socket to this port number. If the value begins with + or -, it will be added to the value of --port. Ignored if --reload is not used.",
+    type=int,
+    default=0,
+    help="Bind autoreload socket to this port. If 0, a random port will be used. Ignored if --reload is not used.",
     show_default=True,
 )
 @click.option(
@@ -97,17 +96,25 @@ def main() -> None:
     help="Treat APP as an application factory, i.e. a () -> <ASGI app> callable.",
     show_default=True,
 )
+@click.option(
+    "--launch-browser",
+    is_flag=True,
+    default=False,
+    help="Launch app browser after app starts, using the Python webbrowser module.",
+    show_default=True,
+)
 def run(
     app: Union[str, shiny.App],
     host: str,
     port: int,
-    autoreload_port: str,
+    autoreload_port: int,
     debug: bool,
     reload: bool,
     ws_max_size: int,
     log_level: str,
     app_dir: str,
     factory: bool,
+    launch_browser: bool,
 ) -> None:
     return run_app(
         app,
@@ -120,20 +127,22 @@ def run(
         log_level=log_level,
         app_dir=app_dir,
         factory=factory,
+        launch_browser=launch_browser,
     )
 
 
 def run_app(
     app: Union[str, shiny.App] = "app:app",
     host: str = "127.0.0.1",
     port: int = 8000,
-    autoreload_port: str = "",
+    autoreload_port: int = 0,
     debug: bool = False,
     reload: bool = False,
     ws_max_size: int = 16777216,
     log_level: Optional[str] = None,
     app_dir: Optional[str] = ".",
     factory: bool = False,
+    launch_browser: bool = False,
 ) -> None:
     """
     Starts a Shiny app. Press ``Ctrl+C`` (or ``Ctrl+Break`` on Windows) to stop.
@@ -152,7 +161,10 @@ def run_app(
     host
         The address that the app should listen on.
     port
-        The port that the app should listen on.
+        The port that the app should listen on. Set to 0 to use a random port.
+    autoreload_port
+        The port that should be used for an additional websocket that is used to support
+        hot-reload. Set to 0 to use a random port.
     debug
         Enable debug mode.
     reload
@@ -163,6 +175,10 @@ def run_app(
         Log level.
     app_dir
         Look for ``app`` under this directory (by adding this to the ``PYTHONPATH``).
+    factory
+        Treat ``app`` as an application factory, i.e. a () -> <ASGI app> callable.
+    launch_browser
+        Launch app browser after app starts, using the Python webbrowser module.
 
     Tip
     ---
@@ -189,6 +205,13 @@ def run_app(
         run_app("myapp:my_app", app_dir="..")
     """
 
+    # If port is 0, randomize
+    if port == 0:
+        port = _utils.random_port(host=host)
+
+    os.environ["SHINY_HOST"] = host
+    os.environ["SHINY_PORT"] = str(port)
+
     if isinstance(app, str):
         app, app_dir = resolve_app(app, app_dir)
 
@@ -202,25 +225,20 @@ def run_app(
     else:
         reload_dirs = []
 
-    if reload and autoreload_port != "":
-        m = re.search("^([+-]?)(\\d+)$", autoreload_port)
-        if not m:
-            sys.stderr.write(
-                "Error: Couldn't understand the provided value for --autoreload-port\n"
-            )
-            exit(1)
-        autoreload_port_num = int(m.group(2))
-        if m.group(1) == "+":
-            autoreload_port_num += port
-        elif m.group(1) == "-":
-            autoreload_port_num = port - autoreload_port_num
-
-        if autoreload_port_num == port:
+    if reload:
+        if autoreload_port == 0:
+            autoreload_port = _utils.random_port(host=host)
+
+        if autoreload_port == port:
             sys.stderr.write(
                 "Autoreload port is already being used by the app; disabling autoreload\n"
             )
+            reload = False
         else:
-            setup_hot_reload(log_config, autoreload_port_num, port)
+            setup_hot_reload(log_config, autoreload_port, port, launch_browser)
+
+    if launch_browser and not reload:
+        setup_launch_browser(log_config)
 
     maybe_setup_rsw_proxying(log_config)
 
@@ -240,17 +258,32 @@ def run_app(
 
 
 def setup_hot_reload(
-    log_config: Dict[str, Any], autoreload_port: int, app_port: int
+    log_config: Dict[str, Any],
+    autoreload_port: int,
+    app_port: int,
+    launch_browser: bool,
 ) -> None:
     # The only way I've found to get notified when uvicorn decides to reload, is by
     # inserting a custom log handler.
     log_config["handlers"]["shiny_hot_reload"] = {
         "class": "shiny._autoreload.HotReloadHandler",
         "level": "INFO",
     }
-    log_config["loggers"]["uvicorn.error"]["handlers"] = ["shiny_hot_reload"]
+    if "handlers" not in log_config["loggers"]["uvicorn.error"]:
+        log_config["loggers"]["uvicorn.error"]["handlers"] = []
+    log_config["loggers"]["uvicorn.error"]["handlers"].append("shiny_hot_reload")
 
-    _autoreload.start_server(autoreload_port, app_port)
+    _autoreload.start_server(autoreload_port, app_port, launch_browser)
+
+
+def setup_launch_browser(log_config: Dict[str, Any]):
+    log_config["handlers"]["shiny_launch_browser"] = {
+        "class": "shiny._launchbrowser.LaunchBrowserHandler",
+        "level": "INFO",
+    }
+    if "handlers" not in log_config["loggers"]["uvicorn.error"]:
+        log_config["loggers"]["uvicorn.error"]["handlers"] = []
+    log_config["loggers"]["uvicorn.error"]["handlers"].append("shiny_launch_browser")
 
 
 def maybe_setup_rsw_proxying(log_config: Dict[str, Any]) -> None:

shiny/_utils.py

@@ -7,6 +7,7 @@
 import os
 import random
 import secrets
+import socketserver
 import sys
 import tempfile
 from typing import (
@@ -81,6 +82,54 @@ def guess_mime_type(
     return mimetypes.guess_type(url, strict)[0] or default
 
 
+def random_port(
+    min: int = 1024, max: int = 49151, host: str = "127.0.0.1", n: int = 20
+) -> int:
+    """Find an open TCP port
+
+    Finds a random available TCP port for listening on, within a specified range
+    of ports. The default range of ports to check is 1024 to 49151, which is the
+    set of TCP User Ports. This function automatically excludes some ports which
+    are considered unsafe by web browsers.
+
+    Parameters
+    ----------
+    min
+        Minimum port number.
+    max
+        Maximum port number, inclusive.
+    host
+        Before returning a port number, ensure that we can successfully bind it on this
+        host.
+    n
+        Number of times to attempt before giving up.
+    """
+
+    # fmt: off
+    # From https://github.com/rstudio/httpuv/blob/main/R/random_port.R
+    unsafe_ports = [1, 7, 9, 11, 13, 15, 17, 19, 20, 21, 22, 23, 25, 37, 42, 43, 53, 77, 79, 87, 95, 101, 102, 103, 104, 109, 110, 111, 113, 115, 117, 119, 123, 135, 139, 143, 179, 389, 427, 465, 512, 513, 514, 515, 526, 530, 531, 532, 540, 548, 556, 563, 587, 601, 636, 993, 995, 2049, 3659, 4045, 6000, 6665, 6666, 6667, 6668, 6669, 6697]
+    # fmt: on
+    unusable = set([x for x in unsafe_ports if x >= min and x <= max])
+    while n > 0:
+        if (max - min + 1) <= len(unusable):
+            break
+        port = round(random.random() * (max - min) + min)
+        if port in unusable:
+            continue
+        try:
+            # See if we can successfully bind
+            with socketserver.TCPServer(
+                (host, port), socketserver.BaseRequestHandler, bind_and_activate=False
+            ) as s:
+                s.server_bind()
+                return port
+        except Exception:
+            n -= 1
+            continue
+
+    raise RuntimeError("Failed to find a usable random port")
+
+
 # ==============================================================================
 # Private random stream
 # ==============================================================================
@@ -163,8 +212,7 @@ def run_coro_sync(coro: Awaitable[T]) -> T:
     value. If it does not complete, then it will throw a `RuntimeError`.
 
     What it means to be "in fact synchronous": the coroutine must not yield
-    control to the event loop. A coroutine may have an `await` expression in it,
-    and that may call another function that has an `await`, but the chain will
+    control to the event loop. A coroutine may have an `await` expression in it, and that may call another function that has an `await`, but the chain will
     only yield control if a `yield` statement bubbles through `await`s all the
     way up. For example, `await asyncio.sleep(0)` will have a `yield` which
     bubbles up to the next level. Note that a `yield` in a generator used the

tests/test_utils.py

@@ -1,7 +1,9 @@
-import pytest
 import random
-from shiny._utils import AsyncCallbacks, Callbacks, private_seed
-from typing import List
+import socketserver
+from typing import List, Set
+
+import pytest
+from shiny._utils import AsyncCallbacks, Callbacks, private_seed, random_port
 
 
 def test_randomness():
@@ -132,3 +134,26 @@ async def mutate_registrations():
     assert cb2.exec_count == 1  # Unregistered by previous invoke, not called again
     assert cb3.exec_count == 1  # once=True, so not called again
     assert cb4.exec_count == 1  # Registered during previous invoke(), was called
+
+
+def test_random_port():
+    assert random_port(9000, 9000) == 9000
+
+    seen: Set[int] = set()
+    # Ensure that 10 unique random ports are eventually generated. If not (e.g. if the
+    # max port number is treated as exclusive instead of inclusive, say) then the while
+    # loop will not exit and the test will timeout.
+    while len(seen) < 10:
+        seen.add(random_port(9001, 9010))
+
+
+def test_random_port_unusable():
+    # 6000 is an unsafe port, make sure that it fails
+    with pytest.raises(RuntimeError, match="Failed to find a usable random port"):
+        random_port(6000, 6000)
+
+
+def test_random_port_starvation():
+    with socketserver.TCPServer(("127.0.0.1", 9000), socketserver.BaseRequestHandler):
+        with pytest.raises(RuntimeError, match="Failed to find a usable random port"):
+            random_port(9000, 9000)