Cap merged-range size in coalesce_ranges to bound HTTP over-fetch (#2266)

[brendancol]

Summary

• Add a max_coalesced_range_bytes cap to coalesce_ranges so a tile table with many small valid byte counts and sub-MiB gaps can no longer chain into a multi-GiB merged GET. The cap follows the per-tile cap pattern: default MAX_COALESCED_RANGE_BYTES_DEFAULT (256 MiB), overridable via XRSPATIAL_COG_MAX_COALESCED_RANGE_BYTES.
• Plumb the cap through _HTTPSource.read_ranges_coalesced and _FSSpecSource.read_ranges_coalesced so both COG remote-read paths pick up the bound automatically.
• Add eight unit tests: the 4096-tile adversarial case from the issue, byte-level round-trip after a forced split, env-var override, the zero-cap escape hatch, no false splits on legitimate back-to-back tiles, and HTTP wrapper propagation.

Closes #2266.

Backend coverage

HTTP / cloud range-fetching code; the four-backend grid does not apply. The fix is in _sources.py and is exercised by both _HTTPSource (urllib3) and _FSSpecSource (cloud).

Test plan

• pytest xrspatial/geotiff/tests/test_http_cog_coalesce.py -- 19 passed (11 existing + 8 new)
• Full xrspatial/geotiff/tests/ minus one pre-existing lz4 opt-in test unrelated to this change -- 5045 passed

[brendancol]

PR Review: Cap merged-range size in coalesce_ranges to bound HTTP over-fetch (#2266)

Blockers (must fix before merge)

• None.

Suggestions (should fix, not blocking)

• xrspatial/geotiff/_cog_http.py:914 -- the call site reads XRSPATIAL_COG_COALESCE_GAP from env explicitly and passes it through gap_threshold, but it does not read XRSPATIAL_COG_MAX_COALESCED_RANGE_BYTES the same way. The env var is still honored because coalesce_ranges resolves None against the env, so behavior is correct. The asymmetry is a readability hazard: a future reader of the call site cannot tell from the call whether the cap is enforced. Either drop the explicit gap lookup at the call site (let coalesce_ranges read both env vars), or add the symmetric max_coalesced_range_bytes lookup at the call site. Either way the call becomes self-documenting.

Nits (optional improvements)

• _sources.py:657 -- the comment "Gaps may be negative if a later-listed range overlaps an earlier one; clamp so the merged length covers both" is slightly stale. The clamp is still there (new_end = max(cur_end, off + length)), but it moved out of the if body to a few lines above. Either move the comment up next to the line where the clamp actually happens, or trim it.
• test_coalesce_caps_merged_range_size_2266 (line 138) asserts the set of mapping triples has 8 distinct entries. The next test (test_coalesce_cap_round_trips_bytes_2266) already covers byte-level round-trip, so the set assertion is redundant. Not a bug, just dead weight.

What looks good

• The cap is layered on top of the gap check, not replacing it. Legitimate back-to-back tiles still coalesce.
• Both _HTTPSource and _FSSpecSource get the parameter, so the cloud path inherits the same defense.
• Re-exports in _reader.py keep the public import surface (from xrspatial.geotiff._reader import ...) consistent with the existing pattern.
• Tests cover the 4096-tile adversarial scenario, env-override, the zero-cap escape hatch, byte round-trip after a forced split, and HTTP wrapper propagation through a mock source.
• "Single oversized input is emitted intact" is the correct semantics and is documented. Rejecting oversized individual tiles belongs at the per-tile cap, not in the coalescer.

Checklist

• Algorithm correctness: bug fix; cap added correctly.
• [n/a] Backend grid: HTTP / cloud code, not a four-backend op.
• Edge cases (zero cap, oversized single, legitimate back-to-back, env override).
• [n/a] Dask boundaries.
• No premature materialization or unnecessary copies.
• [n/a] Benchmark: internal helper, no perf-sensitive new API.
• [n/a] README feature matrix: no new public function.
• Docstrings present and accurate.

[brendancol]

Follow-up review after f3ec887

All three findings from the previous review are applied. No new findings.

• Suggestion (call-site asymmetry): fixed. _cog_http.py:914 now resolves _max_coalesced_range_bytes_from_env() explicitly and passes the cap as max_coalesced_range_bytes=.... The env var was already honoured implicitly; the explicit lookup just makes the call site self-documenting.
• Nit (stale clamp comment): fixed. The "Gaps may be negative ..." comment moved up next to the new_end = max(cur_end, off + length) line where the clamp actually happens.
• Nit (redundant set assertion): fixed. The 8-distinct-mapping-triples check was removed; test_coalesce_cap_round_trips_bytes_2266 already covers correctness after a forced split.

Test mocks in tests/test_security.py and tests/test_strip_zero_dims_2053.py picked up the new max_coalesced_range_bytes kwarg so the call from _read_cog_http keeps working under the mock.

Checklist (re-verified)

• No new blockers, suggestions, or nits.
• pytest xrspatial/geotiff/tests/ -- 5045 passed, 1 deselected (pre-existing lz4 failure unrelated to this PR).