hub

package
v1.6.28 Latest Latest
Warning

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

 Go to latest Published: Dec 2, 2024 License: GPL-3.0 Imports: 25 Imported by: 0

Documentation

Index

Constants

View Source 
const (
	MsgTypeAnnouncement = "announcement"
	MsgTypeStatus       = "status"
)

Message Types.

View Source 
const (
	// FlagNetError signifies that the Hub reports a network connectivity failure or impairment.
	FlagNetError = "net-error"

	// FlagOffline signifies that the Hub has gone offline by itself.
	FlagOffline = "offline"

	// FlagAllowUnencrypted signifies that the Hub is available to handle unencrypted connections.
	FlagAllowUnencrypted = "allow-unencrypted"
)

Status Flags.

View Source 
const MaxCalculatedCost = 1000000

MaxCalculatedCost specifies the max calculated cost to be used for an unknown high cost.

View Source 
const VersionOffline = "offline"

VersionOffline is a special version used to signify that the Hub has gone offline. This is depracated, please use FlagOffline instead.

Variables

View Source 
var (
	// ErrMissingInfo signifies that the hub is missing the HubAnnouncement.
	ErrMissingInfo = errors.New("hub has no announcement")

	// ErrMissingTransports signifies that the hub announcement did not specify any transports.
	ErrMissingTransports = errors.New("hub announcement has no transports")

	// ErrMissingIPs signifies that the hub announcement did not specify any IPs,
	// or none of the IPs is supported by the client.
	ErrMissingIPs = errors.New("hub announcement has no (supported) IPs")

	// ErrTemporaryValidationError is returned when a validation error might be temporary.
	ErrTemporaryValidationError = errors.New("temporary validation error")

	// ErrOldData is returned when received data is outdated.
	ErrOldData = errors.New("")
)
View Source 
var BaselineCharset = regexp.MustCompile(

	`^[` +

		` !#()*+,\-\./0-9:=?@A-Z[\]^_a-z{|}~` +

		`ŠŒŽšœžŸ¡¿ÀÁÂÃÄÅÆÇÈÉÊËÌÍÎÏÐÑÒÓÔÕÖØÙÚÛÜÝÞßàáâãäåæçèéêëìíîïðñòóôõöøùúûüýþÿ` +

		`]*$`,
)

BaselineCharset defines the permitted characters.

Functions

func CreateHubSignet 

func CreateHubSignet(toolID string, securityLevel int) (private, public *jess.Signet, err error)

CreateHubSignet creates a signet with the correct ID for usage as a Hub Identity.

func FlagsEqual 

func FlagsEqual(a, b []string) bool

FlagsEqual returns whether the given status flags are equal.

func LanesEqual 

func LanesEqual(a, b []*Lane) bool

LanesEqual returns whether the given []*Lane are equal.

func MakeHubDBKey 

func MakeHubDBKey(mapName, hubID string) string

MakeHubDBKey makes a hub db key.

func MakeHubMsgDBKey 

func MakeHubMsgDBKey(mapName string, msgType MsgType, hubID string) string

MakeHubMsgDBKey makes a hub msg db key.

func QueryRawGossipMsgs 

func QueryRawGossipMsgs(mapName string, msgType MsgType) (it *iterator.Iterator, err error)

QueryRawGossipMsgs queries the database for raw gossip messages.

func RemoveHubAndMsgs 

func RemoveHubAndMsgs(mapName string, hubID string) (err error)

RemoveHubAndMsgs deletes a Hub and it's saved messages from the database.

func SaveHubMsg 

func SaveHubMsg(id string, mapName string, msgType MsgType, data []byte) error

SaveHubMsg saves a raw (and signed) message received by another Hub.

func SetNavigatorAccess 

func SetNavigatorAccess(fn func(mapName, hubID string) *Hub)

SetNavigatorAccess sets a shortcut function to access hubs from the navigator instead of having go through the database. This also reduces the number of object in RAM and better caches parsed attributes.

