hosttree

README

Host Tree

Coming Soon...

Weight Function

The HostTree Weight Function is a function used to weight a given HostDBEntry in the tree. Each HostTree is initialized with a weight function. This allows the entries to be selected at random, weighted by the hosttree's weight function.

NOTE: Developers should be aware of where the weight function is defined and what it uses to determine the weight of an entry. The weight function may or may not require a lock from another package in order to calculate the weight safely.

Documentation

Index

• Constants
• Variables
• type Filter
  • func NewFilter(resolver modules.Resolver) *Filter
  • func (af *Filter) Add(host modules.NetAddress)
  • func (af *Filter) Filtered(host modules.NetAddress) bool
  • func (af *Filter) Reset()
• type HostAdjustments
  • func (h HostAdjustments) HostScoreBreakdown(totalScore types.Currency, ignoreAge, ignoreDuration, ignoreUptime bool) modules.HostScoreBreakdown
  • func (h HostAdjustments) Score() types.Currency
• type HostTree
  • func New(wf WeightFunc, resolver modules.Resolver) *HostTree
  • func (ht *HostTree) All() []modules.HostDBEntry
  • func (ht *HostTree) Insert(hdbe modules.HostDBEntry) error
  • func (ht *HostTree) Modify(hdbe modules.HostDBEntry) error
  • func (ht *HostTree) Remove(pk types.SiaPublicKey) error
  • func (ht *HostTree) Select(spk types.SiaPublicKey) (modules.HostDBEntry, bool)
  • func (ht *HostTree) SelectRandom(n int, blacklist, addressBlacklist []types.SiaPublicKey) []modules.HostDBEntry
  • func (ht *HostTree) SetFiltered(pubKey types.SiaPublicKey, filtered bool) error
  • func (ht *HostTree) SetWeightFunction(wf WeightFunc) error
• type ScoreBreakdown
• type WeightFunc

Constants

const (
	// IPv4FilterRange is the number of bits within an IP address (starting
	// from the left) which have to be unique for the host not to be filtered.
	IPv4FilterRange = 24
	// IPv6FilterRange is the number of bits within an IP address (starting
	// from the left) which have to be unique for the host not to be filtered.
	IPv6FilterRange = 54
)

Variables

var (
	// ErrHostExists is returned if an Insert is called with a public key that
	// already exists in the tree.
	ErrHostExists = errors.New("host already exists in the tree")

	// ErrNoSuchHost is returned if Remove is called with a public key that does
	// not exist in the tree.
	ErrNoSuchHost = errors.New("no host with specified public key")
)

Types

type Filter

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

Filter filters host addresses which belong to the same subnet to avoid selecting hosts from the same region.

func NewFilter

func NewFilter(resolver modules.Resolver) *Filter

NewFilter creates a new addressFilter object.

func (*Filter) Add

func (af *Filter) Add(host modules.NetAddress)

Add adds a host to the filter. This will resolve the hostname into one or more IP addresses, extract the subnets used by those addresses and add the subnets to the filter. Add doesn't return an error, but if the addresses of a host can't be resolved it will be handled as if the host had no addresses associated with it.

func (*Filter) Filtered

func (af *Filter) Filtered(host modules.NetAddress) bool

Filtered checks if a host uses a subnet that is already in use by a host that was previously added to the filter. If it is in use, or if the host is associated with 2 addresses of the same type (e.g. IPv4 and IPv4) or if it is associated with more than 2 addresses, Filtered will return 'true'.

func (*Filter) Reset

func (af *Filter) Reset()

Reset clears the filter's contents.

type HostAdjustments

type HostAdjustments struct {
	AcceptContractAdjustment   float64
	AgeAdjustment              float64
	BasePriceAdjustment        float64
	BurnAdjustment             float64
	CollateralAdjustment       float64
	DurationAdjustment         float64
	InteractionAdjustment      float64
	PriceAdjustment            float64
	StorageRemainingAdjustment float64
	UptimeAdjustment           float64
	VersionAdjustment          float64
}

HostAdjustments contains all the adjustments relevant to a host's score and implements the scoreBreakdown interface.

func (HostAdjustments) HostScoreBreakdown

func (h HostAdjustments) HostScoreBreakdown(totalScore types.Currency, ignoreAge, ignoreDuration, ignoreUptime bool) modules.HostScoreBreakdown

HostScoreBreakdown converts a HostAdjustments object into a modules.HostScoreBreakdown.

func (HostAdjustments) Score

func (h HostAdjustments) Score() types.Currency

Score combines the individual adjustments of the breakdown into a single score.

type HostTree

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

HostTree is used to store and select host database entries. Each HostTree is initialized with a weighting func that is able to assign a weight to each entry. The entries can then be selected at random, weighted by the weight func.

func New

func New(wf WeightFunc, resolver modules.Resolver) *HostTree

New creates a new HostTree given a weight function and a resolver for hostnames.

func (*HostTree) All

func (ht *HostTree) All() []modules.HostDBEntry

All returns all of the hosts in the host tree, sorted by weight.

func (*HostTree) Insert

func (ht *HostTree) Insert(hdbe modules.HostDBEntry) error

Insert inserts the entry provided to `entry` into the host tree. Insert will return an error if the input host already exists.

func (*HostTree) Modify

func (ht *HostTree) Modify(hdbe modules.HostDBEntry) error

Modify updates a host entry at the given public key, replacing the old entry with the entry provided by `newEntry`.

func (*HostTree) Remove

func (ht *HostTree) Remove(pk types.SiaPublicKey) error

Remove removes the host with the public key provided by `pk`.

func (*HostTree) Select

func (ht *HostTree) Select(spk types.SiaPublicKey) (modules.HostDBEntry, bool)

Select returns the host with the provided public key, should the host exist.

func (*HostTree) SelectRandom

func (ht *HostTree) SelectRandom(n int, blacklist, addressBlacklist []types.SiaPublicKey) []modules.HostDBEntry

SelectRandom grabs a random n hosts from the tree. There will be no repeats, but the length of the slice returned may be less than n, and may even be zero. The hosts that are returned first have the higher priority.

Hosts passed to 'blacklist' will not be considered; pass `nil` if no blacklist is desired. 'addressBlacklist' is similar to 'blacklist' but instead of not considering the hosts in the list, hosts that use the same IP subnet as those hosts will be ignored. In most cases those blacklists contain the same elements but sometimes it is useful to block a host without blocking its IP range.

Hosts with a score of 1 will be ignored. 1 is the lowest score possible, at which point it's impossible to distinguish between hosts. Any sane scoring system should always have scores greater than 1 unless the host is intentionally being given a low score to indicate that the host should not be used.

func (*HostTree) SetFiltered

func (ht *HostTree) SetFiltered(pubKey types.SiaPublicKey, filtered bool) error

SetFiltered updates a host entry filtered field.

func (*HostTree) SetWeightFunction

func (ht *HostTree) SetWeightFunction(wf WeightFunc) error

SetWeightFunction resets the HostTree and assigns it a new weight function. This resets the tree and reinserts all the hosts.

type ScoreBreakdown

type ScoreBreakdown interface {
	HostScoreBreakdown(totalScore types.Currency, ignoreAge, ignoreDuration, ignoreUptime bool) modules.HostScoreBreakdown
	Score() types.Currency
}

ScoreBreakdown is an interface that allows us to mock the hostAdjustments during testing.

type WeightFunc

type WeightFunc func(modules.HostDBEntry) ScoreBreakdown

WeightFunc is a function used to weight a given HostDBEntry in the tree.