renter

Documentation

Overview

Package renter is responsible for uploading and downloading files on the sia network.

Index

• Constants
• Variables
• func NewRSCode(nData, nParity int) (modules.ErasureCoder, error)
• type Renter
  • func New(g modules.Gateway, cs modules.ConsensusSet, wallet modules.Wallet, ...) (*Renter, error)
  • func (r *Renter) ActiveHosts() []modules.HostDBEntry
  • func (r *Renter) AllHosts() []modules.HostDBEntry
  • func (r *Renter) Close() error
  • func (r *Renter) ContractUtility(id types.FileContractID) (modules.ContractUtility, bool)
  • func (r *Renter) Contracts() []modules.RenterContract
  • func (r *Renter) CurrentPeriod() types.BlockHeight
  • func (r *Renter) DeleteFile(nickname string) error
  • func (r *Renter) Download(p modules.RenterDownloadParameters) error
  • func (r *Renter) DownloadHistory() []modules.DownloadInfo
  • func (r *Renter) EstimateHostScore(e modules.HostDBEntry) modules.HostScoreBreakdown
  • func (r *Renter) FileList() []modules.FileInfo
  • func (r *Renter) Host(spk types.SiaPublicKey) (modules.HostDBEntry, bool)
  • func (r *Renter) LoadSharedFiles(filename string) ([]string, error)
  • func (r *Renter) LoadSharedFilesASCII(asciiSia string) ([]string, error)
  • func (r *Renter) PeriodSpending() modules.ContractorSpending
  • func (r *Renter) PriceEstimation() modules.RenterPriceEstimation
  • func (r *Renter) ProcessConsensusChange(cc modules.ConsensusChange)
  • func (r *Renter) RenameFile(currentName, newName string) error
  • func (r *Renter) ScoreBreakdown(e modules.HostDBEntry) modules.HostScoreBreakdown
  • func (r *Renter) SetSettings(s modules.RenterSettings) error
  • func (r *Renter) Settings() modules.RenterSettings
  • func (r *Renter) ShareFiles(nicknames []string, shareDest string) error
  • func (r *Renter) ShareFilesASCII(nicknames []string) (string, error)
  • func (r *Renter) Upload(up modules.FileUploadParams) error

Constants

const (

	// PersistFilename is the filename to be used when persisting renter information to a JSON file
	PersistFilename = "renter.json"
	// ShareExtension is the extension to be used
	ShareExtension = ".sia"
)

Variables

var (
	// ErrEmptyFilename is an error when filename is empty
	ErrEmptyFilename = errors.New("filename must be a nonempty string")
	// ErrPathOverload is an error when a file already exists at that location
	ErrPathOverload = errors.New("a file already exists at that location")
	// ErrUnknownPath is an error when a file cannot be found with the given path
	ErrUnknownPath = errors.New("no file known with that path")
)

var (
	//ErrBadFile is an error when a file does not qualify as .sia file
	ErrBadFile = errors.New("not a .sia file")
	// ErrIncompatible is an error when file is not compatible with current version
	ErrIncompatible = errors.New("file is not compatible with current version")
	// ErrNoNicknames is an error when no nickname is given
	ErrNoNicknames = errors.New("at least one nickname must be supplied")
	// ErrNonShareSuffix is an error when the suffix of a file does not match the defined share extension
	ErrNonShareSuffix = errors.New("suffix of file must be " + ShareExtension)
)

Functions

func NewRSCode

func NewRSCode(nData, nParity int) (modules.ErasureCoder, error)

NewRSCode creates a new Reed-Solomon encoder/decoder using the supplied parameters.

Types

type Renter

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

A Renter is responsible for tracking all of the files that a user has uploaded to Sia, as well as the locations and health of these files.

TODO: Separate the workerPool to have its own mutex. The workerPool doesn't interfere with any of the other fields in the renter, should be fine for it to have a separate mutex, that way operations on the worker pool don't block operations on other parts of the struct. If we're going to do it that way, might make sense to split the worker pool off into it's own struct entirely the same way that we split of the memoryManager entirely.

func New

func New(g modules.Gateway, cs modules.ConsensusSet, wallet modules.Wallet, tpool modules.TransactionPool, persistDir string) (*Renter, error)

New returns an initialized renter.

func (*Renter) ActiveHosts

func (r *Renter) ActiveHosts() []modules.HostDBEntry

ActiveHosts returns an array of hostDB's active hosts

