renterutil

Documentation

Overview

Package renterutil provides convenience functions for common renter actions.

Index

• Variables
• type HostError
  • func (he HostError) Error() string
  • func (he HostError) Unwrap() error
• type HostErrorSet
  • func (hes HostErrorSet) Error() string
• type HostSet
  • func NewHostSet(hkr renter.HostKeyResolver, currentHeight types.BlockHeight) *HostSet
  • func (set *HostSet) AddHost(c renter.Contract)
  • func (set *HostSet) Close() error
  • func (set *HostSet) HasHost(hostKey hostdb.HostPublicKey) bool
  • func (set *HostSet) SetLockTimeout(timeout time.Duration)
  • func (set *HostSet) SetRPCStatsRecorder(r proto.RPCStatsRecorder)
• type Migrator
  • func NewMigrator(hosts *HostSet) *Migrator
  • func (m *Migrator) AddFile(f *renter.MetaFile, source io.Reader, onFinish func(*renter.MetaFile) error) error
  • func (m *Migrator) Flush() error
  • func (m *Migrator) NeedsMigrate(f *renter.MetaFile) bool
• type PseudoFS
  • func NewFileSystem(root string, hosts *HostSet) *PseudoFS
  • func (fs *PseudoFS) Chmod(name string, mode os.FileMode) error
  • func (fs *PseudoFS) Close() error
  • func (fs *PseudoFS) Create(name string, minShards int) (*PseudoFile, error)
  • func (fs *PseudoFS) GC() error
  • func (fs *PseudoFS) Mkdir(name string, perm os.FileMode) error
  • func (fs *PseudoFS) MkdirAll(path string, perm os.FileMode) error
  • func (fs *PseudoFS) Open(name string) (*PseudoFile, error)
  • func (fs *PseudoFS) OpenFile(name string, flag int, perm os.FileMode, minShards int) (*PseudoFile, error)
  • func (fs *PseudoFS) Remove(name string) error
  • func (fs *PseudoFS) RemoveAll(path string) error
  • func (fs *PseudoFS) Rename(oldname, newname string) error
  • func (fs *PseudoFS) Stat(name string) (os.FileInfo, error)
• type PseudoFile
  • func (pf PseudoFile) Close() error
  • func (pf PseudoFile) Free() error
  • func (pf PseudoFile) Name() string
  • func (pf PseudoFile) Read(p []byte) (int, error)
  • func (pf PseudoFile) ReadAt(p []byte, off int64) (int, error)
  • func (pf PseudoFile) ReadAtP(p []byte, off int64) (int, error)
  • func (pf PseudoFile) Readdir(n int) ([]os.FileInfo, error)
  • func (pf PseudoFile) Readdirnames(n int) ([]string, error)
  • func (pf PseudoFile) Seek(offset int64, whence int) (int64, error)
  • func (pf PseudoFile) Stat() (os.FileInfo, error)
  • func (pf PseudoFile) Sync() error
  • func (pf PseudoFile) Truncate(size int64) error
  • func (pf PseudoFile) Write(p []byte) (int, error)
  • func (pf PseudoFile) WriteAt(p []byte, off int64) (int, error)
• type SiadClient
  • func NewSiadClient(addr, password string) *SiadClient
  • func (c *SiadClient) AcceptTransactionSet(txnSet []types.Transaction) error
  • func (c *SiadClient) Address() (types.UnlockHash, error)
  • func (c *SiadClient) ChainHeight() (types.BlockHeight, error)
  • func (c *SiadClient) FeeEstimate() (minFee, maxFee types.Currency, err error)
  • func (c *SiadClient) FundTransaction(txn *types.Transaction, amount types.Currency) ([]crypto.Hash, error)
  • func (c *SiadClient) LookupHost(prefix string) (hostdb.HostPublicKey, error)
  • func (c *SiadClient) ResolveHostKey(pubkey hostdb.HostPublicKey) (modules.NetAddress, error)
  • func (c *SiadClient) SignTransaction(txn *types.Transaction, toSign []crypto.Hash) error
  • func (c *SiadClient) Synced() (bool, error)
  • func (c *SiadClient) UnconfirmedParents(txn types.Transaction) ([]types.Transaction, error)

Variables

var ErrAppendOnly = errors.New("file is append-only")

ErrAppendOnly is returned for seek operations on append-only files.

var ErrDirectory = errors.New("file is a directory")

ErrDirectory is returned for operations that are not valid for directories.

