workspacefs

Documentation

Overview

Package workspacefs exposes a remote workspace as a local FUSE filesystem. It receives a remote.FileClient, mount root, logging, and UID/GID translation options from the runtime, and feeds go-fuse nodes used by the namespace and target process with POSIX-like file behavior.

Index

• func Mount(ctx context.Context, backend *FileSystem, mountpoint string) (*fuse.Server, error)
• type FileSystem
  • func New(sftp remote.FileClient, root string, log *slog.Logger, opts *Options) *FileSystem
  • func (f *FileSystem) Chmod(ctx context.Context, rel string, mode os.FileMode) syscall.Errno
  • func (f *FileSystem) Chown(ctx context.Context, rel string, uid, gid uint32) syscall.Errno
  • func (f *FileSystem) Chtimes(ctx context.Context, rel string, atime, mtime time.Time) syscall.Errno
  • func (f *FileSystem) CreateFile(ctx context.Context, rel string, flags uint32, mode uint32) syscall.Errno
  • func (f *FileSystem) Fsync(ctx context.Context, rel string) syscall.Errno
  • func (f *FileSystem) Link(ctx context.Context, oldRel, newRel string) syscall.Errno
  • func (f *FileSystem) MkDir(ctx context.Context, rel string, mode uint32) syscall.Errno
  • func (f *FileSystem) ReadDir(ctx context.Context, rel string) ([]os.FileInfo, syscall.Errno)
  • func (f *FileSystem) ReadFile(ctx context.Context, rel string, off int64, size int) ([]byte, syscall.Errno)
  • func (f *FileSystem) Readlink(ctx context.Context, rel string) ([]byte, syscall.Errno)
  • func (f *FileSystem) Rename(ctx context.Context, oldRel, newRel string) syscall.Errno
  • func (f *FileSystem) Rmdir(ctx context.Context, rel string) syscall.Errno
  • func (f *FileSystem) Stat(ctx context.Context, rel string) (os.FileInfo, syscall.Errno)
  • func (f *FileSystem) Statfs(ctx context.Context, rel string, out *remote.Statfs) syscall.Errno
  • func (f *FileSystem) Symlink(ctx context.Context, target, linkRel string) syscall.Errno
  • func (f *FileSystem) Truncate(ctx context.Context, rel string, size int64) syscall.Errno
  • func (f *FileSystem) Unlink(ctx context.Context, rel string) syscall.Errno
  • func (f *FileSystem) WriteFile(ctx context.Context, rel string, data []byte, off int64) (uint32, syscall.Errno)
• type IDMapEntry
• type IDMode
• type Options

Functions

func Mount

func Mount(ctx context.Context, backend *FileSystem, mountpoint string) (*fuse.Server, error)

Types

type FileSystem

type FileSystem struct {
	// contains filtered or unexported fields
}

FileSystem backs a FUSE mount with a remote.FileClient. Each op is translated into the corresponding FileClient method call.

func New

func New(sftp remote.FileClient, root string, log *slog.Logger, opts *Options) *FileSystem

New constructs a FileSystem backed by sftp, rooted at root. opts may be nil to accept the default override mapping with localUID/localGID both zero (mostly useful for tests; production callers should set the local IDs explicitly).

func (*FileSystem) Chmod

func (f *FileSystem) Chmod(ctx context.Context, rel string, mode os.FileMode) syscall.Errno

func (*FileSystem) Chown

func (f *FileSystem) Chown(ctx context.Context, rel string, uid, gid uint32) syscall.Errno

func (*FileSystem) Chtimes

func (f *FileSystem) Chtimes(ctx context.Context, rel string, atime, mtime time.Time) syscall.Errno

func (*FileSystem) CreateFile

func (f *FileSystem) CreateFile(ctx context.Context, rel string, flags uint32, mode uint32) syscall.Errno

func (*FileSystem) Fsync

func (f *FileSystem) Fsync(ctx context.Context, rel string) syscall.Errno

