From f523d8068626671f75a6a87cf366224b2cbfa84a Mon Sep 17 00:00:00 2001 From: Christian Tabedzki <35670232+tabedzki@users.noreply.github.com> Date: Sat, 7 Nov 2026 07:13:39 -0500 Subject: [PATCH 1/2] fix: warm the first session before the server accepts connections panel serve runs app.py per session on the event loop that serves every session and /liveness, so the first visit after each start paid for the imports, the wiring pickle and the default atlas's metadata on that loop. Run one throwaway ChannelmapGUI through panel serve --setup instead, before the port is bound. It has no document, so it leaves no session behind. A failed warmup logs a warning and the server still starts. Assisted-by: ClaudeCode:claude-opus-5-5 --- entrypoint.sh | 4 ++ pixelmap/gui/gui.py | 18 +++---- scripts/warm_first_session.py | 31 +++++++++++ tests/test_startup_warmup.py | 98 +++++++++++++++++++++++++++++++++++ 4 files changed, 142 insertions(+), 9 deletions(-) create mode 100644 scripts/warm_first_session.py create mode 100644 tests/test_startup_warmup.py 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..0c0acc6 100644 --- a/pixelmap/gui/gui.py +++ b/pixelmap/gui/gui.py @@ -77,12 +77,12 @@ # 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 only covers notebook/library use. +# `pn.config.notifications` is stored per-session (keyed on `pn.state.curdoc`), +# and under `panel serve` this module is imported once, by the startup warmup +# or by whichever session comes first, so later sessions wouldn't be +# configured by it. `create_app` therefore repeats the call per session -- see +# the note there. PANEL_EXTENSIONS = ("tabulator",) pn.extension(*PANEL_EXTENSIONS, notifications=True) @@ -3392,9 +3392,9 @@ 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, and without this + # sessions get `pn.state.notifications is None`. 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..e9a266d --- /dev/null +++ b/scripts/warm_first_session.py @@ -0,0 +1,31 @@ +"""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, including bytecode compilation on a fresh +image, 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 exactly what a session needs, without a list here to keep +in step with the constructor. It has no document, so no session, analytics +event or callback outlives it. + +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..378730f --- /dev/null +++ b/tests/test_startup_warmup.py @@ -0,0 +1,98 @@ +"""The first session must not pay one-time startup costs on the event loop. + +``panel serve`` imports ``app.py`` per session, on the Bokeh event loop that +serves every session and ``/liveness``. Whatever is cold (the imports, the +wiring pickle, the default atlas's metadata) therefore froze the server during +the first visit after every start. ``entrypoint.sh`` warms all of it through +Panel's ``--setup`` hook, before the server accepts connections. +""" + +from __future__ import annotations + +import logging +import re +import runpy +import subprocess +import sys +from pathlib import Path + +import panel as pn +import pytest + +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" + + +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_one_time_caches_in_a_fresh_process(): + probe = ( + "import runpy, sys\n" + f"runpy.run_path({str(SCRIPT)!r})\n" + "assert 'pixelmap.gui.gui' in sys.modules\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): + built = [] + real = gui_module.ChannelmapGUI + + def spy(*args, **kwargs): + built.append(real(*args, **kwargs)) + return built[-1] + + monkeypatch.setattr(gui_module, "ChannelmapGUI", spy) + views_before = set(pn.state._views) + + namespace = runpy.run_path(str(SCRIPT)) + + assert len(built) == 1 + assert pn.state.curdoc is None + assert set(pn.state._views) == views_before + assert not any(isinstance(v, real) for v in namespace.values()) + + +@pytest.mark.parametrize("error", [RuntimeError("no wiring"), OSError("disk"), ValueError("bad")]) +def test_a_failing_warmup_does_not_stop_the_server(monkeypatch, caplog, error): + def boom(): + raise error + + monkeypatch.setattr(gui_module, "ChannelmapGUI", boom) + with caplog.at_level(logging.WARNING, logger="pixelmap.startup"): + runpy.run_path(str(SCRIPT)) # Panel aborts startup if this raises + assert any(str(error) in r.getMessage() or r.exc_info for r in caplog.records) + + +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) + with caplog.at_level(logging.WARNING, logger="pixelmap.startup"): + runpy.run_path(str(SCRIPT)) + assert any(r.exc_info for r in caplog.records) + + +def test_warmup_with_no_atlas_on_disk_never_opens_or_downloads_one(monkeypatch): + opened = [] + monkeypatch.setattr(atlas_module, "get_downloaded_atlases", list) + monkeypatch.setattr(atlas_module, "BrainGlobeAtlas", lambda *a, **k: opened.append(a)) + atlas_module.get_atlas.cache_clear() + try: + runpy.run_path(str(SCRIPT)) + finally: + atlas_module.get_atlas.cache_clear() + assert opened == [] From 15635de4c6833bd03de96bb28acc03eb3f47be2a Mon Sep 17 00:00:00 2001 From: Christian Tabedzki <35670232+tabedzki@users.noreply.github.com> Date: Sat, 7 Nov 2026 08:04:51 -0500 Subject: [PATCH 2/2] test: tighten warmup coverage and correct its docs The script swallows every exception, so tests must also assert no failure was logged, or they pass when the constructor raises. Cover opening the default atlas when it is on disk, and share the run-and-collect-failures helper. Say that the warmup only runs before the port is bound with NUM_PROCS=1, and drop the bytecode and "exactly what a session needs" claims. Assisted-by: ClaudeCode:claude-opus-5-5 --- pixelmap/gui/gui.py | 13 ++---- scripts/warm_first_session.py | 14 ++++-- tests/test_startup_warmup.py | 86 +++++++++++++++++++---------------- 3 files changed, 59 insertions(+), 54 deletions(-) diff --git a/pixelmap/gui/gui.py b/pixelmap/gui/gui.py index 0c0acc6..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. -# `pn.config.notifications` is stored per-session (keyed on `pn.state.curdoc`), -# and under `panel serve` this module is imported once, by the startup warmup -# or by whichever session comes first, so later sessions wouldn't be -# configured by it. `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 whatever happened to trigger the import, and without this - # sessions get `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 index e9a266d..d1e5911 100644 --- a/scripts/warm_first_session.py +++ b/scripts/warm_first_session.py @@ -2,13 +2,17 @@ ``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, including bytecode compilation on a fresh -image, the wiring pickle, the default atlas's metadata) would freeze that loop. +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 exactly what a session needs, without a list here to keep -in step with the constructor. It has no document, so no session, analytics -event or callback outlives it. +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. diff --git a/tests/test_startup_warmup.py b/tests/test_startup_warmup.py index 378730f..f10a129 100644 --- a/tests/test_startup_warmup.py +++ b/tests/test_startup_warmup.py @@ -1,11 +1,4 @@ -"""The first session must not pay one-time startup costs on the event loop. - -``panel serve`` imports ``app.py`` per session, on the Bokeh event loop that -serves every session and ``/liveness``. Whatever is cold (the imports, the -wiring pickle, the default atlas's metadata) therefore froze the server during -the first visit after every start. ``entrypoint.sh`` warms all of it through -Panel's ``--setup`` hook, before the server accepts connections. -""" +"""Tests for scripts/warm_first_session.py, which explains why the warmup exists.""" from __future__ import annotations @@ -15,9 +8,9 @@ import subprocess import sys from pathlib import Path +from unittest.mock import MagicMock, Mock import panel as pn -import pytest from pixelmap.anatomy import atlas as atlas_module from pixelmap.gui import gui as gui_module @@ -25,6 +18,14 @@ 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(): @@ -34,11 +35,10 @@ def test_entrypoint_runs_the_warmup_before_serving(): assert (ROOT / match.group(1)).resolve() == SCRIPT -def test_warmup_fills_the_one_time_caches_in_a_fresh_process(): +def test_warmup_fills_the_wiring_cache_in_a_fresh_process(): probe = ( - "import runpy, sys\n" + "import runpy\n" f"runpy.run_path({str(SCRIPT)!r})\n" - "assert 'pixelmap.gui.gui' in sys.modules\n" "from pixelmap import backend\n" "assert backend._load_wiring_maps.cache_info().currsize == 1\n" ) @@ -48,51 +48,57 @@ def test_warmup_fills_the_one_time_caches_in_a_fresh_process(): assert done.returncode == 0, done.stderr -def test_warmup_builds_one_gui_and_keeps_no_session_state(monkeypatch): - built = [] +def test_warmup_builds_one_gui_and_keeps_no_session_state(monkeypatch, caplog): real = gui_module.ChannelmapGUI - - def spy(*args, **kwargs): - built.append(real(*args, **kwargs)) - return built[-1] - + spy = Mock(wraps=real) monkeypatch.setattr(gui_module, "ChannelmapGUI", spy) views_before = set(pn.state._views) - namespace = runpy.run_path(str(SCRIPT)) + namespace, failures = _run_warmup(caplog) - assert len(built) == 1 + 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(v, real) for v in namespace.values()) + assert not any(isinstance(value, real) for value in namespace.values()) -@pytest.mark.parametrize("error", [RuntimeError("no wiring"), OSError("disk"), ValueError("bad")]) -def test_a_failing_warmup_does_not_stop_the_server(monkeypatch, caplog, error): - def boom(): - raise error - - monkeypatch.setattr(gui_module, "ChannelmapGUI", boom) - with caplog.at_level(logging.WARNING, logger="pixelmap.startup"): - runpy.run_path(str(SCRIPT)) # Panel aborts startup if this raises - assert any(str(error) in r.getMessage() or r.exc_info for r in caplog.records) +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) - with caplog.at_level(logging.WARNING, logger="pixelmap.startup"): - runpy.run_path(str(SCRIPT)) - assert any(r.exc_info for r in caplog.records) + _, 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): - opened = [] - monkeypatch.setattr(atlas_module, "get_downloaded_atlases", list) - monkeypatch.setattr(atlas_module, "BrainGlobeAtlas", lambda *a, **k: opened.append(a)) +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: - runpy.run_path(str(SCRIPT)) + _, failures = _run_warmup(caplog) finally: atlas_module.get_atlas.cache_clear() - assert opened == [] + assert failures == [] + fake_atlas.assert_not_called()