Skip to content

Replace completed-download handoff transactions with a simple recovery package #67

Description

@thsnkhn

Objective

Replace the completed-download transaction protocol with a small per-attempt recovery package.

Complete #65 before this work. Coordinate with #66.

Current problem

CompletedDownloadHandoffStore uses claiming, ready, and destination-recorded phases, placement staging, repeated hashing, package promotion, and package-level locking. The surrounding reconciliation code in DownloadCenter, DownloadCoordinator, and BrowserDownloadCoordinator makes completion behave like a database transaction.

Proposed design

Use one per-attempt directory containing:

  • manifest.json
  • payload
  • optional resume data

On successful backend completion:

  1. Move the completed payload into the attempt directory.
  2. Write one manifest atomically.
  3. Resolve and move the payload to its final destination.
  4. Save the completed DownloadItem.
  5. Remove the attempt directory with best-effort cleanup.

Remove:

  • claiming and destination-recorded phases
  • placement staging files
  • repeated SHA-256 verification
  • staging-package promotion
  • per-attempt registry locks that no longer serve the simple flow
  • complex invalid-package startup classification

Accepted edge cases

  • A crash between payload placement and record persistence can leave an orphan file.
  • A crash during completion can require a retry or redownload.
  • A destination collision discovered after relaunch can require user action.
  • Multiple Harbor instances are not supported.

Safeguards to retain

  • Attempt identifiers.
  • Basic source, size, and regular-file validation.
  • Valid completion recovery after a normal relaunch.
  • Atomic manifest writes.
  • Safe destination containment.
  • Normal pause, cancel, and retry behavior.

Acceptance criteria

  • Direct and browser downloads use the same simple completion package.
  • Normal completion and relaunch recovery work.
  • The old phase-based handoff protocol is removed.
  • Production code decreases by approximately 1,000 to 1,500 lines.
  • Focused direct, browser, and completion-recovery tests pass.

Metadata

Metadata

Assignees

No one assigned

    Labels

    No labels
    No labels

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions