papersearch 0.4.2 → 0.4.3

package/carsi/paper_search_carsi/browser/preview.py

@@ -1,10 +1,10 @@
 """Live previews of the download browser, written by the owning thread (no debug port).
 
 On by default for institutional downloads: every page of the download context
-is screenshotted on navigation and whenever the workflow reads the page (login
+is screenshotted when the workflow reads the page after navigation (login
 and verification waits included, at most every 4 s). Frames go to
 ``<data dir>/previews/<run_id>/`` (or ``browser_preview_dir``) as JPEG. A page
-that has not changed (same URL and title) keeps only its newest frame, earlier
+that has not changed (same URL and document revision) keeps only its newest frame, earlier
 page states are kept up to ``MAX_KEPT_FRAMES`` per download, a successful
 download's frames are removed, and only the most recent runs are kept. ``browser_preview: false`` turns it off. Readers
 (``paper-search-carsi preview``) inspect artifacts only and report the
@@ -12,6 +12,7 @@ frame age explicitly. Screenshots are unmasked and stay on this machine.
 """
 from __future__ import annotations
 
+from contextlib import contextmanager
 import json
 import logging
 import os
@@ -22,6 +23,9 @@ from urllib.parse import urlsplit
 from uuid import UUID, uuid4
 from weakref import WeakKeyDictionary
 
+from .watchdog import BrowserUnresponsive
+from ..entitlements import UserMarkedNoEntitlement
+
 _OBSERVERS = WeakKeyDictionary()
 _ACTIVE = {}
 _KINDS = {'blank', 'article', 'pdf', 'login', 'other'}
@@ -49,12 +53,14 @@ class BrowserPreview:
         self.revision = 0
         self.last_observed = 0.0
         self.page_ids = {}
-        self.last_frame = {}  # page_id -> ((url, title), image name)
+        self.page_revisions = {}
+        self.last_frame = {}  # page_id -> ((url, document revision), image name)
         self.kept = []  # frames of earlier page states, oldest first
         self.pages = []
         self.observed_at = time.time()
         self.closed = False
         self.observing = False
+        self.paused = 0
         self._cdp = WeakKeyDictionary()
         context.on('close', self.close)
         self._write([])
@@ -63,13 +69,12 @@ class BrowserPreview:
             self._attach_page(page)
 
     def _attach_page(self, page):
-        page.on('domcontentloaded', lambda *_args: self._refresh())
-
-    def _refresh(self):
-        try:
-            self.observe()
-        except Exception:
-            logging.getLogger(__name__).warning('browser_preview_unavailable')
+        def changed(*_args):
+            # A Playwright event callback must not make nested synchronous
+            # browser calls. Capture at the next workflow observation instead.
+            self.page_revisions[page] = self.page_revisions.get(page, 0) + 1
+            self.last_observed = 0.0
+        page.on('domcontentloaded', changed)
 
     def close(self, *_args):
         self.closed = True
@@ -98,14 +103,8 @@ class BrowserPreview:
         _atomic(self.directory / 'current.json', json.dumps(packet).encode())
 
     def observe(self, *, force=False):
-        if force and self.observing and not self.closed:
-            # A navigation callback can still be finishing its screenshot when
-            # goto() returns. Pump the owning loop for that bounded operation.
-            deadline = time.monotonic() + 2
-            pages = list(self.context.pages)
-            while self.observing and pages and not self.closed and time.monotonic() < deadline:
-                pages[0].wait_for_timeout(50)
-        if self.closed or not self._is_current() or self.observing or (not force and time.monotonic() - self.last_observed < OBSERVE_INTERVAL_SEC):
+        if self.closed or not self._is_current() or self.observing or (not force and (
+                self.paused or time.monotonic() - self.last_observed < OBSERVE_INTERVAL_SEC)):
             return
         self.observing = True
         try:
@@ -127,6 +126,8 @@ class BrowserPreview:
             try:
                 session = page.context.new_cdp_session(page)
                 self._cdp[page] = session
+            except (BrowserUnresponsive, UserMarkedNoEntitlement):
+                raise
             except Exception:
                 session = False
                 self._cdp[page] = session
@@ -169,12 +170,14 @@ class BrowserPreview:
                 _atomic(self.directory / image_name, frame)
                 row.update(image_name=image_name, captured_at=captured_at)
                 row['screenshot_status'] = 'available'
-                key = (captured_url, self._page_title(page))
+                key = (captured_url, self.page_revisions.get(page, 0))
                 previous = self.last_frame.get(page_id)
                 if previous:
                     # The same page again replaces its frame; a changed page keeps the old one.
                     (superseded if previous[0] == key else self.kept).append(previous[1])
                 self.last_frame[page_id] = (key, image_name)
+            except (BrowserUnresponsive, UserMarkedNoEntitlement):
+                raise
             except Exception:
                 # Preview failure is explicit and cannot change download success.
                 pass