Fsync is the path-based fallback used when FUSE does not provide one of our open file handles. It syncs the file currently named by rel, so callers that have a specific file descriptor should prefer syncing that handle directly.

Backends whose protocol cannot express fsync are expected to make Sync a successful no-op; real open/sync failures are returned to the kernel.

func (*FileSystem) Link

func (f *FileSystem) Link(ctx context.Context, oldRel, newRel string) syscall.Errno

func (*FileSystem) MkDir

func (f *FileSystem) MkDir(ctx context.Context, rel string, mode uint32) syscall.Errno

func (*FileSystem) ReadDir

func (f *FileSystem) ReadDir(ctx context.Context, rel string) ([]os.FileInfo, syscall.Errno)

func (*FileSystem) ReadFile

func (f *FileSystem) ReadFile(ctx context.Context, rel string, off int64, size int) ([]byte, syscall.Errno)

func (*FileSystem) Readlink

func (f *FileSystem) Readlink(ctx context.Context, rel string) ([]byte, syscall.Errno)

func (*FileSystem) Rename

func (f *FileSystem) Rename(ctx context.Context, oldRel, newRel string) syscall.Errno

func (*FileSystem) Rmdir

func (f *FileSystem) Rmdir(ctx context.Context, rel string) syscall.Errno

func (*FileSystem) Stat

func (f *FileSystem) Stat(ctx context.Context, rel string) (os.FileInfo, syscall.Errno)

func (*FileSystem) Statfs

func (f *FileSystem) Statfs(ctx context.Context, rel string, out *remote.Statfs) syscall.Errno

func (*FileSystem) Symlink

func (f *FileSystem) Symlink(ctx context.Context, target, linkRel string) syscall.Errno

func (*FileSystem) Truncate

func (f *FileSystem) Truncate(ctx context.Context, rel string, size int64) syscall.Errno

func (*FileSystem) Unlink

func (f *FileSystem) Unlink(ctx context.Context, rel string) syscall.Errno

func (*FileSystem) WriteFile

func (f *FileSystem) WriteFile(ctx context.Context, rel string, data []byte, off int64) (uint32, syscall.Errno)

type IDMapEntry

type IDMapEntry struct {
	RemoteID uint32
	LocalID  uint32
	Count    uint32
}

IDMapEntry describes one contiguous translation between the remote and local UID/GID spaces. A UID/GID r matches when RemoteID <= r < RemoteID+Count, and is reported locally as LocalID + (r - RemoteID). The reverse mapping is used to translate chown values from the local view back to the remote backend.

type IDMode

type IDMode string

IDMode controls how a single ID dimension (uid or gid) is translated between the remote backend and the local FUSE mount. See Options.UIDMode / Options.GIDMode.

const (
	// IDModeTransparent forwards the remote-reported ID through to the
	// FUSE client unchanged, and forwards chown calls verbatim.
	IDModeTransparent IDMode = "transparent"
	// IDModeOverride substitutes the local user's UID/GID on every stat
	// reply and turns chown into a no-op on that dimension. Useful when
	// the remote runs as a different user (often root) than the local
	// process: without it, default_permissions in the kernel denies the
	// local user access to files the remote claims root owns.
	IDModeOverride IDMode = "override"
)

type Options

type Options struct {
	// UIDMode selects the fallback UID translation when no UIDMap entry
	// covers the ID being translated. Empty value defaults to
	// IDModeOverride.
	UIDMode IDMode
	// GIDMode is the GID counterpart to UIDMode.
	GIDMode IDMode
	// UIDMap is consulted before falling back to UIDMode. The first
	// matching entry wins; entries are searched in order.
	UIDMap []IDMapEntry
	// GIDMap is the GID counterpart to UIDMap.
	GIDMap []IDMapEntry
	// LocalUID is the UID to report when UIDMode == IDModeOverride and
	// no UIDMap entry matches.
	LocalUID uint32
	// LocalGID is the GID counterpart to LocalUID.
	LocalGID uint32
}

Options configures FileSystem behaviour that is not derivable from the remote.FileClient alone.