storage

Documentation

Overview

Package storage implements storage backends for package torrent.

Index

• func CreateNativeZeroLengthFile(name string) error
• func NewMMapWithCompletion(baseDir string, completion PieceCompletion) *mmapClientImpl
• func NewSqlitePieceCompletion(dir string) (ret *sqlitePieceCompletion, err error)
• func ToSafeFilePath(fileInfoComponents ...string) (string, error)
• type Client
  • func NewClient(cl ClientImpl) *Client
  • func (cl Client) OpenTorrent(info *metainfo.Info, infoHash metainfo.Hash) (*Torrent, error)
• type ClientImpl
  • func NewResourcePieces(p PieceProvider) ClientImpl
  • func NewResourcePiecesOpts(p PieceProvider, opts ResourcePiecesOpts) ClientImpl
• type ClientImplCloser
  • func NewBoltDB(filePath string) ClientImplCloser
  • func NewFile(baseDir string) ClientImplCloser
  • func NewFileByInfoHash(baseDir string) ClientImplCloser
  • func NewFileOpts(opts NewFileClientOpts) ClientImplCloser
  • func NewFileWithCompletion(baseDir string, completion PieceCompletion) ClientImplCloser
  • func NewFileWithCustomPathMaker(baseDir string, ...) ClientImplCloser
  • func NewFileWithCustomPathMakerAndCompletion(baseDir string, pathMaker TorrentDirFilePathMaker, completion PieceCompletion) ClientImplCloser
  • func NewMMap(baseDir string) ClientImplCloser
• type Completion
• type ConsecutiveChunkReader
• type FileMapping
  • func WrapFileMapping(region mmap.MMap, file *os.File) FileMapping
• type FilePathMaker
• type FilePathMakerOpts
• type MovePrefixer
• type NewFileClientOpts
• type Piece
  • func (p Piece) ReadAt(b []byte, off int64) (n int, err error)
  • func (p Piece) WriteAt(b []byte, off int64) (n int, err error)
  • func (p Piece) WriteTo(w io.Writer) (int64, error)
• type PieceCompletion
  • func NewBoltPieceCompletion(dir string) (ret PieceCompletion, err error)
  • func NewDefaultPieceCompletionForDir(dir string) (PieceCompletion, error)
  • func NewMapPieceCompletion() PieceCompletion
• type PieceCompletionGetSetter
• type PieceImpl
• type PieceProvider
• type PrefixDeleter
• type ResourcePiecesOpts
• type SelfHashing
• type SizedPutter
• type Torrent
  • func (t Torrent) Piece(p metainfo.Piece) Piece
  • func (t Torrent) PieceWithHash(p metainfo.Piece, pieceHash g.Option[[]byte]) Piece
• type TorrentCapacity
• type TorrentDirFilePathMaker
• type TorrentImpl

Functions

func CreateNativeZeroLengthFile

func CreateNativeZeroLengthFile(name string) error

A helper to create zero-length files which won't appear for file-orientated storage since no writes will ever occur to them (no torrent data is associated with a zero-length file). The caller should make sure the file name provided is safe/sanitized.

func NewMMapWithCompletion

func NewMMapWithCompletion(baseDir string, completion PieceCompletion) *mmapClientImpl

func NewSqlitePieceCompletion

func NewSqlitePieceCompletion(dir string) (ret *sqlitePieceCompletion, err error)

func ToSafeFilePath

func ToSafeFilePath(fileInfoComponents ...string) (string, error)

Combines file info path components, ensuring the result won't escape into parent directories.

Types

type Client

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

func NewClient

func NewClient(cl ClientImpl) *Client

func (Client) OpenTorrent

func (cl Client) OpenTorrent(info *metainfo.Info, infoHash metainfo.Hash) (*Torrent, error)

type ClientImpl

type ClientImpl interface {
	OpenTorrent(info *metainfo.Info, infoHash metainfo.Hash) (TorrentImpl, error)
}

Represents data storage for an unspecified torrent.

func NewResourcePieces

func NewResourcePieces(p PieceProvider) ClientImpl

func NewResourcePiecesOpts

func NewResourcePiecesOpts(p PieceProvider, opts ResourcePiecesOpts) ClientImpl

type ClientImplCloser

type ClientImplCloser interface {
	ClientImpl
	Close() error
}

func NewBoltDB

func NewBoltDB(filePath string) ClientImplCloser

func NewFile

func NewFile(baseDir string) ClientImplCloser

All Torrent data stored in this baseDir. The info names of each torrent are used as directories.

func NewFileByInfoHash

func NewFileByInfoHash(baseDir string) ClientImplCloser

File storage with data partitioned by infohash.

func NewFileOpts

func NewFileOpts(opts NewFileClientOpts) ClientImplCloser

NewFileOpts creates a new ClientImplCloser that stores files using the OS native filesystem.

func NewFileWithCompletion

func NewFileWithCompletion(baseDir string, completion PieceCompletion) ClientImplCloser

func NewFileWithCustomPathMaker

func NewFileWithCustomPathMaker(baseDir string, pathMaker func(baseDir string, info *metainfo.Info, infoHash metainfo.Hash) string) ClientImplCloser

Deprecated: Allows passing a function to determine the path for storing torrent data. The function is responsible for sanitizing the info if it uses some part of it (for example sanitizing info.Name).

func NewFileWithCustomPathMakerAndCompletion

func NewFileWithCustomPathMakerAndCompletion(
	baseDir string,
	pathMaker TorrentDirFilePathMaker,
	completion PieceCompletion,
) ClientImplCloser