func SignHubMsg 

func SignHubMsg(msg []byte, env *jess.Envelope, enableTofu bool) ([]byte, error)

SignHubMsg signs the given serialized hub msg with the given configuration.

func SortLanes 

func SortLanes(l []*Lane)

SortLanes sorts a slice of Lanes.

func SortTransports 

func SortTransports(ts []*Transport)

SortTransports sorts the transports to emphasize certain protocols, but otherwise leaves the order intact.

Types

type Announcement 

type Announcement struct {
	// Primary Key
	// hash of public key
	// must be checked if it matches the public key
	ID string `cbor:"i"` // via jess.LabeledHash

	// PublicKey *jess.Signet
	// PublicKey // if not part of signature
	// Signature *jess.Letter
	Timestamp int64 `cbor:"t"` // Unix timestamp in seconds

	// Node Information
	Name           string `cbor:"n"`                              // name of the node
	Group          string `cbor:"g,omitempty"  json:",omitempty"` // person or organisation, who is in control of the node (should be same for all nodes of this person or organisation)
	ContactAddress string `cbor:"ca,omitempty" json:",omitempty"` // contact possibility  (recommended, but optional)
	ContactService string `cbor:"cs,omitempty" json:",omitempty"` // type of service of the contact address, if not email

	// currently unused, but collected for later use
	Hosters    []string `cbor:"ho,omitempty" json:",omitempty"` // hoster supply chain (reseller, hosting provider, datacenter operator, ...)
	Datacenter string   `cbor:"dc,omitempty" json:",omitempty"` // datacenter will be bullshit checked

	// Network Location and Access
	// If node is behind NAT (or similar), IP addresses must be configured
	IPv4       net.IP   `cbor:"ip4,omitempty" json:",omitempty"` // must be global and accessible
	IPv6       net.IP   `cbor:"ip6,omitempty" json:",omitempty"` // must be global and accessible
	Transports []string `cbor:"tp,omitempty"  json:",omitempty"`

	// Policies - default permit
	Entry []string `cbor:"pi,omitempty" json:",omitempty"`

	// {"+ ", "- *"}
	Exit []string `cbor:"po,omitempty" json:",omitempty"`

	// Flags holds flags that signify special states.
	Flags []string `cbor:"f,omitempty" json:",omitempty"`
	// contains filtered or unexported fields
}

Announcement is the main message type to publish Hub Information. This only changes if updated manually.

func (*Announcement) Copy 

func (a *Announcement) Copy() *Announcement

Copy returns a deep copy of the Announcement.

func (*Announcement) EntryPolicy 

func (a *Announcement) EntryPolicy() endpoints.Endpoints

EntryPolicy returns the Hub's entry policy.

func (*Announcement) Equal 

func (a *Announcement) Equal(b *Announcement) bool

Equal returns whether the given Announcements are equal.

func (*Announcement) ExitPolicy 

func (a *Announcement) ExitPolicy() endpoints.Endpoints

ExitPolicy returns the Hub's exit policy.

func (*Announcement) Export 

func (a *Announcement) Export(env *jess.Envelope) ([]byte, error)

Export exports the announcement with the given signature configuration.

func (*Announcement) HasFlag 

func (a *Announcement) HasFlag(flagName string) bool

HasFlag returns whether the Announcement has the given flag set.

func (*Announcement) ParsedTransports 

func (a *Announcement) ParsedTransports() []*Transport

ParsedTransports returns the Hub's parsed transports.

type Hub 

type Hub struct {
	sync.Mutex
	record.Base

	ID        string
	PublicKey *jess.Signet
	Map       string

	Info   *Announcement
	Status *Status

	Measurements *Measurements

	FirstSeen     time.Time
	VerifiedIPs   bool
	InvalidInfo   bool
	InvalidStatus bool
	// contains filtered or unexported fields
}

