Better management of requireWifi at the application level for download tasks

[781flyingdutchman]

Although each task can specify whether it requires WiFi to run or not, this mechanism does not address the situation where a user switches a global toggle to 'Download over WiFi only' when tasks are already running. Because they were enqueued with whatever requiresWiFi setting, they'll stay like that. To the end user, this seems wrong.

This proposal introduces a new method to set requiresWiFi globally, across all download tasks, including those already enqueued or running.

Introduce a new method FileDownloader().requireWifi(RequireWifi when), with RequireWifi and enum with values forAllTasks, forNoTasks and asRequestedByTask. The action of this call only affects downloads, not uploads, and only affects iOS and Android

• The default (and also the state when you don't call this method at all, and the current behavior) is asRequestedByTask and in that case the requirement for WiFi is dictated by the requiresWiFi field of the Task
• The other two states are directly related to a toggle at the application level where a user can say whether they want to restrict downloads to WiFi or not, and these states apply to all tasks, overriding the task-specific setting
• For new tasks, this is simple: in the native logic the value of the global forAllTasks or forNoTasks overrides any task-specific settings at the moment the task is enqueued
• For tasks already active (enqueued or running), when you call FileDownloader().requireWifi(RequireWifi when), then on the native side two things happen:
  • For tasks already enqueued but not yet running (and whose WiFi requirement is different from what the when value dictates), we cancel the task and re-enqueue with the new when setting. This will be invisible to the user, and to the developer in that no state changes will be sent (we'll intercept those on the native side)
  • For tasks already running (and whose WiFi requirement is different from what the when value dictates), we pause the task and immediately resume it with the new when setting (a resume is really an enqueue with extra resume data). The task will emit state changes enqueued, then running once WiFi conditions are met. If resume fails (uncommon for long downloads, but always if the task's allowPause is false), the task is cancelled and re-enqueued (emitting canceled and enqueued states) and will start downloading from the beginning once running
• The return value of the call FileDownloader().requireWifi(RequireWifi when) is a Future with a list of tasks that are now waiting for WiFi as a result of the call - in case you want to act on that information in the app's UI or via a notification. We could expose another method to directly set or cancel the notification for a task so you can say something like 'Waiting for WiFi', or add another TaskNotification type waitingForWiFi to the FileDownloader().configureNotification(...) method that automatically shows that notification when a task is waiting for WiFi. I don't intend to ask a TaskStatus value for waitingForWiFi as I consider it a form of enqueued and don't want to introduce a breaking change.

A few observations:

• In no case is the task's actual requiresWiFi field changed, so it may not reflect the actual WiFi requirement used during downloads.
• One special case is a bit awkward: if the task was enqueued without a condition on WiFi availability, and is downloading while on WiFi, then the call FileDownloader().requireWifi(RequireWifi.forAllTasks) will pause the task, then resume it with the new condition that WiFi be available. This seems odd, given we were happily downloading on WiFi anyway, but it's required to allow the native system to pause or fail the task when moving out of WiFi range. There's a small chance the resume fails, and spoils a perfectly fine download, but I think this is acceptable, given you've explicitly requested that tasks require WiFi.
• Another similar special case is the reverse: task enqueued with condition on WiFi availability, downloading on WiFi, then calling FileDownloader().requireWifi(RequireWifi.forNoTasks) removes the condition, but pauses and resumes the task to do so, with the same small risk of failure
• The pause/resume sequence may be visible to the user (via notification or application UI) because it triggers a series of state changes. We can suppress the paused (or failed) state (because we intercept it) but we should not suppress enqueued and running as the task may not get back to running for a while. Ideally there is a waiting for WiFi state, but this is breaking and complicated to implement

[Chaphasilor]

Seems reasonable to me.

Can the native code intercept the OS pausing a task because of a (missing) WiFi connection? Because if that is so, you wouldn't need to preemptively restart tasks if the global toggle changes, you could simply wait until the task is paused and then update and resume it. That would mean that if the network conditions don't change, a task without WiFi-only requirement can just keep running...

Another thing, why does this only apply to downloads? I'm sure there are use cases for uploading only via WiFi, e.g. for a backup application like immich. So unless there are technical reasons why it's not possible, I'd treat uploads the exact same.

[781flyingdutchman]

Thanks for the feedback and ideas.

Unfortunately, when wifi is required and becomes unavailable, then iOS pauses without any way to detect that, and Android bluntly cancels the taskworker. Maybe the Android case can be twisted to do what you suggest, but not iOS.

Uploads are not supported because pause/resume is currently not supported for uploads. If that were to change (no plans!) then I agree this could apply similarly there.

[781flyingdutchman]

@Chaphasilor @kodomo5197 I implemented this on branch 'wifi' of the background_downloader repo. Use FileDownloader().requireWiFi to set the app-wide WiFi requirement, and FileDownloader().getRequireWiFiSetting to see what the current setting is. Let me know if this works for your implementation.

[781flyingdutchman]

This has been implemented roughly as described in this discussion, in version 8.2.0

[Chaphasilor]

@781flyingdutchman is there a way for you to detect metered networks on desktop platforms (and also mobile I guess)? That might be a good addition to prevent excessive downloading in some scenarios even on desktop.

And on mobile, it would be nice if downloads would also be prevented if the "Data Saver" is enabled, although that might already be handled automatically by the OS?

[781flyingdutchman]

The requireWiFi field does actually mean it waits for a non-metered network, so it does what you want, but only on Mobile. The connectivity_plus package doesn't offer any information on metered versus unmetered for desktop, and that was one reason why I didn't see how I could implement this for desktop (the other is that it is a bit of an edge case to worry about network connection on desktop). Data saver is an interesting one, that I know little about. It seems that most of it is handled by the OS but there are some developer overrides possible. It does get complicated though, as the implementation differs between iOS and Android so perhaps this is more a configuration thing than an API thing. I'll think about it some more.