Deprecated: Allows passing custom PieceCompletion

func NewMMap

func NewMMap(baseDir string) ClientImplCloser

TODO: Support all the same native filepath configuration that NewFileOpts provides.

type Completion

type Completion struct {
	Complete bool
	Ok       bool
	Err      error
}

type ConsecutiveChunkReader

type ConsecutiveChunkReader interface {
	ReadConsecutiveChunks(prefix string) (io.ReadCloser, error)
}

type FileMapping

type FileMapping = mmap_span.Mmap

func WrapFileMapping

func WrapFileMapping(region mmap.MMap, file *os.File) FileMapping

Combines a mmapped region and file into a storage Mmap abstraction, which handles closing the mmap file handle.

type FilePathMaker

type FilePathMaker func(opts FilePathMakerOpts) string

Determines the filepath to be used for each file in a torrent.

type FilePathMakerOpts

type FilePathMakerOpts struct {
	Info *metainfo.Info
	File *metainfo.FileInfo
}

Info passed to a FilePathMaker.

type MovePrefixer

type MovePrefixer interface {
	MovePrefix(old, new string) error
}

type NewFileClientOpts

type NewFileClientOpts struct {
	// The base directory for all downloads.
	ClientBaseDir   string
	FilePathMaker   FilePathMaker
	TorrentDirMaker TorrentDirFilePathMaker
	PieceCompletion PieceCompletion
}

type Piece

type Piece struct {
	PieceImpl
	// contains filtered or unexported fields
}

func (Piece) ReadAt

func (p Piece) ReadAt(b []byte, off int64) (n int, err error)

func (Piece) WriteAt

func (p Piece) WriteAt(b []byte, off int64) (n int, err error)

func (Piece) WriteTo

func (p Piece) WriteTo(w io.Writer) (int64, error)

Why do we have this wrapper? Well PieceImpl doesn't implement io.Reader, so we can't let io.Copy and friends check for io.WriterTo and fallback for us since they expect an io.Reader.

type PieceCompletion

type PieceCompletion interface {
	PieceCompletionGetSetter
	Close() error
}

Implementations track the completion of pieces. It must be concurrent-safe.

func NewBoltPieceCompletion

func NewBoltPieceCompletion(dir string) (ret PieceCompletion, err error)

func NewDefaultPieceCompletionForDir

func NewDefaultPieceCompletionForDir(dir string) (PieceCompletion, error)

sqlite is always the default when available.

func NewMapPieceCompletion

func NewMapPieceCompletion() PieceCompletion

type PieceCompletionGetSetter

type PieceCompletionGetSetter interface {
	Get(metainfo.PieceKey) (Completion, error)
	Set(_ metainfo.PieceKey, complete bool) error
}

type PieceImpl

type PieceImpl interface {
	// These interfaces are not as strict as normally required. They can
	// assume that the parameters are appropriate for the dimensions of the
	// piece.
	io.ReaderAt
	io.WriterAt
	// Called when the client believes the piece data will pass a hash check.
	// The storage can move or mark the piece data as read-only as it sees
	// fit.
	MarkComplete() error
	MarkNotComplete() error
	// Returns true if the piece is complete.
	Completion() Completion
}

Interacts with torrent piece data. Optional interfaces to implement include:

io.WriterTo, such as when a piece supports a more efficient way to write out incomplete chunks.
SelfHashing, such as when a piece supports a more efficient way to hash its contents.

type PieceProvider

type PieceProvider interface {
	resource.Provider
}

type PrefixDeleter

type PrefixDeleter interface {
	DeletePrefix(prefix string) error
}

type ResourcePiecesOpts

type ResourcePiecesOpts struct {
	// After marking a piece complete, don't bother deleting its incomplete blobs.
	LeaveIncompleteChunks bool
	// Sized puts require being able to stream from a statement executed on another connection.
	// Without them, we buffer the entire read and then put that.
	NoSizedPuts bool
	Capacity    *int64
}

type SelfHashing

type SelfHashing interface {
	SelfHash() (metainfo.Hash, error)
}

Allows a storage backend to override hashing (i.e. if it can do it more efficiently than the torrent client can)

type SizedPutter

type SizedPutter interface {
	PutSized(io.Reader, int64) error
}

type Torrent

type Torrent struct {
	TorrentImpl
}

func (Torrent) Piece

func (t Torrent) Piece(p metainfo.Piece) Piece

Deprecated. Use PieceWithHash, as this doesn't work with pure v2 torrents.

func (Torrent) PieceWithHash

func (t Torrent) PieceWithHash(p metainfo.Piece, pieceHash g.Option[[]byte]) Piece

type TorrentCapacity

type TorrentCapacity *func() (cap int64, capped bool)

type TorrentDirFilePathMaker

type TorrentDirFilePathMaker func(baseDir string, info *metainfo.Info, infoHash metainfo.Hash) string

Determines the directory for a given torrent within a storage client.

type TorrentImpl

type TorrentImpl struct {
	// v2 infos might not have the piece hash available even if we have the info. The
	// metainfo.Piece.Hash method was removed to enforce this.
	Piece func(p metainfo.Piece) PieceImpl
	// Preferred over PieceWithHash. Called with the piece hash if it's available.
	PieceWithHash func(p metainfo.Piece, pieceHash g.Option[[]byte]) PieceImpl
	Close         func() error
	Flush         func() error
	// Storages that share the same space, will provide equal pointers. The function is called once
	// to determine the storage for torrents sharing the same function pointer, and mutated in
	// place.
	Capacity TorrentCapacity
}

Data storage bound to a torrent.