Hub represents a network node in the SPN.

func ApplyAnnouncement 

func ApplyAnnouncement(existingHub *Hub, data []byte, mapName string, scope Scope, selfcheck bool) (hub *Hub, known, changed bool, err error)

ApplyAnnouncement applies the announcement to the Hub if it passes all the checks. If no Hub is provided, it is loaded from the database or created.

func ApplyStatus 

func ApplyStatus(existingHub *Hub, data []byte, mapName string, scope Scope, selfcheck bool) (hub *Hub, known, changed bool, err error)

ApplyStatus applies a status update if it passes all the checks.

func EnsureHub 

func EnsureHub(r record.Record) (*Hub, error)

EnsureHub makes sure a database record is a Hub.

func GetHub 

func GetHub(mapName string, hubID string) (*Hub, error)

GetHub get a Hub from the database - or the navigator, if configured.

func GetHubByKey 

func GetHubByKey(key string) (*Hub, error)

GetHubByKey returns a hub by its raw DB key.

func OpenHubMsg 

func OpenHubMsg(hub *Hub, data []byte, mapName string, tofu bool) (msg []byte, sendingHub *Hub, known bool, err error)

OpenHubMsg opens a signed hub msg and verifies the signature using the provided hub or the local database. If TOFU is enabled, the signature is always accepted, if valid.

func (*Hub) AddLane 

func (h *Hub) AddLane(newLane *Lane) error

AddLane adds a new Lane to the Hub Status.

func (*Hub) GetInfo 

func (h *Hub) GetInfo() *Announcement

GetInfo returns the hub info.

func (*Hub) GetLaneTo 

func (h *Hub) GetLaneTo(hubID string) *Lane

GetLaneTo returns the lane to the given Hub, if it exists.

func (*Hub) GetMeasurements 

func (h *Hub) GetMeasurements() *Measurements

GetMeasurements returns the hub measurements. This method should always be used instead of direct access.

func (*Hub) GetMeasurementsWithLockedHub 

func (h *Hub) GetMeasurementsWithLockedHub() *Measurements

GetMeasurementsWithLockedHub returns the hub measurements. The caller must hold the lock to Hub. This method should always be used instead of direct access.

func (*Hub) GetSignet 

func (h *Hub) GetSignet(id string, recipient bool) (*jess.Signet, error)

GetSignet returns the public key identified by the given ID from the Hub Status.

func (*Hub) GetStatus 

func (h *Hub) GetStatus() *Status

GetStatus returns the hub status.

func (*Hub) HasFlag 

func (h *Hub) HasFlag(flagName string) bool

HasFlag returns whether the Announcement or Status has the given flag set.

func (*Hub) Name 

func (h *Hub) Name() string

Name returns a human-readable version of a Hub's name. This name will likely consist of two parts: the given name and the ending of the ID to make it unique.

func (*Hub) Obsolete 

func (h *Hub) Obsolete() bool

Obsolete returns if the Hub is obsolete and may be deleted.

func (*Hub) RemoveLane 

func (h *Hub) RemoveLane(hubID string) error

RemoveLane removes a Lane from the Hub Status.

func (*Hub) Save 

func (h *Hub) Save() error

Save saves to Hub to the correct scope in the database.

func (*Hub) SelectSignet 

func (h *Hub) SelectSignet() *jess.Signet

SelectSignet selects the public key to use for initiating connections to that Hub.

func (*Hub) String 

func (h *Hub) String() string

String returns a human-readable representation of the Hub.

func (*Hub) StringWithoutLocking 

func (h *Hub) StringWithoutLocking() string

StringWithoutLocking returns a human-readable representation of the Hub without locking it.

func (*Hub) Verified 

func (h *Hub) Verified() bool

Verified return whether the Hub has been verified.

type HubIntel 

