drive

Documentation

Overview

Package drive provides a filesystem that allows sharing folders between Tailscale nodes using WebDAV. The actual implementation of the core Taildrive functionality lives in package driveimpl. These packages are separated to allow users of Taildrive to refer to the interfaces without having a hard dependency on Taildrive, so that programs which don't actually use Taildrive can avoid its transitive dependencies.

Index

• Variables
• func AllowShareAs() bool
• func Clone(dst, src any) bool
• func CompareShares(a, b *Share) int
• func NormalizeShareName(name string) (string, error)
• func ShareViewsEqual(a, b ShareView) bool
• func SharesEqual(a, b *Share) bool
• type FileSystemForLocal
• type FileSystemForRemote
• type Permission
• type Permissions
  • func ParsePermissions(rawGrants [][]byte) (Permissions, error)
  • func (p Permissions) For(share string) Permission
• type Remote
• type Share
  • func (src *Share) Clone() *Share
  • func (p *Share) View() ShareView
• type ShareView
  • func (v ShareView) As() string
  • func (v ShareView) AsStruct() *Share
  • func (v ShareView) BookmarkData() views.ByteSlice[[]byte]
  • func (v ShareView) MarshalJSON() ([]byte, error)
  • func (v ShareView) Name() string
  • func (v ShareView) Path() string
  • func (v *ShareView) UnmarshalJSON(b []byte) error
  • func (v ShareView) Valid() bool

Variables

var (
	// DisallowShareAs forcibly disables sharing as a specific user, only used
	// for testing.
	DisallowShareAs     = false
	ErrDriveNotEnabled  = errors.New("Taildrive not enabled")
	ErrInvalidShareName = errors.New("Share names may only contain the letters a-z, underscore _, parentheses (), or spaces")
)

Functions

func AllowShareAs

func AllowShareAs() bool

AllowShareAs reports whether sharing files as a specific user is allowed.

func Clone

func Clone(dst, src any) bool

Clone duplicates src into dst and reports whether it succeeded. To succeed, <src, dst> must be of types <*T, *T> or <*T, **T>, where T is one of Share.

func CompareShares

func CompareShares(a, b *Share) int

func NormalizeShareName

func NormalizeShareName(name string) (string, error)

NormalizeShareName normalizes the given share name and returns an error if it contains any disallowed characters.

func ShareViewsEqual

func ShareViewsEqual(a, b ShareView) bool

func SharesEqual

func SharesEqual(a, b *Share) bool

Types

type FileSystemForLocal

type FileSystemForLocal interface {
	// HandleConn handles connections from local WebDAV clients
	HandleConn(conn net.Conn, remoteAddr net.Addr) error

	// SetRemotes sets the complete set of remotes on the given tailnet domain
	// using a map of name -> url. If transport is specified, that transport
	// will be used to connect to these remotes.
	SetRemotes(domain string, remotes []*Remote, transport http.RoundTripper)

	// Close() stops serving the WebDAV content
	Close() error
}

FileSystemForLocal is the Taildrive filesystem exposed to local clients. It provides a unified WebDAV interface to remote Taildrive shares on other nodes.

type FileSystemForRemote

type FileSystemForRemote interface {
	// SetFileServerAddr sets the address of the file server to which we
	// should proxy. This is used on platforms like Windows and MacOS
	// sandboxed where we can't spawn user-specific sub-processes and instead
	// rely on the UI application that's already running as an unprivileged
	// user to access the filesystem for us.
	SetFileServerAddr(addr string)

	// SetShares sets the complete set of shares exposed by this node. If
	// AllowShareAs() reports true, we will use one subprocess per user to
	// access the filesystem (see userServer). Otherwise, we will use the file
	// server configured via SetFileServerAddr.
	SetShares(shares []*Share)

	// ServeHTTPWithPerms behaves like the similar method from http.Handler but
	// also accepts a Permissions map that captures the permissions of the
	// connecting node.
	ServeHTTPWithPerms(permissions Permissions, w http.ResponseWriter, r *http.Request)

	// Close() stops serving the WebDAV content
	Close() error
}

FileSystemForRemote is the drive filesystem exposed to remote nodes. It provides a unified WebDAV interface to local directories that have been shared.

type Permission

type Permission uint8

const (
	PermissionNone Permission = iota
	PermissionReadOnly
	PermissionReadWrite
)

type Permissions

type Permissions map[string]Permission

Permissions represents the set of permissions for a given principal to a set of shares.

func ParsePermissions

func ParsePermissions(rawGrants [][]byte) (Permissions, error)

ParsePermissions builds a Permissions map from a lis of raw grants.

func (Permissions) For

func (p Permissions) For(share string) Permission

type Remote

type Remote struct {
	Name      string
	URL       string
	Available func() bool
}

Remote represents a remote Taildrive node.

type Share

type Share struct {
	// Name is how this share appears on remote nodes.
	Name string `json:"name,omitempty"`

	// Path is the path to the directory on this machine that's being shared.
	Path string `json:"path,omitempty"`

	// As is the UNIX or Windows username of the local account used for this
	// share. File read/write permissions are enforced based on this username.
	// Can be left blank to use the default value of "whoever is running the
	// Tailscale GUI".
	As string `json:"who,omitempty"`

	// BookmarkData contains security-scoped bookmark data for the Sandboxed
	// Mac application. The Sandboxed Mac application gains permission to
	// access the Share's folder as a result of a user selecting it in a file
	// picker. In order to retain access to it across restarts, it needs to
	// hold on to a security-scoped bookmark. That bookmark is stored here. See
	// https://developer.apple.com/documentation/security/app_sandbox/accessing_files_from_the_macos_app_sandbox#4144043
	BookmarkData []byte `json:"bookmarkData,omitempty"`
}

Share configures a folder to be shared through drive.

func (*Share) Clone

func (src *Share) Clone() *Share

Clone makes a deep copy of Share. The result aliases no memory with the original.

func (*Share) View

func (p *Share) View() ShareView

View returns a readonly view of Share.

type ShareView

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

ShareView provides a read-only view over Share.

Its methods should only be called if `Valid()` returns true.

func (ShareView) As

func (v ShareView) As() string

func (ShareView) AsStruct

func (v ShareView) AsStruct() *Share

AsStruct returns a clone of the underlying value which aliases no memory with the original.

func (ShareView) BookmarkData

func (v ShareView) BookmarkData() views.ByteSlice[[]byte]

func (ShareView) MarshalJSON

func (v ShareView) MarshalJSON() ([]byte, error)

func (ShareView) Name

func (v ShareView) Name() string

func (ShareView) Path

func (v ShareView) Path() string

func (*ShareView) UnmarshalJSON

func (v *ShareView) UnmarshalJSON(b []byte) error

func (ShareView) Valid

func (v ShareView) Valid() bool

Valid reports whether underlying value is non-nil.