Secure, Fast, and Extensible Sandbox runtime for AI agents.
fix(execd): replace uploads atomically so a failed write keeps the old file
Jason Cat97bca01a4885
diff --git a/components/execd/pkg/web/controller/file_owner_other.go b/components/execd/pkg/web/controller/file_owner_other.gonew file mode 100644index 000000000..e73bd0636--- /dev/null+++ b/components/execd/pkg/web/controller/file_owner_other.go@@ -0,0 +1,25 @@+//go:build !unix++// Copyright 2026 The OpenSandbox Authors+//+// Licensed under the Apache License, Version 2.0 (the "License");+// you may not use this file except in compliance with the License.+// You may obtain a copy of the License at+//+// http://www.apache.org/licenses/LICENSE-2.0+//+// Unless required by applicable law or agreed to in writing, software+// distributed under the License is distributed on an "AS IS" BASIS,+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.+// See the License for the specific language governing permissions and+// limitations under the License.++package controller++import "os"++// copyFileOwnership is a no-op where the platform exposes no numeric owner and+// group on a FileInfo.+func copyFileOwnership(string, os.FileInfo) error {+ return nil+}diff --git a/components/execd/pkg/web/controller/file_owner_unix.go b/components/execd/pkg/web/controller/file_owner_unix.gonew file mode 100644index 000000000..9a2d1ffaf--- /dev/null+++ b/components/execd/pkg/web/controller/file_owner_unix.go@@ -0,0 +1,37 @@+//go:build unix++// Copyright 2026 The OpenSandbox Authors+//+// Licensed under the Apache License, Version 2.0 (the "License");+// you may not use this file except in compliance with the License.+// You may obtain a copy of the License at+//+// http://www.apache.org/licenses/LICENSE-2.0+//+// Unless required by applicable law or agreed to in writing, software+// distributed under the License is distributed on an "AS IS" BASIS,+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.+// See the License for the specific language governing permissions and+// limitations under the License.++package controller++import (+ "fmt"+ "os"+ "syscall"+)++// copyFileOwnership records the owner and group of info on path, so staging a+// file and renaming it over an existing one keeps the ownership an in-place+// write preserved.+func copyFileOwnership(path string, info os.FileInfo) error {+ stat, ok := info.Sys().(*syscall.Stat_t)+ if !ok {+ return nil+ }+ if err := os.Chown(path, int(stat.Uid), int(stat.Gid)); err != nil {+ return fmt.Errorf("chown %s to %d:%d: %w", path, stat.Uid, stat.Gid, err)+ }+ return nil+}diff --git a/components/execd/pkg/web/controller/filesystem_upload.go b/components/execd/pkg/web/controller/filesystem_upload.goindex 72229b7f9..7acbc9d00 100644--- a/components/execd/pkg/web/controller/filesystem_upload.go+++ b/components/execd/pkg/web/controller/filesystem_upload.go@@ -15,9 +15,13 @@package controllerimport (+ "crypto/rand"+ "encoding/hex""encoding/json"+ "errors""fmt""io"+ "io/fs""mime/multipart""net/http""os"@@ -173,35 +177,108 @@ func writeUploadFile(resolvedPath string, fileHeader *multipart.FileHeader) *upl}defer file.Close()- dst, err := os.OpenFile(resolvedPath, os.O_WRONLY|os.O_CREATE|os.O_TRUNC, os.ModePerm)- if err != nil {+ return writeUploadStream(resolvedPath, file)+}++// uploadTempPattern prefixes the staging file an upload writes next to its+// destination. The leading dot keeps it out of a plain directory listing.+const uploadTempPattern = ".osb-upload-"++// maxUploadSymlinkDepth bounds the final-component symlink walk; it mirrors the+// kernel's ELOOP threshold closely enough to reject a link cycle.+const maxUploadSymlinkDepth = 40++// writeUploadStream replaces target with the bytes read from r.+//+// The bytes are staged in this directory and renamed into place only once they+// are fully written and synced, so a write that fails partway - ENOSPC, an I/O+// error, the daemon being killed mid-copy - leaves the file it was replacing+// intact. An in-place O_TRUNC write destroyed it, and a sandbox usually holds+// the only copy of the file an upload overwrites.+func writeUploadStream(target string, r io.Reader) *uploadError {+ resolvedTarget, uerr := resolveUploadTargetPath(target)+ if uerr != nil {+ return uerr+ }++ existing, statErr := os.Stat(resolvedTarget)+ switch {+ case statErr == nil && !existing.Mode().IsRegular():+ // A device or a FIFO cannot be staged and renamed over without being+ // replaced by a regular file, so keep refusing them as before.return newUploadError(http.StatusInternalServerError,model.ErrorCodeRuntimeError,- fmt.Sprintf("error opening destination file %s. %v", resolvedPath, err),+ fmt.Sprintf("error opening destination file %s. not a regular file", resolvedTarget),+ )+ case statErr == nil:+ // A rename only needs a writable directory, so probe the file itself to+ // keep rejecting a read-only destination the way an in-place write did.+ probe, err := os.OpenFile(resolvedTarget, os.O_WRONLY, 0)+ if err != nil {+ return newUploadError(+ http.StatusInternalServerError,+ model.ErrorCodeRuntimeError,+ fmt.Sprintf("error opening destination file %s. %v", resolvedTarget, err),+ )+ }+ _ = probe.Close()+ case !errors.Is(statErr, fs.ErrNotExist):+ return newUploadError(+ http.StatusInternalServerError,+ model.ErrorCodeRuntimeError,+ fmt.Sprintf("error opening destination file %s. %v", resolvedTarget, statErr),)}- if _, err := io.Copy(dst, file); err != nil {- dst.Close()+ tmp, err := createUploadTemp(filepath.Dir(resolvedTarget))+ if err != nil {return newUploadError(http.StatusInternalServerError,model.ErrorCodeRuntimeError,- fmt.Sprintf("error copying file %s. %v", resolvedPath, err),+ fmt.Sprintf("error creating the upload staging file for %s. %v", resolvedTarget, err),)}+ tmpName := tmp.Name()+ committed := false+ defer func() {+ if committed {+ return+ }+ _ = tmp.Close()+ _ = os.Remove(tmpName)+ }()++ if statErr == nil {+ // An in-place write kept the metadata of the file it overwrote: carry+ // the mode over, and the owner/group where the platform exposes them,+ // so replacing the file does not change who can read or write it.+ if err := tmp.Chmod(existing.Mode().Perm()); err != nil {+ return uploadWriteError(resolvedTarget, err)+ }+ if err := copyFileOwnership(tmpName, existing); err != nil {+ log.Warn("upload: preserve owner/group of %s: %v", resolvedTarget, err)+ }+ }- if err := dst.Sync(); err != nil {+ if _, err := io.Copy(tmp, r); err != nil {+ return uploadWriteError(resolvedTarget, err)+ }+ if err := tmp.Sync(); err != nil {log.Error("upload: sync target file: %v", err)}- if err := dst.Close(); err != nil {- log.Error("upload: close target file: %v", err)+ if err := tmp.Close(); err != nil {+ return uploadWriteError(resolvedTarget, err)}+ if err := os.Rename(tmpName, resolvedTarget); err != nil {+ return uploadWriteError(resolvedTarget, err)+ }+ committed = true// fsync parent directory so the new dirent is durable and visible on// weakly-coherent filesystems (virtio-fs, 9pfs, etc.). Best-effort:// some filesystems return ENOTSUP for directory fsync.- targetDir := filepath.Dir(resolvedPath)+ targetDir := filepath.Dir(resolvedTarget)if d, err := os.Open(targetDir); err == nil {if err := d.Sync(); err != nil {log.Warn("upload: sync parent dir %s: %v", targetDir, err)@@ -211,6 +288,76 @@ func writeUploadFile(resolvedPath string, fileHeader *multipart.FileHeader) *uplreturn nil}+func uploadWriteError(path string, err error) *uploadError {+ return newUploadError(+ http.StatusInternalServerError,+ model.ErrorCodeRuntimeError,+ fmt.Sprintf("error writing file %s. %v", path, err),+ )+}++// createUploadTemp creates the staging file with the mode a plain create in+// this directory has today (os.ModePerm masked by the umask), so a client that+// sends no permission keeps the mode it used to get.+func createUploadTemp(dir string) (*os.File, error) {+ var suffix [8]byte+ for attempt := 0; attempt < 10; attempt++ {+ if _, err := rand.Read(suffix[:]); err != nil {+ return nil, err+ }+ name := filepath.Join(dir, uploadTempPattern+hex.EncodeToString(suffix[:]))+ f, err := os.OpenFile(name, os.O_WRONLY|os.O_CREATE|os.O_EXCL, os.ModePerm)+ if err == nil {+ return f, nil+ }+ if !errors.Is(err, fs.ErrExist) {+ return nil, err+ }+ }+ return nil, errors.New("could not allocate a unique staging file name")+}++// resolveUploadTargetPath follows a symlink in the final path component, so the+// rename replaces the file an in-place write would have written through the+// link instead of replacing the link itself.+func resolveUploadTargetPath(path string) (string, *uploadError) {+ resolved := path+ for i := 0; i < maxUploadSymlinkDepth; i++ {+ info, err := os.Lstat(resolved)+ if err != nil {+ if errors.Is(err, fs.ErrNotExist) {+ // A new file, or the target of a dangling link.+ return resolved, nil+ }+ return "", newUploadError(+ http.StatusInternalServerError,+ model.ErrorCodeRuntimeError,+ fmt.Sprintf("error resolving destination file %s. %v", path, err),+ )+ }+ if info.Mode()&os.ModeSymlink == 0 {+ return resolved, nil+ }+ link, err := os.Readlink(resolved)+ if err != nil {+ return "", newUploadError(+ http.StatusInternalServerError,+ model.ErrorCodeRuntimeError,+ fmt.Sprintf("error resolving destination symlink %s. %v", resolved, err),+ )+ }+ if !filepath.IsAbs(link) {+ link = filepath.Join(filepath.Dir(resolved), link)+ }+ resolved = link+ }+ return "", newUploadError(+ http.StatusInternalServerError,+ model.ErrorCodeRuntimeError,+ fmt.Sprintf("error resolving destination file %s. too many levels of symbolic links", path),+ )+}+// applyUploadPermission applies the metadata permission with one retry to// absorb metadata-propagation delay on weakly-coherent filesystems// (virtio-fs, 9pfs). ChmodFile always invokes chown under the hood, so adiff --git a/components/execd/pkg/web/controller/filesystem_upload_atomic_test.go b/components/execd/pkg/web/controller/filesystem_upload_atomic_test.gonew file mode 100644index 000000000..3e170df59--- /dev/null+++ b/components/execd/pkg/web/controller/filesystem_upload_atomic_test.go@@ -0,0 +1,143 @@+// Copyright 2026 The OpenSandbox Authors+//+// Licensed under the Apache License, Version 2.0 (the "License");+// you may not use this file except in compliance with the License.+// You may obtain a copy of the License at+//+// http://www.apache.org/licenses/LICENSE-2.0+//+// Unless required by applicable law or agreed to in writing, software+// distributed under the License is distributed on an "AS IS" BASIS,+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.+// See the License for the specific language governing permissions and+// limitations under the License.++package controller++import (+ "bytes"+ "errors"+ "mime/multipart"+ "net/http"+ "os"+ "path/filepath"+ "runtime"+ "testing"+ "testing/iotest"++ "github.com/stretchr/testify/require"+)++// requireNoUploadStaging asserts the staging file of a failed upload is gone.+func requireNoUploadStaging(t *testing.T, dir string) {+ t.Helper()+ entries, err := os.ReadDir(dir)+ require.NoError(t, err)+ for _, entry := range entries {+ require.NotContainsf(t, entry.Name(), uploadTempPattern, "staging file %s was left behind", entry.Name())+ }+}++// A copy that fails after the destination was opened must not cost the sandbox+// the file it was replacing: the upload fails and the old content survives.+func TestWriteUploadStreamFailureKeepsTheReplacedFile(t *testing.T) {+ dir := t.TempDir()+ target := filepath.Join(dir, "notes.md")+ original := []byte("previous content\n")+ require.NoError(t, os.WriteFile(target, original, 0o640))++ uerr := writeUploadStream(target, iotest.ErrReader(errors.New("source failed mid-copy")))++ require.NotNil(t, uerr)+ got, err := os.ReadFile(target)+ require.NoError(t, err)+ require.Equal(t, string(original), string(got))+ if runtime.GOOS != "windows" {+ info, err := os.Stat(target)+ require.NoError(t, err)+ require.Equal(t, os.FileMode(0o640), info.Mode().Perm(),+ "an in-place write kept the destination mode; a staged replace must keep it too")+ }+ requireNoUploadStaging(t, dir)+}++func TestWriteUploadStreamFailureLeavesNoNewFile(t *testing.T) {+ dir := t.TempDir()+ target := filepath.Join(dir, "absent.txt")++ uerr := writeUploadStream(target, iotest.ErrReader(errors.New("source failed mid-copy")))++ require.NotNil(t, uerr)+ _, err := os.Stat(target)+ require.ErrorIs(t, err, os.ErrNotExist)+ requireNoUploadStaging(t, dir)+}++func TestWriteUploadStreamReplacesContent(t *testing.T) {+ dir := t.TempDir()+ target := filepath.Join(dir, "notes.md")+ require.NoError(t, os.WriteFile(target, []byte("old"), 0o644))++ uerr := writeUploadStream(target, bytes.NewReader([]byte("new content")))++ require.Nil(t, uerr)+ got, err := os.ReadFile(target)+ require.NoError(t, err)+ require.Equal(t, "new content", string(got))+ requireNoUploadStaging(t, dir)+}++// An upload to a symlinked path keeps writing the link target, as an in-place+// write did, instead of replacing the link with a regular file.+func TestWriteUploadStreamFollowsSymlinkTarget(t *testing.T) {+ dir := t.TempDir()+ realFile := filepath.Join(dir, "real.txt")+ link := filepath.Join(dir, "current")+ require.NoError(t, os.WriteFile(realFile, []byte("old"), 0o644))+ if err := os.Symlink(realFile, link); err != nil {+ t.Skipf("symlinks unavailable: %v", err)+ }++ uerr := writeUploadStream(link, bytes.NewReader([]byte("through the link")))++ require.Nil(t, uerr)+ info, err := os.Lstat(link)+ require.NoError(t, err)+ require.NotZero(t, info.Mode()&os.ModeSymlink, "the symlink itself must survive the replace")+ got, err := os.ReadFile(realFile)+ require.NoError(t, err)+ require.Equal(t, "through the link", string(got))+}++// The multipart entry point keeps honoring the metadata path and mode.+func TestUploadFileWritesThroughMultipart(t *testing.T) {+ dir := t.TempDir()+ target := filepath.Join(dir, "uploaded.txt")++ body := &bytes.Buffer{}+ writer := multipart.NewWriter(body)+ metadata, err := writer.CreateFormFile("metadata", "metadata")+ require.NoError(t, err)+ _, err = metadata.Write([]byte(`{"path":"` + filepath.ToSlash(target) + `","mode":644}`))+ require.NoError(t, err)+ filePart, err := writer.CreateFormFile("file", "uploaded.txt")+ require.NoError(t, err)+ _, err = filePart.Write([]byte("multipart payload"))+ require.NoError(t, err)+ require.NoError(t, writer.Close())++ ctrl, rec := newFilesystemController(t, http.MethodPost, "/files/upload", body.Bytes())+ ctrl.ctx.Request.Header.Set("Content-Type", writer.FormDataContentType())+ ctrl.UploadFile()++ require.Equal(t, http.StatusOK, rec.Code)+ got, err := os.ReadFile(target)+ require.NoError(t, err)+ require.Equal(t, "multipart payload", string(got))+ if runtime.GOOS != "windows" {+ info, err := os.Stat(target)+ require.NoError(t, err)+ require.Equal(t, os.FileMode(0o644), info.Mode().Perm())+ }+ requireNoUploadStaging(t, dir)+}diff --git a/docs/architecture/data-plane/execd.md b/docs/architecture/data-plane/execd.mdindex 89dac5abf..00086485a 100644--- a/docs/architecture/data-plane/execd.md+++ b/docs/architecture/data-plane/execd.md@@ -100,6 +100,8 @@ This is a sandbox-wide credential, not a restricted terminal ticket. Obtain it tOne API covers the whole filesystem tree: stream files in and out, list and search directories, inspect and change permissions, replace file contents, move and remove paths. The file APIs in every sandbox SDK are a thin wrapper over these endpoints.+An upload replaces its destination only after the bytes are fully written and synced: a copy that fails partway leaves the file it was replacing untouched instead of truncating it. The replacement keeps the destination's mode and, on Unix, its owner and group.+### Filesystem execution identityOn Linux, a trusted backend can select the identity performing ordinary file operations by prefixing the file API path with `/v1/filesystem/{uid}/{gid}`. Both IDs are required decimal integers between 0 and 4294967294. For example, `GET /v1/filesystem/1001/1001/files/download?path=/workspace/session-b/result.txt` reads the file as UID 1001 with primary GID 1001. The same prefix supports all ordinary file and directory operations, including uploads, metadata, search, replacement, rename, deletion, and permission changes.