transfer/indexer: say which file blocks a download and what to do (#200)

[0g-peterzhb]

Fixes #200. Supersedes #199, which took the other approach and was dropped.

The problem

checkFileExistence reported both outcomes anonymously, so the user saw:

Failed to download file: Failed to check file existence: File already exists

No path anywhere. These fire for two very different files.

For the caller's own destination it's merely terse — they passed --file out.dat and can guess.

For a fragment temp file it misleads. Fragments download to <root>.temp in the process working directory. If one survives an attempt — the copy into the output failed (a full disk, which I hit myself today), os.Remove failed, the process was killed mid-iteration — every later attempt reports File already exists for a file the caller never created. So they inspect the out.dat they asked for, find nothing wrong with it, delete it, retry, and get the identical error, with nothing pointing at the real obstacle.

Change

Name the file in both errors, and at the six fragment sites say what to do:

a previous attempt left this fragment file behind; remove it and retry: 0x1111.temp: File already exists

The hint deliberately does not repeat the path — checkFileExistence supplies it — and there's an assertion that it appears exactly once.

The sentence lives in one place, FragmentLeftBehindError, rather than being copied at each of the six fragment sites. It's exported because indexer.Client runs the same loops; the alternative was two unexported copies. Sharing the constructor rather than a bare string constant means the wrapping can't drift either.

The guidance is fragment-specific on purpose: for the caller's own destination, "remove it" would be bad advice, since they may well want to keep the file they already have.

ErrFileAlreadyExists stays wrapped, not replaced, so the errors.Is checks that depend on it keep matching — download_dir.go relies on that in three places. Asserted, not assumed.

Why not reuse the leftover instead

That was #199, and I closed it. Reuse means trusting checkFileExistence as a completeness signal, and it compares only the Merkle root, never the size. Because the root covers zero-padded chunks, a file short by less than a chunk of trailing zeros has the same root:

 16 bytes -> 0xdb4eca15…be3dc
256 bytes -> 0xdb4eca15…be3dc
same root for different sizes? true

The fragment path never validates the assembled output, so a short temp would silently produce a short result. Telling the caller to remove the file requires no such trust.

Testing

Test
TestCheckFileExistence_NamesTheFile	both errors carry the path; the matching case still satisfies errors.Is(err, ErrFileAlreadyExists); a different hash stays a distinct, fatal error
TestCheckFileExistence_MissingFileIsNotAnError	an absent path is not an error
..._LeftoverFragmentTellsUserToRemoveIt	the fragment failure names 0x1111.temp, says "remove it and retry", and mentions the path exactly once

The last test asserts the literal words rather than referencing FragmentLeftBehindError. A test that reads the same constant it verifies would pass for any message, including nonsense — the point is that the user sees actionable wording, so that belongs as a literal in the test.

RED on main: "the message must say which file", twice. go build, go vet, gofmt and go test -count=1 ./... (14 packages) all pass.

---

This change is