clawhdf5-remote: object stores through object_store (S3, GCS, Azure)

ObjectStoreStorage (feature `object-store`, pure Rust) reads one object
of any object_store store by ranged get_opts, pinned at open by a head
request: If-Match with its ETag (and the ETag and size of every response
compared), else its version or modification time. A change is
RemoteError::FileChanged. object_store is async and Storage is not, so
the storage owns a small multi-threaded tokio runtime (two workers) and
blocks the calling thread on it; the ranges of one read_ranges call are
fetched concurrently (up to 8). From inside another tokio runtime it
refuses with RemoteError::Usage instead of blocking a worker, and it
shuts its runtime down in the background on drop so dropping it in async
code does not panic.

open_object(store, path, options) opens a file through a block cache
(first block prefetched); open_url accepts s3://, gs:// and az:// with
the `s3`, `gcs` and `azure` features, configured from the environment by
object_store's from_env builders. Those pull object_store's cloud clients
and aws-lc-rs (C), so they are opt-in; without them the URL is a clean
UnsupportedScheme error naming the feature.

Tests against object_store's in-memory and local-file stores (no cloud):
every fixture's transcript equals File::open's, a multi-block object is
fetched in coalesced block runs, an object replaced while open is an
error, and a missing object or a read from inside a runtime is a clean
error. ci-test.sh lints all backends, runs these tests (with s3 for its
URL parsing test) and checks object-store for C in the no-C step.

Co-Authored-By: Claude Opus 5.5 (1M context) <[email protected]>

crates/clawhdf5-remote/README.md

@@ -1,6 +1,7 @@
 # clawhdf5-remote
 
-Read HDF5 files where they live — on an HTTP(S) server — with
+Read HDF5 files where they live — on an HTTP(S) server or in an object
+store (S3, GCS, Azure) — with
 [clawhdf5](../../README.md), without downloading them first.
 
 ```rust
@@ -52,8 +53,35 @@ The zero-copy methods of `clawhdf5` (`read_raw_ref`, `read_*_zerocopy`,
 |---|---|---|
 | `http` (default) | `http://` through `ureq`, no TLS | none |
 | `https` | `https://` through rustls, ring provider, Mozilla roots | ring (C and assembly) |
+| `object-store` | `ObjectStoreStorage` and `open_object` over any [`object_store`](https://docs.rs/object_store) store (in-memory, local files, or one you configure) | none |
+| `s3`, `gcs`, `azure` | `s3://bucket/key`, `gs://bucket/key`, `az://container/key` in `open_url`, configured from the environment (`AWS_*`, `GOOGLE_*`, `AZURE_*`) as object_store's `from_env` builders read it | aws-lc-rs (object_store's cloud clients) |
 
-The default build compiles no C (`scripts/ci-test.sh` checks it).
+The default build and `object-store` compile no C (`scripts/ci-test.sh`
+checks both).
+
+## Object stores
+
+`object_store` is async; `Storage` is synchronous (parsing is CPU work).
+`ObjectStoreStorage` owns a small tokio runtime (two worker threads) and
+blocks the calling thread on it for each read, so it is read from ordinary
+threads, several at once. From inside an async runtime it refuses
+(`RemoteError::Usage`) rather than block a worker: read in
+`tokio::task::spawn_blocking`. The object is pinned by its ETag
+(`If-Match`, and compared on every response), else its version or
+modification time, and its size. The ranges of one read are fetched
+concurrently (up to 8).
+
+```rust
+use std::sync::Arc;
+use clawhdf5_remote::object_store::{memory::InMemory, ObjectStore};
+let store: Arc<dyn ObjectStore> = Arc::new(InMemory::new());
+// ... put a file at "data.h5" ...
+let (file, cache) = clawhdf5_remote::open_object(store, "data.h5", &Default::default())?;
+```
+
+The tests use object_store's in-memory and local-file stores; no cloud
+account is needed. The cloud schemes are only built (and unit-tested for
+URL parsing) in CI, not run against a real bucket.
 
 ## Counting requests