navigator

package
v0.4.13 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Jul 19, 2022 License: AGPL-3.0 Imports: 34 Imported by: 2

Documentation

Index

Constants

View Source 
const (
	NavigatorMeasurementTTLDefault    = 2 * time.Hour
	NavigatorMeasurementTTLByCostBase = 3 * time.Minute
	NavigatorMeasurementTTLByCostMin  = 2 * time.Hour
	NavigatorMeasurementTTLByCostMax  = 30 * time.Hour
)

Measurements Configuration.

View Source 
const (
	OptimizePurposeBootstrap       = "bootstrap"
	OptimizePurposeDesegregate     = "desegregate"
	OptimizePurposeWait            = "wait"
	OptimizePurposeTargetStructure = "target-structure"
)

Optimization Purposes.

View Source 
const (
	RoutingProfileHomeID      = "home"
	RoutingProfileSingleHopID = "single-hop"
	RoutingProfileDoubleHopID = "double-hop"
	RoutingProfileTripleHopID = "triple-hop"

	DefaultRoutingProfileID = RoutingProfileDoubleHopID
)

Routing Profile Names.

Variables

View Source 
var (
	// ErrHomeHubUnset is returned when the Home Hub is required and not set.
	ErrHomeHubUnset = errors.New("map has no Home Hub set")

	// ErrEmptyMap is returned when the Map is empty.
	ErrEmptyMap = errors.New("map is empty")

	// ErrHubNotFound is returned when the Hub was not found on the Map.
	ErrHubNotFound = errors.New("hub not found")
)
View Source 
var (
	RoutingProfileHome = &RoutingProfile{
		ID:      "home",
		Name:    "Plain VPN Mode",
		MinHops: 1,
		MaxHops: 1,
	}
	RoutingProfileSingleHop = &RoutingProfile{
		ID:           "single-hop",
		Name:         "Speed Focused",
		MinHops:      1,
		MaxHops:      2,
		MaxExtraHops: 1,
		MaxExtraCost: 10000,
	}
	RoutingProfileDoubleHop = &RoutingProfile{
		ID:           "double-hop",
		Name:         "Balanced",
		MinHops:      2,
		MaxHops:      3,
		MaxExtraHops: 2,
		MaxExtraCost: 10000,
	}
	RoutingProfileTripleHop = &RoutingProfile{
		ID:           "triple-hop",
		Name:         "Privacy Focused",
		MinHops:      3,
		MaxHops:      4,
		MaxExtraHops: 3,
		MaxExtraCost: 10000,
	}
)

Routing Profiles.

Functions

func CalculateDestinationCost added in v0.3.12 

func CalculateDestinationCost(proximity float32) (cost float32)

CalculateDestinationCost calculates the cost of a destination hub to a destination server based on the given proximity.

func CalculateHubCost added in v0.3.12 

func CalculateHubCost(load int) (cost float32)

CalculateHubCost calculates the cost of using a Hub based on the given Hub load.

func CalculateLaneCost added in v0.3.12 

func CalculateLaneCost(latency time.Duration, capacity int) (cost float32)

CalculateLaneCost calculates the cost of using a Lane based on the given Lane latency and capacity.

Types

type AnalysisState added in v0.3.13 

type AnalysisState struct {
	// Suggested signifies that a direct connection to this Hub is suggested by
	// the optimization algorithm.
	Suggested bool

	// SuggestedHopDistance holds the hop distance to this Hub when only
	// considering the suggested Hubs as connected.
	SuggestedHopDistance int

	// SuggestedHopDistanceInRegion holds the hop distance to this Hub in the
	// same region when only considering the suggested Hubs as connected.
	SuggestedHopDistanceInRegion int

	// CrossRegionalConnections holds the amount of connections a Pin has from
	// the current region.
	CrossRegionalConnections int
	// CrossRegionalLowestCostLane holds the lowest cost of the counted
	// connections from the current region.
	CrossRegionalLowestCostLane float32
	// CrossRegionalLaneCosts holds all the cross regional lane costs.
	CrossRegionalLaneCosts []float32
	// CrossRegionalHighestCostInHubLimit holds to highest cost of the lowest
	// cost connections within the maximum allowed lanes on a Hub from the
	// current region.
	CrossRegionalHighestCostInHubLimit float32
}

AnalysisState holds state for analyzing the network for optimizations.

type Hop added in v0.3.0 

type Hop struct {

	// HubID is the Hub ID.
	HubID string

	// Cost is the cost for both Lane to this Hub and the Hub itself.
	Cost float32
	// contains filtered or unexported fields
}

Hop is one hop of a route's path.

