feat: add in-memory caching for faster wrapper data loading

[SebastianBoehler]

Context

Repeated data loading through the Tue API wrapper can be slow when the local API/sidecar repeatedly asks the same upstream university systems for data that has not changed yet. Add a small in-memory caching layer so repeated reads within one local process are faster while keeping credentialed university workflows local.

Source: Discord request from sebastian_boehler on 2026-05-21: "pls make the data loading faster and implement memory side caching in tue api wrapper".

Scope

• Add or finalize a small typed in-memory cache utility under package/src/tue_api_wrapper/.
• Support TTL-based entries, explicit cache keys, and cache clearing/invalidation.
• Apply it first to high-impact read paths where the wrapper currently re-loads the same portal/dashboard data repeatedly, especially portal_service.py and the API route handlers that compose portal/dashboard responses.
• Keep cache state process-local only. Do not persist credentials, session cookies, raw secret-bearing responses, or user data to disk.
• Keep cache keys isolated by credential/session/user context and by request parameters so one user's data cannot be served to another user.
• Do not cache failed upstream calls in a way that hides transient recovery.
• Invalidate or bypass cached reads after mutating actions such as registration/edit/mail actions where stale data would be misleading.
• Preserve existing route contracts and response shapes.

Acceptance criteria

• Repeated identical read calls within the TTL avoid duplicate upstream loader/client calls.
• Calls with different users/sessions or different request parameters use distinct cache entries.
• Expired entries are reloaded.
• Mutating endpoints either bypass cache or invalidate the affected cached data before returning.
• Tests cover cache hit, miss, expiry, clear/invalidation, parameter isolation, and at least one integrated wrapper/route read path.
• cd package && pytest passes.

Notes / risks

• Prefer existing wrapper patterns and keep files focused, following the repository's 300-line modularity guideline.
• Choose conservative TTL defaults so users see fresher university data rather than surprising stale results.
• If adding observability, expose lightweight debug-friendly behavior without logging credentials or raw private payloads.

[SebastianBoehler]

Owner clarification after triage: the intended caching shape should stay abstracted behind the normal wrapper methods. The caller should not switch to alternate cache-specific APIs.

Desired implementation shape:

• one small library-level config surface to enable or disable caching globally for the current process
• configurable TTL / cache duration through that same setup path
• conservative defaults, with caching off by default unless explicitly enabled
• repeated calls keep using the existing public methods; the cache layer stays internal to the wrapper
• cache keys must remain isolated by credential/session/user context and request parameters
• mutating actions should bypass or invalidate affected cached reads
• failures should not be cached in a way that hides recovery

Examples of acceptable API shapes:

• configure_cache(enabled=True, ttl_seconds=60)
• PortalService(cache=CacheConfig(enabled=True, ttl_seconds=60))

The important part is the behavior contract, not the exact naming: opt-in, TTL-based, process-local, invisible to normal consumers apart from one setup/config step.

[SebastianBoehler]

Thanks, this clarification makes the intended contract much sharper. I think the issue is now close to implementation-ready, with a few scope boundaries worth making explicit before someone starts coding.

Suggested first PR scope:

• Add one small cache config surface, defaulting to disabled, e.g. CacheConfig(enabled=False, ttl_seconds=...) plus either a package-level configure_cache(...) or PortalService(cache=...) injection path.
• Implement a process-local TTL cache utility under package/src/tue_api_wrapper/ with explicit keys, expiry, clear/invalidate support, and no disk persistence.
• Apply it first to the highest-impact authenticated read composition path, probably PortalService.build_dashboard(...), build_search_index(...), search(...), and fetch_item(...), because those repeatedly rebuild the same dashboard/search data through normal public methods.
• Keep direct client-level caching for AlmaClient, IliasClient, MailClient, etc. out of the first PR unless needed for the portal-service integration. That avoids turning this into a broad wrapper-wide caching rewrite.
• Do not cache exceptions or logged-out/auth-failed responses. A failed upstream call should leave the previous cache state untouched unless there is an explicit reason to invalidate it.

Likely duplicate/overlap check: I only see this issue matching caching/performance work. There is existing local lru_cache usage in campus_client.py for public metadata and an ios/Shared/Cache folder, but those look like implementation details rather than duplicate feature tickets.

Open questions to answer in the issue before implementation:

1. Should the first implementation cache only PortalService composed reads, or should it also wrap selected direct AlmaClient fetch methods in the same PR?
2. For user/session isolation, is a stable non-secret fingerprint of the configured username plus service name enough, or should the cache key be derived from the live client/session object identity where available?
3. Which mutating routes should invalidate portal/dashboard reads in v1: course registration/edit actions only, mail actions too, or a broad clear_all_authenticated_cache() after any authenticated mutation?
4. Should configure_cache(...) be exported from tue_api_wrapper.__init__, or is keeping it under a cache/config module acceptable for now?
5. What TTL should examples and tests use? I would keep production defaults disabled and use a conservative example like 30-60 seconds when enabled.

Proposed acceptance criteria refinement:

• Caching is opt-in and disabled by default for existing users.
• Existing wrapper methods and API route response shapes do not change.
• Repeated identical reads through the selected v1 paths hit cache within TTL and reload after TTL expiry.
• Different users/sessions/service contexts and different request parameters cannot share cache entries.
• Mutating actions either bypass cache or invalidate affected authenticated read cache entries before returning.
• Exceptions, auth failures, and transient upstream failures are not cached as successful values.
• Tests cover the cache utility plus one integrated PortalService read path, including hit, miss, expiry, invalidation, parameter isolation, and failure-not-cached behavior.
• cd package && pytest passes.

My recommendation: treat this issue as a focused PortalService/dashboard caching PR first. Once that shape is reviewed, follow-up issues can decide whether lower-level clients should opt into the same utility path-by-path.

[SebastianBoehler]

Implemented in PR #18: opt-in process-local in-memory portal caching with TTL configuration, internal cache behavior behind the existing wrapper methods, and mutation-driven invalidation. This stays intentionally lightweight; larger deployments should still own their own app-level caching layer.