var ErrInvalidFileDescriptor = errors.New("invalid file descriptor")

ErrInvalidFileDescriptor is returned when I/O is attempted on an unknown file descriptor.

var ErrNoHostAnnouncement = errors.New("host announcement not found")

ErrNoHostAnnouncement is returned when a host announcement cannot be found.

var ErrNotDirectory = errors.New("file is not a directory")

ErrNotDirectory is returned for operations that are not valid for files.

var ErrNotReadable = errors.New("file is not readable")

ErrNotReadable is returned for read operations on write-only files.

var ErrNotWriteable = errors.New("file is not writeable")

ErrNotWriteable is returned for write operations on read-only files.

Types

type HostError

type HostError struct {
	HostKey hostdb.HostPublicKey
	Err     error
}

A HostError associates an error with a given host.

func (HostError) Error

func (he HostError) Error() string

Error implements error.

func (HostError) Unwrap

func (he HostError) Unwrap() error

Unwrap returns the underlying error.

type HostErrorSet

type HostErrorSet []*HostError

A HostErrorSet is a collection of errors from various hosts.

func (HostErrorSet) Error

func (hes HostErrorSet) Error() string

Error implements error.

type HostSet

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

A HostSet is a collection of renter-host protocol sessions.

func NewHostSet

func NewHostSet(hkr renter.HostKeyResolver, currentHeight types.BlockHeight) *HostSet

NewHostSet creates an empty HostSet using the provided resolver and current height.

func (*HostSet) AddHost

func (set *HostSet) AddHost(c renter.Contract)

AddHost adds a host to the set for later use.

func (*HostSet) Close

func (set *HostSet) Close() error

Close closes all of the sessions in the set.

func (*HostSet) HasHost

func (set *HostSet) HasHost(hostKey hostdb.HostPublicKey) bool

HasHost returns true if the specified host is in the set.

func (*HostSet) SetLockTimeout

func (set *HostSet) SetLockTimeout(timeout time.Duration)

SetLockTimeout sets the timeout used for all Lock RPCs in Sessions initiated by the HostSet.

func (*HostSet) SetRPCStatsRecorder

func (set *HostSet) SetRPCStatsRecorder(r proto.RPCStatsRecorder)

SetRPCStatsRecorder sets the RPCStatsRecorder for all Sessions initiated by the HostSet.

type Migrator

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

A Migrator facilitates migrating metafiles from one set of hosts to another.

func NewMigrator

func NewMigrator(hosts *HostSet) *Migrator

NewMigrator creates a Migrator that migrates files to the specified host set.

func (*Migrator) AddFile

func (m *Migrator) AddFile(f *renter.MetaFile, source io.Reader, onFinish func(*renter.MetaFile) error) error

AddFile uses data read from source to migrate f to the Migrator's new host set. Since the Migrator buffers data internally, the migration may not be complete until the Flush method has been called. onFinish is called on the new metafile when the file has been fully migrated.

func (*Migrator) Flush

func (m *Migrator) Flush() error

Flush flushes any un-uploaded migration data to the new hosts. Flush must be called to guarantee that migration is complete.

func (*Migrator) NeedsMigrate

func (m *Migrator) NeedsMigrate(f *renter.MetaFile) bool

NeedsMigrate returns true if at least one of the hosts of f is not present in the Migrator's HostSet.

type PseudoFS

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

PseudoFS implements a filesystem by uploading and downloading data from Sia hosts.

func NewFileSystem

func NewFileSystem(root string, hosts *HostSet) *PseudoFS

NewFileSystem returns a new pseudo-filesystem rooted at root, which must be a directory containing only metafiles and other directories.

func (*PseudoFS) Chmod

func (fs *PseudoFS) Chmod(name string, mode os.FileMode) error

Chmod changes the mode of the named file to mode.

func (*PseudoFS) Close

func (fs *PseudoFS) Close() error

Close closes the filesystem by flushing any uncommitted writes, closing any open files, and terminating all active host sessions.

func (*PseudoFS) Create

func (fs *PseudoFS) Create(name string, minShards int) (*PseudoFile, error)

Create creates the named file with the specified redundancy and mode 0666 (before umask), truncating it if it already exists. The returned file has mode O_RDWR.

func (*PseudoFS) GC

func (fs *PseudoFS) GC() error

GC deletes unused data from the filesystem's host set. Any data not referenced by the files within the filesystem will be deleted. This has important implications for shared files: if you share a metafile and do not retain a local copy of it, then running GC will cause that file's data to be deleted, making it inaccessible.

