taildrop

Documentation

Overview

Package taildrop contains the implementation of the Taildrop functionality including sending and retrieving files. This package does not validate permissions, the caller should be responsible for ensuring correct authorization.

For related documentation see: http://go/taildrop-how-does-it-work

Index

• Variables
• func NextFilename(name string) string
• func ResumeReader(r io.Reader, hashNext func() (BlockChecksum, error)) (int64, io.Reader, error)
• type BlockChecksum
• type Checksum
  • func (cs Checksum) AppendText(b []byte) ([]byte, error)
  • func (cs Checksum) MarshalText() ([]byte, error)
  • func (cs Checksum) String() string
  • func (cs *Checksum) UnmarshalText(b []byte) error
• type ClientID
• type Manager
  • func (m *Manager) DeleteFile(baseName string) error
  • func (m *Manager) Dir() string
  • func (m *Manager) HasFilesWaiting() (has bool)
  • func (m *Manager) HashPartialFile(id ClientID, baseName string) (next func() (BlockChecksum, error), close func() error, err error)
  • func (m *Manager) IncomingFiles() []ipn.PartialFile
  • func (m *Manager) OpenFile(baseName string) (rc io.ReadCloser, size int64, err error)
  • func (m *Manager) PartialFiles(id ClientID) (ret []string, err error)
  • func (m *Manager) PutFile(id ClientID, baseName string, r io.Reader, offset, length int64) (int64, error)
  • func (m *Manager) Shutdown()
  • func (m *Manager) WaitingFiles() (ret []apitype.WaitingFile, err error)
• type ManagerOptions
  • func (opts ManagerOptions) New() *Manager

Variables

var (
	ErrNoTaildrop      = errors.New("Taildrop disabled; no storage directory")
	ErrInvalidFileName = errors.New("invalid filename")
	ErrFileExists      = errors.New("file already exists")
	ErrNotAccessible   = errors.New("Taildrop folder not configured or accessible")
)

Functions

func NextFilename

func NextFilename(name string) string

NextFilename returns the next filename in a sequence. It is used for construction a new filename if there is a conflict.

For example, "Foo.jpg" becomes "Foo (1).jpg" and "Foo (1).jpg" becomes "Foo (2).jpg".

func ResumeReader

func ResumeReader(r io.Reader, hashNext func() (BlockChecksum, error)) (int64, io.Reader, error)

ResumeReader reads and discards the leading content of r that matches the content based on the checksums that exist. It returns the number of bytes consumed, and returns an io.Reader representing the remaining content.

Types

type BlockChecksum

type BlockChecksum struct {
	Checksum  Checksum `json:"checksum"`
	Algorithm string   `json:"algo"` // always "sha256" for now
	Size      int64    `json:"size"` // always (64<<10) for now
}

BlockChecksum represents the checksum for a single block.

type Checksum

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

Checksum is an opaque checksum that is comparable.

func (Checksum) AppendText

func (cs Checksum) AppendText(b []byte) ([]byte, error)

func (Checksum) MarshalText

func (cs Checksum) MarshalText() ([]byte, error)

func (Checksum) String

func (cs Checksum) String() string

func (*Checksum) UnmarshalText

func (cs *Checksum) UnmarshalText(b []byte) error

type ClientID

type ClientID string // e.g., "n12345CNTRL"

ClientID is an opaque identifier for file resumption. A client can only list and resume partial files for its own ID. It must contain any filesystem specific characters (e.g., slashes).

type Manager

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

Manager manages the state for receiving and managing taildropped files.

func (*Manager) DeleteFile

func (m *Manager) DeleteFile(baseName string) error

DeleteFile deletes a file of the given baseName from [Handler.Dir]. This method is only allowed when [Handler.DirectFileMode] is false.

func (*Manager) Dir

func (m *Manager) Dir() string

Dir returns the directory.

func (*Manager) HasFilesWaiting

func (m *Manager) HasFilesWaiting() (has bool)

HasFilesWaiting reports whether any files are buffered in [Handler.Dir]. This always returns false when [Handler.DirectFileMode] is false.

func (*Manager) HashPartialFile

func (m *Manager) HashPartialFile(id ClientID, baseName string) (next func() (BlockChecksum, error), close func() error, err error)

HashPartialFile returns a function that hashes the next block in the file, starting from the beginning of the file. It returns (BlockChecksum{}, io.EOF) when the stream is complete. It is the caller's responsibility to call close.

func (*Manager) IncomingFiles

func (m *Manager) IncomingFiles() []ipn.PartialFile

IncomingFiles returns a list of active incoming files.

func (*Manager) OpenFile

func (m *Manager) OpenFile(baseName string) (rc io.ReadCloser, size int64, err error)

OpenFile opens a file of the given baseName from [Handler.Dir]. This method is only allowed when [Handler.DirectFileMode] is false.

func (*Manager) PartialFiles

func (m *Manager) PartialFiles(id ClientID) (ret []string, err error)

PartialFiles returns a list of partial files in [Handler.Dir] that were sent (or is actively being sent) by the provided id.

func (*Manager) PutFile

func (m *Manager) PutFile(id ClientID, baseName string, r io.Reader, offset, length int64) (int64, error)

PutFile stores a file into Manager.Dir from a given client id. The baseName must be a base filename without any slashes. The length is the expected length of content to read from r, it may be negative to indicate that it is unknown. It returns the length of the entire file.

If there is a failure reading from r, then the partial file is not deleted for some period of time. The Manager.PartialFiles and Manager.HashPartialFile methods may be used to list all partial files and to compute the hash for a specific partial file. This allows the client to determine whether to resume a partial file. While resuming, PutFile may be called again with a non-zero offset to specify where to resume receiving data at.

func (*Manager) Shutdown

func (m *Manager) Shutdown()

Shutdown shuts down the Manager. It blocks until all spawned goroutines have stopped running.

func (*Manager) WaitingFiles

func (m *Manager) WaitingFiles() (ret []apitype.WaitingFile, err error)

WaitingFiles returns the list of files that have been sent by a peer that are waiting in [Handler.Dir]. This always returns nil when [Handler.DirectFileMode] is false.

type ManagerOptions

type ManagerOptions struct {
	Logf  logger.Logf         // may be nil
	Clock tstime.DefaultClock // may be nil
	State ipn.StateStore      // may be nil

	// Dir is the directory to store received files.
	// This main either be the final location for the files
	// or just a temporary staging directory (see DirectFileMode).
	Dir string

	// DirectFileMode reports whether we are writing files
	// directly to a download directory, rather than writing them to
	// a temporary staging directory.
	//
	// The following methods:
	//	- HasFilesWaiting
	//	- WaitingFiles
	//	- DeleteFile
	//	- OpenFile
	// have no purpose in DirectFileMode.
	// They are only used to check whether files are in the staging directory,
	// copy them out, and then delete them.
	DirectFileMode bool

	// SendFileNotify is called periodically while a file is actively
	// receiving the contents for the file. There is a final call
	// to the function when reception completes.
	// It is not called if nil.
	SendFileNotify func()
}

ManagerOptions are options to configure the Manager.

func (ManagerOptions) New

func (opts ManagerOptions) New() *Manager

New initializes a new taildrop manager. It may spawn asynchronous goroutines to delete files, so the Shutdown method must be called for resource cleanup.