pex

Documentation

Overview

* The MIT License (MIT)

Copyright (c) 2016 Protocol Labs, Inc.

Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

* The MIT License (MIT)

Copyright (c) 2016 Protocol Labs, Inc.

Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

* The MIT License (MIT)

Copyright (c) 2016 Protocol Labs, Inc.

Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

* The MIT License (MIT)

Copyright (c) 2016 Protocol Labs, Inc.

Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

* The MIT License (MIT)

Copyright (c) 2016 Protocol Labs, Inc.

Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

Index

• Constants
• Variables
• func NewMetrics() *metrics
• func SortClosestPeers(peers []peer.ID, target peer.ID) []peer.ID
• type AddrManager
  • func NewAddrManager() *AddrManager
  • func (mgr *AddrManager) AddAddr(p peer.ID, addr net.Addr, ttl time.Duration)
  • func (mgr *AddrManager) Addr(p peer.ID) net.Addr
  • func (mgr *AddrManager) ClearAddr(p peer.ID)
  • func (mgr *AddrManager) ForRePing() ([]peer.ID, []net.Addr)
  • func (mgr *AddrManager) Peers() []peer.ID
  • func (mgr *AddrManager) SetAddr(p peer.ID, addr net.Addr, ttl time.Duration)
  • func (mgr *AddrManager) UpdateAddr(p peer.ID, oldTTL time.Duration, newTTL time.Duration)
• type Bucket
  • func (b *Bucket) Has(id peer.ID) bool
  • func (b *Bucket) Len() int
  • func (b *Bucket) MoveToFront(id peer.ID)
  • func (b *Bucket) Peers() []peer.ID
  • func (b *Bucket) PopBack() peer.ID
  • func (b *Bucket) PushFront(p peer.ID)
  • func (b *Bucket) Remove(id peer.ID)
  • func (b *Bucket) Split(cpl int, target peer.ID) *Bucket
• type KadDHT
  • func GetDHT() *KadDHT
• type Metrics
• type RoutingTable
  • func NewRoutingTable(bucketsize int, localID peer.ID, latency time.Duration, m Metrics) *RoutingTable
  • func (rt *RoutingTable) Find(id peer.ID) peer.ID
  • func (rt *RoutingTable) ListPeers() []peer.ID
  • func (rt *RoutingTable) NearestPeer(id peer.ID) peer.ID
  • func (rt *RoutingTable) NearestPeers(id peer.ID, count int) []peer.ID
  • func (rt *RoutingTable) Print()
  • func (rt *RoutingTable) Remove(p peer.ID)
  • func (rt *RoutingTable) Size() int
  • func (rt *RoutingTable) Update(p peer.ID)

Constants

const (
	// TempAddrTTL is the ttl used for a short lived address
	TempAddrTTL = time.Second * 10

	// ProviderAddrTTL is the TTL of an address we've received from a provider.
	// This is also a temporary address, but lasts longer. After this expires,
	// the records we return will require an extra lookup.
	ProviderAddrTTL = time.Minute * 10

	// RecentlyConnectedAddrTTL is used when we recently connected to a peer.
	// It means that we are reasonably certain of the peer's address.
	RecentlyConnectedAddrTTL = time.Minute * 10

	// OwnObservedAddrTTL is used for our own external addresses observed by peers.
	OwnObservedAddrTTL = time.Minute * 10

	// PermanentAddrTTL is the ttl for a "permanent address" (e.g. bootstrap nodes).
	PermanentAddrTTL = math.MaxInt64 - iota

	// ConnectedAddrTTL is the ttl used for the addresses of a peer to whom
	// we're connected directly. This is basically permanent, as we will
	// clear them + re-add under a TempAddrTTL after disconnecting.
	ConnectedAddrTTL
)

Permanent TTLs (distinct so we can distinguish between them, constant as they are, in fact, permanent)

const (
	DefaultBucketSize             = 8
	DefaultLatencyToleranceMillis = 1000
	NumBootstrapQueries           = 5
	//Parallelism factor for lookups.
	Alpha = 3
)

Variables

var LatencyEWMASmoothing = 0.1

LatencyEWMASmooting governs the decay of the EWMA (the speed at which it changes). This must be a normalized (0-1) value. 1 is 100% change, 0 is no change.

Functions

func NewMetrics

func NewMetrics() *metrics

func SortClosestPeers

func SortClosestPeers(peers []peer.ID, target peer.ID) []peer.ID

Types

type AddrManager

type AddrManager struct {
	sync.Mutex // guards addrs
	// contains filtered or unexported fields
}

AddrManager manages addresses. The zero-value is ready to be used.

func NewAddrManager

func NewAddrManager() *AddrManager

ensures the AddrManager is initialized. So we can use the zero value.

func (*AddrManager) AddAddr