GC complements the (PseudoFile).Free method. Free cannot safely delete non-full sectors, because those sectors may be referenced by other files, e.g. when multiple files are packed into a single sector. GC is guaranteed to delete all unreferenced sectors, but is much slower than Free because it must examine the full filesystem. Free should be called frequently as a "first line of defense," while GC should be called infrequently to remove any sectors missed by Free.

func (*PseudoFS) Mkdir

func (fs *PseudoFS) Mkdir(name string, perm os.FileMode) error

Mkdir creates a new directory with the specified name and permission bits (before umask).

func (*PseudoFS) MkdirAll

func (fs *PseudoFS) MkdirAll(path string, perm os.FileMode) error

MkdirAll creates a directory named path, along with any necessary parents, and returns nil, or else returns an error. The permission bits perm (before umask) are used for all directories that MkdirAll creates. If path is already a directory, MkdirAll does nothing and returns nil.

func (*PseudoFS) Open

func (fs *PseudoFS) Open(name string) (*PseudoFile, error)

Open opens the named file for reading. The returned file is read-only.

func (*PseudoFS) OpenFile

func (fs *PseudoFS) OpenFile(name string, flag int, perm os.FileMode, minShards int) (*PseudoFile, error)

OpenFile is the generalized open call; most users will use Open or Create instead. It opens the named file with specified flag (os.O_RDONLY etc.) and perm (before umask), if applicable.

func (*PseudoFS) Remove

func (fs *PseudoFS) Remove(name string) error

Remove removes the named file or (empty) directory. It does NOT delete the file data on the host; use (PseudoFS).GC and (PseudoFile).Free for that.

func (*PseudoFS) RemoveAll

func (fs *PseudoFS) RemoveAll(path string) error

RemoveAll removes path and any children it contains. It removes everything it can but returns the first error it encounters. If the path does not exist, RemoveAll returns nil (no error).

func (*PseudoFS) Rename

func (fs *PseudoFS) Rename(oldname, newname string) error

Rename renames (moves) oldpath to newpath. If newpath already exists and is not a directory, Rename replaces it. OS-specific restrictions may apply when oldpath and newpath are in different directories.

func (*PseudoFS) Stat

func (fs *PseudoFS) Stat(name string) (os.FileInfo, error)

Stat returns the FileInfo structure describing file.

type PseudoFile

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

A PseudoFile presents a file-like interface for a metafile stored on Sia hosts.

func (PseudoFile) Close

func (pf PseudoFile) Close() error

Close implements io.Closer.

func (PseudoFile) Free

func (pf PseudoFile) Free() error

Free truncates the file to 0 bytes and deletes file data from the filesystem's host set. Free only deletes sectors that it can prove are exclusively storing the file's data. If multiple files were packed into the same sector, Free will not delete that sector. Similarly, Free cannot safely delete "trailing" sectors at the end of a file. Use (PseudoFS).GC to delete such sectors after calling Remove on all the relevant files.

Note that Free also discards any uncommitted Writes, so it may be necessary to call Sync prior to Free.

func (PseudoFile) Name

func (pf PseudoFile) Name() string

Name returns the file's name, as passed to OpenFile.

func (PseudoFile) Read

func (pf PseudoFile) Read(p []byte) (int, error)

Read implements io.Reader.

func (PseudoFile) ReadAt

func (pf PseudoFile) ReadAt(p []byte, off int64) (int, error)

ReadAt implements io.ReaderAt.

func (PseudoFile) ReadAtP

func (pf PseudoFile) ReadAtP(p []byte, off int64) (int, error)

ReadAtP is a helper method that makes multiple concurrent ReadAt calls, with each call filling part of p. This may increase throughput depending on the file's redundancy. For example, if the file is stored at 2x redundancy, then in ideal circumstances, ReadAtP will be 2x faster than the equivalent ReadAt call.

ReadAtP returns the first non-nil error returned by a ReadAt call. The contents of p are undefined if an error other than io.EOF is returned.

func (PseudoFile) Readdir

func (pf PseudoFile) Readdir(n int) ([]os.FileInfo, error)

Readdir reads the contents of the directory associated with pf and returns a slice of up to n FileInfo values, as would be returned by Lstat, in directory order. Subsequent calls on the same file will yield further FileInfos.

If n > 0, Readdir returns at most n FileInfo structures. In this case, if Readdir returns an empty slice, it will return a non-nil error explaining why. At the end of a directory, the error is io.EOF.

