fix(reflink): retry EAGAIN clones

[s0up4200]

Summary

• retry reflink clone on EAGAIN with short backoff
• add linux test coverage for retry behavior

Testing

• go test ./pkg/reflinktree

Refs #1352

Summary by CodeRabbit

• New Features

  • Improved Linux file-clone reliability with automatic retries and exponential backoff for transient errors.
  • Added transparent fallback to an alternative clone method when primary cloning ultimately fails.

• Tests

  • Added Linux tests covering retry behavior, backoff timing, exhausted retries, and fallback-to-clone-range scenarios.

[coderabbitai]

Walkthrough

Adds retry-with-backoff for FICLONE on Linux, falls back to FICLONERANGE when appropriate, and replaces direct unix.Ioctl calls with package-level wrapper variables (and a sleep wrapper) to enable mocking; all new symbols are unexported.

Changes

Cohort / File(s)	Summary
Retry & ioctl wrappers pkg/reflinktree/reflink_linux.go	Added retry loop for FICLONE with exponential backoff (reflinkCloneRetryAttempts, reflinkCloneRetryBaseDelay); introduced package-level wrappers ioctlFileClone, ioctlFileCloneRange, and sleepForRetry; added fallback to FICLONERANGE when clone-range-eligible errors occur; adjusted error wrapping.
Linux tests for retry & fallback pkg/reflinktree/reflink_linux_test.go	New Linux-only tests: verify retries on EAGAIN with backoff, verify behavior when retries are exhausted, and verify fallback to FICLONERANGE; tests stub ioctl/sleep wrappers and assert attempt/sleep counts and outcomes.

Sequence Diagram

sequenceDiagram
    participant Caller
    participant CloneLogic as "reflink clone logic"
    participant Ioctl as "ioctlFileClone"
    participant Sleep as "sleepForRetry"
    participant CloneRange as "ioctlFileCloneRange"

    Caller->>CloneLogic: cloneFile(src, dst)
    alt Attempt FICLONE
        CloneLogic->>Ioctl: ioctlFileClone(srcFd, dstFd)
        alt Success
            Ioctl-->>CloneLogic: OK
            CloneLogic-->>Caller: Success
        else EAGAIN
            Ioctl-->>CloneLogic: EAGAIN
            CloneLogic->>Sleep: sleepForRetry(delay)
            Sleep-->>CloneLogic: resumed
            CloneLogic->>Ioctl: retry ioctlFileClone(...)
        else Clone-Range-Eligible Error
            Ioctl-->>CloneLogic: error (eligible)
            CloneLogic->>CloneRange: ioctlFileCloneRange(srcFd, dstFd)
            alt CloneRange Success
                CloneRange-->>CloneLogic: OK
                CloneLogic-->>Caller: Success
            else CloneRange Failure
                CloneRange-->>CloneLogic: error
                CloneLogic-->>Caller: Error (wrapped)
            end
        end
    end

Loading

Estimated code review effort

🎯 3 (Moderate) | ⏱️ ~20 minutes

Possibly related PRs

• fix(reflinktree): fall back to FICLONERANGE when FICLONE unsupported #1221: Also adds fallback to FICLONERANGE when FICLONE is unsupported or fails.

Suggested labels

codex

Poem

🐰 I nudge the clone, then wait and try again,
A hop, a pause, a tiny backoff then—
If FICLONE balks, I gently re-arrange,
And wiggle to FICLONERANGE for change. 🥕

🚥 Pre-merge checks | ✅ 2 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 20.00% which is insufficient. The required threshold is 80.00%.	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (2 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title 'fix(reflink): retry EAGAIN clones' directly and clearly summarizes the main change—adding retry logic for EAGAIN errors in reflink clone operations, which aligns with the primary objective and implementation.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing touches

• 📝 Generate docstrings

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Post copyable unit tests in a comment
• Commit unit tests in branch fix/reflink-eagain-retry

---

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[coderabbitai]

Actionable comments posted: 1

🤖 Fix all issues with AI agents

In `@pkg/reflinktree/reflink_linux_test.go`:
- Around line 21-23: The test writes a temp file using os.WriteFile with mode
0o644 which fails gosec G306; change the file permission in the os.WriteFile
call in reflink_linux_test.go (the line that writes to srcPath in the test) to
0o600 so the file is created with owner-only read/write permissions and the
pipeline will pass.

🧹 Nitpick comments (2)

pkg/reflinktree/reflink_linux.go (2)

114-128: Redundant nil check on cloneErr.

At line 114, cloneErr is guaranteed to be non-nil when this block is reached (the loop only exits via break at line 111 when cloneErr != nil and it's not EAGAIN). The outer if cloneErr != nil check is redundant but harmless.

♻️ Proposed simplification

-	if cloneErr != nil {
-		if shouldTryCloneRange(cloneErr) {
-			cloneRange := unix.FileCloneRange{
-				Src_fd:      int64(srcFd),
-				Src_offset:  0,
-				Src_length:  0,
-				Dest_offset: 0,
-			}
-			if rangeErr := ioctlFileCloneRange(dstFd, &cloneRange); rangeErr != nil {
-				return fmt.Errorf("ioctl FICLONERANGE: %w", rangeErr)
-			}
-			return nil
-		}
-		return fmt.Errorf("ioctl FICLONE: %w", cloneErr)
+	if shouldTryCloneRange(cloneErr) {
+		cloneRange := unix.FileCloneRange{
+			Src_fd:      int64(srcFd),
+			Src_offset:  0,
+			Src_length:  0,
+			Dest_offset: 0,
+		}
+		if rangeErr := ioctlFileCloneRange(dstFd, &cloneRange); rangeErr != nil {
+			return fmt.Errorf("ioctl FICLONERANGE: %w", rangeErr)
+		}
+		return nil
 	}
+	return fmt.Errorf("ioctl FICLONE: %w", cloneErr)
 
-	return nil

Note: After this change, the final return nil at line 130 becomes unreachable and should also be removed.

---

98-112: Modernize the for loop using range over int.

This project uses Go 1.25, which fully supports the range-over-int syntax (available since Go 1.22). The proposed modernization is valid and maintains identical semantics.

♻️ Proposed fix

-	for attempt := 0; attempt < reflinkCloneRetryAttempts; attempt++ {
+	for attempt := range reflinkCloneRetryAttempts {