bevy_asset: support upgrading Reader to SeekableReader

[cart]

Objective

#22104 added AsyncSeek support, but it has some downsides:

• It is very "loose": it relies on AssetLoader to "attest" that it needs the seek feature. However, AssetLoaders both have access to the AsyncSeek API no matter what (it is a supertrait of Reader), and AssetReaders provide AsyncSeek behavior even if it isn't requested. In practice this is likely to create situations where AssetLoaders don't request AsyncSeek and just rely on it being provided by default, causing unexpected incompatibilities when AssetLoader consumers try to use other AssetReaders that don't support AsyncSeek.
• It encourages building "fallback" behavior into the AssetReader in cases where AsyncSeek cannot be supported directly (ex: read the while contents into a Vec). From the perspective of loaders, this silently changes the performance characteristics, and forces a specific kind of fallback behavior. It would be better if the fallback behavior was in the hands of the AssetLoader.

Solution

• Remove ReaderRequiredFeatures and associated functionality
• Add a new SeekableReader trait, where SeekableReader: Reader + AsyncSeek.
• Add a new Reader::seekable(&mut self) -> Result<&mut dyn SeekableReader, ReaderNotSeekableError>, which can either fail or cast to SeekableReader, if that is supported.

let seekable_reader = reader.seekable()?;
seekable_reader.seek(SeekFrom::Start(10)).await?;

This gives AssetLoader implementers more clarity when it comes to Reader feature support, gives them more autonomy over fallback behavior, makes our APIs more static, and cuts down on the complexity of the system as a whole.

[andriyDev]

LGTM, but we need to delete the remnants: android, wasm, and web modules need to be cleaned up, custom_asset_reader example also need to be cleaned up. Also some migration guides we need to update (we can leave this until later).

[cart]

Also some migration guides we need to update (we can leave this until later)

I updated these (and release notes) right before you posted 😄

[andriyDev]

Approved but for the doctest, which I've made a PR against this branch for: cart#50

Thanks for taking the time to fix this!!

[janhohenheim]

Looks much cleaner to me, good job! The PR introduces some new public API that is missing documentation. Approving after that :)

[cart]

(just checking to see what backporting will look like in terms of conflicts)

[janhohenheim]

These docs suggest that bytes should be readonly, which makes me think it should have stayed private with an accessor function.

[greeble-dev]

Noticed a couple of issues with this PR on the 0.18.0 branch. I can make a PR to clean them up if requested. EDIT: Decided to go ahead without request.

Firstly, compile error related to InstrumentedAssetLoader if trace feature is enabled:

error[E0432]: unresolved import `crate::io::ReaderRequiredFeatures`
  --> crates\bevy_asset\src\server\loaders.rs:18:5
   |
18 |     crate::io::ReaderRequiredFeatures,
   |     ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ no `ReaderRequiredFeatures` in `io`

InstrumentedAssetLoader has been removed in main but still exists in 0.18.

Also noticed some release content that references ReaderRequiredFeatures - I think they should have been removed by this PR?

[greeble-dev]

Followed up previous comment in #22430.