docs: range-read milestone M3 — remote files

README: "Reading remote files" (open_url, the range_server and read_url
examples with their real output against the fixtures, h5rs on URLs), the
crate in the crate map and the unreleased highlights. CHANGELOG: the
clawhdf5-remote crate, h5rs URLs, File::storage and
VlResolver::element_in, with the request counts over the conformance
corpus (tank, 2026-09-26, the command given). known-issues: the M2
range-read entry updated (the cache now exists; h5rs reads through
storage) and a new entry for the remote backends' limits (no Python or
browser URLs yet, fixed block size, cloud stores not run against a real
bucket, validators, credentials). Design doc: M3 status with the choices
that differ from the plan (a crate rather than a clawhdf5-io feature,
ureq for HTTP so the default build has no C) and the corpus counts.

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

docs/known-issues.md

@@ -766,20 +766,22 @@ which is what libhdf5 itself writes.
 ## Range reads (`File::open_storage`) limits
 
 **Status:** open (added 2026-09-26, milestone M2 of
-`docs/design/range-reads.md`). `File::open_storage` reads any
-`clawhdf5_format::storage::Storage` through the whole read API, and every
-format-crate read path works through `Storage::read_at`/`read_ranges`, but:
+`docs/design/range-reads.md`; remote backends added by M3). `File::open_storage`
+reads any `clawhdf5_format::storage::Storage` through the whole read API,
+every format-crate read path works through `Storage::read_at`/`read_ranges`,
+and `clawhdf5-remote` serves HTTP(S) and object-store files through a block
+cache, but:
 
-- **No remote backend and no block cache yet** (milestone M3). A `Storage`
-  is asked for each structure as the parsers need it, several times over
-  for some (an object header is re-read by each lookup through it): one
-  pass over the conformance corpus — open, list, every attribute, every
-  dataset once — is 176 092 `read_at` calls for 621 files, 92 489 of them
-  for the 35 001-group `h5stat_newgrat.h5` (2026-09-26, tank,
-  `crates/clawhdf5/tests/storage_equivalence.rs` with
-  `CLAWHDF5_STORAGE_CORPUS`). A backend over a network needs a cache in
-  front of it. `Storage::read_ranges` defaults to one `read_at` per range;
-  coalescing is the backend's job.
+- **A `Storage` without a cache is asked for each structure as the parsers
+  need it**, several times over for some (an object header is re-read by
+  each lookup through it): one pass over the conformance corpus — open,
+  list, every attribute, every dataset once — is 176 092 `read_at` calls
+  for 621 files, 92 489 of them for the 35 001-group `h5stat_newgrat.h5`
+  (2026-09-26, tank, `crates/clawhdf5/tests/storage_equivalence.rs` with
+  `CLAWHDF5_STORAGE_CORPUS`). A backend of your own over a network needs a
+  cache in front of it: wrap it in `clawhdf5_remote::BlockCache`, as
+  `open_url` does. `Storage::read_ranges` defaults to one `read_at` per
+  range; coalescing is the backend's (or the cache's) job.
 - A group lookup by name in a version-1 (symbol-table) group lists the whole
   group (dense groups use their name index). Over a range backend that is
   one read per symbol-table node and name, per lookup.
@@ -790,10 +792,12 @@ format-crate read path works through `Storage::read_at`/`read_ranges`, but:
   `read_*_zerocopy`) need the file in memory and answer
   `FormatError::ContiguousStorageRequired` otherwise; `File::as_bytes()`
   panics for such a file (`File::contiguous_bytes()` is the fallible form).
-  `LazyFile`, `MmapFile`, the Python and wasm bindings and `h5rs` still read
-  a whole file.
+  `LazyFile`, `MmapFile` and the Python and wasm bindings still read a
+  whole file (`h5rs` reads through `File::storage`, and takes URLs with its
+  `remote` feature).
 - The file's length is read once, at open: a growing file (SWMR) is not
-  followed (milestone M5).
+  followed (milestone M5). A remote file is pinned at open, so one that
+  grows is `RemoteError::FileChanged`.
 - Not new, but visible through the equivalence tests: a full read through
   the file's chunk cache (`read_raw_data_cached`, `read_raw_data_indexed`,
   and so `Dataset::read_*`) lists a damaged dataset's chunks in hash-map
@@ -801,6 +805,38 @@ format-crate read path works through `Storage::read_at`/`read_ranges`, but:
   the next (`cve-2025-2310.h5`); the values of a dataset that reads are
   not affected.
 
+## Remote files (`clawhdf5-remote`) limits
+
+**Status:** open (added 2026-09-26, milestone M3 of
+`docs/design/range-reads.md`).
+
+- **Python and the browser cannot open URLs yet.** `clawhdf5.File` (PyO3)
+  parses through `File::as_bytes`, which a remote file does not have; the
+  wasm reader's `openUrl` is milestone M4.
+- **The block size is fixed** (1 MiB unless `CacheConfig` says otherwise).
+  The design's policy of using a paged file's page size as the block size
+  is not implemented, and only the first block is read ahead.
+- **Checked against local servers and one public one.** The tests use an
+  in-process HTTP/1.1 server and object_store's in-memory and local-file
+  stores. HTTPS was checked by hand against `raw.githubusercontent.com`
+  (2026-09-26, tank: `h5rs dump` of h5py's `vlen_string_dset.h5` by URL
+  equals the downloaded file's). The `s3`, `gcs` and `azure` backends are
+  built and their URL parsing tested, but they have not been run against a
+  real bucket.
+- **A server with neither a strong ETag nor Last-Modified** can only be
+  checked by length, so a same-length replacement mid-read would go
+  unnoticed; `HttpOptions::require_validator` refuses such servers. A weak
+  ETag (`W/"…"`) cannot be sent as `If-Match`, so it counts as none.
+- **Credentials:** HTTP takes extra headers (`HttpOptions::headers`, e.g.
+  `Authorization`); `h5rs` has no option for them. The cloud stores read
+  credentials from the environment only.
+- Each `ObjectStoreStorage` owns a tokio runtime with two worker threads.
+- `h5rs check` downloads a remote file whole (it validates every byte), and
+  a URL cannot carry a `FILE/OBJECT` suffix; `h5rs` uses the default cache
+  settings.
+- The zero-copy methods and `File::as_bytes` are unavailable on a remote
+  file (see the range-read limits above).
+
 ## `clawhdf5-wasm` (browser) limits
 
 **Status:** open (by design for now; added 2026-09-26).