feat(session): Add session.allow_reconnect() (#2441)

Author: schloerke

CHANGELOG.md

@@ -13,6 +13,10 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 * `playwright.controller.OutputTextVerbatim` is deprecated alongside `ui.output_text_verbatim()` and now emits a `ShinyDeprecationWarning` when constructed. Please use `playwright.controller.OutputCode` instead. (#2097)
 
+### New features
+
+* Added `session.allow_reconnect()`, the Python counterpart to Shiny for R's `session$allowReconnect()`. Call it with `True` to let the browser reconnect to its session (showing a countdown dialog instead of the "Disconnected from server" overlay) when the hosting environment keeps sessions alive after a client disconnects, or with `"force"` to attempt the reconnect anywhere. (#2441)
+
 ### Improvements
 
 * The README and the `shiny skills` CLI help now explain that [`library-skills`](https://library-skills.io) must be run from your own project directory, since it installs the bundled Agent Skills of the packages that project has installed. The previous wording left that precondition implicit, so running the command from an empty directory or from a clone of py-shiny silently installed nothing. (#2447)

docs/_quartodoc-core.yml

@@ -296,6 +296,7 @@ quartodoc:
             - session.Session.on_flushed
             - session.Session.on_ended
             - session.Session.dynamic_route
+            - session.Session.allow_reconnect
             - session.Session.close
             - input_handler.input_handlers
         - kind: page

shiny/api-examples/session_allow_reconnect/app-core.py

@@ -0,0 +1,32 @@
+from shiny import App, Inputs, Outputs, Session, render, ui
+
+app_ui = ui.page_fluid(
+    ui.markdown("""
+        This app lets the browser reconnect after its connection to the server
+        drops. Use the button below to close the connection: instead of the
+        usual "Disconnected from server" overlay, you should see a countdown
+        dialog while the client reconnects, and the counter below should keep
+        working once it does.
+
+        `"force"` is used here so the reconnect is attempted even when the
+        hosting environment does not support resuming sessions. Use `True` in
+        production so the client only reconnects where the session is actually
+        kept alive.
+        """),
+    ui.input_action_button(
+        "close", "Close the connection", onclick="Shiny.shinyapp.$socket.close()"
+    ),
+    ui.input_action_button("count", "Count"),
+    ui.output_text("counter"),
+)
+
+
+def server(input: Inputs, output: Outputs, session: Session):
+    session.allow_reconnect("force")
+
+    @render.text
+    def counter():
+        return f"Clicked {input.count()} times."
+
+
+app = App(app_ui, server)

shiny/api-examples/session_allow_reconnect/app-express.py

@@ -0,0 +1,25 @@
+from shiny.express import input, render, session, ui
+
+ui.markdown("""
+    This app lets the browser reconnect after its connection to the server
+    drops. Use the button below to close the connection: instead of the usual
+    "Disconnected from server" overlay, you should see a countdown dialog while
+    the client reconnects, and the counter below should keep working once it
+    does.
+
+    `"force"` is used here so the reconnect is attempted even when the hosting
+    environment does not support resuming sessions. Use `True` in production so
+    the client only reconnects where the session is actually kept alive.
+    """)
+
+ui.input_action_button(
+    "close", "Close the connection", onclick="Shiny.shinyapp.$socket.close()"
+)
+ui.input_action_button("count", "Count")
+
+session.allow_reconnect("force")
+
+
+@render.text
+def counter():
+    return f"Clicked {input.count()} times."

shiny/session/_session.py

@@ -260,6 +260,46 @@ async def close(self, code: int = 1001) -> None:
         Close the session.
         """
 
+    @add_example(example_name="session_allow_reconnect")
+    def allow_reconnect(self, value: bool | Literal["force"]) -> None:
+        """
+        Allow the client to reconnect to a session after a disconnect.
+
+        By default, when the websocket connection between the browser and the server
+        drops, Shiny displays the "Disconnected from server" overlay and the client
+        gives up. Calling this method with ``True`` tells the client to instead show a
+        countdown dialog and attempt to reconnect to its session.
+
+        On a successful reconnect, the browser sends all of its current input values to
+        the session on the server, and the server recalculates any outputs and sends
+        them back to the client.
+
+        Parameters
+        ----------
+        value
+            One of the following:
+
+            * ``True``: allow the client to reconnect after a disconnect, but only when
+              running in a hosting environment (such as Posit Connect or Shiny Server)
+              that has reconnections enabled.
+            * ``False``: do not allow the client to reconnect. This is the default.
+            * ``"force"``: always attempt to reconnect, regardless of what the hosting
+              environment reports.
+
+        Note
+        ----
+        Reconnecting requires the server to keep the session alive after the client
+        disconnects, which is a feature of the hosting environment rather than of Shiny
+        itself. ``"force"`` exists for testing on a local connection: the client will
+        try to reconnect anywhere, but on a plain ``shiny run`` server the attempt
+        starts a brand new session rather than resuming the old one.
+        """
+        if value is not True and value is not False and value != "force":
+            raise ValueError(
+                f'`value` must be `True`, `False`, or `"force"`, not {value!r}.'
+            )
+        self._send_message_sync({"allowReconnect": value})
+
     @abstractmethod
     def _is_closed(self) -> bool:
         """

shiny/www/shared/_version.json

@@ -1,5 +1,5 @@
 {
   "note!": "Generated by scripts/htmlDependencies.R: do not edit by hand",
   "package": "shiny",
-  "version": "1.14.0.9000 (rstudio/shiny@ef93041ff7cbef679dbc37f527e09427eaf8d80a)"
+  "version": "1.14.0.9000 (rstudio/shiny@d19095f4b3dd2b699406db2693c487fb38bd2d4a)"
 }

shiny/www/shared/bootstrap/_version.json

@@ -1,6 +1,6 @@
 {
   "note!": "Generated by scripts/htmlDependencies.R: do not edit by hand",
-  "shiny_version": "1.14.0.9000 (rstudio/shiny@ef93041ff7cbef679dbc37f527e09427eaf8d80a)",
+  "shiny_version": "1.14.0.9000 (rstudio/shiny@d19095f4b3dd2b699406db2693c487fb38bd2d4a)",
   "bslib_version": "0.12.0.9000 (rstudio/bslib@97aa1abc262bff3fdfab686d4206a45fe7276ad6)",
   "htmltools_version": "0.5.9.9000 (rstudio/htmltools@5135d17923ab80b3599da1f335d5d33eb9aa63a3)",
   "bootstrap_version": "5.3.8"