diff --git a/entrypoint.sh b/entrypoint.sh index 301e35c..0cccb76 100644 --- a/entrypoint.sh +++ b/entrypoint.sh @@ -68,7 +68,11 @@ log "NUM_PROCS $NUM_PROCS" # # --mem-log-frequency periodically logs RSS (via psutil) so an OOM kill # (SIGKILL, exit 137) leaves a trail in the logs instead of nothing. +# +# --setup warms what the first session would otherwise load on the event loop, +# freezing every session and /liveness (see scripts/warm_first_session.py). exec "$PYTHON_BIN" -m panel serve ./app.py \ + --setup ./scripts/warm_first_session.py \ --address "$ADDRESS" \ --port "$INTERNAL_PORT" \ --allow-websocket-origin "$ALLOW_WEBSOCKET_ORIGIN" \ diff --git a/pixelmap/gui/gui.py b/pixelmap/gui/gui.py index 61a73dd..dd5c2f1 100644 --- a/pixelmap/gui/gui.py +++ b/pixelmap/gui/gui.py @@ -77,12 +77,8 @@ # Enable Panel extensions. # -# This module-level call only covers notebook/library use and the *first* -# session of a server. `pn.config.notifications` is stored per-session -# (keyed on `pn.state.curdoc`), and under `panel serve` this module is -# imported inside the first session's document context, so every later -# session would inherit the default of False. `create_app` therefore -# repeats the call per session -- see the note there. +# This module-level call is for notebook/library use. `create_app` repeats it +# per session -- see the note there. PANEL_EXTENSIONS = ("tabulator",) pn.extension(*PANEL_EXTENSIONS, notifications=True) @@ -3392,9 +3388,8 @@ def create_app(): """Create and configure the Panel app""" # Re-arm the extensions for *this* session. Panel keys `config` on the # current document, so the module-level `pn.extension` above only ever - # configured whichever session happened to trigger the import -- under - # `panel serve` that is session #1, and everyone after it got - # `pn.state.notifications is None`. Must stay inside the app factory. + # configured whatever happened to trigger the import, so each session arms + # its own. Must stay inside the app factory. # `exception_handler` is per-session for the same reason: it turns any # callback error into a toast + webhook report instead of a re-raise. pn.extension( diff --git a/scripts/warm_first_session.py b/scripts/warm_first_session.py new file mode 100644 index 0000000..d1e5911 --- /dev/null +++ b/scripts/warm_first_session.py @@ -0,0 +1,35 @@ +"""Pay the first session's one-time costs before the server accepts connections. + +``panel serve`` runs ``app.py`` per session on the Bokeh event loop, which also +serves every other session and ``/liveness``. Whatever is still cold when the +first visitor arrives (the imports, the wiring pickle, the default atlas's +metadata) would freeze that loop. + +``entrypoint.sh`` runs this through ``panel serve --setup``. Building one +throwaway GUI warms the one-time costs of a session's build, without a list here +to keep in step with the constructor. It has no document, so it creates no +session or analytics event. + +This runs before the port is bound only with ``NUM_PROCS=1``, the image's +default. Above that, Panel runs it on each process's event loop after the +server starts, which costs about what the first session would pay anyway. + +A failure only costs the speed-up, and the first session reports it properly, +so it must not stop the server: Panel aborts startup if this script raises. +""" + +import logging +import time + +_started = time.perf_counter() +try: + from pixelmap.gui.gui import ChannelmapGUI + + ChannelmapGUI() +except Exception: # see the module docstring + logging.getLogger("pixelmap.startup").warning( + "First-session warmup failed; the first visitor will pay for it", + exc_info=True, + ) +else: + print(f"First-session warmup finished in {time.perf_counter() - _started:.1f} s") diff --git a/tests/test_startup_warmup.py b/tests/test_startup_warmup.py new file mode 100644 index 0000000..f10a129 --- /dev/null +++ b/tests/test_startup_warmup.py @@ -0,0 +1,104 @@ +"""Tests for scripts/warm_first_session.py, which explains why the warmup exists.""" + +from __future__ import annotations + +import logging +import re +import runpy +import subprocess +import sys +from pathlib import Path +from unittest.mock import MagicMock, Mock + +import panel as pn + +from pixelmap.anatomy import atlas as atlas_module +from pixelmap.gui import gui as gui_module + +ROOT = Path(__file__).resolve().parent.parent +ENTRYPOINT = ROOT / "entrypoint.sh" +SCRIPT = ROOT / "scripts" / "warm_first_session.py" +DEFAULT_ATLAS = "allen_mouse_25um" + + +def _run_warmup(caplog): + """Run the script as Panel would; return its namespace and logged failures.""" + with caplog.at_level(logging.WARNING, logger="pixelmap.startup"): + namespace = runpy.run_path(str(SCRIPT)) # Panel aborts startup if this raises + return namespace, [r for r in caplog.records if r.name == "pixelmap.startup"] + + +def test_entrypoint_runs_the_warmup_before_serving(): + entrypoint = ENTRYPOINT.read_text() + match = re.search(r"--setup\s+(\./\S+)", entrypoint) + assert match, "entrypoint.sh must pass --setup to panel serve" + assert (ROOT / match.group(1)).resolve() == SCRIPT + + +def test_warmup_fills_the_wiring_cache_in_a_fresh_process(): + probe = ( + "import runpy\n" + f"runpy.run_path({str(SCRIPT)!r})\n" + "from pixelmap import backend\n" + "assert backend._load_wiring_maps.cache_info().currsize == 1\n" + ) + done = subprocess.run( + [sys.executable, "-c", probe], capture_output=True, text=True, cwd=ROOT, timeout=300, check=False + ) + assert done.returncode == 0, done.stderr + + +def test_warmup_builds_one_gui_and_keeps_no_session_state(monkeypatch, caplog): + real = gui_module.ChannelmapGUI + spy = Mock(wraps=real) + monkeypatch.setattr(gui_module, "ChannelmapGUI", spy) + views_before = set(pn.state._views) + + namespace, failures = _run_warmup(caplog) + + spy.assert_called_once() + assert failures == [] # the script swallows errors, so the spy alone proves nothing + assert pn.state.curdoc is None + assert set(pn.state._views) == views_before + assert not any(isinstance(value, real) for value in namespace.values()) + + +def test_a_failing_warmup_does_not_stop_the_server(monkeypatch, caplog): + monkeypatch.setattr(gui_module, "ChannelmapGUI", Mock(side_effect=RuntimeError("no wiring"))) + _, failures = _run_warmup(caplog) + assert [r for r in failures if r.exc_info] + + +def test_a_failing_import_does_not_stop_the_server(monkeypatch, caplog): + # None in sys.modules makes `import pixelmap.gui.gui` raise ImportError. + monkeypatch.setitem(sys.modules, "pixelmap.gui.gui", None) + _, failures = _run_warmup(caplog) + assert [r for r in failures if r.exc_info] + + +def test_warmup_opens_the_default_atlas_when_it_is_on_disk(monkeypatch, caplog): + fake_atlas = MagicMock(return_value=MagicMock(orientation="asr", resolution=(25.0, 25.0, 25.0))) + monkeypatch.setattr(atlas_module, "get_downloaded_atlases", lambda: [DEFAULT_ATLAS]) + monkeypatch.setattr(atlas_module, "_annotation_is_cached", lambda atlas: True) + monkeypatch.setattr(atlas_module, "BrainGlobeAtlas", fake_atlas) + atlas_module.get_atlas.cache_clear() + try: + _, failures = _run_warmup(caplog) + assert failures == [] + fake_atlas.assert_any_call(DEFAULT_ATLAS, check_latest=False) + assert atlas_module.get_atlas.cache_info().currsize == 1 + finally: + atlas_module.get_atlas.cache_clear() + + +def test_warmup_with_no_atlas_on_disk_never_opens_or_downloads_one(monkeypatch, caplog): + fake_atlas = Mock() + monkeypatch.setattr(atlas_module, "get_downloaded_atlases", list) # always empty + monkeypatch.setattr(atlas_module, "BrainGlobeAtlas", fake_atlas) + atlas_module.get_atlas.cache_clear() + try: + _, failures = _run_warmup(caplog) + finally: + atlas_module.get_atlas.cache_clear() + assert failures == [] + fake_atlas.assert_not_called()