feat: warn about every 0.4.0 breaking change in 0.3.9

[allen0099]

0.3.9 is the last 0.3.x release. This PR adds a warning for every 0.4.0 breaking change that 0.3.9 can detect, a "Migrating to 0.4.0" page covering the whole 0.4.0 milestone, and the release notice.

Closes #352

New warnings

Issue	Category	When it fires	How to silence it (forward compatible)
#256 cookie defaults	FutureWarning	Once, when FastAPICacheXSessionMiddleware is built, if its config leaves cookie_name or cookie_https_only at the default	Set both: cookie_name="session", cookie_https_only=False keeps today's cookie, or "__Host-session" + True switches now
#256 contradictory prefixes	UserWarning	SessionConfig with a __Host- name without cookie_https_only=True, with cookie_path != "/" or with a cookie_domain, or a __Secure- name without cookie_https_only=True	Fix the config (browsers already drop such a cookie). 0.4.0 rejects it
#280 get_or_set lock	FutureWarning	Once per manager, on a get_or_set() call that passes no lock= when the manager was created without lock=	lock=False/True per call or on CacheManager(...); for AppCache, CacheManagerProxy.set(CacheManager(lock=...))
#131 get_session_manager	FutureWarning	Once per app, when get_session_manager (and SessionManagerDep, ClientIPDep, rotate_session_id()) returns the middleware's manager but SessionManagerProxy holds none or a different one	SessionManagerProxy.set(session_manager) at startup
#126 Redis encoding	DeprecationWarning	AsyncRedisCacheBackend(encoding=...) or a RedisConfig with encoding set, passed to load_from_config()	Leave it out (UTF-8 is what you get without it). Non-UTF-8 values keep their RuntimeWarning and get no second warning
#129 short JWT key	existing UserWarning	unchanged	The message now ends "Version 0.4.0 will reject a shorter key (…/issues/129)."