@@ -187,13 +190,6 @@ class BrowserPreview:
         for name in superseded:
             (self.directory / name).unlink(missing_ok=True)
 
-    @staticmethod
-    def _page_title(page) -> str:
-        try:
-            return str(page.title() or "")
-        except Exception:
-            return ""
-
     def discard_frames(self):
         """Remove this download's frames; a successful download needs no record."""
         for name in [*self.kept, *(frame for _key, frame in self.last_frame.values())]:
@@ -238,10 +234,32 @@ def observe_page(page, *, force=False) -> None:
     if observer is not None:
         try:
             observer.observe(force=force)
+        except (BrowserUnresponsive, UserMarkedNoEntitlement):
+            raise
         except Exception:
             logging.getLogger(__name__).warning('browser_preview_unavailable')
 
 
+@contextmanager
+def pause(context):
+    """Keep the last frame while a download operation needs the browser.
+
+    Optional screenshots must not spend a PDF operation's budget. Explicit
+    force observations still run; browser and user interrupts are not caught.
+    """
+    try:
+        observer = _OBSERVERS.get(context)
+    except TypeError:
+        observer = None
+    if observer is not None:
+        observer.paused += 1
+    try:
+        yield
+    finally:
+        if observer is not None:
+            observer.paused -= 1
+
+
 def snapshot(directory: str | Path, run_id: str, identifier: str) -> dict:
     """A requested run can return a clearly labelled retained or stale view."""
     from ..progress_status import normalize_identifier, snapshot as progress_snapshot

package/carsi/paper_search_carsi/browser/profiles.py

@@ -0,0 +1,161 @@
+"""Persistent browser profile state and ownership, independent of the launcher.
+
+Session cookies use their existing per-profile file and expiry. Native lock
+checks never remove another process's lock or change the profile location.
+"""
+from __future__ import annotations
+
+import json
+import logging
+import os
+import re
+import time
+from pathlib import Path
+from typing import Any
+
+logger = logging.getLogger(__name__)
+PROFILE_RELEASE_TIMEOUT_SEC = 20.0
+
+
+SESSION_COOKIES_FILE = ".paper-search-session-cookies.json"
+SESSION_COOKIES_MAX_AGE_SEC = 12 * 3600
+
+
+def _save_session_cookies(context: Any, profile: Path) -> None:
+    """Keep session cookies (IdP and publisher logins) for the next launch.
+
+    Each paper runs in a new backend process and browser; Firefox drops
+    cookies without an expiry when it closes, so every paper asked for the
+    school login again. Only session cookies are kept: persistent ones are in
+    the profile already. The file is readable by the user only.
+    """
+    try:
+        cookies = [c for c in context.cookies() if not c.get("expires") or c.get("expires", -1) < 0]
+    except Exception:
+        return
+    path = profile / SESSION_COOKIES_FILE
+    try:
+        if not cookies:
+            path.unlink(missing_ok=True)
+            return
+        tmp = path.with_suffix(".tmp")
+        tmp.write_text(json.dumps({"saved_at": time.time(), "cookies": cookies}),
+                       encoding="utf-8")
+        os.chmod(tmp, 0o600)
+        os.replace(tmp, path)
+    except Exception as exc:
+        logger.debug("browser_backend: session cookies not saved: %s", type(exc).__name__)
+
+
+def _restore_session_cookies(context: Any, profile: Path) -> int:
+    path = profile / SESSION_COOKIES_FILE
+    try:
+        data = json.loads(path.read_text(encoding="utf-8"))
+    except Exception:
+        return 0
+    if time.time() - float(data.get("saved_at", 0)) > SESSION_COOKIES_MAX_AGE_SEC:
+        return 0
+    restored = 0
+    for cookie in data.get("cookies") or []:
+        try:
+            context.add_cookies([{k: v for k, v in cookie.items() if k != "expires" or v not in (None, -1)}])
+            restored += 1
+        except Exception:
+            continue
+    return restored
+
+
+def _profile_owner_pid(user_data_dir: str) -> int | None:
+    """PID of the browser holding this profile, if any.
+
+    Firefox (Camoufox) leaves a ``lock`` symlink to ``<host>:+<pid>``;
+    Chromium leaves ``SingletonLock`` to ``<host>-<pid>``.
+    """
+    for name in ("lock", "SingletonLock"):
+        try:
+            target = os.readlink(Path(user_data_dir) / name)
+        except OSError:
+            continue
+        match = re.search(r"[-+](\d+)$", target)
+        if match:
+            return int(match.group(1))
+    return None
+
+
+def _lock_file_held(path: Path) -> bool:
+    """Another process holds this lock file: Firefox's ``.parentlock`` on macOS
+    and Linux (an fcntl lock; macOS has no ``lock`` symlink), its ``parent.lock``
+    on Windows (opened without sharing). The lock is tested, never kept."""
+    if not path.exists():
+        return False
+    try:
+        fd = os.open(str(path), os.O_RDWR)
+    except PermissionError:
+        return True  # Windows: the running browser has it open
+    except OSError:
+        return False
+    try:
+        try:
+            import fcntl
+        except ImportError:
+            return False
+        try:
+            fcntl.lockf(fd, fcntl.LOCK_EX | fcntl.LOCK_NB)
+        except OSError:
+            return True
+        fcntl.lockf(fd, fcntl.LOCK_UN)
+        return False
+    finally:
+        os.close(fd)
+
+
+def profile_holder(user_data_dir: str) -> str:
+    """Who still holds this profile ("" = nobody): a live ``lock`` owner, or a
+    lock file another process holds."""
+    pid = _profile_owner_pid(user_data_dir)
+    if pid is not None and _pid_alive(pid):
+        return f"lock of pid {pid}"
+    for name in (".parentlock", "parent.lock"):
+        if _lock_file_held(Path(user_data_dir) / name):
+            return f"{name} held"
+    return ""
+
+
+def _pid_alive(pid: int) -> bool:
+    if pid <= 0 or pid == os.getpid():
+        return False
+    try:
+        os.kill(pid, 0)
+    except ProcessLookupError:
+        return False
+    except PermissionError:
+        return True
+    except OSError:
+        return False
+    return True
+
+
+def wait_for_profile_release(user_data_dir: str, timeout: float = PROFILE_RELEASE_TIMEOUT_SEC) -> bool:
+    """Wait while a previous browser process still owns this persistent profile.
+
+    Back-to-back downloads reuse one profile; the previous Chrome can take a
+    few seconds to exit after its context closed. Launching meanwhile fails,
+    and the fallback launcher then reports a misleading "executable doesn't
+    exist". Returns True when the profile is free (or never locked).
+    """
+    import time
+
+    deadline = time.monotonic() + max(0.0, timeout)
+    waited = False
+    while True:
+        if not profile_holder(user_data_dir):
+            if waited:
+                logger.info("browser_backend: persistent profile released by previous browser")
+            return True
+        if time.monotonic() >= deadline:
+            logger.info("browser_backend: persistent profile still in use by another browser process")
+            return False
+        if not waited:
+            logger.info("browser_backend: waiting for the previous browser to release the profile")
+            waited = True
+        time.sleep(0.5)

package/carsi/paper_search_carsi/browser/watchdog.py

@@ -24,6 +24,7 @@ import logging
 import threading
 import time
 import traceback
+from contextlib import contextmanager
 from typing import Any
 
 log = logging.getLogger(__name__)
@@ -33,6 +34,8 @@ log = logging.getLogger(__name__)
 LIMIT_SEC = 90
 
 _inflight: dict[int, tuple[float, str, list[str], Any, Any]] = {}
+_call_deadlines: dict[int, tuple[float, str]] = {}
+_local = threading.local()
 _installed = False
 # A browser call longer than this is reported to ``on_slow_call(name, seconds,
 # ended, caller)``, set by the downloader for the article it runs: a Playwright
@@ -59,6 +62,48 @@ class BrowserUnresponsive(Exception):
     """A browser call did not return within the watchdog limit."""
 
 
+class BrowserOperationTimeout(BrowserUnresponsive):
+    """The whole page operation exhausted its budget across browser calls."""
+
+
+@contextmanager
+def operation(seconds: float, label: str):
+    """One monotonic deadline shared by all calls and retries in this scope."""
+    stack = getattr(_local, "budgets", None)
+    if stack is None:
+        stack = _local.budgets = []
+    stack.append([time.monotonic() + seconds, label])
+    try:
+        yield
+    finally:
+        stack.pop()
+
+
+@contextmanager
+def pause_operation():
+    """Explicit human interaction does not spend the enclosing automation budget."""
+    stack = getattr(_local, "budgets", [])
+    started = time.monotonic()
+    _local.budgets = []
+    try:
+        yield
+    finally:
+        elapsed = time.monotonic() - started
+        for budget in stack:
+            budget[0] += elapsed
+        _local.budgets = stack
+
+
+def failure_code() -> str:
+    return "browser_operation_timeout" if fired and fired.get("operation") else "browser_unresponsive"
+
+
+def _timeout_error() -> BrowserUnresponsive:
+    if fired and fired.get("operation"):
+        return BrowserOperationTimeout(f"{fired['operation']} exceeded its page budget during {fired['call']}")
+    return BrowserUnresponsive(f"browser unresponsive since {fired['call']}")
+
+
 def install(limit_sec: float = LIMIT_SEC) -> None:
     """Time every sync Playwright call of this process (once)."""
     global _installed
