diff --git a/docker-compose.yml b/docker-compose.yml index 755f733..f613fd1 100644 --- a/docker-compose.yml +++ b/docker-compose.yml @@ -18,6 +18,9 @@ services: - ANALYTICS_COOKIE_MAX_AGE_DAYS=365 - ANALYTICS_COOKIE_SAMESITE=Lax - ANALYTICS_COOKIE_SECURE=false + # Optional: POST unhandled errors to a webhook (see docs/getting-started.md). + - PIXELMAP_ERROR_WEBHOOK_URL=${PIXELMAP_ERROR_WEBHOOK_URL:-} + - PIXELMAP_ERROR_WEBHOOK_TOKEN=${PIXELMAP_ERROR_WEBHOOK_TOKEN:-} volumes: - ./output:/app/output - brainglobe_cache:/root/.brainglobe diff --git a/docs/getting-started.md b/docs/getting-started.md index 32aeaf1..fd3e355 100644 --- a/docs/getting-started.md +++ b/docs/getting-started.md @@ -62,6 +62,20 @@ RAM is sized for multiple copies of every cache. Mount the RSS is logged to stdout every 60 s. ::: +:::{note} +**Error notifications**: errors raised while handling a user's action are +shown to that user as a toast and logged with a traceback; they do not take +down the session or the server. To also receive them, set +`PIXELMAP_ERROR_WEBHOOK_URL` to an `http(s)` endpoint. Each error is POSTed +as JSON with a one-line `text`/`content` summary (so Slack, Mattermost and +Discord incoming webhooks work as-is) and an `event` object holding the +type, message, traceback, session id, host and version. Optional settings: +`PIXELMAP_ERROR_WEBHOOK_TOKEN` (sent as `Authorization: Bearer `), +`PIXELMAP_ERROR_WEBHOOK_TIMEOUT` (seconds, default 5) and +`PIXELMAP_ERROR_WEBHOOK_DEDUPE_SECONDS` (identical errors are sent at most +once per window, default 60; `0` sends every one). +::: + ## Quick Start ### Option 1: Browser GUI diff --git a/env.template b/env.template index fdbdadd..7ab20da 100644 --- a/env.template +++ b/env.template @@ -16,3 +16,10 @@ ANALYTICS_COOKIE_NAME=pixelmap_visitor_id ANALYTICS_COOKIE_MAX_AGE_DAYS=365 ANALYTICS_COOKIE_SAMESITE=Lax ANALYTICS_COOKIE_SECURE=false + +# Error notifications (optional). Errors are always toasted to the user and +# logged; set a URL to also POST them as JSON (Slack/Discord-compatible). +PIXELMAP_ERROR_WEBHOOK_URL= +PIXELMAP_ERROR_WEBHOOK_TOKEN= +PIXELMAP_ERROR_WEBHOOK_TIMEOUT=5 +PIXELMAP_ERROR_WEBHOOK_DEDUPE_SECONDS=60 diff --git a/pixelmap/error_reporting.py b/pixelmap/error_reporting.py new file mode 100644 index 0000000..1d2a0aa --- /dev/null +++ b/pixelmap/error_reporting.py @@ -0,0 +1,443 @@ +"""Catch-all error reporting: toast for the user, webhook for the deployer. + +An exception escaping a GUI callback must never kill the server or leave a +session silently broken. Every such error is routed through `report_error`, +which + +* logs the full traceback (``pixelmap.errors`` logger), +* shows an error toast in the session that hit it (if there is one), and +* POSTs a JSON description to a webhook, if the deployer configured one. + +Webhook configuration (environment variables, read on every report): + +``PIXELMAP_ERROR_WEBHOOK_URL`` + http(s) endpoint to POST errors to. Unset or blank disables the webhook. +``PIXELMAP_ERROR_WEBHOOK_TOKEN`` + Optional; sent as ``Authorization: Bearer ``. +``PIXELMAP_ERROR_WEBHOOK_TIMEOUT`` + Seconds before a POST is abandoned (default 5). +``PIXELMAP_ERROR_WEBHOOK_DEDUPE_SECONDS`` + Identical errors (same type, message and location) are posted at most + once per window (default 60; 0 posts every occurrence). + +The payload carries ``text`` (Slack, Mattermost) and ``content`` (Discord) +summaries plus an ``event`` object with the structured details, so it can be +pointed straight at a chat webhook or at a custom collector. + +Webhook delivery runs on a single daemon thread with a bounded queue: a slow +or unreachable endpoint can neither block the Bokeh event loop nor pile up +memory, and excess reports are dropped rather than queued forever. +""" + +from __future__ import annotations + +import asyncio +import functools +import json +import logging +import math +import os +import queue +import socket +import sys +import threading +import time +import traceback +import urllib.error +import urllib.parse +import urllib.request +import weakref +from collections.abc import Callable, Mapping +from dataclasses import dataclass +from datetime import UTC, datetime +from typing import Any + +import panel as pn + +from pixelmap import __version__ + +logger = logging.getLogger("pixelmap.errors") + +DEFAULT_TIMEOUT_SECONDS = 5.0 +DEFAULT_DEDUPE_SECONDS = 60.0 +DEFAULT_MAX_PENDING = 20 +# Discord rejects `content` over 2000 chars; keep the summary under that. +MAX_TEXT_CHARS = 1900 +MAX_FIELD_CHARS = 8000 +MAX_TOAST_CHARS = 300 + + +def _safe_str(value: Any) -> str: + try: + return str(value) + except Exception: + return f"" + + +def _truncate(text: str, limit: int) -> str: + return text if len(text) <= limit else text[: limit - 1] + "…" + + +def _env_float(environ: Mapping[str, str], name: str, default: float, *, allow_zero: bool) -> float: + raw = environ.get(name) + if raw is None: + return default + try: + value = float(raw) + except ValueError: + return default + if not math.isfinite(value) or value < 0 or (value == 0 and not allow_zero): + return default + return value + + +####################### +#### Configuration #### +####################### + + +@dataclass(frozen=True) +class WebhookConfig: + url: str | None = None + token: str | None = None + timeout: float = DEFAULT_TIMEOUT_SECONDS + dedupe_seconds: float = DEFAULT_DEDUPE_SECONDS + + @property + def enabled(self) -> bool: + return self.url is not None + + def headers(self) -> dict[str, str]: + headers = { + "Content-Type": "application/json", + "User-Agent": f"pixelmap/{__version__}", + } + if self.token: + headers["Authorization"] = f"Bearer {self.token}" + return headers + + +def _valid_webhook_url(raw: str | None) -> str | None: + url = (raw or "").strip() + if not url: + return None + parsed = urllib.parse.urlsplit(url) + # Only http(s): urllib would happily "POST" to file:// or ftp:// URLs. + if parsed.scheme not in {"http", "https"} or not parsed.netloc: + logger.warning("Ignoring PIXELMAP_ERROR_WEBHOOK_URL: not an http(s) URL") + return None + return url + + +def load_webhook_config(environ: Mapping[str, str] | None = None) -> WebhookConfig: + environ = os.environ if environ is None else environ + return WebhookConfig( + url=_valid_webhook_url(environ.get("PIXELMAP_ERROR_WEBHOOK_URL")), + token=(environ.get("PIXELMAP_ERROR_WEBHOOK_TOKEN") or "").strip() or None, + timeout=_env_float( + environ, "PIXELMAP_ERROR_WEBHOOK_TIMEOUT", DEFAULT_TIMEOUT_SECONDS, allow_zero=False + ), + dedupe_seconds=_env_float( + environ, "PIXELMAP_ERROR_WEBHOOK_DEDUPE_SECONDS", DEFAULT_DEDUPE_SECONDS, allow_zero=True + ), + ) + + +################# +#### Payload #### +################# + + +def _format_traceback(exc: BaseException) -> str: + try: + return "".join(traceback.format_exception(type(exc), exc, exc.__traceback__)) + except Exception: + return f"" + + +def _current_session_id() -> str | None: + try: + return pn.state.curdoc.session_context.id + except Exception: + return None + + +def build_payload( + exc: BaseException, context: str | None = None, session_id: str | None = None +) -> dict[str, Any]: + error_type = type(exc).__name__ + message = _truncate(_safe_str(exc), MAX_FIELD_CHARS) + host = socket.gethostname() + summary = f"PixelMap {__version__} error on {host}" + if context: + summary += f" ({context})" + summary = _truncate(f"{summary}: {error_type}: {message}", MAX_TEXT_CHARS) + return { + "text": summary, + "content": summary, + "event": { + "app": "pixelmap", + "version": __version__, + "host": host, + "timestamp": datetime.now(UTC).isoformat(timespec="seconds"), + "context": _truncate(context, MAX_FIELD_CHARS) if context else None, + "session_id": session_id, + "error_type": error_type, + "error_message": message, + "traceback": _truncate(_format_traceback(exc), MAX_FIELD_CHARS), + }, + } + + +def post_webhook(payload: dict[str, Any], config: WebhookConfig) -> bool: + """POST ``payload`` to the webhook. Returns success; never raises.""" + if not config.enabled: + return False + try: + request = urllib.request.Request( + config.url, + data=json.dumps(payload).encode("utf-8"), + headers=config.headers(), + method="POST", + ) + with urllib.request.urlopen(request, timeout=config.timeout) as response: + return 200 <= response.status < 300 + except Exception as exc: + # Deliberately not report_error: a dead webhook must not recurse. + logger.warning("Error webhook delivery failed: %s", _safe_str(exc)) + return False + + +################## +#### Reporter #### +################## + + +def _dedupe_key(exc: BaseException) -> tuple: + location = None + tb = exc.__traceback__ + while tb is not None and tb.tb_next is not None: + tb = tb.tb_next + if tb is not None: + location = (tb.tb_frame.f_code.co_filename, tb.tb_lineno) + return (type(exc).__qualname__, _safe_str(exc)[:200], location) + + +def _toast(message: str) -> None: + """Show an error toast in the current session, if it has a notification area.""" + try: + notifications = pn.state.notifications + if notifications is not None: + notifications.error(message, duration=10_000) + except Exception: + logger.debug("Could not show error toast", exc_info=True) + + +class ErrorReporter: + def __init__( + self, + config_loader: Callable[[], WebhookConfig] = load_webhook_config, + sender: Callable[[dict[str, Any], WebhookConfig], bool] = post_webhook, + clock: Callable[[], float] = time.monotonic, + synchronous: bool = False, + max_pending: int = DEFAULT_MAX_PENDING, + ): + self._config_loader = config_loader + self._sender = sender + self._clock = clock + self._synchronous = synchronous + self._queue: queue.Queue = queue.Queue(maxsize=max_pending) + self._lock = threading.Lock() + self._last_sent: dict[tuple, float] = {} + self._worker: threading.Thread | None = None + + @property + def pending(self) -> int: + return self._queue.qsize() + + def report( + self, exc: BaseException, context: str | None = None, *, notify_user: bool = True + ) -> None: + """Log, toast and webhook ``exc``. Never raises.""" + try: + self._report(exc, context, notify_user) + except Exception: + # Last line of defence: the reporter itself must not crash callers. + try: + logger.exception("Error reporter failed") + except Exception: + pass + + def _report(self, exc: BaseException, context: str | None, notify_user: bool) -> None: + logger.error( + "Unhandled error%s: %s", + f" in {context}" if context else "", + _safe_str(exc), + exc_info=(type(exc), exc, exc.__traceback__), + ) + try: + config = self._config_loader() + except Exception: + logger.exception("Could not load error webhook config") + config = WebhookConfig() + + if notify_user: + message = f"Something went wrong: {type(exc).__name__}: {_safe_str(exc)}" + message = _truncate(message, MAX_TOAST_CHARS) + if config.enabled: + message += " (the error has been reported)" + _toast(message) + + if config.enabled and self._should_send(exc, config): + self._dispatch(build_payload(exc, context, _current_session_id()), config) + + def _should_send(self, exc: BaseException, config: WebhookConfig) -> bool: + if config.dedupe_seconds <= 0: + return True + key = _dedupe_key(exc) + now = self._clock() + with self._lock: + last = self._last_sent.get(key) + if last is not None and now - last < config.dedupe_seconds: + return False + self._last_sent[key] = now + # Keep the table from growing without bound under varied errors. + if len(self._last_sent) > 1000: + cutoff = now - config.dedupe_seconds + self._last_sent = {k: t for k, t in self._last_sent.items() if t >= cutoff} + return True + + def _dispatch(self, payload: dict[str, Any], config: WebhookConfig) -> None: + if self._synchronous: + self._sender(payload, config) + return + self._ensure_worker() + try: + self._queue.put_nowait((payload, config)) + except queue.Full: + logger.warning("Error webhook backlog full; dropping report") + + def _ensure_worker(self) -> None: + with self._lock: + if self._worker is None or not self._worker.is_alive(): + self._worker = threading.Thread( + target=self._drain, name="pixelmap-error-webhook", daemon=True + ) + self._worker.start() + + def _drain(self) -> None: + while True: + payload, config = self._queue.get() + try: + self._sender(payload, config) + except Exception: + logger.warning("Error webhook sender raised", exc_info=True) + + +_REPORTER = ErrorReporter() + + +def report_error( + exc: BaseException, context: str | None = None, *, notify_user: bool = True +) -> None: + """Report ``exc`` via the process-wide reporter. Never raises.""" + _REPORTER.report(exc, context, notify_user=notify_user) + + +############### +#### Hooks #### +############### + + +def session_exception_handler(exc: BaseException) -> None: + """Panel ``config.exception_handler``: every widget/param callback error lands here. + + Returning normally (rather than re-raising, Panel's default) also keeps + Bokeh from discarding the document writes the callback already made. + """ + try: + report_error(exc, context="GUI callback") + except Exception: + pass + + +def guarded(context: str): + """Decorate a raw Bokeh callback so its errors are reported, not raised. + + Panel's ``exception_handler`` only covers Panel-managed callbacks; Bokeh + ``on_change`` callbacks bypass it, and an exception there makes Bokeh drop + the pending document patch for the whole callback. + """ + + def decorate(func): + @functools.wraps(func) + def wrapper(*args, **kwargs): + try: + return func(*args, **kwargs) + except Exception as exc: + report_error(exc, context=context) + return None + + return wrapper + + return decorate + + +_GLOBAL_HANDLERS_INSTALLED = False +_LOOPS_WITH_HANDLER: weakref.WeakSet = weakref.WeakSet() + + +def install_global_handlers() -> None: + """Report errors from background threads and anything reaching top level. + + No toast: these are not tied to a user session. Idempotent. + """ + global _GLOBAL_HANDLERS_INSTALLED + if _GLOBAL_HANDLERS_INSTALLED: + return + _GLOBAL_HANDLERS_INSTALLED = True + + previous_thread_hook = threading.excepthook + + def thread_hook(args): + if args.exc_value is not None and not issubclass(args.exc_type, SystemExit): + name = args.thread.name if args.thread is not None else "unknown" + report_error(args.exc_value, context=f"thread {name}", notify_user=False) + previous_thread_hook(args) + + previous_sys_hook = sys.excepthook + + def sys_hook(exc_type, exc_value, exc_tb): + if exc_value is not None and not issubclass(exc_type, KeyboardInterrupt): + report_error(exc_value, context="uncaught", notify_user=False) + previous_sys_hook(exc_type, exc_value, exc_tb) + + threading.excepthook = thread_hook + sys.excepthook = sys_hook + + +def install_loop_handler(loop: asyncio.AbstractEventLoop | None = None) -> None: + """Report exceptions the event loop would otherwise only log (e.g. orphaned tasks).""" + if loop is None: + try: + loop = asyncio.get_running_loop() + except RuntimeError: + return + if loop in _LOOPS_WITH_HANDLER: + return + _LOOPS_WITH_HANDLER.add(loop) + + previous = loop.get_exception_handler() + + def handler(loop, context): + exc = context.get("exception") + message = _safe_str(context.get("message", "event loop error")) + if exc is None: + exc = RuntimeError(message) + report_error(exc, context=f"event loop: {message}", notify_user=False) + if previous is not None: + previous(loop, context) + else: + loop.default_exception_handler(context) + + loop.set_exception_handler(handler) diff --git a/pixelmap/gui/app_util.py b/pixelmap/gui/app_util.py index ac5a315..935d1eb 100644 --- a/pixelmap/gui/app_util.py +++ b/pixelmap/gui/app_util.py @@ -8,9 +8,12 @@ import panel as pn import psutil +from pixelmap.error_reporting import install_global_handlers from pixelmap.gui.gui import create_app pn.extension(notifications=True) +# Background-thread and top-level errors go to the error webhook too. +install_global_handlers() # Browser tab icon, served by Bokeh at /favicon.ico -- assets/npix_map_logo.png # centred on a transparent square canvas, at 16-256px. Passed to pn.serve below; diff --git a/pixelmap/gui/gui.py b/pixelmap/gui/gui.py index 14c3a21..c103016 100644 --- a/pixelmap/gui/gui.py +++ b/pixelmap/gui/gui.py @@ -42,6 +42,8 @@ from pixelmap import __version__, backend from pixelmap.analytics import AnalyticsSessionTracker +from pixelmap import error_reporting +from pixelmap.error_reporting import guarded from pixelmap.constants import ( PROBE_FEATURES, PROBE_TYPE_MAP, @@ -2211,7 +2213,9 @@ def setup_interactions(self): ) # Python callbacks for interactions - this is the key part - self.electrode_source.selected.on_change("indices", self.on_electrode_selection) + self.electrode_source.selected.on_change( + "indices", guarded("electrode selection")(self.on_electrode_selection) + ) def setup_tool_monitoring(self, select_box_string, deselect_box_string, zigzagselect_box_string, interleavedselect_box_string, dependentdeselect_box_string): """JS callback to expose active tools in toolbar""" @@ -2280,7 +2284,9 @@ def setup_tool_monitoring(self, select_box_string, deselect_box_string, zigzagse self.plot.js_on_event("selectiongeometry", JS_selection_monitor) # Selection events self.plot.js_on_event("tap", JS_selection_monitor) # Plot clicks self.plot.js_on_event(events.MouseMove, JS_selection_monitor) # Mouse move - self.tool_state_source.on_change("data", self.on_tool_state_change) + self.tool_state_source.on_change( + "data", guarded("selection tool change")(self.on_tool_state_change) + ) def on_tool_state_change(self, attr, old, new): """Handle tool detection during selection""" @@ -3173,9 +3179,25 @@ def create_app(): # 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. - pn.extension(*PANEL_EXTENSIONS, notifications=True) + # `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( + *PANEL_EXTENSIONS, + notifications=True, + exception_handler=error_reporting.session_exception_handler, + ) + error_reporting.install_loop_handler() - gui = ChannelmapGUI() + try: + gui = ChannelmapGUI() + except Exception as exc: + # Show the visitor something instead of a blank page. + error_reporting.report_error(exc, context="session startup", notify_user=False) + return pn.pane.Alert( + "PixelMap failed to start. Please reload the page; if this keeps " + "happening, report it at https://github.com/m-beau/pixelmap/issues.", + alert_type="danger", + ) cfg = _extract_cfg_from_session_args() if cfg: diff --git a/tests/test_error_reporting.py b/tests/test_error_reporting.py new file mode 100644 index 0000000..000acb3 --- /dev/null +++ b/tests/test_error_reporting.py @@ -0,0 +1,555 @@ +"""Tests for centralised error reporting (toast + webhook). + +An exception escaping a GUI callback must never take down the server or a +session: it is shown to the user as a toast, logged, and -- if the deployer +configured one -- posted to a webhook. +""" + +import asyncio +import json +import sys +import threading +from http.server import BaseHTTPRequestHandler, HTTPServer + +import panel as pn +import pytest + +from pixelmap import error_reporting +from pixelmap.error_reporting import ( + ErrorReporter, + WebhookConfig, + build_payload, + guarded, + load_webhook_config, + post_webhook, +) + + +def _raise(exc): + try: + raise exc + except BaseException as caught: + return caught + + +class _Recorder: + """Stands in for ``post_webhook``; records what would have been sent.""" + + def __init__(self, result=True): + self.calls = [] + self.result = result + + def __call__(self, payload, config): + self.calls.append((payload, config)) + return self.result + + +def _reporter(url="https://hooks.example/abc", dedupe=60.0, sender=None, clock=None): + sender = sender or _Recorder() + config = WebhookConfig(url=url, dedupe_seconds=dedupe) + reporter = ErrorReporter( + config_loader=lambda: config, + sender=sender, + clock=clock or (lambda: 0.0), + synchronous=True, + ) + return reporter, sender + + +@pytest.fixture +def toasts(monkeypatch): + seen = [] + + class FakeArea: + def __getattr__(self, level): + return lambda message, **kwargs: seen.append((level, message, kwargs)) + + monkeypatch.setattr(type(pn.state), "notifications", property(lambda self: FakeArea())) + return seen + + +@pytest.fixture +def no_toasts(monkeypatch): + monkeypatch.setattr(type(pn.state), "notifications", property(lambda self: None)) + + +# -------------------------------------------------------------------------- +# Configuration +# -------------------------------------------------------------------------- + + +def test_webhook_disabled_when_env_unset(): + config = load_webhook_config({}) + assert config.url is None + assert not config.enabled + + +@pytest.mark.parametrize("raw", ["", " ", "\n"]) +def test_blank_webhook_url_means_disabled(raw): + assert not load_webhook_config({"PIXELMAP_ERROR_WEBHOOK_URL": raw}).enabled + + +@pytest.mark.parametrize( + "url", ["file:///etc/passwd", "ftp://example.com/x", "not a url", "//example.com"] +) +def test_non_http_webhook_urls_are_rejected(url): + assert not load_webhook_config({"PIXELMAP_ERROR_WEBHOOK_URL": url}).enabled + + +def test_webhook_config_reads_all_settings(): + config = load_webhook_config( + { + "PIXELMAP_ERROR_WEBHOOK_URL": " https://hooks.example/abc ", + "PIXELMAP_ERROR_WEBHOOK_TIMEOUT": "2.5", + "PIXELMAP_ERROR_WEBHOOK_DEDUPE_SECONDS": "0", + "PIXELMAP_ERROR_WEBHOOK_TOKEN": "s3cret", + } + ) + assert config.url == "https://hooks.example/abc" + assert config.timeout == 2.5 + assert config.dedupe_seconds == 0 + assert config.headers()["Authorization"] == "Bearer s3cret" + + +@pytest.mark.parametrize("raw", ["abc", "0", "-1", "", "nan", "inf"]) +def test_bad_timeout_falls_back_to_default(raw): + config = load_webhook_config( + {"PIXELMAP_ERROR_WEBHOOK_URL": "https://h.example", "PIXELMAP_ERROR_WEBHOOK_TIMEOUT": raw} + ) + assert config.timeout == error_reporting.DEFAULT_TIMEOUT_SECONDS + + +@pytest.mark.parametrize("raw", ["abc", "-5", "", "nan"]) +def test_bad_dedupe_falls_back_to_default(raw): + config = load_webhook_config( + { + "PIXELMAP_ERROR_WEBHOOK_URL": "https://h.example", + "PIXELMAP_ERROR_WEBHOOK_DEDUPE_SECONDS": raw, + } + ) + assert config.dedupe_seconds == error_reporting.DEFAULT_DEDUPE_SECONDS + + +def test_no_auth_header_without_token(): + config = load_webhook_config({"PIXELMAP_ERROR_WEBHOOK_URL": "https://h.example"}) + assert "Authorization" not in config.headers() + assert config.headers()["Content-Type"] == "application/json" + + +# -------------------------------------------------------------------------- +# Payload +# -------------------------------------------------------------------------- + + +def test_payload_carries_error_details(): + exc = _raise(ValueError("boom")) + payload = build_payload(exc, context="apply preset", session_id="sess-1") + + event = payload["event"] + assert event["error_type"] == "ValueError" + assert event["error_message"] == "boom" + assert event["context"] == "apply preset" + assert event["session_id"] == "sess-1" + assert "Traceback" in event["traceback"] + assert event["app"] == "pixelmap" + # Chat-style webhooks (Slack/Mattermost use `text`, Discord `content`). + assert "ValueError: boom" in payload["text"] + assert payload["content"] == payload["text"] + json.dumps(payload) # must be serialisable + + +def test_payload_without_context_or_session(): + payload = build_payload(_raise(RuntimeError("x")), context=None, session_id=None) + assert payload["event"]["context"] is None + assert payload["event"]["session_id"] is None + + +def test_payload_survives_an_exception_whose_str_raises(): + class Nasty(Exception): + def __str__(self): + raise RuntimeError("str() exploded") + + payload = build_payload(_raise(Nasty()), context="x") + assert payload["event"]["error_type"] == "Nasty" + json.dumps(payload) + + +def test_payload_for_exception_without_traceback(): + payload = build_payload(KeyError("never raised"), context=None) + assert payload["event"]["error_type"] == "KeyError" + json.dumps(payload) + + +def test_payload_text_is_bounded(): + payload = build_payload(_raise(ValueError("x" * 50_000)), context="y" * 50_000) + assert len(payload["text"]) <= error_reporting.MAX_TEXT_CHARS + assert len(payload["event"]["error_message"]) <= error_reporting.MAX_FIELD_CHARS + assert len(payload["event"]["traceback"]) <= error_reporting.MAX_FIELD_CHARS + + +# -------------------------------------------------------------------------- +# Webhook transport +# -------------------------------------------------------------------------- + + +@pytest.fixture +def webhook_server(): + received = [] + + class Handler(BaseHTTPRequestHandler): + status = 204 + + def do_POST(self): + length = int(self.headers.get("Content-Length", 0)) + received.append( + {"headers": dict(self.headers), "body": json.loads(self.rfile.read(length))} + ) + self.send_response(Handler.status) + self.end_headers() + + def log_message(self, *args): + pass + + server = HTTPServer(("127.0.0.1", 0), Handler) + thread = threading.Thread(target=server.serve_forever, daemon=True) + thread.start() + try: + yield f"http://127.0.0.1:{server.server_port}/hook", received, Handler + finally: + server.shutdown() + server.server_close() + + +def test_post_webhook_delivers_json(webhook_server): + url, received, _ = webhook_server + config = WebhookConfig(url=url, token="tok") + + assert post_webhook({"text": "hello"}, config) is True + assert received[0]["body"] == {"text": "hello"} + assert received[0]["headers"]["Authorization"] == "Bearer tok" + assert received[0]["headers"]["Content-Type"] == "application/json" + + +def test_post_webhook_reports_http_errors_without_raising(webhook_server): + url, _, handler = webhook_server + handler.status = 500 + assert post_webhook({"text": "x"}, WebhookConfig(url=url)) is False + + +def test_post_webhook_unreachable_host_does_not_raise(): + # Port 9 (discard) on localhost is essentially never listening. + assert post_webhook({"text": "x"}, WebhookConfig(url="http://127.0.0.1:9/", timeout=1)) is False + + +def test_post_webhook_disabled_is_a_noop(): + assert post_webhook({"text": "x"}, WebhookConfig(url=None)) is False + + +# -------------------------------------------------------------------------- +# Reporter +# -------------------------------------------------------------------------- + + +def test_report_toasts_and_posts(toasts): + reporter, sender = _reporter() + reporter.report(_raise(ValueError("boom")), context="apply preset") + + assert len(sender.calls) == 1 + assert sender.calls[0][0]["event"]["context"] == "apply preset" + assert len(toasts) == 1 + level, message, _ = toasts[0] + assert level == "error" + assert "boom" in message + assert "reported" in message.lower() + + +def test_toast_does_not_claim_reporting_without_webhook(toasts): + reporter, sender = _reporter(url=None) + reporter.report(_raise(ValueError("boom"))) + + assert sender.calls == [] + assert "reported" not in toasts[0][1].lower() + + +def test_report_without_notification_area_still_posts(no_toasts): + reporter, sender = _reporter() + reporter.report(_raise(ValueError("boom"))) + assert len(sender.calls) == 1 + + +def test_report_can_skip_the_toast(toasts): + reporter, sender = _reporter() + reporter.report(_raise(ValueError("boom")), notify_user=False) + assert toasts == [] + assert len(sender.calls) == 1 + + +def test_report_never_raises_when_toast_fails(monkeypatch): + class Broken: + def error(self, *args, **kwargs): + raise RuntimeError("notification area is broken") + + monkeypatch.setattr(type(pn.state), "notifications", property(lambda self: Broken())) + reporter, sender = _reporter() + reporter.report(_raise(ValueError("boom"))) + assert len(sender.calls) == 1 + + +def test_report_never_raises_when_sender_fails(no_toasts): + def sender(payload, config): + raise RuntimeError("network stack on fire") + + reporter, _ = _reporter(sender=sender) + reporter.report(_raise(ValueError("boom"))) # must not raise + + +def test_report_never_raises_when_config_loader_fails(no_toasts): + def loader(): + raise RuntimeError("bad env") + + reporter = ErrorReporter(config_loader=loader, sender=_Recorder(), synchronous=True) + reporter.report(_raise(ValueError("boom"))) # must not raise + + +def test_duplicate_errors_are_deduplicated_within_window(no_toasts): + now = [0.0] + reporter, sender = _reporter(dedupe=60.0, clock=lambda: now[0]) + + def fail(): + raise ValueError("same") + + for _ in range(3): + reporter.report(_raise_from(fail)) + assert len(sender.calls) == 1 + + now[0] = 61.0 + reporter.report(_raise_from(fail)) + assert len(sender.calls) == 2 + + +def test_distinct_errors_are_not_deduplicated(no_toasts): + reporter, sender = _reporter(dedupe=60.0) + reporter.report(_raise(ValueError("a"))) + reporter.report(_raise(TypeError("a"))) + reporter.report(_raise(ValueError("b"))) + assert len(sender.calls) == 3 + + +def test_zero_dedupe_window_sends_every_error(no_toasts): + reporter, sender = _reporter(dedupe=0) + for _ in range(3): + reporter.report(_raise(ValueError("same"))) + assert len(sender.calls) == 3 + + +def test_toast_is_shown_even_for_deduplicated_errors(toasts): + reporter, sender = _reporter(dedupe=60.0) + reporter.report(_raise(ValueError("same"))) + reporter.report(_raise(ValueError("same"))) + assert len(toasts) == 2 + assert len(sender.calls) == 1 + + +def test_asynchronous_dispatch_delivers(no_toasts): + sender = _Recorder() + done = threading.Event() + + def wrapped(payload, config): + sender(payload, config) + done.set() + return True + + reporter = ErrorReporter( + config_loader=lambda: WebhookConfig(url="https://h.example"), sender=wrapped + ) + reporter.report(_raise(ValueError("boom"))) + assert done.wait(5) + assert len(sender.calls) == 1 + + +def test_asynchronous_dispatch_drops_when_backlogged(no_toasts): + release = threading.Event() + calls = [] + + def slow(payload, config): + calls.append(payload) + release.wait(5) + return True + + reporter = ErrorReporter( + config_loader=lambda: WebhookConfig(url="https://h.example", dedupe_seconds=0), + sender=slow, + max_pending=2, + ) + try: + for i in range(10): + reporter.report(_raise(ValueError(str(i)))) + assert reporter.pending <= 2 + finally: + release.set() + + +def _raise_from(fn): + try: + fn() + except Exception as exc: + return exc + + +# -------------------------------------------------------------------------- +# Hooks +# -------------------------------------------------------------------------- + + +def test_guarded_swallows_and_reports(monkeypatch): + reported = [] + monkeypatch.setattr(error_reporting, "report_error", lambda exc, **kw: reported.append((exc, kw))) + + @guarded("electrode selection") + def callback(attr, old, new): + raise ValueError("bad selection") + + assert callback("indices", [], [1]) is None + assert isinstance(reported[0][0], ValueError) + assert reported[0][1]["context"] == "electrode selection" + + +def test_guarded_passes_through_return_values(): + @guarded("x") + def callback(a, b=2): + return a + b + + assert callback(1) == 3 + assert callback(1, b=5) == 6 + + +def test_guarded_preserves_signature_for_bokeh(): + """Bokeh's ``on_change`` inspects the callback's arity.""" + import inspect + + class Owner: + def on_change(self, attr, old, new): + pass + + wrapped = guarded("x")(Owner().on_change) + assert list(inspect.signature(wrapped).parameters) == ["attr", "old", "new"] + + +def test_guarded_lets_keyboard_interrupt_through(): + @guarded("x") + def callback(): + raise KeyboardInterrupt + + with pytest.raises(KeyboardInterrupt): + callback() + + +def test_session_exception_handler_reports(monkeypatch): + reported = [] + monkeypatch.setattr(error_reporting, "report_error", lambda exc, **kw: reported.append(exc)) + exc = ValueError("x") + error_reporting.session_exception_handler(exc) + assert reported == [exc] + + +def test_session_exception_handler_never_raises(monkeypatch): + def explode(*args, **kwargs): + raise RuntimeError("reporter broke") + + monkeypatch.setattr(error_reporting, "report_error", explode) + error_reporting.session_exception_handler(ValueError("x")) # must not raise + + +def test_install_global_handlers_is_idempotent(monkeypatch): + monkeypatch.setattr(sys, "excepthook", sys.__excepthook__) + monkeypatch.setattr(threading, "excepthook", threading.__excepthook__) + monkeypatch.setattr(error_reporting, "_GLOBAL_HANDLERS_INSTALLED", False) + + error_reporting.install_global_handlers() + first_sys, first_thread = sys.excepthook, threading.excepthook + error_reporting.install_global_handlers() + + assert sys.excepthook is first_sys + assert threading.excepthook is first_thread + assert sys.excepthook is not sys.__excepthook__ + + +def test_thread_exceptions_are_reported(monkeypatch): + reported = [] + monkeypatch.setattr(error_reporting, "report_error", lambda exc, **kw: reported.append((exc, kw))) + monkeypatch.setattr(threading, "excepthook", threading.__excepthook__) + monkeypatch.setattr(sys, "excepthook", sys.__excepthook__) + monkeypatch.setattr(error_reporting, "_GLOBAL_HANDLERS_INSTALLED", False) + error_reporting.install_global_handlers() + + def boom(): + raise ValueError("in a thread") + + t = threading.Thread(target=boom, name="pixelmap-test") + t.start() + t.join() + + assert isinstance(reported[0][0], ValueError) + assert reported[0][1]["notify_user"] is False + assert "pixelmap-test" in reported[0][1]["context"] + + +def test_asyncio_loop_exceptions_are_reported(monkeypatch): + reported = [] + monkeypatch.setattr(error_reporting, "report_error", lambda exc, **kw: reported.append(exc)) + + async def scenario(): + loop = asyncio.get_running_loop() + error_reporting.install_loop_handler(loop) + error_reporting.install_loop_handler(loop) # idempotent + loop.call_exception_handler({"message": "task died", "exception": ValueError("x")}) + loop.call_exception_handler({"message": "no exception attached"}) + + asyncio.run(scenario()) + assert isinstance(reported[0], ValueError) + assert isinstance(reported[1], RuntimeError) + assert len(reported) == 2 + + +# -------------------------------------------------------------------------- +# GUI wiring +# -------------------------------------------------------------------------- + + +def test_create_app_installs_session_exception_handler(): + import inspect + + from pixelmap.gui import gui + + source = inspect.getsource(gui.create_app) + assert "exception_handler=" in source + + +def test_create_app_survives_a_failing_gui_build(monkeypatch, no_toasts): + from pixelmap.gui import gui + + reported = [] + monkeypatch.setattr(error_reporting, "report_error", lambda exc, **kw: reported.append(exc)) + + def broken(*args, **kwargs): + raise RuntimeError("wiring maps missing") + + monkeypatch.setattr(gui, "ChannelmapGUI", broken) + app = gui.create_app() + + assert app is not None + assert isinstance(reported[0], RuntimeError) + + +def test_raw_bokeh_callbacks_are_guarded(): + """Panel's exception_handler doesn't see raw Bokeh ``on_change`` callbacks.""" + import inspect + import re + + from pixelmap.gui import gui + + source = inspect.getsource(gui) + raw = re.findall(r"\.on_change\(\s*\"\w+\",\s*([^)]+)\)", source) + assert raw, "expected Bokeh on_change registrations in gui.py" + for callback in raw: + assert callback.strip().startswith("guarded("), callback