The messages follow the existing ones (#298, #125): they name what is relied on, say "Version 0.4.0 …", give the fix, and end with the issue link. stacklevel points at the user's call: for the middleware, that is add_middleware/the first request, since Starlette builds the stack lazily.

Warning texts:

• 0.4.0: explicit login()/logout() that always rotate the session ID, and __Host- cookie by default #256: FastAPICacheXSessionMiddleware is using the default cookie_name and cookie_https_only of SessionConfig. Version 0.4.0 changes the session cookie defaults to cookie_name='__Host-session' with the Secure flag (cookie_https_only=True): the new name logs every cookie session out once on upgrade, and a Secure cookie is not sent over plain HTTP. Set both explicitly: cookie_name='session', cookie_https_only=False keeps the current cookie; cookie_name='__Host-session', cookie_https_only=True switches now (https://github.com/allen0099/FastAPI-CacheX/issues/256).
• 0.4.0: explicit login()/logout() that always rotate the session ID, and __Host- cookie by default #256 prefixes: cookie_name='__Host-session' requires cookie_https_only=True: browsers refuse a cookie with this prefix otherwise, so the session cookie would never be stored. Version 0.4.0 will reject this configuration.
• 0.4.0: enable get_or_set() stampede protection by default #280: CacheManager.get_or_set() is relying on the default lock=False: neither the call nor CacheManager(...) passed lock=. Version 0.4.0 turns stampede protection on by default (lock=True). Pass lock=False to keep the current behaviour, or lock=True to opt in now, to get_or_set() or to CacheManager() (for AppCache, register one with CacheManagerProxy.set()) (https://github.com/allen0099/FastAPI-CacheX/issues/280).
• 0.4.0: resolve get_session_manager through SessionManagerProxy #131: get_session_manager() returned the SessionManager the session middleware registered, which is not the one set in SessionManagerProxy. Version 0.4.0 resolves get_session_manager() (and SessionManagerDep, ClientIPDep and rotate_session_id(), which use it) through SessionManagerProxy only. Call SessionManagerProxy.set(session_manager) at startup (https://github.com/allen0099/FastAPI-CacheX/issues/131).
• 0.4.0: drop the Redis encoding option and read raw bytes #126: AsyncRedisCacheBackend(encoding='utf-8') is deprecated. Version 0.4.0 removes it: the client will read raw bytes, and entries are always UTF-8. Remove the argument; UTF-8 is what you get without it (https://github.com/allen0099/FastAPI-CacheX/issues/126). (the same text with RedisConfig(encoding=...) for load_from_config)

Decisions

• 0.4.0: explicit login()/logout() that always rotate the session ID, and __Host- cookie by default #256 cookie: warn at middleware construction, not in SessionConfig. Only FastAPICacheXSessionMiddleware sends the cookie. A warning in SessionConfig would also hit header-only users (the deprecated SessionMiddleware, bare SessionManager), who are unaffected. The warning covers cookie_https_only too: the Secure default is what breaks plain-HTTP development. Either explicit form silences it and keeps working on 0.4.0. Not detectable at runtime, so docs only: the rest of 0.4.0: explicit login()/logout() that always rotate the session ID, and __Host- cookie by default #256 (read-only Session.user, login starting a new session, grace period, logout API). Their shape is still undecided, and a warning now could point users at the wrong replacement; login() already exists and the migration page recommends it.
• 0.4.0: enable get_or_set() stampede protection by default #280: warn in get_or_set(), not at construction. This deviates from the plan in 0.4.0: enable get_or_set() stampede protection by default #280, which proposed warning at CacheManager() construction and skipping the AppCache default manager. A construction-time warning would fire for managers that never call get_or_set() and are unaffected. Skipping AppCache would leave the most common path silent, even though the user wrote the get_or_set() call whose behaviour changes. The warning fires only when neither the manager nor the call chose, once per manager, and a per-call lock= silences it without registering a manager. CacheManager(lock=None) is now accepted as "not chosen" (it used to raise TypeError); manager.lock is still a bool.
• 0.4.0: resolve get_session_manager through SessionManagerProxy #131: warn only when the proxy disagrees. Apps that already call SessionManagerProxy.set() (the forward-compatible wiring) stay silent.
• 0.4.0: drop the Redis encoding option and read raw bytes #126: warn only on an explicit encoding. The parameter's default becomes None (still meaning UTF-8), and load_from_config checks model_fields_set, so only code that passes the option sees the warning. Removing that code is exactly the 0.4.0 fix.
• 0.4.0: make BaseCacheBackend.delete() return whether a key was removed #71 delete() returns bool: docs only. A custom backend cannot declare -> bool today without a mypy override error against the 0.3.x base class. The only callers of the None return are the library's own. A warning would fire for everyone and could not be silenced by forward-compatible code.
• 0.4.0: make UserSessionDep require a session with a user #127 UserSessionDep: docs only. A type alias has no hook that runs when it is used. A module-level __getattr__ warning would fire on import for anyone who imports it, including code that is about to switch.
• Remove the deprecated memcache extra #202 memcache extra: docs only. The installer resolves extras; the library cannot tell which extra was requested.
• Cache key format (0.4.0: use a single | as the cache-key separator #271, Cache key: a single CacheKey type to encode and parse the format #270, Cache key: hash long query strings to bound key length #269, Cache key: add a format version tag to HTTP keys #266, Cache key: normalise the host (case, default port) #265, Cache keys do not normalize query parameter order #72) and Repeated response headers are collapsed when a response is cached #105 CacheEntry.headers: docs only. 0.3.x cannot tell whether a clear_pattern pattern or custom key builder will match the new format. The runtime cost of the key change is a single cache miss, and code that reads CacheEntry.headers cannot adopt the list shape before 0.4.0. The page covers clear_pattern("*|||*") cleanup and the rolling-deploy note for Repeated response headers are collapsed when a response is cached #105.
• 0.4.0: conditional session writes so a stale request cannot restore a deleted session #128 conditional writes, Allow cookies in token_source_priority #75 cookie in token_source_priority: docs only. No user code changes; custom-backend requirements are not decided yet.
• Already warned, unchanged: 0.4.0: remove BackendProxy.get_backend() / set_backend() #70, 0.4.0: remove the unused CacheError exception #130, 0.4.0: remove the deprecated SessionMiddleware #69, 0.4.0: remove the Redis clear_pattern prefix fallback #125, add_routes: monitoring routes are unauthenticated and expose content previews by default #298.

Docs

• docs/MIGRATING_0_4.md and i18n/zh-TW/docs/MIGRATING_0_4.md: added to both navs, with {#anchor} ids and one line per paragraph. They include a summary table of every 0.4.0 milestone item (issue, warned or not, section) and a section per item with before/after code. Details still open in an issue (login keep=, the key format tag, sort-by-default, the Repeated response headers are collapsed when a response is cached #105 version marker, the Allow cookies in token_source_priority #75 default order, the 0.4.0: conditional session writes so a stale request cannot restore a deleted session #128 primitive) are marked as not decided.
• Guide updates, mirrored in zh-TW:
  • SESSION: explicit cookie settings in the examples, SessionManagerProxy.set() in the basic and Redis examples, a "Cookie defaults change in 0.4.0" section, and a 0.4.0 note on get_session_manager.
  • APP_CACHE: explicit lock= in the examples and a "The default changes in 0.4.0" subsection.
  • JWT_CLAIMS: middleware configs use __Host-session.
  • BACKENDS: encoding dropped from the RedisConfig example.
  • README / index: get_or_set(..., lock=True).
• Examples (app_cache.py, session_login.py, session_jwt.py) use the explicit forms, and tests/test_examples.py runs them under filterwarnings = error.

Changelog

• Fragments: 256.deprecated.md, 256.deprecated.2.md, 280.deprecated.md, 131.deprecated.md, 126.deprecated.md, 129.deprecated.md.
• The release notice under ## [Unreleased] links to https://fastapi-cachex.readthedocs.io/en/stable/MIGRATING_0_4/. scripts/changelog_release.py --version 0.3.9 --dry-run prints it first.
• test_the_repository_changelog_can_be_released assumed the section opens with ###; it now allows the notice above the first heading.

Tests

• New tests/session/test_0_4_0_notices.py covers 0.4.0: explicit login()/logout() that always rotate the session ID, and __Host- cookie by default #256 and 0.4.0: resolve get_session_manager through SessionManagerProxy #131. The 0.4.0: enable get_or_set() stampede protection by default #280 tests are in tests/test_cache_manager.py, the 0.4.0: drop the Redis encoding option and read raw bytes #126 tests in tests/backends/test_redis.py, and the 0.4.0: reject JWT HMAC secrets shorter than the hash output #129 message check in tests/session/test_token_serializers.py.
• Each warning is tested both ways: it fires when the default is relied on and stays silent with an explicit value.
• Existing tests that relied on the defaults now pass the explicit values.

Checks

• Full pytest with live Redis and Memcached: 1445 passed, coverage 99.82%.
• tox -e lowest: passed.
• mypy fastapi_cachex --strict: clean.
• pre-commit run --all-files: clean.
• zensical build --strict (en and zh-TW): clean.