func (*Hop) Pin added in v0.3.0 

func (hop *Hop) Pin() *Pin

Pin returns the Pin of the Hop.

type HubType added in v0.3.0 

type HubType uint8

HubType is the usage type of a Hub in routing. 

const (
	HomeHub HubType = iota
	TransitHub
	DestinationHub
)

Hub Types.

type Lane added in v0.3.0 

type Lane struct {
	// Pin is the Pin/Hub this Lane connects to.
	Pin *Pin

	// Capacity designates the available bandwidth between these Hubs.
	// It is specified in bit/s.
	Capacity int

	// Lateny designates the latency between these Hubs.
	// It is specified in nanoseconds.
	Latency time.Duration

	// Cost is the routing cost of this lane.
	Cost float32
	// contains filtered or unexported fields
}

Lane is a connection to another Hub.

type LaneExport added in v0.3.7 

type LaneExport struct {
	HubID string

	// Capacity designates the available bandwidth between these Hubs.
	// It is specified in bit/s.
	Capacity int

	// Lateny designates the latency between these Hubs.
	// It is specified in nanoseconds.
	Latency time.Duration
}

LaneExport is the exportable version of a Lane.

type Map 

type Map struct {
	sync.RWMutex
	Name string
	// contains filtered or unexported fields
}

Map represent a collection of Pins and their relationship and status. 

var (

	// Main is the primary map used.
	Main *Map
)

func NewMap 

func NewMap(name string, enableMeasuring bool) *Map

NewMap returns a new and empty Map.

func (*Map) AddBootstrapHubs added in v0.3.0 

func (m *Map) AddBootstrapHubs(bootstrapTransports []string) error

AddBootstrapHubs adds the given bootstrap hubs to the map.

func (*Map) CancelHubUpdateHook added in v0.3.13 

func (m *Map) CancelHubUpdateHook()

CancelHubUpdateHook cancels the map's update hook.

func (*Map) Close added in v0.3.0 

func (m *Map) Close()

Close removes the map's integration, taking it "offline".

func (*Map) DefaultOptions added in v0.3.0 

func (m *Map) DefaultOptions() *Options

DefaultOptions returns the default options for this Map.

func (*Map) FindNearestHubs added in v0.3.0 

func (m *Map) FindNearestHubs(locationV4, locationV6 *geoip.Location, opts *Options, matchFor HubType, maxMatches int) ([]*hub.Hub, error)

FindNearestHubs searches for the nearest Hubs to the given IP address. The returned Hubs must not be modified in any way.

func (*Map) FindRouteToHub added in v0.4.6 

func (m *Map) FindRouteToHub(hubID string, opts *Options, maxRoutes int) (*Routes, error)

FindRouteToHub finds possible routes to the given Hub, with the given options.

func (*Map) FindRoutes added in v0.3.0 

func (m *Map) FindRoutes(ip net.IP, opts *Options, maxRoutes int) (*Routes, error)

FindRoutes finds possible routes to the given IP, with the given options.

func (*Map) GetHome added in v0.3.0 

func (m *Map) GetHome() (*Pin, *docks.CraneTerminal)

GetHome returns the current home and it's accompanying terminal. Both may be nil.

func (*Map) GetIntel added in v0.4.3 

func (m *Map) GetIntel() *hub.Intel

GetIntel returns the map's intel data.

func (*Map) GetPin added in v0.3.7 

func (m *Map) GetPin(hubID string) (pin *Pin, ok bool)

GetPin returns the Pin of the Hub with the given ID.

func (*Map) InitializeFromDatabase added in v0.3.0 

func (m *Map) InitializeFromDatabase()

InitializeFromDatabase loads all Hubs from the given database prefix and adds them to the Map.

func (*Map) Optimize added in v0.3.0 

func (m *Map) Optimize(opts *Options) (result *OptimizationResult, err error)

Optimize analyzes the map and suggests changes.

func (*Map) PushPinChanges added in v0.3.7 

func (m *Map) PushPinChanges()

PushPinChanges pushes all changed pins to subscribers.

func (*Map) RegisterHubUpdateHook added in v0.3.0 

func (m *Map) RegisterHubUpdateHook() (err error)

RegisterHubUpdateHook registers a database pre-put hook that updates all Hubs saved at the given database prefix.

func (*Map) RemoveHub added in v0.3.0 

func (m *Map) RemoveHub(id string)

RemoveHub removes a Hub from the Map.

func (*Map) SaveMeasuredHubs added in v0.3.13 

func (m *Map) SaveMeasuredHubs()

SaveMeasuredHubs saves all Hubs that have unsaved measurements.

