fix: register session listeners in framework extension configs (#709)

[hasansezertasan]

Summary

Fixes #709 — framework extension configs (Litestar, Starlette, Sanic, Flask, async and sync each) override create_session_maker without delegating to super(), silently skipping AsyncFileObjectListener / SyncFileObjectListener, touch_updated_timestamp, and AsyncCacheListener / SyncCacheListener registration. User-visible effect: file uploads via FileObject / StoredObject persist metadata to the database but the actual file content is silently discarded.

• Fix: Each override now delegates to super().create_session_maker() so the middle-layer listener wiring runs. Framework-specific pre-steps (notably Starlette/Sanic/Flask's engine_instance caching) are preserved verbatim — the principle is add listener wiring, preserve every other observable behavior.
• Scope: 8 source files (4 extensions × async + sync). FastAPI re-exports the Starlette configs at the package level, so it inherits the fix for free (pinned by a dedicated regression test).
• Tests: Listener-registration contract is locked per extension via a shared helper module (tests/unit/test_extensions/_listener_contract.py). Flask, Sanic, Starlette, FastAPI, and Litestar each get 6 thin tests that call into the shared assertions, so future overrides cannot silently drop listeners again.

Design notes

• Why mock-based unit tests and not integration tests? The base class's integration tests already cover end-to-end listener behavior. The bug is that listeners weren't registered at all in subclasses — a unit-test question. Mocks catch exactly that failure mode loudly and specifically (call_count == 0 vs expected 6), whereas an integration test would fail as a confusing silent missing-file, which is exactly the failure mode Bug: Litestar SQLAlchemyAsyncConfig.create_session_maker() does not register FileObject session listeners #709 reported.
• Why engine_instance pre-step preserved in Starlette/Sanic/Flask? Analysis shows it's technically redundant with get_engine()'s internal memoization, so the overrides could be deleted outright. But "minimal harm" mandates preserving exact call sequences in case downstream users have subclassed or monkey-patched in unexpected ways. The tests pre-populate config.engine_instance = MagicMock() to isolate listener-count assertions from the aiosqlite dialect's internal event.listen calls.
• Shared test helper: Flask/Sanic/Starlette/FastAPI listener tests now delegate to _listener_contract.py helpers (~160 lines) instead of duplicating ~600 lines across four files. Each per-extension test file is now ~45 lines of thin wrappers that pass the extension's config class into the shared assertions. Litestar tests remain separate because they predate the extraction and live under their own subdirectory.
• Atomic commits: small commits tell the full story: failing-test commits (red) → super() delegation commits (green) → test-isolation commit → pre-step restoration commits → test strengthening and helper-extraction commits. Each commit is individually revertable.

Side effects worth noting

• Litestar session_maker caching is now enabled. The pre-fix Litestar async/sync overrides ended with return self.session_maker_class(**session_kws) — they built and returned a session maker but never assigned it to self.session_maker, so every call rebuilt it. After the fix, super().create_session_maker() routes through the middle layer (advanced_alchemy/config/{asyncio,sync}.py), which does cache via self.session_maker = .... The if self.session_maker: return self.session_maker guard at the top of the Litestar override now short-circuits on subsequent calls. This is a latent bug fix (nothing wants multiple session makers for one config), not a regression — flagged here so anyone tracking id(config.session_maker) stability across calls isn't surprised.
• Starlette/Sanic/Flask overrides are unchanged in this dimension — they already cached via self.session_maker = self.session_maker_class(**session_kws) in the pre-fix code, and the middle layer preserves the same caching semantics.

Test Plan

• Shared helper passes on all 5 extensions (Flask, Sanic, Starlette, FastAPI, Litestar) — 30 tests total
• Full tests/unit/ suite — no regressions (pre-existing failures in test_repository.py and test_utils/test_fixtures.py confirmed unrelated by checking out base commit)
• Reviewer manually verifies MCVE from Bug: Litestar SQLAlchemyAsyncConfig.create_session_maker() does not register FileObject session listeners #709 now produces "file_exists_on_disk": true
• Reviewer confirms the "minimal harm" design approach (preserve engine_instance pre-step) matches project preference

Draft status

Drafting for reviewer discussion on whether to keep the conservative engine_instance pre-step or delete the non-Litestar overrides outright (simpler, provably safe per get_engine() memoization analysis). CHANGELOG entries deferred to the release-bump process per project convention.

Supersedes

Supersedes #711 — same commits, renamed branch (feat/hasansezertasan/a → fix/extension-create-session-maker-listeners). The GitHub branch rename API closed the previous PR because cross-fork PRs don't preserve rename linkage.

🤖 Generated with Claude Code

[codecov-commenter]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 80.68%. Comparing base (e1e16b1) to head (6d862c9).
⚠️ Report is 1 commits behind head on main.

Additional details and impacted files

@@            Coverage Diff             @@
##             main     #712      +/-   ##
==========================================
+ Coverage   80.61%   80.68%   +0.07%     
==========================================
  Files          99       99              
  Lines        8227     8197      -30     
  Branches     1124     1116       -8     
==========================================
- Hits         6632     6614      -18     
+ Misses       1270     1269       -1     
+ Partials      325      314      -11     

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.

[cofin]

@hasansezertasan what did you have remaining on this? the change looks correct from what i can tell.

[hasansezertasan]

@hasansezertasan what did you have remaining on this? the change looks correct from what i can tell.

Hey @cofin, thanks for your time. I converted this one because I had some stuff in mind but I can't recall right now 🫤. I'll do a final review of my work and mark it as "ready for review".

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: f169d58f00

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".