If n <= 0, Readdir returns all the FileInfo from the directory in a single slice. In this case, if Readdir succeeds (reads all the way to the end of the directory), it returns the slice and a nil error. If it encounters an error before the end of the directory, Readdir returns the FileInfo read until that point and a non-nil error.

func (PseudoFile) Readdirnames

func (pf PseudoFile) Readdirnames(n int) ([]string, error)

Readdirnames reads and returns a slice of names from the directory pf.

If n > 0, Readdirnames returns at most n names. In this case, if Readdirnames returns an empty slice, it will return a non-nil error explaining why. At the end of a directory, the error is io.EOF.

If n <= 0, Readdirnames returns all the names from the directory in a single slice. In this case, if Readdirnames succeeds (reads all the way to the end of the directory), it returns the slice and a nil error. If it encounters an error before the end of the directory, Readdirnames returns the names read until that point and a non-nil error.

func (PseudoFile) Seek

func (pf PseudoFile) Seek(offset int64, whence int) (int64, error)

Seek implements io.Seeker.

func (PseudoFile) Stat

func (pf PseudoFile) Stat() (os.FileInfo, error)

Stat returns the FileInfo structure describing the file. If the file is a metafile, its renter.MetaIndex will be available via the Sys method.

func (PseudoFile) Sync

func (pf PseudoFile) Sync() error

Sync commits the current contents of the file to stable storage. Any new data will be uploaded to hosts, and the metafile will be atomically updated to match the current state of the file. Calling Sync on one file may cause other files to be synced as well. Sync typically results in a full sector of data being uploaded to each host.

func (PseudoFile) Truncate

func (pf PseudoFile) Truncate(size int64) error

Truncate changes the size of the file. It does not change the I/O offset. The new size must not exceed the current size.

func (PseudoFile) Write

func (pf PseudoFile) Write(p []byte) (int, error)

Write implements io.Writer.

func (PseudoFile) WriteAt

func (pf PseudoFile) WriteAt(p []byte, off int64) (int, error)

WriteAt implements io.WriterAt.

type SiadClient

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

SiadClient wraps the siad API client. It satisfies the proto.Wallet, proto.TransactionPool, and renter.HostKeyResolver interfaces. The proto.Wallet methods require that the wallet is unlocked.

func NewSiadClient

func NewSiadClient(addr, password string) *SiadClient

NewSiadClient returns a SiadClient that communicates with the siad API server at the specified address.

func (*SiadClient) AcceptTransactionSet

func (c *SiadClient) AcceptTransactionSet(txnSet []types.Transaction) error

AcceptTransactionSet submits a transaction set to the transaction pool, where it will be broadcast to other peers.

func (*SiadClient) Address

func (c *SiadClient) Address() (types.UnlockHash, error)

Address returns an address derived from the wallet's seed.

func (*SiadClient) ChainHeight

func (c *SiadClient) ChainHeight() (types.BlockHeight, error)

ChainHeight returns the current block height.

func (*SiadClient) FeeEstimate

func (c *SiadClient) FeeEstimate() (minFee, maxFee types.Currency, err error)

FeeEstimate returns the current estimate for transaction fees, in Hastings per byte.

func (*SiadClient) FundTransaction

func (c *SiadClient) FundTransaction(txn *types.Transaction, amount types.Currency) ([]crypto.Hash, error)

FundTransaction adds the specified signatures to the transaction using private keys known to the wallet.

func (*SiadClient) LookupHost

func (c *SiadClient) LookupHost(prefix string) (hostdb.HostPublicKey, error)

LookupHost returns the host public key matching the specified prefix.

func (*SiadClient) ResolveHostKey

func (c *SiadClient) ResolveHostKey(pubkey hostdb.HostPublicKey) (modules.NetAddress, error)

ResolveHostKey resolves a host public key to that host's most recently announced network address.

func (*SiadClient) SignTransaction

func (c *SiadClient) SignTransaction(txn *types.Transaction, toSign []crypto.Hash) error

SignTransaction adds the specified signatures to the transaction using private keys known to the wallet.

func (*SiadClient) Synced

func (c *SiadClient) Synced() (bool, error)

Synced returns whether the siad node believes it is fully synchronized with the rest of the network.

func (*SiadClient) UnconfirmedParents

func (c *SiadClient) UnconfirmedParents(txn types.Transaction) ([]types.Transaction, error)

UnconfirmedParents returns any currently-unconfirmed parents of the specified transaction.