func (*Map) SetHome added in v0.3.0 

func (m *Map) SetHome(id string, t *docks.CraneTerminal) (ok bool)

SetHome sets the given hub as the new home. Optionally, a terminal may be supplied to accompany the home hub.

func (*Map) Stats added in v0.3.0 

func (m *Map) Stats() *MapStats

Stats collects and returns statistics from the map.

func (*Map) UpdateHub added in v0.3.0 

func (m *Map) UpdateHub(h *hub.Hub)

UpdateHub updates a Hub on the Map.

func (*Map) UpdateIntel added in v0.3.0 

func (m *Map) UpdateIntel(update *hub.Intel) error

UpdateIntel supplies the map with new intel data. The data is not copied, so it must not be modified after being supplied. If the map is empty, the bootstrap hubs will be added to the map.

type MapStats added in v0.3.0 

type MapStats struct {
	Name            string
	States          map[PinState]int
	Lanes           map[int]int
	ActiveTerminals int
}

MapStats holds generic map statistics.

func (*MapStats) String added in v0.3.0 

func (ms *MapStats) String() string

type OptimizationResult added in v0.3.13 

type OptimizationResult struct {
	// Purpose holds a semi-human readable constant of the optimization purpose.
	Purpose string

	// Approach holds human readable descriptions of how the stated purpose
	// should be achieved.
	Approach []string

	// SuggestedConnections holds the Hubs to which connections are suggested.
	SuggestedConnections []*SuggestedConnection

	// MaxConnect specifies how many connections should be created at maximum
	// based on this optimization.
	MaxConnect int

	// StopOthers specifies if other connections than the suggested ones may
	// be stopped.
	StopOthers bool
	// contains filtered or unexported fields
}

OptimizationResult holds the result of an optimizaion analysis.

type Options added in v0.3.0 

type Options struct {
	// Regard holds required States. Only Hubs where all of these are present
	// will taken into account for the operation. If NoDefaults is not set, a
	// basic set of desirable states is added automatically.
	Regard PinState

	// Disregard holds disqualifying States. Only Hubs where none of these are
	// present will be taken into account for the operation. If NoDefaults is not
	// set, a basic set of undesirable states is added automatically.
	Disregard PinState

	// HubPolicies is a collecion of endpoint lists that Hubs must pass in order
	// to be taken into account for the operation.
	HubPolicies []endpoints.Endpoints

	// CheckHubEntryPolicyWith provides an entity that must match the Hubs entry
	// policy in order to be taken into account for the operation.
	CheckHubEntryPolicyWith *intel.Entity

	// CheckHubExitPolicyWith provides an entity that must match the Hubs exit
	// policy in order to be taken into account for the operation.
	CheckHubExitPolicyWith *intel.Entity

	// NoDefaults declares whether default and recommended Regard and Disregard states should not be used.
	NoDefaults bool

	// RequireTrustedDestinationHubs declares whether only Destination Hubs that have the Trusted state should be used.
	RequireTrustedDestinationHubs bool

	// RoutingProfile defines the algorithm to use to find a route.
	RoutingProfile string
}

Options holds configuration options for operations with the Map.

func (*Options) Copy added in v0.3.0 

func (o *Options) Copy() *Options

Copy returns a shallow copy of the Options.

func (*Options) HubPoliciesAreSet added in v0.4.3 

func (o *Options) HubPoliciesAreSet() bool

HubPoliciesAreSet returns whether any hub policies are set and non-empty.

func (*Options) Matcher added in v0.3.0 

func (o *Options) Matcher(hubType HubType, hubIntel *hub.Intel) PinMatcher

Matcher generates a PinMatcher based on the Options.

type Pin added in v0.3.0 

type Pin struct {
	// Hub Information
	Hub        *hub.Hub
	EntityV4   *intel.Entity
	EntityV6   *intel.Entity
	LocationV4 *geoip.Location
	LocationV6 *geoip.Location

	// Hub Status
	State PinState
	// HopDistance signifies the needed hops to reach this Hub.
	// HopDistance is measured from the view of a client.
	// A Hub itself will have itself at distance 1.
	// Directly connected Hubs have a distance of 2.
	HopDistance int
	// Cost is the routing cost of this Hub.
	Cost float32
	// ConnectedTo holds validated lanes.
	ConnectedTo map[string]*Lane // Key is Hub ID.

	// FailingUntil specifies until when this Hub should be regarded as failing.
	// This is connected to StateFailing.
	FailingUntil time.Time

	// Connection holds a information about a connection to the Hub of this Pin.
	Connection *PinConnection
	// contains filtered or unexported fields
}