func (*Renter) AllHosts

func (r *Renter) AllHosts() []modules.HostDBEntry

AllHosts returns an array of all hosts

func (*Renter) Close

func (r *Renter) Close() error

Close closes the Renter and its dependencies

func (*Renter) ContractUtility

func (r *Renter) ContractUtility(id types.FileContractID) (modules.ContractUtility, bool)

ContractUtility returns the utility field for a given contract, along with a bool indicating if it exists.

func (*Renter) Contracts

func (r *Renter) Contracts() []modules.RenterContract

Contracts returns an array of host contractor's contracts

func (*Renter) CurrentPeriod

func (r *Renter) CurrentPeriod() types.BlockHeight

CurrentPeriod returns the host contractor's current period

func (*Renter) DeleteFile

func (r *Renter) DeleteFile(nickname string) error

DeleteFile removes a file entry from the renter and deletes its data from the hosts it is stored on.

TODO: The data is not cleared from any contracts where the host is not immediately online.

func (*Renter) Download

func (r *Renter) Download(p modules.RenterDownloadParameters) error

Download performs a file download using the passed parameters.

func (*Renter) DownloadHistory

func (r *Renter) DownloadHistory() []modules.DownloadInfo

DownloadHistory returns the list of downloads that have been performed. Will include downloads that have not yet completed. Downloads will be roughly, but not precisely, sorted according to start time.

TODO: Currently the DownloadHistory only contains downloads from this session, does not contain downloads that were executed for the purposes of repairing, and has no way to clear the download history if it gets long or unwieldy. It's not entirely certain which of the missing features are actually desirable, please consult core team + app dev community before deciding what to implement.

func (*Renter) EstimateHostScore

func (r *Renter) EstimateHostScore(e modules.HostDBEntry) modules.HostScoreBreakdown

EstimateHostScore returns the estimated host score

func (*Renter) FileList

func (r *Renter) FileList() []modules.FileInfo

FileList returns all of the files that the renter has.

func (*Renter) Host

func (r *Renter) Host(spk types.SiaPublicKey) (modules.HostDBEntry, bool)

Host returns the host associated with the given public key

func (*Renter) LoadSharedFiles

func (r *Renter) LoadSharedFiles(filename string) ([]string, error)

LoadSharedFiles loads a .sia file into the renter. It returns the nicknames of the loaded files.

func (*Renter) LoadSharedFilesASCII

func (r *Renter) LoadSharedFilesASCII(asciiSia string) ([]string, error)

LoadSharedFilesASCII loads an ASCII-encoded .sia file into the renter. It returns the nicknames of the loaded files.

func (*Renter) PeriodSpending

func (r *Renter) PeriodSpending() modules.ContractorSpending

PeriodSpending returns the host contractor's period spending

func (*Renter) PriceEstimation

func (r *Renter) PriceEstimation() modules.RenterPriceEstimation

PriceEstimation estimates the cost in siacoins of performing various storage and data operations.

TODO: Make this function line up with the actual settings in the renter. Perhaps even make it so it uses the renter's actual contracts if it has any.

func (*Renter) ProcessConsensusChange

func (r *Renter) ProcessConsensusChange(cc modules.ConsensusChange)

ProcessConsensusChange returns the process consensus change

func (*Renter) RenameFile

func (r *Renter) RenameFile(currentName, newName string) error

RenameFile takes an existing file and changes the nickname. The original file must exist, and there must not be any file that already has the replacement nickname.

func (*Renter) ScoreBreakdown

func (r *Renter) ScoreBreakdown(e modules.HostDBEntry) modules.HostScoreBreakdown

ScoreBreakdown returns the score breakdown

func (*Renter) SetSettings

func (r *Renter) SetSettings(s modules.RenterSettings) error

SetSettings will update the settings for the renter.

func (*Renter) Settings

func (r *Renter) Settings() modules.RenterSettings

Settings returns the host contractor's allowance

func (*Renter) ShareFiles

func (r *Renter) ShareFiles(nicknames []string, shareDest string) error

ShareFiles saves the specified files to shareDest.

func (*Renter) ShareFilesASCII

func (r *Renter) ShareFilesASCII(nicknames []string) (string, error)

ShareFilesASCII returns the specified files in ASCII format.

func (*Renter) Upload

func (r *Renter) Upload(up modules.FileUploadParams) error

Upload instructs the renter to start tracking a file. The renter will automatically upload and repair tracked files using a background loop.