6 - API (refactor): Remove Global State

[RobertRosca]

PR no. 6 of the big refactor.

This PR gets rid of the module-level singletons that the app bootstrapped at startup (_db.__ENGINE, _mymdc.CLIENT, auth.__CLIENT, TOKEN_STORE, registry metaclass, etc...) and replaces them with a single frozen AppState that's built once in the lifespan and handed out via DI. Also adds ADR-002 and ADR-003 which cover the reasoning.

Details

Previously any function could reach any dependency by importing a global, which is easy/short to write but has a bunch of downsides: init order is critical and pretty opaque, tests have to mutate/clear process-wide state between cases, you can't have two differently-configured apps in one process, in-process state looks shareable but silently breaks under multiple workers, etc...

ADR-002 goes through this and decides on a single typed AppState container built in the lifespan with dependencies injected everywhere else, so init is typed and order-explicit (defined by constructor) and tests inject fakes by building state instead of patching modules.

AppState + factories

state.py holds a frozen AppState dataclass and the create_* factory functions. The factories are pure - they take Settings (or already-built collaborators) and construct their object, no module state/side effects.

AppState currently has:

• db_engine / db_sessionmaker
• mymdc_client
• oauth_client (None when auth is disabled)
• token_store
• damnit_registry
• subscription_cursors

The lifespan builds all of these and attaches the result to app.state, slices can get it via a get_app_state FastAPI dependency.

Along the way this also:

• swaps the TOKEN_STORE dict for a TokenStore (InMemoryTokenStore)
• replaces the Registry metaclass with a plain DamnitDBRegistry
• moves the subscription cursors off the module and onto AppState
• drops some now-dead code (registry eviction, get_connection)

Settings

ADR-003 covers the way that settings are injected and is included here too since it is part of the global state that I wanted to remove, but (again) a bit of a lie since the actual removal of the settings = Settings() singleton isn't in this branch and create_app() still imports the global for now. The actual implementation of this is in a later branch.

Tests

test_state.py covers the AppState DI surface, factories, and stores. conftest.pys now build an AppState with fakes (mock MyMdC client, in-memory token store) instead of monkeypatching modules and clearing caches between tests 🎉

[CammilleCC]

Hmm, when I checked Settings() on the end of a stack, it still seems to be a singleton, and not injected. Could you please have a look if this is intended? (if it is, maybe we can relax the ADRs here?)

Also we still seem to use @alru_cache on the end, which is opposite to what the ADR2 is leading to. Maybe we can revisit these or the ADR as well.

[CammilleCC]

The question about Settings() still stands: you mentioned that it is intended to be removed, but I don't see it removed on the top of the stack. What are the plans for this?

Also on the @async_lru calls on MyMDC, there's a claim that we'll use Hishel instead of this. Do we still intend to do this? Of course we can leave the caches as these are now on the dependencies layer.