Skip to content

docs: wrap up the download strategy hardening - #211

Draft
greenhat616 wants to merge 1 commit into
feat/hardening-45-resume-publicfrom
feat/hardening-46-wrapup
Draft

greenhat616 wants to merge 1 commit into
feat/hardening-45-resume-publicfrom
feat/hardening-46-wrapup

Conversation

@greenhat616

Copy link
Copy Markdown
Owner

T22, the last commit of the download strategy hardening plan (docs/spec/2026-11-01-download-strategy-hardening/). It is stacked on #210 (C20c), its base branch. Docs only.

What

P2 deferred (maintainer decision, 2026-11-11)

T16–T18 are not implemented in this plan:

  • admission and per-host connection caps (Limits);
  • a shared token bucket;
  • the host capability cache.

They are policies across tasks, so they belong in a client or job layer above Task, by the same principle as §11.5.1 and #195.

  • Where it is recorded: design §14.31 and the D4 row; tasks.md, as a note before T16 with the boxes left unticked as a reference; and row 8 of the IDM plan, marked deferred.
  • Effect: the 85% speed-limit brake (§9.2) and turning off the slow restart under a speed limit (§9.5) assume a shared limit. Their input is always None, so they never apply now.

IDM plan §5 table

Gaps compared with IDM (design §14.32)

Each row gives:

  • the IDM behaviour, with its source section;
  • bolt-load's current state;
  • a suggested layer;
  • a rough size.
# Gap Layer Size
G1a–c Queue admission; IDM's per-site connection count, per download; IDM's speed limit, per download, with the 85% peak-rate brake client/job large
G2 IDM's configured per-site exemption from the single-connection downgrade; separately, bolt-load's own learned host cache (S7) client/job medium
G3 Task-level scheduler retry client/job medium
G4 Schedules and quotas client/job medium
G5 Hedging during the download, not only at the end engine medium
G6 A finished connection takes over the next chunk engine medium
G7 IDM's faster growth tier engine small
G8 An extra content-fingerprint check. Resuming without a validator is unverified and would need its own design engine medium
G9 Disk-space precheck or real preallocation engine small–medium
G10 IDM's endgame tolerance, which conflicts with never corrupting data engine small
G11 Protocols other than HTTP adapter medium–large each

Where an IDM claim is an inference, it keeps the source's confidence. Shared host caps and an aggregate bandwidth bucket are bolt-load's own P2 extension, not IDM behaviour. The section decides nothing. It ends by asking the maintainer which gaps to fill, and in which layer.

READMEs

  • Crate README:
    • a resumable-downloads feature bullet;
    • an Options table: max_connections (8), max_attempts_per_range (5), and the other options with their builder methods and defaults, checked against the code;
    • a note that limits across tasks are not part of bolt-load.
  • Root README:
    • Connections: the limit is max_connections (8 whatever the CPU count), no longer "one runner per CPU core".
    • Growth: the old Legacy "Thread Control Algorithm" is replaced by a short description of Doubling, including the silent-runner exception and the average-rate fallback.
    • Resuming:
      • which downloads keep state: known non-zero size, no content coding, ranges, and a validator of at most 1024 bytes;
      • when On behaves as Off;
      • which failures keep the pair;
      • what happens when ResourceChanged or a fallback cannot clear the state: kept_for_resume vs leftover_temp_file;
      • ResumeRejected and discard_partial.
    • Limits across tasks: they belong above Task.
  • Limits: not mentioned, since P2 is deferred.

tasks.md

The three T22 boxes are ticked. The note on the IDM table says to update it again when the PRs merge.

Review

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

  1. Round 1 (84).
    • Major: §5 rows 5–7 were marked not breaking. Fixed, with migrations.
    • Six Minors, all fixed:
      • G1 conflated per-download IDM limits with shared ones;
      • G2 equated a configured exemption with a learned cache;
      • G8 presented resuming without a validator as an IDM fact;
      • the root README's growth summary left out the silent-runner exception;
      • its resume section promised retention unconditionally;
      • its tasks.md note was inaccurate.
  2. Round 2: PASS (93/100). Its three Minors are fixed: the resume conditions, the discard outcomes when invalidation fails, and G1c's per-download effective limit with the peak-rate brake. Its Suggestion, to keep the source's confidence on an inference, is applied.

Checks

  • No code changes, and no file included in rustdoc changed. The only README pulled in by include_str! is bolt-load-sync's, which is untouched.
  • cargo fmt --all -- --check passes, and git diff --check is clean.

@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-46-wrapup branch from aee88fa to e486b90 Compare November 13, 2026 07:44
@greenhat616
greenhat616 marked this pull request as draft November 13, 2026 08:56
Close out the plan. The maintainer decided on 2026-11-11 to defer P2
(admission, per-host connection caps, a shared speed limit and the host
capability cache): these are policies across tasks and belong in a
client or job layer above Task. T16 to T18 stay unticked as a reference
for that layer.

The IDM improvement plan's PR table marks every other row as
implemented and awaiting merge, with its PRs and migrations, and the
design notes gain an inventory of what bolt-load still lacks compared
with IDM, for the maintainer to decide on.

The READMEs describe the connection limit, the per-range budget and the
other task options, resuming and its conditions, the current growth
strategy, and that limits across tasks belong above Task.
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