@@ -72,7 +117,7 @@ def install(limit_sec: float = LIMIT_SEC) -> None:
         name = getattr(coro, "__qualname__", "") or type(coro).__name__
         if fired is not None:
             coro.close()
-            raise BrowserUnresponsive(f"browser unresponsive since {fired['call']}; {name} not sent")
+            raise _timeout_error()
         if interrupted is not None:
             coro.close()
             raise interrupted
@@ -86,13 +131,21 @@ def install(limit_sec: float = LIMIT_SEC) -> None:
         started = time.monotonic()
         _inflight[key] = (started, name, traceback.format_stack(limit=8)[:-1],
                           getattr(self, "_loop", None), coro)
+        budgets = getattr(_local, "budgets", [])
+        if budgets:
+            _call_deadlines[key] = tuple(min(budgets, key=lambda budget: budget[0]))
         ended = "returned"
         try:
+            # Refuse to start another candidate after the shared budget expired.
+            if key in _call_deadlines and started >= _call_deadlines[key][0]:
+                check(limit_sec)
+                coro.close()
+                raise _timeout_error()
             return original(self, coro)
         except asyncio.CancelledError:
             ended = "cancelled"
             if fired is not None:
-                raise BrowserUnresponsive(f"{name} did not return within {int(limit_sec)} s") from None
+                raise _timeout_error() from None
             if interrupted is not None:
                 raise interrupted from None
             raise
@@ -101,6 +154,7 @@ def install(limit_sec: float = LIMIT_SEC) -> None:
             raise
         finally:
             _inflight.pop(key, None)
+            _call_deadlines.pop(key, None)
             elapsed = time.monotonic() - started
             _period["calls"] += 1
             _period["seconds"] += elapsed
@@ -125,15 +179,9 @@ def _report_slow(name: str, seconds: float, ended: str) -> None:
         pass  # a record, never the article's end
 
 
-def stuck_call(now: float, limit_sec: float) -> tuple[float, str, list[str], Any, Any] | None:
-    """The oldest call running for longer than ``limit_sec``."""
-    stuck = [entry for entry in list(_inflight.values()) if now - entry[0] > limit_sec]
-    return min(stuck, key=lambda entry: entry[0]) if stuck else None
-
-
 def _watch(limit_sec: float) -> None:
     while not check(limit_sec):
-        time.sleep(5)
+        time.sleep(0.25)
 
 
 def check(limit_sec: float) -> bool:
@@ -141,16 +189,25 @@ def check(limit_sec: float) -> bool:
     global fired
     if fired is not None:
         return True
-    entry = stuck_call(time.monotonic(), limit_sec)
-    if entry is None:
+    now = time.monotonic()
+    deadlines = dict(_call_deadlines)
+    overdue = [(key, entry) for key, entry in list(_inflight.items())
+               if now - entry[0] > limit_sec
+               or (key in deadlines and now >= deadlines[key][0])]
+    if not overdue:
         return False
+    key, entry = min(overdue, key=lambda pair: pair[1][0])
     started, name, stack, loop, coro = entry
-    fired = {"call": name, "seconds": int(time.monotonic() - started)}
-    log.warning("browser_unresponsive: %s waited %ss; caller:\n%s", name, fired["seconds"], "".join(stack))
+    fired = {"call": name, "seconds": int(now - started)}
+    deadline = deadlines.get(key)
+    if deadline and deadline[0] <= now and deadline[0] <= started + limit_sec:
+        fired["operation"] = deadline[1]
+    log.warning("%s: %s waited %ss; operation=%s; caller:\n%s", failure_code(), name,
+                fired["seconds"], fired.get("operation", ""), "".join(stack))
     # Every thread's stack, for the cause of the hang (still unknown, 2026-11-01).
     from ..log import dump_stacks
 
-    dump_stacks(f"browser_unresponsive: {name} waited {fired['seconds']}s")
+    dump_stacks(f"{failure_code()}: {name} waited {fired['seconds']}s")
     if loop is not None and not loop.is_closed():
         loop.call_soon_threadsafe(_cancel, coro)
     return True

package/carsi/paper_search_carsi/download_diagnostics.py

@@ -26,7 +26,7 @@ challenge_or_viewer_timeout ip_blocked access_blocked pdf_not_captured
 pdf_identity_mismatch pdf_identity_unverified invalid_pdf
 profile_busy cancelled interrupted skipped_cached_attempt target_verified_reached navigation_error
 unsupported_platform unsupported_publisher user_skipped user_marked_no_entitlement pdf_wrong_article
-institution_federation_unavailable browser_unresponsive login_not_reached idp_no_return_to_publisher
+institution_federation_unavailable browser_unresponsive browser_operation_timeout login_not_reached idp_no_return_to_publisher
 generic_institution_entry_missing
 """.split())
 _STATES = _FAILURES | _STATUSES | frozenset("""