gateway: create interface for reading from container filesystem

This creates an interface that can be used to read the filesystem of a
new container created through the gateway API. These filesystem reading
methods are tied to a specific container that has been created, but
aren't tied to the container itself.

Due to being run inside of buildkit, these containers have access to the
same mounts that a container request would have. This is useful for
features like the file explorer in `buildx dap` because it can access
container filesystem state from stages that error along with ones that
have completed successfully.

Signed-off-by: Jonathan A. Sternberg <jonathan.sternberg@docker.com>

Author: jsternberg

client/build.go

@@ -178,6 +178,36 @@ func (g *gatewayClientForBuild) ReleaseContainer(ctx context.Context, in *gatewa
 	return g.gateway.ReleaseContainer(ctx, in, opts...)
 }
 
+func (g *gatewayClientForBuild) ReadFileContainer(ctx context.Context, in *gatewayapi.ReadFileRequest, opts ...grpc.CallOption) (*gatewayapi.ReadFileResponse, error) {
+	if g.caps != nil {
+		if err := g.caps.Supports(gatewayapi.CapGatewayExecFilesystem); err != nil {
+			return nil, err
+		}
+	}
+	ctx = buildid.AppendToOutgoingContext(ctx, g.buildID)
+	return g.gateway.ReadFileContainer(ctx, in, opts...)
+}
+
+func (g *gatewayClientForBuild) ReadDirContainer(ctx context.Context, in *gatewayapi.ReadDirRequest, opts ...grpc.CallOption) (*gatewayapi.ReadDirResponse, error) {
+	if g.caps != nil {
+		if err := g.caps.Supports(gatewayapi.CapGatewayExecFilesystem); err != nil {
+			return nil, err
+		}
+	}
+	ctx = buildid.AppendToOutgoingContext(ctx, g.buildID)
+	return g.gateway.ReadDirContainer(ctx, in, opts...)
+}
+
+func (g *gatewayClientForBuild) StatFileContainer(ctx context.Context, in *gatewayapi.StatFileRequest, opts ...grpc.CallOption) (*gatewayapi.StatFileResponse, error) {
+	if g.caps != nil {
+		if err := g.caps.Supports(gatewayapi.CapGatewayExecFilesystem); err != nil {
+			return nil, err
+		}
+	}
+	ctx = buildid.AppendToOutgoingContext(ctx, g.buildID)
+	return g.gateway.StatFileContainer(ctx, in, opts...)
+}
+
 func (g *gatewayClientForBuild) ExecProcess(ctx context.Context, opts ...grpc.CallOption) (gatewayapi.LLBBridge_ExecProcessClient, error) {
 	if g.caps != nil {
 		if err := g.caps.Supports(gatewayapi.CapGatewayExec); err != nil {

control/gateway/gateway.go

@@ -188,6 +188,30 @@ func (gwf *GatewayForwarder) ReleaseContainer(ctx context.Context, req *gwapi.Re
 	return fwd.ReleaseContainer(ctx, req)
 }
 
+func (gwf *GatewayForwarder) ReadFileContainer(ctx context.Context, req *gwapi.ReadFileRequest) (*gwapi.ReadFileResponse, error) {
+	fwd, err := gwf.lookupForwarder(ctx)
+	if err != nil {
+		return nil, errors.Wrap(err, "forwarding ReadFileContainer")
+	}
+	return fwd.ReadFileContainer(ctx, req)
+}
+
+func (gwf *GatewayForwarder) ReadDirContainer(ctx context.Context, req *gwapi.ReadDirRequest) (*gwapi.ReadDirResponse, error) {
+	fwd, err := gwf.lookupForwarder(ctx)
+	if err != nil {
+		return nil, errors.Wrap(err, "forwarding ReadDirContainer")
+	}
+	return fwd.ReadDirContainer(ctx, req)
+}
+
+func (gwf *GatewayForwarder) StatFileContainer(ctx context.Context, req *gwapi.StatFileRequest) (*gwapi.StatFileResponse, error) {
+	fwd, err := gwf.lookupForwarder(ctx)
+	if err != nil {
+		return nil, errors.Wrap(err, "forwarding StatFileContainer")
+	}
+	return fwd.StatFileContainer(ctx, req)
+}
+
 func (gwf *GatewayForwarder) ExecProcess(srv gwapi.LLBBridge_ExecProcessServer) error {
 	fwd, err := gwf.lookupForwarder(srv.Context())
 	if err != nil {

frontend/gateway/client/client.go

@@ -66,6 +66,9 @@ type Mount struct {
 type Container interface {
 	Start(context.Context, StartRequest) (ContainerProcess, error)
 	Release(context.Context) error
+	ReadFile(ctx context.Context, req ReadContainerRequest) ([]byte, error)
+	StatFile(ctx context.Context, req StatContainerRequest) (*fstypes.Stat, error)
+	ReadDir(ctx context.Context, req ReadDirContainerRequest) ([]*fstypes.Stat, error)
 }
 
 // StartRequest encapsulates the arguments to define a process within a
@@ -111,6 +114,11 @@ type ReadRequest struct {
 	Range    *FileRange
 }
 
+type ReadContainerRequest struct {
+	ReadRequest
+	Index int
+}
+
 type FileRange struct {
 	Offset int
 	Length int
@@ -121,10 +129,20 @@ type ReadDirRequest struct {
 	IncludePattern string
 }
 
+type ReadDirContainerRequest struct {
+	ReadDirRequest
+	Index int
+}
+
 type StatRequest struct {
 	Path string
 }
 
+type StatContainerRequest struct {
+	StatRequest
+	Index int
+}
+
 // SolveRequest is same as frontend.SolveRequest but avoiding dependency
 type SolveRequest struct {
 	Evaluate       bool

frontend/gateway/container/container.go

@@ -4,6 +4,8 @@ import (
 	"cmp"
 	"context"
 	"fmt"
+	"io/fs"
+	"os"
 	"path/filepath"
 	"runtime"
 	"slices"
@@ -25,6 +27,7 @@ import (
 	"github.com/moby/buildkit/util/stack"
 	"github.com/moby/buildkit/worker"
 	"github.com/pkg/errors"
+	fstypes "github.com/tonistiigi/fsutil/types"
 	"golang.org/x/sync/errgroup"
 )
 
@@ -104,6 +107,26 @@ func NewContainer(ctx context.Context, cm cache.Manager, exec executor.Executor,
 	ctr.rootFS = p.Root
 	ctr.mounts = p.Mounts
 
+	// Setup the local mounts. These need to be in the same order as the original
+	// parameters.
+	ctr.localMounts = make([]gatewayContainerMount, len(mnts))
+	for i, m := range mnts {
+		if m.Dest == "/" {
+			ctr.localMounts[i].Src = p.Root.Src
+			continue
+		}
+
+		index := slices.IndexFunc(p.Mounts, func(em executor.Mount) bool {
+			return em.Dest == m.Dest
+		})
+		if index < 0 {
+			// This shouldn't happen but handle it just in case.
+			continue
+		}
+
+		ctr.localMounts[i].Src = p.Mounts[index].Src
+	}
+
 	for _, o := range p.OutputRefs {
 		ctr.cleanup = append(ctr.cleanup, func() error {
 			return o.Ref.Release(context.TODO())
@@ -281,22 +304,23 @@ func PrepareMounts(ctx context.Context, mm *mounts.MountManager, cm cache.Manage
 }
 
 type gatewayContainer struct {
-	id         string
-	netMode    opspb.NetMode
-	hostname   string
-	extraHosts []executor.HostIP
-	platform   *opspb.Platform
-	rootFS     executor.Mount
-	mounts     []executor.Mount
-	executor   executor.Executor
-	sm         *session.Manager
-	group      session.Group
-	started    bool
-	errGroup   *errgroup.Group
-	mu         sync.Mutex
-	cleanup    []func() error
-	ctx        context.Context
-	cancel     func(error)
+	id          string
+	netMode     opspb.NetMode
+	hostname    string
+	extraHosts  []executor.HostIP
+	platform    *opspb.Platform
+	rootFS      executor.Mount
+	mounts      []executor.Mount
+	executor    executor.Executor
+	sm          *session.Manager
+	group       session.Group
+	started     bool
+	errGroup    *errgroup.Group
+	mu          sync.Mutex
+	cleanup     []func() error
+	ctx         context.Context
+	cancel      func(error)
+	localMounts []gatewayContainerMount
 }
 
 func (gwCtr *gatewayContainer) Start(ctx context.Context, req client.StartRequest) (client.ContainerProcess, error) {
@@ -419,6 +443,122 @@ func (gwCtr *gatewayContainer) Release(ctx context.Context) error {
 	return stack.Enable(err2)
 }
 
+func (gwCtr *gatewayContainer) ReadFile(ctx context.Context, req client.ReadContainerRequest) ([]byte, error) {
+	fsys, err := gwCtr.mount(ctx, req.Index)
+	if err != nil {
+		return nil, err
+	}
+
+	path, err := filepath.Rel("/", req.Filename)
+	if err != nil {
+		return nil, err
+	}
+	return fs.ReadFile(fsys, path)
+}
+
+func (gwCtr *gatewayContainer) ReadDir(ctx context.Context, req client.ReadDirContainerRequest) ([]*fstypes.Stat, error) {
+	fsys, err := gwCtr.mount(ctx, req.Index)
+	if err != nil {
+		return nil, err
+	}
+
+	path, err := filepath.Rel("/", req.Path)
+	if err != nil {
+		return nil, err
+	}
+
+	entries, err := fs.ReadDir(fsys, path)
+	if err != nil {
+		return nil, err
+	}
+
+	files := make([]*fstypes.Stat, len(entries))
+	for i, e := range entries {
+		fullpath := filepath.Join(req.Path, e.Name())
+		fi, err := e.Info()
+		if err != nil {
+			return nil, err
+		}
+
+		files[i], err = mkstat(fsys, fullpath, e.Name(), fi)
+		if err != nil {
+			return nil, errors.Wrap(err, "mkstat")
+		}
+	}
+	return files, nil
+}
+
+func (gwCtr *gatewayContainer) StatFile(ctx context.Context, req client.StatContainerRequest) (*fstypes.Stat, error) {
+	fsys, err := gwCtr.mount(ctx, req.Index)
+	if err != nil {
+		return nil, err
+	}
+
+	path, err := filepath.Rel("/", req.Path)
+	if err != nil {
+		return nil, err
+	}
+
+	fi, err := fs.Stat(fsys, path)
+	if err != nil {
+		return nil, err
+	}
+	return mkstat(fsys, req.Path, filepath.Base(req.Path), fi)
+}
+
+func (gwCtr *gatewayContainer) mount(ctx context.Context, index int) (fs.FS, error) {
+	// No lock needed for this because the number of mounts does
+	// not change.
+	if index < 0 || index >= len(gwCtr.localMounts) {
+		return nil, errors.Errorf("mount index %d is out of bounds (%d available)", index, len(gwCtr.localMounts))
+	}
+
+	gwCtr.mu.Lock()
+	defer gwCtr.mu.Unlock()
+
+	mount := gwCtr.localMounts[index]
+
+	// Already mounted?
+	if mount.FS != nil {
+		return mount.FS, nil
+	}
+
+	// Defensively check that this mount really exists.
+	if mount.Src == nil {
+		return nil, errors.Errorf("mountable %d not found", index)
+	}
+
+	// Need to mount an instance.
+	ref, err := mount.Src.Mount(ctx, true)
+	if err != nil {
+		return nil, err
+	}
+
+	mounter := snapshot.LocalMounter(ref)
+	dir, err := mounter.Mount()
+	if err != nil {
+		return nil, err
+	}
+
+	// Register cleanup.
+	gwCtr.cleanup = append(gwCtr.cleanup, func() error {
+		return mounter.Unmount()
+	})
+
+	root, err := os.OpenRoot(dir)
+	if err != nil {
+		return nil, err
+	}
+
+	gwCtr.cleanup = append(gwCtr.cleanup, func() error {
+		return root.Close()
+	})
+
+	f := root.FS()
+	gwCtr.localMounts[index].FS = f
+	return f, nil
+}
+
 type gatewayContainerProcess struct {
 	errGroup *errgroup.Group
 	groupCtx context.Context
@@ -511,3 +651,49 @@ type mountable struct {
 func (m *mountable) Mount(ctx context.Context, readonly bool) (snapshot.Mountable, error) {
 	return m.m.Mount(ctx, readonly, m.g)
 }
+
+// constructs a Stat object. path is where the path can be found right
+// now, relpath is the desired path to be recorded in the stat (so
+// relative to whatever base dir is relevant). fi is the os.Stat
+// info. inodemap is used to calculate hardlinks over a series of
+// mkstat calls and maps inode to the canonical (aka "first") path for
+// a set of hardlinks to that inode.
+func mkstat(fsys fs.FS, path, relpath string, fi os.FileInfo) (*fstypes.Stat, error) {
+	relpath = filepath.ToSlash(relpath)
+
+	stat := &fstypes.Stat{
+		Path:    filepath.FromSlash(relpath),
+		Mode:    uint32(fi.Mode()),
+		ModTime: fi.ModTime().UnixNano(),
+	}
+
+	if !fi.IsDir() {
+		stat.Size = fi.Size()
+		if fi.Mode()&os.ModeSymlink != 0 {
+			link, err := fs.ReadLink(fsys, path)
+			if err != nil {
+				return nil, errors.WithStack(err)
+			}
+			stat.Linkname = link
+		}
+	}
+
+	if runtime.GOOS == "windows" {
+		permPart := stat.Mode & uint32(os.ModePerm)
+		noPermPart := stat.Mode &^ uint32(os.ModePerm)
+		// Add the x bit: make everything +x from windows
+		permPart |= 0o111
+		permPart &= 0o755
+		stat.Mode = noPermPart | permPart
+	}
+
+	// Clear the socket bit since archive/tar.FileInfoHeader does not handle it
+	stat.Mode &^= uint32(os.ModeSocket)
+
+	return stat, nil
+}
+
+type gatewayContainerMount struct {
+	Src executor.Mountable
+	FS  fs.FS
+}