fix(uffd): treat UFFDIO_COPY EAGAIN and partial copies as soft, let kernel redeliver

Folds audit findings #1 and #7 into one commit since they share the same
error arm in faultPage. The kernel surfaces concurrent mm churn (e.g.
balloon-driven madvise(MADV_DONTNEED), mremap, fork against the same mm)
through UFFDIO_COPY in two distinct ways: as an EAGAIN errno from the
syscall, or — once UFFD_FEATURE_EVENT_REMOVE is enabled — through the
partial-copy convention where the syscall returns 0 and cpy.copy carries
either -EAGAIN or 0..pagesize. Hugetlb pages can also surface a positive
short copy if a fault preempts the operation mid-page (#7).

Pre-#2520 the latter path went through fmt.Errorf("UFFDIO_COPY copied N
bytes...") and fell into the catch-all writeErr != nil arm — which calls
onFailure() / fdExit.SignalExit(), tears the uffd serve loop down, and
crashes the sandbox the moment the guest touches an unmapped page. The
pre-existing errno-EAGAIN soft handler covered only the syscall errno
path.

Move the partial-copy classification into a small helper so both surfaces
collapse onto the existing EAGAIN-returning-(false, nil) branch in
faultPage. No retry budget — matches Firecracker's reference handler in
src/firecracker/examples/uffd/uffd_utils.rs (Err(PartiallyCopied(n)) if
n == 0 || n == -EAGAIN ⇒ return false). Add a uffd.copy_eagain span
attribute for observability.

Tests: unit-test classifyCopyResult directly. faultPage doesn't expose
an Fd seam to mock UFFDIO_COPY without an interface refactor that would
materially expand the diff; per the audit's "smallest pragmatic test"
guidance the classifier covers the new branching and the existing
cross-process matrix tests cover the integration path.

Author: ValentaTomas

packages/orchestrator/pkg/sandbox/uffd/userfaultfd/fd.go

@@ -155,9 +155,26 @@ func (f Fd) copy(addr, pagesize uintptr, data []byte, mode CULong) error {
 		return errno
 	}
 
-	// Check if the copied size matches the requested pagesize
-	if cpy.copy != CLong(pagesize) {
-		return fmt.Errorf("UFFDIO_COPY copied %d bytes, expected %d", cpy.copy, pagesize)
+	return classifyCopyResult(int64(cpy.copy), int64(pagesize))
+}
+
+// classifyCopyResult interprets the bytes-copied field returned by a
+// UFFDIO_COPY ioctl whose syscall returned no errno. The kernel uses a
+// partial-copy convention: a negative value carries the negated errno of
+// the underlying failure (notably -EAGAIN when mmap_changing was set
+// mid-copy by a concurrent madvise(MADV_DONTNEED), mremap, or fork); a
+// positive value less than pagesize means the kernel made partial
+// progress (e.g. a hugetlb fault preempted the copy mid-page). Both
+// cases are surfaced as a soft errno so the caller drops the fault and
+// lets the kernel redeliver once the racing operation settles. Matches
+// Firecracker's reference handler in src/firecracker/examples/uffd/uffd_utils.rs.
+func classifyCopyResult(bytesCopied, pagesize int64) error {
+	if bytesCopied < 0 {
+		return syscall.Errno(-bytesCopied)
+	}
+
+	if bytesCopied != pagesize {
+		return syscall.EAGAIN
 	}
 
 	return nil

packages/orchestrator/pkg/sandbox/uffd/userfaultfd/fd_test.go

@@ -0,0 +1,79 @@
+package userfaultfd
+
+import (
+	"syscall"
+	"testing"
+
+	"github.com/stretchr/testify/assert"
+)
+
+// TestClassifyCopyResult covers UFFD audit findings #1 and #7. It pins the
+// kernel partial-copy convention used by UFFDIO_COPY: when the syscall
+// returns no errno, cpy.copy carries either the bytes copied or a negative
+// -errno. Both EAGAIN-surfacing paths and any short positive copy must be
+// classified as a soft errno so the caller drops the fault and lets the
+// kernel redeliver instead of tearing the sandbox down.
+//
+// Mocking faultPage end-to-end would require an interface seam over Fd
+// that this PR is too small to introduce; per the audit's "smallest
+// pragmatic test" guidance we test the extracted classifier directly and
+// rely on the existing cross-process matrix tests for integration coverage.
+func TestClassifyCopyResult(t *testing.T) {
+	t.Parallel()
+
+	const fourKi = int64(4096)
+	const twoMi = int64(2 * 1024 * 1024)
+
+	tests := []struct {
+		name        string
+		bytesCopied int64
+		pagesize    int64
+		wantErr     error
+		wantEAGAIN  bool
+	}{
+		{
+			name:        "full 4k copy succeeds",
+			bytesCopied: fourKi,
+			pagesize:    fourKi,
+			wantErr:     nil,
+		},
+		{
+			name:        "kernel convention -EAGAIN surfaces as EAGAIN",
+			bytesCopied: -int64(syscall.EAGAIN),
+			pagesize:    fourKi,
+			wantEAGAIN:  true,
+		},
+		{
+			name:        "zero bytes copied surfaces as EAGAIN (matches Firecracker bytes_copied==0)",
+			bytesCopied: 0,
+			pagesize:    fourKi,
+			wantEAGAIN:  true,
+		},
+		{
+			name:        "partial positive copy on hugepage surfaces as EAGAIN",
+			bytesCopied: fourKi,
+			pagesize:    twoMi,
+			wantEAGAIN:  true,
+		},
+		{
+			name:        "kernel convention -EFAULT surfaces as EFAULT (still fatal upstream)",
+			bytesCopied: -int64(syscall.EFAULT),
+			pagesize:    fourKi,
+			wantErr:     syscall.EFAULT,
+		},
+	}
+
+	for _, tc := range tests {
+		t.Run(tc.name, func(t *testing.T) {
+			t.Parallel()
+
+			err := classifyCopyResult(tc.bytesCopied, tc.pagesize)
+			if tc.wantEAGAIN {
+				assert.ErrorIs(t, err, syscall.EAGAIN)
+
+				return
+			}
+			assert.Equal(t, tc.wantErr, err)
+		})
+	}
+}

packages/orchestrator/pkg/sandbox/uffd/userfaultfd/userfaultfd.go

@@ -527,9 +527,13 @@ func (u *Userfaultfd) faultPage(
 	}
 
 	if errors.Is(writeErr, unix.EAGAIN) {
-		// This happens when a remove event arrives in the UFFD file descriptor while
-		// we are trying to copy()/zero() a page. We need to read all the events from
-		// file descriptor and try again.
+		// Kernel sets mmap_changing during a concurrent madvise(MADV_DONTNEED),
+		// mremap, or fork against the same mm and surfaces it as EAGAIN — either
+		// directly via errno or via the UFFDIO_COPY partial-copy convention
+		// (cpy.copy == -EAGAIN, or 0 <= cpy.copy < pagesize for hugetlb faults
+		// preempted mid-page; see classifyCopyResult). Drop the fault and let
+		// the kernel redeliver it once the racing operation settles.
+		span.SetAttributes(attribute.Bool("uffd.copy_eagain", true))
 		u.logger.Debug(ctx, "UFFD page write EAGAIN, deferring", zap.Uintptr("addr", addr))
 
 		return false, nil