transfer: name the file in the existence errors (#200)

checkFileExistence reported both outcomes without saying which file it meant, so what
reached the user was "Failed to download file: Failed to check file existence: File
already exists" with no path at all.

For the caller's own destination that is merely terse. For a fragment temp file it
misleads: fragments are downloaded to <root>.temp in the process working directory, and
if one survives an attempt - the copy into the output failed, os.Remove failed, the
process was killed mid-iteration - every later attempt reports "File already exists"
for a file the caller never created. They inspect the output file they asked for, find
nothing wrong, delete it, retry, and get the same error, with nothing indicating what
is actually blocking them.

Include the path in both. ErrFileAlreadyExists is wrapped rather than replaced so the
errors.Is checks that depend on it keep matching - download_dir relies on it in three
places, and the fragment loops in #199 will too.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>

Author: 0g-peterzhb

transfer/downloader.go

@@ -288,11 +288,16 @@ func checkFileExistence(filename string, hash common.Hash) error {
 		return errors.WithMessage(err, "Failed to create file merkle tree")
 	}
 
+	// Name the file. Both of these are reported for a fragment's temp file as well as for
+	// the caller's own destination, and without the path the message sends the reader to
+	// the wrong place: they see "File already exists", inspect the output file they asked
+	// for, find nothing wrong with it, and never learn the obstacle is a <root>.temp they
+	// did not create.
 	if tree.Root() == hash {
-		return ErrFileAlreadyExists
+		return errors.WithMessagef(ErrFileAlreadyExists, "%v", filename)
 	}
 
-	return errors.New("File already exists with different hash")
+	return errors.Errorf("File already exists with different hash: %v", filename)
 }
 
 func (downloader *Downloader) downloadFile(ctx context.Context, filename string, root common.Hash, info *node.FileInfo, withProof bool) error {

transfer/downloader_existence_test.go

@@ -0,0 +1,41 @@
+package transfer
+
+import (
+	"os"
+	"path/filepath"
+	"testing"
+
+	"github.com/0gfoundation/0g-storage-client/core"
+	"github.com/ethereum/go-ethereum/common"
+	"github.com/stretchr/testify/assert"
+	"github.com/stretchr/testify/require"
+)
+
+// Both existence errors are reported for a fragment's temp file as well as for the
+// caller's own destination. Without the path, someone hitting the fragment case reads
+// "File already exists", inspects the output file they asked for, finds nothing wrong
+// with it, and never learns the obstacle is a <root>.temp they never created.
+func TestCheckFileExistence_NamesTheFile(t *testing.T) {
+	path := filepath.Join(t.TempDir(), "0x1111.temp")
+	require.NoError(t, os.WriteFile(path, []byte("a completed fragment"), 0644))
+
+	root, err := core.MerkleRoot(path)
+	require.NoError(t, err)
+
+	matching := checkFileExistence(path, root)
+	require.Error(t, matching)
+	assert.ErrorIs(t, matching, ErrFileAlreadyExists,
+		"download_dir matches on this sentinel, so it must stay wrapped rather than replaced")
+	assert.Contains(t, matching.Error(), path, "the message must say which file")
+
+	mismatched := checkFileExistence(path, common.HexToHash("0xdead"))
+	require.Error(t, mismatched)
+	assert.NotErrorIs(t, mismatched, ErrFileAlreadyExists, "a different hash is a distinct, fatal error")
+	assert.Contains(t, mismatched.Error(), "different hash")
+	assert.Contains(t, mismatched.Error(), path, "the message must say which file")
+}
+
+// A path that does not exist is not an error at all.
+func TestCheckFileExistence_MissingFileIsNotAnError(t *testing.T) {
+	assert.NoError(t, checkFileExistence(filepath.Join(t.TempDir(), "absent.dat"), common.HexToHash("0xdead")))
+}