Pin represents a Hub on a Map.

func (*Pin) Export added in v0.3.7 

func (pin *Pin) Export() *PinExport

Export puts the Pin's information into an exportable format.

func (*Pin) GetActiveTerminal added in v0.3.7 

func (pin *Pin) GetActiveTerminal() *docks.ExpansionTerminal

GetActiveTerminal returns the active terminal of the pin.

func (*Pin) HasActiveTerminal added in v0.3.0 

func (pin *Pin) HasActiveTerminal() bool

HasActiveTerminal returns whether the Pin has an active terminal.

func (*Pin) Lock added in v0.3.0 

func (pin *Pin) Lock()

Lock locks the Pin via the Hub's lock.

func (*Pin) NotifyTerminalChange added in v0.3.7 

func (pin *Pin) NotifyTerminalChange()

NotifyTerminalChange notifies subscribers of the changed terminal.

func (*Pin) SetActiveTerminal added in v0.3.7 

func (pin *Pin) SetActiveTerminal(pc *PinConnection)

SetActiveTerminal sets an active terminal for the pin.

func (*Pin) String added in v0.3.0 

func (pin *Pin) String() string

String returns a human-readable representation of the Pin.

func (*Pin) Unlock added in v0.3.0 

func (pin *Pin) Unlock()

Unlock unlocks the Pin via the Hub's lock.

type PinConnection added in v0.3.0 

type PinConnection struct {
	// Terminal holds the active terminal session.
	Terminal *docks.ExpansionTerminal

	// Route is the route built for this terminal.
	Route *Route
}

PinConnection represents a connection to a terminal on the Hub.

type PinExport added in v0.3.7 

type PinExport struct {
	record.Base
	sync.Mutex

	ID        string
	Name      string
	Map       string
	FirstSeen time.Time

	EntityV4 *intel.Entity
	EntityV6 *intel.Entity

	States      []string // From pin.State
	HopDistance int

	ConnectedTo   map[string]*LaneExport // Key is Hub ID.
	Route         []string               // Includes Home Hub and this Pin's ID.
	SessionActive bool
}

PinExport is the exportable version of a Pin.

type PinMatcher added in v0.3.0 

type PinMatcher func(pin *Pin) bool

PinMatcher is a stateful matching function generated by Options.

type PinState added in v0.3.0 

type PinState uint16

PinState holds a bit-mapped collection of Pin states, or a single state used for assigment and matching. 

const (
	// StateNone represents an empty state.
	StateNone PinState = 0

	// StateInvalid signifies that there was an error while processing or
	// handling this Hub.
	StateInvalid PinState = 1 << (iota - 1) // 1 << 0 => 00000001 => 0x01

	// StateSuperseded signifies that this Hub was superseded by another. This is
	// the case if any other Hub with a matching IP was verified after this one.
	// Verification timestamp equals Hub.FirstSeen.
	StateSuperseded // 0x02

	// StateFailing signifies that a recent error was encountered while
	// communicating with this Hub. Pin.IgnoreUntil specifies when this state is
	// re-evaluated at earliest.
	StateFailing // 0x04

	// StateOffline signifies that the Hub is offline.
	StateOffline // 0x08

	// StateHasRequiredInfo signifies that the Hub announces the minimum required
	// information about itself.
	StateHasRequiredInfo // 0x10

	// StateReachable signifies that the Hub is reachable via the network from
	// the currently connected primary Hub.
	StateReachable // 0x20

	// StateActive signifies that everything seems fine with the Hub and
	// connections to it should succeed. This is tested by checking if a valid
	// semi-ephemeral public key is available.
	StateActive // 0x40

	// StateTrusted signifies the Hub has the special trusted status.
	StateTrusted // 0x0100

	// StateUsageDiscouraged signifies that usage of the Hub is discouraged for any task.
	StateUsageDiscouraged // 0x0200

	// StateUsageAsHomeDiscouraged signifies that usage of the Hub as a Home Hub is discouraged.
	StateUsageAsHomeDiscouraged // 0x0400

	// StateUsageAsDestinationDiscouraged signifies that usage of the Hub as a Destination Hub is discouraged.
	StateUsageAsDestinationDiscouraged // 0x0800

	// StateIsHomeHub signifies that the Hub is the current Home Hub. While not
	// negative in itself, selecting the Home Hub does not make sense in almost
	// all cases.
	StateIsHomeHub // 0x1000

	// StateSummaryRegard summarizes all states that must always be set in order to take a Hub into consideration for any task.
	// TODO: Add StateHasRequiredInfo when we start enforcing Hub information.
	StateSummaryRegard = StateReachable | StateActive

	// StateSummaryDisregard summarizes all states that must not be set in order to take a Hub into consideration for any task.
	StateSummaryDisregard = StateInvalid |
		StateSuperseded |
		StateFailing |
		StateOffline |
		StateUsageDiscouraged |
		StateIsHomeHub
)