func (mgr *AddrManager) AddAddr(p peer.ID, addr net.Addr, ttl time.Duration)

AddAddr gives AddrManager an address to use, with a given ttl (time-to-live), after which the address is no longer valid. If the manager has a longer TTL, the operation is a no-op for that address

func (*AddrManager) Addr

func (mgr *AddrManager) Addr(p peer.ID) net.Addr

Addresses returns all known (and valid) addresses for a given peer ID.

func (*AddrManager) ClearAddr

func (mgr *AddrManager) ClearAddr(p peer.ID)

ClearAddress removes previously stored address for a peer ID.

func (*AddrManager) ForRePing

func (mgr *AddrManager) ForRePing() ([]peer.ID, []net.Addr)

Return all known peers and ids to ping. These are copies of the address Managers stored ones. This method is called on reinitialization of the client.

func (*AddrManager) Peers

func (mgr *AddrManager) Peers() []peer.ID

func (*AddrManager) SetAddr

func (mgr *AddrManager) SetAddr(p peer.ID, addr net.Addr, ttl time.Duration)

SetAddr sets the ttl on address. This clears any TTL there previously. This is used when we receive the best estimate of the validity of an address.

func (*AddrManager) UpdateAddr

func (mgr *AddrManager) UpdateAddr(p peer.ID, oldTTL time.Duration, newTTL time.Duration)

UpdateAddr updates the addresses associated with the given peer that have the given oldTTL to have the given newTTL.

type Bucket

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

Bucket holds a list of peers.

func (*Bucket) Has

func (b *Bucket) Has(id peer.ID) bool

func (*Bucket) Len

func (b *Bucket) Len() int

func (*Bucket) MoveToFront

func (b *Bucket) MoveToFront(id peer.ID)

func (*Bucket) Peers

func (b *Bucket) Peers() []peer.ID

func (*Bucket) PopBack

func (b *Bucket) PopBack() peer.ID

func (*Bucket) PushFront

func (b *Bucket) PushFront(p peer.ID)

func (*Bucket) Remove

func (b *Bucket) Remove(id peer.ID)

func (*Bucket) Split

func (b *Bucket) Split(cpl int, target peer.ID) *Bucket

Split splits a buckets peers into two buckets, the methods receiver will have peers with CPL equal to cpl, the returned bucket will have peers with CPL greater than cpl (returned bucket has closer peers)

type KadDHT

type KadDHT struct {
	*RoutingTable
	*AddrManager
	// contains filtered or unexported fields
}

func GetDHT

func GetDHT() *KadDHT

type Metrics

type Metrics interface {

	// RecordLatency records a new latency measurement
	RecordLatency(peer.ID, time.Duration)

	// LatencyEWMA returns an exponentially-weighted moving avg.
	// of all measurements of a peer's latency.
	LatencyEWMA(peer.ID) time.Duration
}

Metrics is just an object that tracks metrics across a set of peers.

type RoutingTable

type RoutingTable struct {

	// kBuckets define all the fingers to other nodes.
	Buckets []*Bucket

	// notification channels
	PeerRemoved chan peer.ID
	PeerAdded   chan peer.ID
	// contains filtered or unexported fields
}

RoutingTable defines the routing table.

func NewRoutingTable

func NewRoutingTable(bucketsize int, localID peer.ID, latency time.Duration, m Metrics) *RoutingTable

NewRoutingTable creates a new routing table with a given bucketsize, local ID, and latency tolerance. Make sure to consume Peer channels or there will be no progress.

func (*RoutingTable) Find

func (rt *RoutingTable) Find(id peer.ID) peer.ID

Find a specific peer by ID or return nil

func (*RoutingTable) ListPeers

func (rt *RoutingTable) ListPeers() []peer.ID

ListPeers takes a RoutingTable and returns a list of all peers from all buckets in the table.

func (*RoutingTable) NearestPeer

func (rt *RoutingTable) NearestPeer(id peer.ID) peer.ID

NearestPeer returns a single peer that is nearest to the given ID

func (*RoutingTable) NearestPeers

func (rt *RoutingTable) NearestPeers(id peer.ID, count int) []peer.ID

NearestPeers returns a list of the 'count' closest peers to the given ID

func (*RoutingTable) Print

func (rt *RoutingTable) Print()

Print prints a descriptive statement about the provided RoutingTable

func (*RoutingTable) Remove

func (rt *RoutingTable) Remove(p peer.ID)

Remove deletes a peer from the routing table. This is to be used when we are sure a node has disconnected completely.

func (*RoutingTable) Size

func (rt *RoutingTable) Size() int

Size returns the total number of peers in the routing table

func (*RoutingTable) Update

func (rt *RoutingTable) Update(p peer.ID)

Update adds or moves the given peer to the front of its respective bucket If a peer gets removed from a bucket, it is returned