From 97ff4e19d15ba9b653991c0ccee385650cbe8aed Mon Sep 17 00:00:00 2001 From: Tom Brow Date: Mon, 2 Nov 2026 12:55:55 -0800 Subject: [PATCH] docs(mobile): describe the role split in the media image keys (#8932) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Follow-up to [#8913](https://github.com/block/buzz/pull/8913). Its review [noted](https://github.com/block/buzz/pull/8913#discussion_r4445612714) that three doc comments in `media_image.dart` still describe the old keys after that PR split direct and thumbnail-fallback loads: - The class doc now says the provider keys on `isThumbnailFallback` as well as url, scale and auth scope. - The `_cooldownUntil` doc says it is keyed by (url, isThumbnailFallback), like `_inFlight` but without auth. - The `_SharedFetch` doc says a download is shared per URL, auth scope and role. Comments only, no behavior change. `flutter analyze` is clean and the full mobile suite passes. No app run, since nothing executes differently. 🤖 Generated with [Claude Code](https://claude.com/claude-code) Signed-off-by: Tom Brow Co-authored-by: Tom Brow Co-authored-by: Claude Opus 5.5 --- mobile/lib/shared/relay/media_image.dart | 16 +++++++++------- 1 file changed, 9 insertions(+), 7 deletions(-) diff --git a/mobile/lib/shared/relay/media_image.dart b/mobile/lib/shared/relay/media_image.dart index 4691e17bf3..96817cf76c 100644 --- a/mobile/lib/shared/relay/media_image.dart +++ b/mobile/lib/shared/relay/media_image.dart @@ -28,8 +28,8 @@ final mediaHttpClientProvider = Provider((ref) { /// headers map in its `==`/`hashCode`, so a freshly signed Authorization /// header on every widget build made the *same URL* a new cache key and /// bypassed the in-memory [ImageCache] entirely. This provider keys on -/// (url, scale, auth scope) and injects auth headers at *fetch* time, so -/// header refreshes never invalidate cached images. +/// (url, scale, auth scope, isThumbnailFallback) and injects auth headers +/// at *fetch* time, so header refreshes never invalidate cached images. /// 2. **Failure cooldown.** A URL that fails to load is not retried until a /// cooldown elapses (honoring `Retry-After` on 429), so error retries on /// rebuild cannot amplify into a request storm against the rate limiter. @@ -83,8 +83,9 @@ class MediaImageProvider extends ImageProvider { static const _defaultCooldown = Duration(seconds: 30); static const _maxRetryAfter = Duration(minutes: 5); - /// Keyed like [_inFlight]: a direct load's failure must not stop a - /// fallback to the same URL from recording a missing thumbnail. + /// Keyed by (url, isThumbnailFallback), like [_inFlight] minus auth: a + /// direct load's failure must not stop a fallback to the same URL from + /// recording a missing thumbnail. static final Map<(String, bool), DateTime> _cooldownUntil = {}; static final Map<(String, MediaGetAuthService, bool), _SharedFetch> _inFlight = {}; @@ -362,9 +363,10 @@ class _MediaImageStreamCompleter extends MultiFrameImageStreamCompleter { } } -/// One download shared by every load of the same URL and auth scope. It is -/// aborted once every load waiting for it has been abandoned, and a load that -/// arrives after that starts a new download. +/// One download shared by every load of the same URL, auth scope and role +/// (direct or thumbnail fallback). It is aborted once every load waiting for +/// it has been abandoned, and a load that arrives after that starts a new +/// download. class _SharedFetch { _SharedFetch( Future Function(Future abort) fetch, {