func (PinState) Export added in v0.3.7 

func (pinState PinState) Export() []string

Export returns a list of all state names.

func (PinState) Name added in v0.3.0 

func (pinState PinState) Name() string

Name returns the name of a single state flag.

func (PinState) String added in v0.3.0 

func (pinState PinState) String() string

String returns the states as a human readable string.

type Region added in v0.3.18 

type Region struct {
	ID   string
	Name string
	// contains filtered or unexported fields
}

Region specifies a group of Hubs for optimization purposes.

type Route 

type Route struct {
	// Path is a list of Transit Hubs and the Destination Hub, including the Cost
	// for each Hop.
	Path []*Hop

	// DstCost is the calculated cost between the Destination Hub and the destination IP.
	DstCost float32

	// TotalCost is the sum of all costs of this Route.
	TotalCost float32

	// Algorithm is the ID of the algorithm used to calculate the route.
	Algorithm string
}

Route is a path through the map.

func (*Route) CopyUpTo added in v0.3.0 

func (r *Route) CopyUpTo(n int) *Route

CopyUpTo makes a somewhat deep copy of the Route up to the specified amount and returns it. Hops themselves are not copied, because their data does not change. Therefore, returned Hops may not be edited. Specify an amount of 0 to copy all.

func (*Route) String 

func (r *Route) String() string

type Routes added in v0.3.0 

type Routes struct {
	All []*Route
	// contains filtered or unexported fields
}

Routes holds a collection of Routes.

func (*Routes) Len added in v0.3.0 

func (r *Routes) Len() int

Len is the number of elements in the collection.

func (*Routes) Less added in v0.3.0 

func (r *Routes) Less(i, j int) bool

Less reports whether the element with index i should sort before the element with index j.

func (*Routes) Swap added in v0.3.0 

func (r *Routes) Swap(i, j int)

Swap swaps the elements with indexes i and j.

type RoutingProfile added in v0.3.0 

type RoutingProfile struct {
	ID string

	// Name is the human readable name of the profile.
	Name string

	// MinHops defines how many hops a route must have at minimum. In order to
	// reduce confusion, the Home Hub is also counted.
	MinHops int

	// MaxHops defines the limit on how many hops a route may have. In order to
	// reduce confusion, the Home Hub is also counted.
	MaxHops int

	// MaxExtraHops sets a limit on how many extra hops are allowed in addition
	// to the amount of Hops in the currently best route. This is an optimization
	// option and should not interfere with finding the best route, but might
	// reduce the amount of routes found.
	MaxExtraHops int

	// MaxExtraCost sets a limit on the extra cost allowed in addition to the
	// cost of the currently best route. This is an optimization option and
	// should not interfere with finding the best route, but might reduce the
	// amount of routes found.
	MaxExtraCost float32
}

RoutingProfile defines a routing algorithm with some options.

type StorageInterface added in v0.3.7 

type StorageInterface struct {
	storage.InjectBase
}

StorageInterface provices a storage.Interface to the configuration manager.

func (*StorageInterface) Get added in v0.3.7 

func (s *StorageInterface) Get(key string) (record.Record, error)

Get returns a database record.

func (*StorageInterface) Query added in v0.3.7 

func (s *StorageInterface) Query(q *query.Query, local, internal bool) (*iterator.Iterator, error)

Query returns a an iterator for the supplied query.

type SuggestedConnection added in v0.3.18 

type SuggestedConnection struct {
	// Hub holds the Hub to which a connection is suggested.
	Hub *hub.Hub

	// Reason holds a reason why this connection is suggested.
	Reason string
	// Duplicate marks duplicate entries. These should be ignored when
	// connecting, but are helpful for understand the optimization result.
	Duplicate bool
	// contains filtered or unexported fields
}

SuggestedConnection holds suggestions by the optimization system.

type UpdateHook added in v0.3.0 

type UpdateHook struct {
	database.HookBase
	// contains filtered or unexported fields
}

UpdateHook updates the a map from database changes.

func (*UpdateHook) PrePut added in v0.3.0 

func (hook *UpdateHook) PrePut(r record.Record) (record.Record, error)

PrePut implements the Hook interface.

func (*UpdateHook) UsesPrePut added in v0.3.0 

func (hook *UpdateHook) UsesPrePut() bool

UsesPrePut implements the Hook interface.

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.