Skip to content

feat(core): carry the If-Range validator in adapter meta - #202

Draft
greenhat616 wants to merge 1 commit into
fix/hardening-37-destination-lockfrom
feat/hardening-38-meta-validator
Draft

greenhat616 wants to merge 1 commit into
fix/hardening-37-destination-lockfrom
feat/hardening-38-meta-validator

Conversation

@greenhat616

Copy link
Copy Markdown
Owner

C34 (T21), the first commit of PR-9d (resume) in the download strategy hardening stack. It is stacked on #201 (the destination lock), which is its base branch. The design notes are in §11.5.7, §11.5.13 (item 2.1) and §14.27.

Why

A resumed download must check that the resource is still the version it started on. The state file will store the validator the adapter used, and C20 will compare it with a fresh probe (§11.5.7). The engine cannot see that validator today: each adapter keeps its If-Range value privately. This PR puts it in the adapter meta.

What

Core (bolt-load-core)

  • Validator moves from bolt-load-http to bolt_load_core::adapter::Validator (adapter/validator.rs). The variants, derives and as_str are unchanged. bolt-load-http re-exports it, so bolt_load_http::Validator still works.

  • Validator::matches, for C20:

    • the kinds must be the same;
    • a strong ETag compares byte for byte;
    • a Last-Modified compares as a parsed date, so the format may differ;
    • an unparseable date matches only the identical string.

    Nothing calls it yet.

  • BoltLoadAdapterMeta::validator: Option<Validator> and with_validator. It holds the validator the adapter sends in If-Range; None means ranges are unconditional.

  • httpdate becomes a dependency of core. It has no dependencies of its own and was already in the lock.

  • The parsing and selection helpers stay in bolt-load-http, since core does not need them.

Adapters (reqwest, ureq2)

  • One place. The separate cached if_range value is gone. The probe builds the meta with etag, last_modified and validator, and the validator comes from the bytes=0-0 GET, as in C19. Every range request takes its If-Range from the cached meta.validator, and so does the check of its response. So the meta always reports what the ranges send.
  • No validator. A rejected or failed probe leaves validator as None, and no If-Range is sent.
  • Customization. The before_request hooks and the adapter README now say that a hook, a ureq call hook or reqwest default headers must not replace the adapter's If-Range, or add one when the meta has none. Response checking always uses the cached value. The behaviour is unchanged since C19.

Not breaking

The only items removed are private:

  • reqwest's Context::if_range;
  • ureq2's Probed::if_range;
  • the tuple return of with_validators.

The new field is on a struct that is already #[non_exhaustive], and the old type path is re-exported. So the commit is feat(core) without !.

Known limitations

  • Caller-provided meta. A meta passed in through TaskBuilder::meta carries whatever validator the caller gives it, and the adapter still sends If-Range from its own probed meta. C20 must compare against the adapter's fresh meta. Noted in §14.27.
  • ureq2 cannot be cloned. UreqAdapter does not implement Clone, because its before_request is a Box, so it is shared through an Arc. Only reqwest has the clone test.

Tests

  • Core. Four unit tests for matches:
    • as_str is the value sent;
    • ETags match byte for byte;
    • dates match as dates;
    • a different kind does not match.
  • bolt-load-adapter/tests/if_range.rs, both adapters.
    • the_meta_names_the_validator_sent checks the exact meta.validator, then that two ranges each send exactly that value, or none. The cases:
      • a strong ETag that differs from the HEAD's;
      • a Last-Modified 1 s old;
      • an RFC 850 date;
      • a weak ETag;
      • a recent Last-Modified;
      • a future Last-Modified;
      • a rejected probe.
    • a_cloned_adapter_shares_the_validator (reqwest): one probe, and the clone and the original send the same If-Range.
    • a_failed_range_request_keeps_the_validator: a hook sends one range to a port that closes every connection. The range fails as retryable, meta.validator is unchanged, and the retried range sends the same If-Range and succeeds.
    • Asserts on meta.validator were added to two existing tests.
  • Mutations: 11 of 11 caught.
    • The validator dropped in core, in reqwest, and in ureq2.
    • The validator taken from the HEAD, on reqwest's fallback path and in ureq2.
    • A weak ETag stored as a validator.
    • Last-Modified compared as strings.
    • An ETag compared ignoring case.
    • The kind ignored in matches.
    • A reqwest clone not sharing the probe.
    • ureq2 dropping its cached probe when a range fails.

Review

Reviewed with /ccg:review, using the codex backend only (a single-model review).

Round 1: PASS (94/100). It found no Critical or Major issue, and its Minor and both suggestions are applied:

  • §14.27 said nothing reads the field; both adapters do, and only the engine does not yet;
  • the hooks now document that they must leave the adapter's If-Range alone;
  • tests were added for clones and for a failed and retried range.

Checks

All on +nightly-2026-11-06, with --no-fail-fast. Clippy allows unnecessary_lazy_evaluations until #183 merges.

  • cargo fmt --all -- --check.
  • 4 clippy configs with -D warnings.
  • cargo test --workspace --all-features --locked: 28 suites, 819 passed.
  • cargo test --workspace --locked: 28 suites, 748 passed. if_range.rs needs both adapter features.
  • RUSTDOCFLAGS=-Dwarnings cargo doc --no-deps --all-features -p bolt-load: the same 18 errors as its base.
  • The same doc command for bolt-load-adapter, bolt-load-core and bolt-load-http: no errors.

@greenhat616
greenhat616 added this pull request to stack #212 November 11, 2026 15:23
@greenhat616
greenhat616 removed this pull request from stack #212 November 11, 2026 15:25
@greenhat616
greenhat616 added this pull request to stack #190 November 11, 2026 15:25
@greenhat616
greenhat616 force-pushed the feat/hardening-38-meta-validator branch from 2f255ee to f324941 Compare November 13, 2026 07:44
@greenhat616
greenhat616 marked this pull request as draft November 13, 2026 08:55
BoltLoadAdapterMeta gains `validator`: the validator an adapter sends in
If-Range, a strong ETag or a Last-Modified, or None when ranges are
unconditional. The resume work will store it in the state file and
compare it with a fresh probe.

Validator moves from bolt-load-http to bolt_load_core::adapter, and
bolt-load-http re-exports it, so the old path still works. It gains
`matches`: the same kind, a strong ETag byte for byte, and a
Last-Modified compared as a date, so its format may differ. Core now
depends on httpdate, which was already in the lock.

Both adapters drop their separate cached If-Range value. They store the
validator once in the probed meta, and every range request takes its
If-Range, and the value its response is checked against, from that
field. So the meta always reports what the ranges send.
@greenhat616
greenhat616 force-pushed the feat/hardening-38-meta-validator branch from f324941 to 3cdeb7b Compare November 13, 2026 22:26
@greenhat616
greenhat616 removed this pull request from stack #190 November 13, 2026 22:28
@greenhat616
greenhat616 added this pull request to stack #215 November 13, 2026 22:29
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant