Skip to content

feat(task): make resuming public - #210

Draft
greenhat616 wants to merge 1 commit into
feat/hardening-44-resume-enginefrom
feat/hardening-45-resume-public
Draft

greenhat616 wants to merge 1 commit into
feat/hardening-44-resume-enginefrom
feat/hardening-45-resume-public

Conversation

@greenhat616

Copy link
Copy Markdown
Owner

C20c (T21), the last of three commits of C20 (resume) and the eighth commit of PR-9d in the download strategy hardening stack. It is stacked on #209 (C20b, engine resume), its base branch. With #208 and #209 it completes C20, and with it T21. The design notes are in §11.5 and §14.30.3.

What

Public API

  • Resume { Off, On }: #[non_exhaustive], Off by default (§11.5.2). Set through TaskBuilder::resume.
  • TaskBuilder::resume_source(impl Into<String>):
    • The source is stored in the state file's header and compared on resume. A mismatch, including a source on one side only, is SourceMismatch.
    • A source over 4096 bytes fails validate() with the existing BuildError::InvalidOptions.
  • TaskStatus::kept_for_resume: the partial file a task kept for resuming (STATUS-13).
  • bolt_load::task::discard_partial: removes the partial file and the state file of a destination, under the lock (C33c).
  • The result types made public in feat(task): resume from a checked state file #209 now describe the real behaviour. The "cannot be switched on yet" wording is gone.

Docs

docs/task.md has a new "Resuming" section, and the README a shorter one. They cover:

  • what is kept and checked, and when a download can be resumed;
  • that a task never starts over on its own, with a client-side example that calls discard_partial;
  • a fresh adapter: the adapters cache their probe. If-Range catches a change only when the resume issues a range request, and a resume that kept every block issues none. To check against the current resource, resume with a fresh adapter;
  • the lock requirement on file systems that cannot lock files;
  • the scope: crashes, power loss and bad sectors, not tampering. Windows has no directory sync;
  • the Singleton exception, documented the same way in TaskBuilder::prefer_mode: a resumable On task runs concurrently with one connection, so that it keeps a state file (§11.5.8);
  • the ureq2 limitation: a blocking call that is still running keeps its connection until it returns. Until then the task can exceed max_connections, and without agent timeouts that can last indefinitely. Tracked in ureq2: a dropped stream can keep its connection open, so a retry briefly overlaps it #207, with a link to the adapter README's timeout guidance.

task-api-spec: STATUS-12 is final. tasks.md: both T21 C20 boxes are ticked.

Not breaking

Checked item by item against the final API:

  • Resume is a new #[non_exhaustive] enum.
  • resume and resume_source are new methods.
  • discard_partial is a new function.
  • kept_for_resume is a new field of the #[non_exhaustive] TaskStatus.
  • BuildError gains no variant.
  • Off is the default, and its behaviour is unchanged.

The test crate gained a server mode, but it is publish = false.

Tests

  • G9 (tests/resume.rs), public API only.
    • Runs: 21 seeds × 3 clients (reqwest, decoding reqwest, ureq2), 63 runs. Running every seed on every client is a lead decision.
    • Each seed picks a byte position, and the server holds the response there.
    • For positions at least one block plus 64 KiB in, the test waits until a whole block is reported written, then cancels.
    • After the cancel, the task ends Cancelled, kept_for_resume is the partial file, and the state file is present.
    • A fresh adapter then resumes: the hash is right, resumed is set, and nothing is left next to the file. Each client keeps blocks on at least one seed.
  • Crash and cross-process locking (src/task/tests/resume_crash.rs). The test binary re-runs itself as a child process. The child stops at a gate with no deadline, prints, and is killed (TerminateProcess or SIGKILL), so no cleanup runs and no test waits on a timer.
    • The kill points cover the three positions G9 names:
      • before the first checkpoint, when only the header is on disk;
      • during a checkpoint, after its records are written and before they are synced;
      • after a failed rename.
    • Before the rename is a fourth point.
    • While the child holds the lock, On and Off tasks in the parent fail with InUse.
    • After the kill, the parent resumes exactly the recorded blocks, fetches only the rest, gets the right content, and leaves the lock free.
  • discard_partial after a cancellation: both files are removed, and the next task starts fresh.
  • resume_source: the same source resumes; another source, or none, is rejected with both files untouched. The 4096-byte limit holds.
  • Mutations: 4 of 4 caught. They cover the source not stored, not compared, a 4096-byte source refused, and no limit.

Review

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

  1. Round 1: PASS (88). Four Minors, all fixed:

    • the crash gate could expire under load; it now has no deadline;
    • G9's kept-block check depended on scheduling; it now waits for a written block;
    • the Singleton exception was undocumented;
    • the ureq2 limitation was understated.

    Its Suggestion, the Send probe's initializer, is fixed, and the probe was checked with both CI configurations.

  2. Round 2: PASS (97/100). Its Suggestion is applied: G9's wait now requires a full block.

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: 29 suites, 960 passed, 1 ignored (the benchmark).
  • cargo test --workspace --locked: 29 suites, 887 passed, 1 ignored.
  • The crash test and G9: 3 runs in a row each, all passed.
  • RUSTDOCFLAGS=-Dwarnings cargo doc --no-deps --all-features -p bolt-load: the same 18 errors as its base.

@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-45-resume-public branch from 6d6e8eb to 48d0115 Compare November 13, 2026 07:44
@greenhat616
greenhat616 marked this pull request as draft November 13, 2026 08:55
Resume::On, set through TaskBuilder::resume, lets a task keep its
partial file and a state file when it ends early, and continue from
them next time. It is off by default, and an Off task behaves exactly
as before. An optional resume_source names the download, for example
by its URL, and a resume with another source is rejected.

A task never starts over on its own. If the pair cannot be resumed, it
fails with ResumeRejected and leaves both files as they were, so the
caller decides. TaskStatus::kept_for_resume names the partial file a
task kept, and discard_partial removes the pair for a destination.

The README and the task guide describe what is kept and checked, why a
fresh adapter is needed to check against the current resource, the
lock requirement, and the ureq2 connection limitation (#207).

End-to-end tests resume after a cancellation at 21 seeded positions on
all three clients, and after a child process is killed before, during
and after a checkpoint and after a failed rename. While a child holds
the lock, tasks in another process fail with InUse.
@greenhat616
greenhat616 force-pushed the feat/hardening-45-resume-public branch from 48d0115 to 21da379 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