fix(mobile): handle image stream completion when no image is emitted

[LeLunZ]

Description

Issue:
Currently if you press on a loading Thumbnail (image not present), the new route (or how its called in flutter) gets created where the RemoteFullImageProvider will try to wait on the initialImageStream of the same Thumbnail (where the request is loading and is still the cache).

The problem: the Thumbnail widget calls .cancel on the Thumbnail provider after the RemoteFullImageProvider already loaded the provider RemoteThumbProvider(assetId: key.assetId, thumbhash: key.thumbhash).

So now the RemoteThumbProvider waits on the initialImage, while the Thumbnail widget canceled the request. So the provider never emits an image, and the RemoteFullImageProvider will wait forever.

So short: race condition because one calls cancel, while the other one waits on the request

---

In the current immich application there are 2 ways the image request can get cancelled:

• by calling provider.cancel() (currently only the Thumbnail widget does that)
• by the OneFramePlaceholderImageStreamCompleter if its disposed and invokes the callback

That makes it problematical, as no Widget actually owns an image/imagestream or whatever. So it actually shouldn't be able to forcefully cancel an image request.
It can be that the "same" stream is used by multiple widgets

---

The fix:

Instead of letting widgets call cancel or waiting till the OneFramePlaceholderImageStreamCompleter is disposed (whenever flutter engine decides to), I think we should just cancel the image if no more listener is subscribed to the ImageStream.

So I think I implemented the quickest fix with the addOnLastListenerRemovedCallback in the ImageStreamCompleter.

No need to call .cancel anymore from the widgets, its just important that you always unsubscribe the stream if you don't need it anymore (same as before).

Fixes #25723

How Has This Been Tested?

• Tested locally by opening a bunch of images on a really slow network connection

Checklist:

• I have performed a self-review of my own code
• I have made corresponding changes to the documentation if applicable
• I have no unrelated changes in the PR.
• I have confirmed that any new dependencies are strictly necessary.
• I have written tests for new code (if applicable)
• I have followed naming conventions/patterns in the surrounding code
• All code in src/services/ uses repositories implementations for database calls, filesystem operations, etc.
• All code in src/repositories/ is pretty basic/simple and does not have any immich specific logic (that belongs in src/services/)

Please describe to which degree, if any, an LLM was used in creating this pull request.

Getting a quick overview of the code, and some insights on where to investigate.

[LeLunZ]

@mertalev sorry for creating a new pr, seems I messed up something up with the branching in pr #25895 and included some other commits from another fix

---

Also now after having an actual fix, and not some workaround like throwing an error, the title of the PR doesn't make any sense anymore.

fix(mobile): fix image stream cancellation for multiple listeners

[LeLunZ]

Also @mertalev

Another question, which does not really have anything to do with the issue but just in general:
Why are we waiting on the initialImageStream in the FullImageProviders? If the images already exists in cache OneFramePlaceholderImageStreamCompleter synchronously sets it as preview.
If the preview doesn't exist, why wait on it and not send the actual request directly instead?

From OneFramePlaceholderImageStreamCompleter

 /// The [initialImage] is an optional image that will be emitted synchronously
  /// until the first stream image is completed, useful as a thumbnail or placeholder.

[Copilot]

Pull request overview

This PR fixes a mobile image-loading race condition where opening an asset before its thumbnail finished loading could cause the full image to wait forever, by moving cancellation logic from widget disposal to ImageStream listener lifecycle.

Changes:

• Removed widget-driven cancel() calls from Thumbnail disposal to avoid canceling shared in-flight requests.
• Updated cancellable image providers to cancel when the last ImageStream listener is removed (instead of waiting for completer disposal).
• Refactored OneFramePlaceholderImageStreamCompleter to use addOnLastListenerRemovedCallback for cancellation signaling.

Reviewed changes

Copilot reviewed 5 out of 5 changed files in this pull request and generated no comments.

Show a summary per file

File	Description
mobile/lib/presentation/widgets/images/thumbnail.widget.dart	Stops canceling image providers on widget dispose; relies on listener removal instead.
mobile/lib/presentation/widgets/images/thumb_hash_provider.dart	Wires cancellation to “last listener removed” on the stream completer.
mobile/lib/presentation/widgets/images/remote_image_provider.dart	Same cancellation wiring for remote thumb/full providers.
mobile/lib/presentation/widgets/images/local_image_provider.dart	Same cancellation wiring for local thumb/full providers.
mobile/lib/presentation/widgets/images/one_frame_multi_image_stream_completer.dart	Switches from onDisposed to addOnLastListenerRemovedCallback to trigger cancellation.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[mertalev]

addOnLastListenerRemovedCallback was what this code used to use and I agree it's a cleaner approach, but it rarely gets called and when it does it's way too late. The Thumbnail widget canceling on dispose is a much more reliable way to actually cancel image requests.

[LeLunZ]

@mertalev Hm, just saw in the docs addOnLastListenerRemovedCallback is only called when there are no keepAlive Handler outstanding. So this delays the removal a bit.

I have pushed another change, where we have a synchronous onLastListenerRemoved invocation. This should now have the same timing as the previous implementation where .cancel was called from the component.

---

But if this is also not wanted, what else do you suggest?
Other things that come to my mind:

• we have to check in the ThumbnailWidget before calling .cancel if the next route actually uses the image we want to cancel. And if the image is used, we don't cancel.
• we say, the ThumbnailWidget has full control over the stream, and just let it cancel, but then we need some way of telling other subscribers that no more frames will come, by eg. throwing an error if listeners are still subscribed.

---

The bug is really annoying, so it would be cool if we could find a fix :) because if you see a blurry image in the Gallery, and already know its the image you want to open, you currently still have to wait till the full thumbnail is shown or else this bug will happen.

[mertalev]

There are many possible approaches here, like making the thumbnail widget not cancel on tap (though this also needs care since disposal happens a lot and doing expensive checks for this will slow things down), marking a request so it can only be canceled by a full-size provider and not a thumbnail provider, tweaking the initial stream / getInitialImage behavior, etc. I'm not sure which is the best approach, but this approach has a higher chance of performance regression than others.

Concerns are addressed

[mertalev]

I did some profiling and didn't identify any regressions, which makes this a strictly better solution since it avoids image provider ownership issues.