type HubIntel struct {
	// Trusted specifies if the Hub is specially designated for more sensitive tasks, such as handling unencrypted traffic.
	Trusted bool

	// Discontinued specifies if the Hub has been discontinued and should be marked as offline and removed.
	Discontinued bool

	// VerifiedOwner holds the name of the verified owner / operator of the Hub.
	VerifiedOwner string

	// Override is used to override certain Hub information.
	Override *InfoOverride
}

HubIntel holds Hub-related data.

type HubMsg 

type HubMsg struct {
	record.Base
	sync.Mutex

	ID   string
	Map  string
	Type MsgType
	Data []byte

	Received int64
}

HubMsg stores raw Hub messages.

func EnsureHubMsg 

func EnsureHubMsg(r record.Record) (*HubMsg, error)

EnsureHubMsg makes sure a database record is a HubMsg.

type InfoOverride 

type InfoOverride struct {
	// ContinentCode overrides the continent code of the geoip data.
	ContinentCode string
	// CountryCode overrides the country code of the geoip data.
	CountryCode string
	// Coordinates overrides the geo coordinates code of the geoip data.
	Coordinates *geoip.Coordinates
	// ASN overrides the Autonomous System Number of the geoip data.
	ASN uint
	// ASOrg overrides the Autonomous System Organization of the geoip data.
	ASOrg string
}

InfoOverride holds data to overide hub info information.

type Intel 

type Intel struct {
	// BootstrapHubs is list of transports that also contain an IP and the Hub's ID.
	BootstrapHubs []string

	// Hubs holds intel regarding specific Hubs.
	Hubs map[string]*HubIntel

	// AdviseOnlyTrustedHubs advises to only use trusted Hubs regardless of intended purpose.
	AdviseOnlyTrustedHubs bool
	// AdviseOnlyTrustedHomeHubs advises to only use trusted Hubs for Home Hubs.
	AdviseOnlyTrustedHomeHubs bool
	// AdviseOnlyTrustedDestinationHubs advises to only use trusted Hubs for Destination Hubs.
	AdviseOnlyTrustedDestinationHubs bool

	// HubAdvisory always affects all Hubs.
	HubAdvisory []string
	// HomeHubAdvisory is only taken into account when selecting a Home Hub.
	HomeHubAdvisory []string
	// DestinationHubAdvisory is only taken into account when selecting a Destination Hub.
	DestinationHubAdvisory []string

	// Regions defines regions to assist network optimization.
	Regions []*RegionConfig

	// VirtualNetworks holds network configurations for virtual cloud networks.
	VirtualNetworks []*VirtualNetworkConfig
	// contains filtered or unexported fields
}

Intel holds a collection of various security related data collections on Hubs.

func ParseIntel 

func ParseIntel(data []byte) (*Intel, error)

ParseIntel parses Hub intelligence data.

func (*Intel) ParseAdvisories 

func (i *Intel) ParseAdvisories() (err error)

ParseAdvisories parses all advisory endpoint lists.

func (*Intel) Parsed 

func (i *Intel) Parsed() *ParsedIntel

Parsed returns the collection of parsed intel data.

type Key 

type Key struct {
	Scheme  string
	Key     []byte
	Expires int64
}

Key represents a semi-ephemeral public key used for 0-RTT connection establishment.

type Lane 

type Lane struct {
	// ID is the Hub ID of the peer.
	ID 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
}

Lane represents a connection to another Hub.

func (*Lane) Equal 

func (l *Lane) Equal(other *Lane) bool

Equal returns whether the Lane is equal to the given one.

func (*Lane) String 

func (l *Lane) String() string

type Measurements 

