aiscr-qgis-amcr-viewer/openspec/changes/archive/2026-10-02-fix-session-expiry-islogged/design.md

Design

Context

• The session lives only in memory (amcr_tools.AMCR_SESSION, a requests.Session with the JSESSIONID cookie). _get_session() logs in from stored credentials only when no session object exists, so after QGIS start the first download always logs in; an expired session object is reused forever.
• All data requests of a download go through _api_get_json() (main query pages and PIAN batches). _is_auth_error() there reacts to HTTP 401 or error text – neither occurs on expiry (see proposal.md – Why).
• Server behaviour (verified 2026-10-02, live API): GET /api/user/islogged → {"remaining": <s>} when logged in, {"error": "nologged"} otherwise, both HTTP 200. It does not extend the session; any search/query does.
• Codelists (amcr_codelists.py) use plain requests.get without the session – unaffected by login state.

Goals / Non-Goals

Goals:

• One check at the start of load_amcr_data, before the first data request.
• Reuse existing login code (login_to_api, LoginDialog.get_credentials).
• Testable offline: the check takes its HTTP behaviour from the session object so the smoke test can inject a fake.

Non-Goals:

• Checking before every page / PIAN batch (a download takes seconds to minutes and every data request renews the sliding timeout).
• Refactoring session handling into a class.

Decisions

1. New helper _ensure_logged_in() -> str in amcr_tools.py, returning one of "anonymous" (no session, no credentials – nothing to check), "logged_in", "relogged", "fallback" (expected login, ended anonymous), "unknown" (check failed, proceeding). Flow: get session via _get_session() (logs in if needed); if none and no credentials → anonymous; if none but credentials → login failed → fallback; otherwise call islogged; remaining → logged_in; nologged → drop session, re-login once, verify again → relogged or fallback; exception / non-JSON → unknown. Alternative: re-login unconditionally before each download – simpler, but one POST with the password per download and no way to distinguish a real failure; rejected. Alternative: compare remaining with a local timestamp of last request – fragile (server timeout may change); rejected.

2. Caller decides UI. load_amcr_data pushes the message bar warning on fallback; the helper only logs (keeps it free of iface for the test).

3. Interpretation of the response: logged in iff the body is a dict with key remaining. Anything else with an error key → not logged in. Unknown shape → unknown (do not trigger a re-login loop on a format change).

4. Keep _is_auth_error as a fallback, with a comment that the current server never triggers it; removing it brings no benefit and it still covers a possible future 401.

5. Never log the response of islogged?wantsUser=true – we do not use that parameter at all; only remaining (number) is logged.

6. Logout on credential removal – new logout_from_api() in amcr_tools.py called from LoginDialog._forget_credentials. The local session is dropped first and unconditionally; the server call is best effort (a failure is logged and reported in the dialog text). Without it, the in-memory session would keep downloading logged-in data until QGIS restarts even though the user believes he is "forgotten".

Risks / Trade-offs

• [Extra request per download] → only for logged-in / credential users; cost ~100 ms.
• [Session expires during a very long download] → practically impossible: each page request renews the 1 h sliding timeout.
• [Re-login prompts for the QGIS master password] → get_credentials() is already called on first download after start; behaviour unchanged.
• [islogged endpoint changes shape] → unknown, logged warning, download proceeds as today (no regression).

Migration Plan

Plain plugin update; no settings or data migration. Rollback = previous release.