sharefetch 1.0.0__py3-none-any.whl

sharefetch/engine.py

@@ -0,0 +1,1055 @@
+"""Orchestration: one URL, one destination, one verified tree and one manifest.
+
+This module joins every other module in the package and is the only thing a
+front end calls. The seam is one function and one protocol: :func:`run` takes a
+:class:`~sharefetch.config.Settings` and an
+:class:`~sharefetch.events.EventSink`, emits the run's events and returns a
+:class:`~sharefetch.events.RunSummary`. Nothing here writes to a
+console and nothing here holds a reference to Tk.
+
+The run has eight stages and each one emits its own event.
+
+1. Parse the URL, which is pure and needs no network.
+2. Build the one :class:`~sharefetch.pacing.Pacer`, the one
+   :class:`~sharefetch.auth.TokenProvider` and the one
+   :class:`~sharefetch.graph.GraphClient` the whole run shares. A second pacer
+   would double the effective request rate at two connections, so exactly one
+   is constructed and it is handed to both the client and every transfer.
+3. Resolve the reference to a drive and a folder.
+4. Enumerate the tree, mapping each drive-relative path onto a local path. An
+   addressed folder that answers ``404`` here is re-resolved once, one
+   percent-decode pass short of the ceiling the URL consumed, under four
+   conditions.
+5. Reconcile the enumeration against what is already on disk.
+6. Check free space against what the queue still has to fetch.
+7. Transfer, on a pool of one or two workers.
+8. Verify the whole tree, apply the hash implementation safeguard, and write
+   the manifest.
+
+``--dry-run`` stops after stage 5 and transfers nothing, so the operator sees
+what would be fetched and the state file records it. ``--verify-only`` runs
+stage 8's tree pass alone: it builds no token provider and no client, so the
+run makes no network call at all and needs no sign-in.
+
+The engine thread owns the queue and the pool. A worker owns one file and
+reaches the state file only through :class:`~sharefetch.state.StateStore`,
+which serialises its own writes.
+``pause`` and ``stop`` are :class:`threading.Event` objects created here and
+passed into every :func:`sharefetch.transfer.fetch` call, so a front end that
+sets one reaches a transfer already in flight at its next chunk boundary.
+"""
+
+from __future__ import annotations
+
+import logging
+import os
+import shutil
+import threading
+import time
+from collections import deque
+from collections.abc import Callable
+from concurrent.futures import FIRST_COMPLETED, Future, ThreadPoolExecutor, wait
+from pathlib import Path
+from typing import Any
+
+from .auth import TokenProvider
+from .config import (
+    CHECK_CONTENT_HASH,
+    CHECK_NOT_SUBSTITUTED,
+    FREE_SPACE_MARGIN,
+    REASON_HASH_MISMATCH,
+    REASON_PATH_TOO_LONG,
+    STATE_FILENAME,
+    STATUS_COMPLETE,
+    STATUS_FAILED,
+    STATUS_SKIPPED,
+    VERIFICATION_FAILED,
+    Settings,
+)
+from .errors import (
+    AuthError,
+    EnumerationError,
+    ManifestError,
+    SharefetchError,
+    ValidationError,
+    VerificationError,
+)
+from .events import (
+    EnumerationComplete,
+    EventSink,
+    FileFinished,
+    Reconciled,
+    Resolved,
+    RunFinished,
+    RunSummary,
+)
+from .graph import GraphClient
+from .listing import RemoteItem, SkippedItem, walk
+from .manifest import write_manifest
+from .pacing import Pacer
+from .paths import long_path, map_drive_path
+from .resolve import DriveTarget, decode_pass_ceiling
+from .resolve import resolve as resolve_reference
+from .state import ItemState, StateStore
+from .transfer import STATUS_PAUSED, fetch
+from .urls import SitePathRef, SourceRef
+from .urls import parse as parse_url
+from .verify import VerificationResult, verify_file
+
+logger = logging.getLogger(__name__)
+
+# How often a paused engine wakes to test whether it has been resumed or
+# stopped. The interval lives beside the only loop that reads it. It bounds the
+# delay between a front end calling resume() and the queue moving again, and
+# nothing else.
+PAUSE_POLL_SECONDS = 0.1
+
+BYTES_PER_MIB = 1024 * 1024
+
+# A worker thread name prefix, so a stack dump taken from a hung run names the
+# pool the frame belongs to rather than an anonymous "ThreadPoolExecutor-0_1".
+WORKER_NAME_PREFIX = "sharefetch-transfer"
+
+# The one HTTP status the decode-pass fallback answers. A 403 names a folder
+# that exists and the account may not read, and
+# re-resolving a different path on that evidence would report the wrong problem
+# and spend a site probe and a drive list doing it.
+NOT_FOUND = 404
+
+
+def _exists(path: Path) -> bool:
+    """Whether ``path`` names an existing file, read through the long-path form.
+
+    Every filesystem call in the package goes through ``paths.long_path``, so a
+    destination deeper than 260 characters behaves the same as a shallow one.
+    """
+    try:
+        return os.path.isfile(long_path(path))  # noqa: PTH113
+    except OSError as exc:
+        logger.warning("could not test whether %s exists, treating it as absent: %s", path, exc)
+        return False
+
+
+class _EnumerationCancelledError(Exception):
+    """Raised inside the walk's progress callback to end enumeration early.
+
+    ``listing.walk`` is a lazy generator and an exception raised inside
+    ``on_progress`` propagates out of it, which is the only way to stop a walk
+    that is part way through paging a large folder. The exception never leaves
+    this module: :meth:`Engine._enumerate` catches it and the run ends without
+    touching the state file, so a stop during enumeration leaves the previous
+    run's records exactly as they were.
+    """
+
+
+def run(settings: Settings, sink: EventSink, **injected: Any) -> RunSummary:
+    """Execute one run and return its summary.
+
+    The convenience both front ends call. ``injected`` is forwarded to
+    :class:`Engine`, which is how a test supplies a client, a resolver, a
+    walker, a clock or a sleep without a socket.
+    """
+    return Engine(settings, sink, **injected).run()
+
+
+class Engine:
+    """One run: resolve, enumerate, reconcile, transfer, verify, report.
+
+    An instance drives a single run and is not reused. :meth:`pause`,
+    :meth:`resume` and :meth:`stop` are the only methods safe to call from
+    another thread, which is what a graphical front end does from its main
+    thread while :meth:`run` executes on a worker.
+    """
+
+    def __init__(
+        self,
+        settings: Settings,
+        sink: EventSink,
+        *,
+        tokens: Any | None = None,
+        client: GraphClient | None = None,
+        resolver: Callable[..., DriveTarget] = resolve_reference,
+        walker: Callable[..., Any] = walk,
+        fetcher: Callable[..., str] = fetch,
+        verifier: Callable[..., VerificationResult] = verify_file,
+        manifest_writer: Callable[[StateStore, Path], Path] = write_manifest,
+        disk_usage: Callable[[str], Any] = shutil.disk_usage,
+        sleep: Callable[[float], None] = time.sleep,
+    ) -> None:
+        """Build the engine and its two control events.
+
+        Every collaborator after ``sink`` has the production default and exists
+        so a test can drive the orchestration without a socket, without a
+        sign-in and without elapsing real time. ``tokens`` and ``client`` are
+        built inside :meth:`run` when they are not supplied, because
+        ``--verify-only`` must build neither.
+        """
+        self._settings = settings
+        self._sink = sink
+        self._dest = Path(settings.dest)
+        self._resolver = resolver
+        self._walker = walker
+        self._fetch = fetcher
+        self._verify = verifier
+        self._write_manifest = manifest_writer
+        self._disk_usage = disk_usage
+        self._sleep = sleep
+
+        self._tokens = tokens
+        self._client = client
+        self._pacer: Pacer | None = None
+        self._store: StateStore | None = None
+        self._drive_id: str | None = None
+        self._remote: dict[str, RemoteItem] = {}
+
+        self._pause = threading.Event()
+        self._stop = threading.Event()
+
+        # Whether the walk produced any output before it failed, and whether
+        # the decode-pass fallback has been spent. Only
+        # the fallback reads either, and the second bounds it to one retry.
+        self._enumeration_produced = False
+        self._decode_fallback_spent = False
+
+        # Run-local tallies. The remaining counts are read off the state store
+        # at summary time, so they cannot disagree with the item statuses.
+        self._transferred = 0
+        self._bytes_transferred = 0
+        self._enumeration_skipped = 0
+        self._unmappable = 0
+        self._hash_comparisons = 0
+        self._hash_matches = 0
+        self._hash_only_failures = 0
+
+    # ------------------------------------------------------------------
+    # Control, called from another thread
+    # ------------------------------------------------------------------
+
+    def pause(self) -> None:
+        """Suspend the queue at the next chunk boundary and flush state."""
+        self._pause.set()
+        logger.info("pause requested")
+
+    def resume(self) -> None:
+        """Release a pause. A paused file continues by range on its next pass."""
+        self._pause.clear()
+        logger.info("resume requested")
+
+    def stop(self) -> None:
+        """Finish the files in flight, stop queueing new work and end the run.
+
+        A stop clears any pause, because a paused engine would otherwise sit in
+        its wait loop rather than draining and returning.
+        """
+        self._stop.set()
+        self._pause.clear()
+        logger.info("stop requested")
+
+    # ------------------------------------------------------------------
+    # The run
+    # ------------------------------------------------------------------
+
+    def run(self) -> RunSummary:
+        """Execute the run and return its summary.
+
+        Raises every fatal error class unchanged:
+        ``ValidationError`` for a bad URL, a bad destination or a free-space
+        shortfall, ``AuthError`` for a refused sign-in, ``ResolveError`` for a
+        site, library or folder that does not resolve, ``EnumerationError`` for
+        a listing that cannot be read, and ``StateError`` for a state file that
+        cannot be written. A per-item ``TransferError`` or ``VerificationError``
+        is recorded against its item by the transfer layer and the queue
+        continues, so neither ever reaches this method.
+        """
+        self._make_destination()
+        if self._settings.verify_only:
+            return self._run_verify_only()
+        return self._run_transfer()
+
+    def _run_verify_only(self) -> RunSummary:
+        """Run the verification tree pass alone, with no network and no token."""
+        logger.info("verify-only run over %s, no network call is made", self._dest)
+        store = StateStore.load(self._dest)
+        if store is None:
+            raise ValidationError(
+                f"--verify-only needs the state file {self._dest / STATE_FILENAME} to know each "
+                f"file's declared size and hash, and no readable state file is present; run "
+                f"without --verify-only first"
+            )
+        self._store = store
+        self._verify_tree()
+        self._apply_hash_safeguard()
+        store.flush(force=True)
+        return self._finish(self._write_the_manifest())
+
+    def _run_transfer(self) -> RunSummary:
+        """Run the full sequence: resolve, enumerate, reconcile, transfer, verify."""
+        reference = parse_url(self._settings.url)
+        self._open_connection()
+        target = self._resolver(reference, self._client)
+        self._announce(target)
+
+        store = StateStore.load(self._dest) or StateStore(self._dest)
+        self._store = store
+
+        target, items = self._enumerate_addressed_folder(reference, target)
+        if items is None:
+            logger.info("the run was stopped during enumeration, the state file is untouched")
+            return self._stopped_during_enumeration_summary()
+
+        # Set from the target that was actually listed, which the decode-pass
+        # fallback can replace with a second resolution.
+        self._drive_id = target.drive_id
+        store.replace_enumeration(self._enumeration_header(target), items)
+        counts = store.reconcile(restart=self._settings.restart)
+        self._sink.emit(Reconciled(counts=dict(counts)))
+
+        if self._settings.dry_run:
+            logger.info("dry run: %d item(s) reconciled and no content transferred", len(items))
+            store.flush(force=True)
+            return self._finish(None)
+
+        self._check_free_space(store.remaining_bytes())
+        self._drain_queue()
+        if not self._stop.is_set():
+            self._verify_tree()
+        self._apply_hash_safeguard()
+        store.flush(force=True)
+        return self._finish(self._write_the_manifest())
+
+    # ------------------------------------------------------------------
+    # Setup
+    # ------------------------------------------------------------------
+
+    def _make_destination(self) -> None:
+        """Create the destination directory, which every later stage writes into."""
+        try:
+            os.makedirs(long_path(self._dest), exist_ok=True)  # noqa: PTH103
+        except OSError as exc:
+            raise ValidationError(
+                f"the destination directory {self._dest} could not be created: {exc}"
+            ) from exc
+
+    def _announce(self, target: DriveTarget) -> None:
+        """Emit ``Resolved`` for the target the run is about to enumerate.
+
+        Called a second time where the decode-pass fallback re-resolved, so the
+        folder a front end shows is the one that was actually listed. Both
+        front ends replace what they hold: the command line writes a second log
+        line and the window resets its source label.
+        """
+        self._sink.emit(
+            Resolved(
+                site_web_url=target.site_web_url,
+                drive_name=target.drive_name,
+                folder_path=target.folder_path,
+                drive_id=target.drive_id,
+            )
+        )
+        logger.info(
+            "resolved %s to the %s library, folder %r",
+            self._settings.url,
+            target.drive_name,
+            target.folder_path,
+        )
+
+    def _open_connection(self) -> None:
+        """Build the one pacer, token provider and client the run shares.
+
+        Exactly one :class:`~sharefetch.pacing.Pacer` exists per run and it is
+        handed to both the client and every transfer. A second one would let
+        two workers each spend the configured inter-request delay independently
+        and double the rate the service sees.
+        """
+        settings = self._settings
+        self._pacer = Pacer(settings.delay, settings.limit_rate_kbps)
+        if self._client is not None:
+            return
+        if self._tokens is None:
+            self._tokens = TokenProvider(
+                settings.client_id,
+                settings.tenant,
+                self._sink,
+                reauth=settings.reauth,
+            )
+        self._client = GraphClient(
+            self._tokens,
+            self._pacer,
+            settings.connections,
+            self._sink,
+        )
+
+    # ------------------------------------------------------------------
+    # Enumeration
+    # ------------------------------------------------------------------
+
+    def _enumerate_addressed_folder(
+        self, reference: SourceRef, target: DriveTarget
+    ) -> tuple[DriveTarget, dict[str, ItemState] | None]:
+        """Enumerate the tree, retrying once one decode pass short where 4.5 allows.
+
+        Returns the target that was listed and its items, with ``None`` items
+        where a stop ended the walk.
+
+        Normalisation rule 5 decodes the ``id`` parameter until the value stops
+        changing, which is right for the doubly encoded value a Teams link
+        carries and wrong for a folder genuinely named ``A%20B``: that arrives
+        as ``A%2520B`` and stabilises at ``A B``. A literal percent sign and an
+        extra encoding pass are indistinguishable by inspection, so the service
+        is the only arbiter. :func:`sharefetch.resolve.resolve` derives the
+        folder path without asking whether the folder exists, so the mistake
+        first shows as a ``404`` when enumeration requests that folder's
+        children, and that is where it is answered.
+        """
+        try:
+            return target, self._enumerate(target)
+        except EnumerationError as first:
+            decode_passes = self._decode_fallback_ceiling(reference, first)
+            if decode_passes is None:
+                raise
+            return self._retry_one_decode_pass_short(reference, target, first, decode_passes)
+
+    def _decode_fallback_ceiling(
+        self, reference: SourceRef, failure: EnumerationError
+    ) -> int | None:
+        """Return the decode-pass ceiling to retry at, or ``None`` for no retry.
+
+        The retry is permitted under four conditions and no others. Each is
+        tested here, and each logs at DEBUG where it is the one that declined,
+        so a run that did not retry says why.
+
+        The ceiling comes from :func:`sharefetch.resolve.decode_pass_ceiling`,
+        which reports the passes this URL's ``id`` parameter actually consumed.
+        Subtracting one from ``config.MAX_DECODE_ITERATIONS`` instead would
+        change nothing for a link that stabilised after three passes, and the
+        retry would silently repeat the first attempt.
+        """
+        if self._decode_fallback_spent:
+            logger.debug("the decode-pass fallback has already been spent on this run")
+            return None
+        if not isinstance(reference, SitePathRef):
+            logger.debug(
+                "the source is a sharing link, whose path was never doubly decoded, so it "
+                "carries no decode pass to drop"
+            )
+            return None
+        if self._enumeration_produced:
+            logger.debug(
+                "the walk had already produced output when it failed, so the failure lies "
+                "below the addressed folder and re-resolving would answer the wrong fault"
+            )
+            return None
+        status = self._failure_status(failure)
+        if status != NOT_FOUND:
+            logger.debug(
+                "the enumeration failure carried status %s and not %d, so the addressed "
+                "folder is not missing and no retry is made",
+                status,
+                NOT_FOUND,
+            )
+            return None
+        ceiling = decode_pass_ceiling(reference)
+        if ceiling < 2:
+            logger.debug(
+                "the id parameter consumed %d decode pass(es), so no lower ceiling exists "
+                "to retry at",
+                ceiling,
+            )
+            return None
+        self._decode_fallback_spent = True
+        return ceiling - 1
+
+    def _retry_one_decode_pass_short(
+        self,
+        reference: SourceRef,
+        target: DriveTarget,
+        first: EnumerationError,
+        decode_passes: int,
+    ) -> tuple[DriveTarget, dict[str, ItemState] | None]:
+        """Re-resolve at ``decode_passes`` and enumerate the folder that names.
+
+        The one retry permitted. A second failure, whether the
+        retry could not be resolved at all or resolved to a folder that is also
+        missing, raises a message naming both folders tried and carrying both
+        refusals: an operator reading it has to see which two names the run
+        actually looked for. Stepping the ceiling down further is not done,
+        because each rung costs a site probe and a drive list and no evidence
+        points at a name two passes short.
+        """
+        status = self._failure_status(first)
+        try:
+            retried = self._resolver(reference, self._client, decode_passes=decode_passes)
+        except AuthError:
+            raise
+        except SharefetchError as exc:
+            raise EnumerationError(
+                f"the addressed folder {target.folder_path!r} was not found, and the one retry "
+                f"at {decode_passes} decode pass(es) could not be resolved at all: {exc}. The "
+                f"first failure was: {first}",
+                status=status,
+            ) from first
+
+        logger.info(
+            "the addressed folder %r was not found; the id parameter of the source URL "
+            "consumed %d decode pass(es), so the run retries once at %d, which addresses %r "
+            "instead",
+            target.folder_path,
+            decode_passes + 1,
+            decode_passes,
+            retried.folder_path,
+        )
+
+        # The first attempt produced nothing, or the retry would have been
+        # declined, so all three are already empty. Clearing them holds that by
+        # construction rather than by the caller's reasoning: _enumerate builds
+        # its own item map and adds to the remote map this instance shares.
+        self._remote.clear()
+        self._enumeration_skipped = 0
+        self._unmappable = 0
+
+        try:
+            items = self._enumerate(retried)
+        except EnumerationError as second:
+            raise EnumerationError(
+                f"the addressed folder was not found at {target.folder_path!r}, and the one "
+                f"retry one decode pass short addressed {retried.folder_path!r}, which was not "
+                f"found either. The first failure was: {first}. The retry failed with: {second}",
+                status=status,
+            ) from first
+
+        logger.info(
+            "%r resolved one decode pass short of the ceiling and the run continues against it",
+            retried.folder_path,
+        )
+        self._announce(retried)
+        return retried, items
+
+    def _failure_status(self, failure: EnumerationError) -> int | None:
+        """Return the HTTP status behind an enumeration failure.
+
+        :func:`sharefetch.listing.walk` reports a refused addressed folder as an
+        ``EnumerationError`` carrying the refusal's text and not its status, and
+        chains the original refusal as the cause, so the status is read off the
+        cause. The HTTP layer also raises ``EnumerationError`` directly for a
+        body it cannot read, and those carry the status themselves.
+        """
+        status = getattr(failure, "status", None)
+        if status is not None:
+            return status
+        return getattr(failure.__cause__, "status", None)
+
+    def _enumerate(self, target: DriveTarget) -> dict[str, ItemState] | None:
+        """Walk the tree and map each item onto a local path.
+
+        Returns the enumerated items keyed on the drive-relative path, or
+        ``None`` where a stop ended the walk before it finished. A partial walk
+        is never installed, because
+        :meth:`~sharefetch.state.StateStore.replace_enumeration` drops every
+        path the walk did not return and a truncated walk would therefore
+        discard the records of files it simply never reached.
+        """
+        settings = self._settings
+        items: dict[str, ItemState] = {}
+        taken: set[str] = set()
+        wanted = target.single_file_name
+        # Reset per attempt, because the decode-pass fallback reads it after a
+        # failure to tell the addressed folder apart from a folder deeper in.
+        self._enumeration_produced = False
+
+        try:
+            for remote in self._walker(
+                target,
+                self._client,
+                include=settings.include,
+                exclude=settings.exclude,
+                max_depth=settings.max_depth,
+                on_progress=self._on_enumeration_progress,
+            ):
+                self._enumeration_produced = True
+                if wanted is not None and remote.name != wanted:
+                    logger.debug(
+                        "%s is not the single file the sharing link addressed", remote.drive_path
+                    )
+                    continue
+                state = self._map_item(remote, taken)
+                if state is None:
+                    continue
+                items[remote.drive_path] = state
+                self._remote[remote.drive_path] = remote
+        except _EnumerationCancelledError:
+            return None
+
+        logger.info("enumeration produced %d transferable item(s)", len(items))
+        return items
+
+    def _map_item(self, remote: RemoteItem, taken: set[str]) -> ItemState | None:
+        """Map one enumerated item onto a local path, or report it unmappable.
+
+        A path whose component survives sanitisation longer than Windows
+        accepts is recorded as failed with the reason ``path_too_long``. The
+        item has no local path, so it has nowhere in the state file to be
+        recorded: it is counted failed for the run and
+        reported on its own ``FileFinished`` event.
+        """
+        try:
+            mapped = map_drive_path(remote.drive_path, taken)
+        except ValidationError as exc:
+            self._unmappable += 1
+            message = str(exc)
+            logger.error("%s cannot be given a local path: %s", remote.drive_path, message)
+            self._sink.emit(
+                FileFinished(
+                    drive_path=remote.drive_path,
+                    status=STATUS_FAILED,
+                    verification=None,
+                    error=f"{REASON_PATH_TOO_LONG}: {message}",
+                )
+            )
+            return None
+
+        taken.add(str(mapped.local_path).lower())
+        return ItemState(
+            item_id=remote.item_id,
+            size=remote.size,
+            etag=remote.etag,
+            ctag=remote.ctag,
+            mime_type=remote.mime_type,
+            quick_xor_hash=remote.quick_xor_hash,
+            local_path=str(mapped.local_path),
+            sanitised=mapped.sanitised,
+            original_name=mapped.original_name,
+        )
+
+    def _on_enumeration_progress(self, event: Any) -> None:
+        """Forward a walk event to the sink, and end the walk on a stop.
+
+        Raising here is the documented way to stop ``listing.walk`` part way
+        through, because it is a lazy generator driven by this engine's own
+        loop.
+
+        Any event at all means the addressed folder's first page was read, so
+        a later failure lies below it. The decode-pass fallback reads that.
+        """
+        self._enumeration_produced = True
+        if self._stop.is_set():
+            raise _EnumerationCancelledError(
+                "the run was stopped while the tree was being enumerated"
+            )
+        if isinstance(event, SkippedItem):
+            self._enumeration_skipped += 1
+            logger.warning("%s was skipped during enumeration: %s", event.drive_path, event.reason)
+            self._sink.emit(
+                FileFinished(
+                    drive_path=event.drive_path,
+                    status=STATUS_SKIPPED,
+                    verification=None,
+                    error=event.reason,
+                )
+            )
+            return
+        if isinstance(event, EnumerationComplete):
+            logger.info(
+                "enumeration complete: %d file(s), %d byte(s), %d folder(s)",
+                event.files,
+                event.total_bytes,
+                event.folders,
+            )
+        self._sink.emit(event)
+
+    def _enumeration_header(self, target: DriveTarget) -> dict[str, Any]:
+        """The header fields the store accepts from this run's enumeration."""
+        return {
+            "source_url": self._settings.url,
+            "drive_id": target.drive_id,
+            "drive_name": target.drive_name,
+            "root_folder_path": target.folder_path,
+            # The store fills this with its own wall clock, so the recorded
+            # instant is the one the enumeration actually finished at.
+            "enumerated_at": None,
+        }
+
+    # ------------------------------------------------------------------
+    # Free space
+    # ------------------------------------------------------------------
+
+    def _check_free_space(self, remaining: int) -> None:
+        """Compare free space against the queue plus its margin.
+
+        Raises ``ValidationError`` naming both figures in bytes and in MiB.
+        ``--ignore-free-space`` skips the check. Checking before the first
+        transfer is preferred because exhaustion part way through produces a
+        truncated file that reconciliation then has to interpret.
+        """
+        if self._settings.ignore_free_space:
+            logger.info("the free-space check is skipped because --ignore-free-space was given")
+            return
+        if remaining <= 0:
+            logger.info("nothing remains to transfer, so no free space is required")
+            return
+
+        required = int(remaining * (1 + FREE_SPACE_MARGIN))
+        try:
+            free = int(self._disk_usage(long_path(self._dest)).free)
+        except OSError as exc:
+            logger.warning(
+                "free space on the volume holding %s could not be read, the check is skipped: %s",
+                self._dest,
+                exc,
+            )
+            return
+
+        if free < required:
+            raise ValidationError(
+                f"the queue needs {required} bytes ({required / BYTES_PER_MIB:.1f} MiB), which is "
+                f"{remaining} bytes of content plus the {FREE_SPACE_MARGIN:.0%} margin, and the "
+                f"volume holding {self._dest} has {free} bytes ({free / BYTES_PER_MIB:.1f} MiB) "
+                f"free; pass --ignore-free-space to proceed anyway"
+            )
+        logger.info(
+            "free space check passed: %d byte(s) required, %d byte(s) available", required, free
+        )
+
+    # ------------------------------------------------------------------
+    # The transfer queue
+    # ------------------------------------------------------------------
+
+    def _drain_queue(self) -> None:
+        """Transfer every queued item on a pool of ``settings.connections`` workers.
+
+        A worker returning ``"paused"`` puts its item back at the head of the
+        queue, so the file it left partly written is the first one resumed. A
+        stop leaves the remaining queue untouched and lets the files already in
+        flight run to the end of their bodies.
+        """
+        store = self._require_store()
+        queue = deque(drive_path for drive_path, _ in store.pending())
+        if not queue:
+            logger.info("nothing is queued for transfer")
+            return
+
+        workers = self._settings.connections
+        logger.info("transferring %d item(s) on %d worker(s)", len(queue), workers)
+        in_flight: dict[Future[tuple[str, int]], str] = {}
+        try:
+            with ThreadPoolExecutor(
+                max_workers=workers, thread_name_prefix=WORKER_NAME_PREFIX
+            ) as pool:
+                while queue or in_flight:
+                    while (
+                        queue
+                        and len(in_flight) < workers
+                        and not self._stop.is_set()
+                        and not self._pause.is_set()
+                    ):
+                        drive_path = queue.popleft()
+                        in_flight[pool.submit(self._transfer_one, drive_path)] = drive_path
+
+                    if not in_flight:
+                        if self._stop.is_set():
+                            logger.info(
+                                "the run was stopped with %d item(s) still queued", len(queue)
+                            )
+                            break
+                        if self._pause.is_set():
+                            store.flush(force=True)
+                            self._wait_while_paused()
+                            continue
+                        break
+
+                    done, _ = wait(list(in_flight), return_when=FIRST_COMPLETED)
+                    for future in done:
+                        finished = in_flight.pop(future)
+                        outcome, written = future.result()
+                        if outcome == STATUS_PAUSED:
+                            queue.appendleft(finished)
+                            logger.info("%s was paused and returns to the queue", finished)
+                            continue
+                        self._bytes_transferred += written
+                        if outcome == STATUS_COMPLETE:
+                            self._transferred += 1
+                        self._note_recorded_hash_outcome(finished)
+        finally:
+            store.flush(force=True)
+
+    def _wait_while_paused(self) -> None:
+        """Block the engine thread until the pause is released or a stop arrives."""
+        logger.info("the queue is paused and state has been flushed")
+        while self._pause.is_set() and not self._stop.is_set():
+            self._sleep(PAUSE_POLL_SECONDS)
+
+    def _transfer_one(self, drive_path: str) -> tuple[str, int]:
+        """Fetch one item and return its outcome and the bytes this run wrote.
+
+        Runs on a worker thread. ``transfer.fetch`` records the item's outcome
+        against the store before returning and never re-raises a per-item
+        ``TransferError``, so the returned string is everything the queue needs.
+        An ``AuthError`` is terminal for the whole run and propagates.
+        """
+        store = self._require_store()
+        record = store.all_items()[drive_path]
+        before = record.bytes_written
+        outcome = self._fetch(
+            self._remote[drive_path],
+            store.final_path(record),
+            self._client,
+            store,
+            self._pacer,
+            self._settings,
+            self._sink,
+            self._pause,
+            self._stop,
+            drive_id=self._drive_id,
+            sleep=self._sleep,
+        )
+        after = store.all_items()[drive_path].bytes_written
+        return outcome, max(after - before, 0)
+
+    # ------------------------------------------------------------------
+    # Verification over the whole tree
+    # ------------------------------------------------------------------
+
+    def _verify_tree(self) -> None:
+        """Re-run checks 1 to 4 over every file sitting at its final name.
+
+        A ``.part`` file is deliberately outside the pass: partial bytes are
+        not a file in the tree, and verifying one would
+        record a size mismatch against an item that is resuming correctly.
+        """
+        store = self._require_store()
+        checked = 0
+        for drive_path, item in sorted(store.all_items().items()):
+            final = store.final_path(item)
+            if not _exists(final):
+                continue
+            result = self._verify_one(final, drive_path, item)
+            if result is None:
+                continue
+            checked += 1
+            failed = result.status == VERIFICATION_FAILED
+            store.record(
+                drive_path,
+                status=STATUS_FAILED if failed else STATUS_COMPLETE,
+                verification=result.to_dict(),
+                last_error=f"verification failed: {result.reason}" if failed else None,
+            )
+            self._note_hash_outcome(item.quick_xor_hash, result.checks, result.reason)
+        logger.info("the end-of-run pass verified %d file(s) under %s", checked, self._dest)
+
+    def _verify_one(
+        self, path: Path, drive_path: str, item: ItemState
+    ) -> VerificationResult | None:
+        """Verify one file in the tree, explaining a hash mismatch in full.
+
+        Checks stop at the first failure, so a file failing check 2 leaves
+        checks 3 and 4 unrun and the safeguard with nothing to read. The file is
+        verified a second time with no hash to compare and that run's check list
+        replaces the truncated one, while the reported reason stays
+        ``hash_mismatch`` because check 2 fails first whatever the second run
+        finds. This mirrors what the transfer layer records for a file that
+        never reached its final name.
+        """
+        name = drive_path.rsplit("/", 1)[-1]
+        try:
+            result = self._verify(
+                path,
+                declared_size=item.size,
+                expected_hash=item.quick_xor_hash,
+                mime_type=item.mime_type,
+                name=name,
+                chunk_size=self._settings.chunk_bytes,
+            )
+        except (VerificationError, OSError) as exc:
+            logger.error("%s could not be verified and keeps its recorded status: %s", path, exc)
+            return None
+
+        if result.reason != REASON_HASH_MISMATCH:
+            return result
+
+        try:
+            without_hash = self._verify(
+                path,
+                declared_size=item.size,
+                expected_hash=None,
+                mime_type=item.mime_type,
+                name=name,
+                chunk_size=self._settings.chunk_bytes,
+            )
+        except (VerificationError, OSError) as exc:
+            logger.warning("%s could not be re-checked without its hash: %s", drive_path, exc)
+            return result
+
+        logger.info(
+            "%s failed the hash comparison while passing %s",
+            drive_path,
+            ", ".join(without_hash.checks) or "no other check",
+        )
+        return VerificationResult(
+            status=VERIFICATION_FAILED,
+            checks=without_hash.checks,
+            warnings=without_hash.warnings,
+            reason=REASON_HASH_MISMATCH,
+        )
+
+    # ------------------------------------------------------------------
+    # The hash implementation safeguard
+    # ------------------------------------------------------------------
+
+    def _note_recorded_hash_outcome(self, drive_path: str) -> None:
+        """Read the verdict the transfer layer recorded and tally it."""
+        item = self._require_store().all_items().get(drive_path)
+        if item is None or not isinstance(item.verification, dict):
+            return
+        checks = item.verification.get("checks") or ()
+        reason = item.verification.get("reason")
+        self._note_hash_outcome(item.quick_xor_hash, tuple(checks), reason)
+
+    def _note_hash_outcome(
+        self, expected_hash: str | None, checks: tuple[str, ...], reason: str | None
+    ) -> None:
+        """Count one file towards the safeguard, where it had a hash to compare.
+
+        A file whose result lists check 2 among the checks that passed is a
+        match. A file whose result names ``hash_mismatch`` while listing check 3
+        is a file that failed the hash alone: checks run in order and stop at
+        the first failure, so a passing check 3 means check 1 passed or was
+        skipped, and the reason names check 2 rather than check 4.
+        """
+        if not expected_hash:
+            return
+        if CHECK_CONTENT_HASH in checks:
+            self._hash_comparisons += 1
+            self._hash_matches += 1
+            return
+        if reason == REASON_HASH_MISMATCH:
+            self._hash_comparisons += 1
+            if CHECK_NOT_SUBSTITUTED in checks:
+                self._hash_only_failures += 1
+
+    def _apply_hash_safeguard(self) -> bool | None:
+        """Decide the safeguard's verdict and write it to the state header.
+
+        One match is evidence the implementation agrees with the service, and
+        the header records ``True``. Every file that had a hash to compare
+        failing check 2 while passing the others points at the implementation
+        in this build rather than at the library contents, and the header
+        records ``False``. A run with no hash to compare, or one whose hash
+        failures were mixed with failures of other checks, reaches no verdict
+        and leaves the header as it stands.
+        """
+        store = self._require_store()
+        if self._hash_comparisons == 0:
+            logger.info(
+                "no verified file carried a quickXorHash, so this run reaches no verdict on the "
+                "hash implementation"
+            )
+            return store.header().get("hash_algorithm_validated")
+
+        if self._hash_matches:
+            logger.info(
+                "%d of %d file(s) matched the quickXorHash the source published",
+                self._hash_matches,
+                self._hash_comparisons,
+            )
+            store.set_hash_algorithm_validated(True)
+            return True
+
+        if self._hash_only_failures == self._hash_comparisons:
+            logger.error(
+                "all %d file(s) that carried a quickXorHash failed the hash comparison while "
+                "passing every other check; this points at the quickXorHash implementation in "
+                "this build rather than at the contents of the library, and the files are left "
+                "on disk for inspection",
+                self._hash_comparisons,
+            )
+            store.set_hash_algorithm_validated(False)
+            return False
+
+        logger.warning(
+            "none of the %d file(s) carrying a quickXorHash matched it, and %d of them also "
+            "failed another check, so no verdict on the hash implementation is recorded",
+            self._hash_comparisons,
+            self._hash_comparisons - self._hash_only_failures,
+        )
+        return store.header().get("hash_algorithm_validated")
+
+    # ------------------------------------------------------------------
+    # Reporting
+    # ------------------------------------------------------------------
+
+    def _write_the_manifest(self) -> Path | None:
+        """Write ``manifest.csv`` and return its path, or ``None`` on a failure.
+
+        A manifest that cannot be written is reported at ERROR and does not
+        abort the run. The tree and the state file are already on disk, and
+        a partly failing operation reports precisely what succeeded, and
+        discarding the summary of completed transfers
+        because the report file could not be written would do the opposite.
+        """
+        try:
+            return self._write_manifest(self._require_store(), self._dest)
+        except ManifestError as exc:
+            logger.error("the manifest could not be written and the run continues: %s", exc)
+            return None
+
+    def _finish(self, manifest_path: Path | None) -> RunSummary:
+        """Build the summary from the state store, emit ``RunFinished`` and return it.
+
+        Every count but ``transferred`` and ``bytes_transferred`` is read off
+        the store at this moment, so no count can disagree with the item
+        statuses the state file and the manifest carry.
+        """
+        store = self._require_store()
+        items = store.all_items()
+        complete = sum(1 for item in items.values() if item.status == STATUS_COMPLETE)
+        failed = sum(1 for item in items.values() if item.status == STATUS_FAILED)
+        skipped = sum(1 for item in items.values() if item.status == STATUS_SKIPPED)
+        verified = sum(
+            1
+            for item in items.values()
+            if isinstance(item.verification, dict)
+            and item.verification.get("status") != VERIFICATION_FAILED
+        )
+
+        summary = RunSummary(
+            transferred=self._transferred,
+            skipped=skipped + self._enumeration_skipped,
+            failed=failed + self._unmappable,
+            already_present=max(complete - self._transferred, 0),
+            verified=verified,
+            bytes_transferred=self._bytes_transferred,
+            manifest_path=manifest_path,
+            hash_algorithm_validated=store.header().get("hash_algorithm_validated"),
+        )
+        logger.info(
+            "run finished: %d transferred, %d already present, %d verified, %d skipped, %d failed",
+            summary.transferred,
+            summary.already_present,
+            summary.verified,
+            summary.skipped,
+            summary.failed,
+        )
+        self._sink.emit(RunFinished(summary=summary, manifest_path=manifest_path))
+        return summary
+
+    def _stopped_during_enumeration_summary(self) -> RunSummary:
+        """Report a run stopped before any enumeration was installed."""
+        summary = RunSummary(
+            transferred=0,
+            skipped=self._enumeration_skipped,
+            failed=self._unmappable,
+            already_present=0,
+            verified=0,
+            bytes_transferred=0,
+            manifest_path=None,
+            hash_algorithm_validated=None,
+        )
+        self._sink.emit(RunFinished(summary=summary, manifest_path=None))
+        return summary
+
+    def _require_store(self) -> StateStore:
+        """Return the store, which every stage after enumeration depends on."""
+        if self._store is None:
+            raise ValidationError(
+                "the run reached a stage that needs the state store before one was opened"
+            )
+        return self._store