type Measurements struct {
	sync.Mutex

	// Latency designates the latency between these Hubs.
	// It is specified in nanoseconds.
	Latency time.Duration
	// LatencyMeasuredAt holds when the latency was measured.
	LatencyMeasuredAt time.Time

	// Capacity designates the available bandwidth between these Hubs.
	// It is specified in bit/s.
	Capacity int
	// CapacityMeasuredAt holds when the capacity measurement expires.
	CapacityMeasuredAt time.Time

	// CalculatedCost stores the calculated cost for direct access.
	// It is not set automatically, but needs to be set when needed.
	CalculatedCost float32

	// GeoProximity stores an approximation of the geolocation proximity.
	// The value is between 0 (other side of the world) and 100 (same location).
	GeoProximity float32
	// contains filtered or unexported fields
}

Measurements holds various measurements relating to a Hub. Fields may not be accessed directly.

func NewMeasurements 

func NewMeasurements() *Measurements

NewMeasurements returns a new measurements struct.

func (*Measurements) Copy 

func (m *Measurements) Copy() *Measurements

Copy returns a copy of the measurements.

func (*Measurements) Expired 

func (m *Measurements) Expired(ttl time.Duration) bool

Expired returns whether any of the measurements has expired - calculated with the given TTL.

func (*Measurements) GetCalculatedCost 

func (m *Measurements) GetCalculatedCost() (cost float32)

GetCalculatedCost returns the calculated cost. The calculated cost is not set automatically, but needs to be set when needed.

func (*Measurements) GetCapacity 

func (m *Measurements) GetCapacity() (capacity int, measuredAt time.Time)

GetCapacity returns the capacity and when it expires. The capacity is measued in bit/s.

func (*Measurements) GetGeoProximity 

func (m *Measurements) GetGeoProximity() (geoProximity float32)

GetGeoProximity returns the geolocation proximity.

func (*Measurements) GetLatency 

func (m *Measurements) GetLatency() (latency time.Duration, measuredAt time.Time)

GetLatency returns the latency and when it expires.

func (*Measurements) IsPersisted 

func (m *Measurements) IsPersisted() bool

IsPersisted return whether changes to the measurements have been persisted.

func (*Measurements) SetCalculatedCost 

func (m *Measurements) SetCalculatedCost(cost float32)

SetCalculatedCost sets the calculated cost to the given value. The calculated cost is not set automatically, but needs to be set when needed.

func (*Measurements) SetCapacity 

func (m *Measurements) SetCapacity(capacity int)

SetCapacity sets the capacity to the given value. The capacity is measued in bit/s.

func (*Measurements) SetGeoProximity 

func (m *Measurements) SetGeoProximity(geoProximity float32)

SetGeoProximity sets the geolocation proximity to the given value.

func (*Measurements) SetLatency 

func (m *Measurements) SetLatency(latency time.Duration)

SetLatency sets the latency to the given value.

func (*Measurements) Valid 

func (m *Measurements) Valid() bool

Valid returns whether there is a valid value .

type MsgType 

type MsgType string

MsgType defines the message type.

type ParsedIntel 

type ParsedIntel struct {
	// HubAdvisory always affects all Hubs.
	HubAdvisory endpoints.Endpoints

	// HomeHubAdvisory is only taken into account when selecting a Home Hub.
	HomeHubAdvisory endpoints.Endpoints

	// DestinationHubAdvisory is only taken into account when selecting a Destination Hub.
	DestinationHubAdvisory endpoints.Endpoints
}

ParsedIntel holds a collection of parsed intel data.

type RegionConfig 

type RegionConfig struct {
	// ID is the internal identifier of the region.
	ID string
	// Name is a human readable name of the region.
	Name string
	// MemberPolicy specifies a list for including members.
	MemberPolicy []string

	// RegionalMinLanes specifies how many lanes other regions should build
	// to this region.
	RegionalMinLanes int
	// RegionalMinLanesPerHub specifies how many lanes other regions should
	// build to this region, per Hub in this region.
	// This value will usually be below one.
	RegionalMinLanesPerHub float64
	// RegionalMaxLanesOnHub specifies how many lanes from or to another region may be
	// built on one Hub per region.
	RegionalMaxLanesOnHub int

	// SatelliteMinLanes specifies how many lanes satellites (Hubs without
	// region) should build to this region.
	SatelliteMinLanes int
	// SatelliteMinLanesPerHub specifies how many lanes satellites (Hubs without
	// region) should build to this region, per Hub in this region.
	// This value will usually be below one.
	SatelliteMinLanesPerHub float64

	// InternalMinLanesOnHub specifies how many lanes every Hub should create
	// within the region at minimum.
	InternalMinLanesOnHub int
	// InternalMaxHops specifies the max hop constraint for internally optimizing
	// the region.
	InternalMaxHops int
}

RegionConfig holds the configuration of a region.

type Scope 

type Scope uint8

Scope is the network scope a Hub can be in. 

const (
	// ScopeInvalid defines an invalid scope.
	ScopeInvalid Scope = 0

	// ScopeLocal identifies local Hubs.
	ScopeLocal Scope = 1

	// ScopePublic identifies public Hubs.
	ScopePublic Scope = 2

	// ScopeTest identifies Hubs for testing.
	ScopeTest Scope = 0xFF
)

func (Scope) String 

func (s Scope) String() string

String returns the string representation of the scope.

type SingleTrustStore 

type SingleTrustStore struct {
	Signet *jess.Signet
}

SingleTrustStore is a simple truststore that always returns the same Signet.

func (*SingleTrustStore) GetSignet 

func (ts *SingleTrustStore) GetSignet(id string, recipient bool) (*jess.Signet, error)

GetSignet implements the truststore interface.

type Status 

type Status struct {
	Timestamp int64 `cbor:"t"`

	// Version holds the current software version of the Hub.
	Version string `cbor:"v"`

	// Routing Information
	Keys  map[string]*Key `cbor:"k,omitempty" json:",omitempty"` // public keys (with type)
	Lanes []*Lane         `cbor:"c,omitempty" json:",omitempty"` // Connections to other Hubs.

	// Status Information
	// Load describes max(CPU, Memory) in percent, averaged over at least 15
	// minutes. Load is published in fixed steps only.
	Load int `cbor:"l,omitempty" json:",omitempty"`

	// Flags holds flags that signify special states.
	Flags []string `cbor:"f,omitempty" json:",omitempty"`
}

Status is the message type used to update changing Hub Information. Changes are made automatically.

func (*Status) Copy 

func (s *Status) Copy() *Status

Copy returns a deep copy of the Status.

func (*Status) Export 

func (s *Status) Export(env *jess.Envelope) ([]byte, error)

Export exports the status with the given signature configuration.

func (*Status) HasFlag 

func (s *Status) HasFlag(flagName string) bool

HasFlag returns whether the Status has the given flag set.

type Transport 

type Transport struct {
	Protocol string
	Domain   string
	Port     uint16
	Path     string
	Option   string
}

Transport represents a "endpoint" that others can connect to. This allows for use of different protocols, ports and infrastructure integration.

func ParseBootstrapHub 

func ParseBootstrapHub(bootstrapTransport string) (t *Transport, hubID string, hubIP net.IP, err error)

ParseBootstrapHub parses a bootstrap hub.

func ParseTransport 

func ParseTransport(definition string) (*Transport, error)

ParseTransport parses a transport definition.

func ParseTransports 

func ParseTransports(definitions []string) (transports []*Transport, errs []error)

ParseTransports returns a list of parsed transports and errors from parsing the given definitions.

func (*Transport) String 

func (t *Transport) String() string

String returns the definition form of the transport.

type VirtualNetworkConfig 

type VirtualNetworkConfig struct {
	// Name is a human readable name of the virtual network.
	Name string
	// Force forces the use of the mapped IP addresses after the Hub's IPs have been verified.
	Force bool
	// Mapping maps Hub IDs to internal IP addresses.
	Mapping map[string]net.IP
}

VirtualNetworkConfig holds configuration of a virtual network that binds multiple Hubs together.

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.