topology

package
v0.7.0 Latest Latest
Warning

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

 Go to latest Published: Mar 12, 2022 License: Apache-2.0 Imports: 22 Imported by: 0

Documentation

Overview

Package topology wraps two versions of the topology. The first is RWTopology, which permits other packages to change topology information. The second topology type is Topology. It is used by packages that only need read access to the topology.

The full JSON format for a SCION address looks like the following: 

"Addrs":{
  "IPv4": {
    "Public": {
      "Addr": "192.168.1.1",
      "L4Port": 31000,
      "OverlayPort": 30041,
    },
    "Bind": {
      "Addr": "127.0.0.1",
      "L4Port": 31000,
      "OverlayPort": 30041,
    }
  },
  "IPv6": {
    "Public": {
      "Addr": "2001:db8:f00:b43::1",
      "L4Port": 31000,
      "OverlayPort": 30041,
    },
    "Bind": {
      "Addr": "2001:db8:f00:b43::1",
      "L4Port": 31000,
      "OverlayPort": 30041,
    }
  }
}

Go applications parse the above in the following manner:

  • Properties not listed in the above are ignored;
  • If a "Bind" property is found, parsing will return an error; bind addresses for SCION sockets are currently not supported.
  • If an "OverlayPort" property is found, parsing will return an error; custom underlay ports for SCION sockets are currently not supported. NOTE: the JSON file uses the old "Overlay" term for the AS-level UDP fabric that forwards traffic. The new term for this (which is also used in the Go code base) is "Underlay".
  • If both property "IPv4" and "IPv6" are present, the address is assumed to be IPv6 and only that address is used (in other words, the IPv4 property contents are discarded); dual stacked addresses are currently not supported.

The full JSON format for a BR data-plane AS-external underlay socket looks like the following: 

{
  "Overlay": "UDP/IPv4",
  "ISD_AS": "1-ff00:0:1",
  "Bandwidth": 1000,
  "PublicOverlay": {
    "Addr": "192.168.0.1",
    "OverlayPort": 50000,
  },
  "BindOverlay": {
    "Addr": "127.0.0.1",
  },
  "RemoteOverlay": {
    "Addr": "192.168.0.2",
    "OverlayPort": 50000,
  },
  "LinkTo": "CORE",
  "MTU": 1472,
}

To construct a BR data-plane AS-external underlay socket address out of the above, the following rules are used:

  • Properties "ISD_AS", "Bandwidth", "LinkTo", and "MTU" are ignored. All unknown properties not included in the above example are silently ignored.
  • Properties "PublicOverlay" and "RemoteOverlay" must exist. An error is returned if one of them is missing.
  • Property "BindOverlay" is optional. If it is not present, then the address checks below do not apply to property "Addr" under "BindOverlay". If it is present, the address is subject to all format constraints below.
  • If property "Overlay" is "UDP/IPv4", all "Addr" properties are checked to be IPv4. If one cannot be parsed as an IPv4 address, an error is returned. If the address is the empty string, an error is returned.
  • If property "Overlay" is "UDP/IPv6", all "Addr" properties are checked to be IPv6. If one cannot be parsed as an IPv6 address, an error is returned. If the address is the empty string, an error is returned.
  • If a port property is missing, it is assumed to be 0. The application is free to interpret this however it sees fit.

The full JSON format for a BR data-plane AS-internal underlay socket address looks like the following: 

{
  "IPv4": {
    "PublicOverlay": {
      "Addr": "192.168.0.1",
      "OverlayPort": 31000,
    },
    BindOverlay": {
      "Addr": "127.0.0.1"
    }
  },
  "IPv6": {
    "PublicOverlay": {
      "Addr": "2001:db8:f00:b43::1",
      "OverlayPort": 31000
    },
    "BindOverlay": {
      "Addr": "::1"
    }
  }
}

To construct a BR data-plane AS-internal underlay socket address out of the above, the following rules are used:

  • Properties not listed in the above are ignored.
  • If both property "IPv4" and "IPv6" are present, the address is assumed to be IPv6 and only that address is used (in other words, the IPv4 property contents are discarded); dual stacked addresses are currently not supported.
  • For the chosen address, the underlay address is taken from the "BindOverlay" property; if this is the case, the "PublicOverlay" address is never parsed. The address must match the address type in the top-level property (IPv4 or IPv6), otherwise an error is returned. If the "BindOverlay" property does not exist, the underlay address is taken from the "PublicOverlay" property. The address must match the address type in the top-level property, otherwise an error is returned. No matter which address is used, the port is always taken from the "PublicOverlay" property". An unset port is interpreted as 0.

Index

Constants

View Source 
const EndhostPort = underlay.EndhostPort

EndhostPort is the underlay port that the dispatcher binds to on non-routers.

Variables

View Source 
var ErrAddressNotFound = serrors.New("address not found")

ErrAddressNotFound indicates the address was not found.

Functions

func Digest added in v0.7.0 

func Digest(t interface{}) ([]byte, error)

Types

type BFD added in v0.6.0 

type BFD struct {
	Disable               bool
	DetectMult            uint8
	DesiredMinTxInterval  time.Duration
	RequiredMinRxInterval time.Duration
}

BFD is the configuration for a BFD session

type BRInfo 

type BRInfo struct {
	Name string
	// InternalAddr is the local data-plane address.
	InternalAddr *net.UDPAddr
	// IFIDs is a sorted list of the interface IDs.
	IFIDs []common.IFIDType
	// IFs is a map of interface IDs.
	IFs map[common.IFIDType]*IFInfo
}

BRInfo is a list of AS-wide unique interface IDs for a router. These IDs are also used to point to the specific internal address clients should send their traffic to in order to use that interface, via the IFInfoMap member of the Topo struct.

type ControlValidator added in v0.7.0 

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

func (*ControlValidator) Validate added in v0.7.0 

func (v *ControlValidator) Validate(new, old *RWTopology) error

type DefaultValidator added in v0.7.0 

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

DefaultValidator is the default topology update validator.

func (*DefaultValidator) Validate added in v0.7.0 

func (v *DefaultValidator) Validate(new, old *RWTopology) error

type GatewayInfo added in v0.6.0 

type GatewayInfo struct {
	CtrlAddr        *TopoAddr
	DataAddr        *net.UDPAddr
	ProbeAddr       *net.UDPAddr
	AllowInterfaces []uint64
}

GatewayInfo describes a scion gateway.

type IDAddrMap added in v0.3.0 

type IDAddrMap map[string]TopoAddr

IDAddrMap maps process IDs to their topology addresses.

func (IDAddrMap) GetByID added in v0.5.0 

func (m IDAddrMap) GetByID(id string) *TopoAddr

GetByID returns the TopoAddr for the given ID, or nil if there is none.

type IFInfo 

type IFInfo struct {
	// ID is the interface ID. It is unique per AS.
	ID           common.IFIDType
	BRName       string
	Underlay     underlay.Type
	InternalAddr *net.UDPAddr
	Local        *net.UDPAddr
	Remote       *net.UDPAddr
	RemoteIFID   common.IFIDType
	IA           addr.IA
	LinkType     LinkType
	MTU          int
	BFD          BFD
}

IFInfo describes a border router link to another AS, including the internal data-plane address applications should send traffic to and information about the link itself and the remote side of it. 

func (i IFInfo) CheckLinks(isCore bool, brName string) error

CheckLinks checks whether the link types are compatible with whether the AS is core or not.

func (IFInfo) String 

func (i IFInfo) String() string

type IfInfoMap added in v0.4.0 

type IfInfoMap map[common.IFIDType]IFInfo

IfInfoMap maps interface ids to the interface information.

type LinkType added in v0.5.0 

type LinkType int

LinkType describes inter-AS links. 

const (
	// Unset is used for unknown link types.
	Unset LinkType = 0
	// Core links connect core ASes.
	Core LinkType = 1
	// Parent links are configured on non-core links pointing towards the core of an ISD.
	Parent LinkType = 2
	// Child links are configured on non-core links pointing away from the core of an ISD.
	Child LinkType = 3
	// Peer links are configured for peering relationships.
	Peer LinkType = 4
)

func LinkTypeFromString 

func LinkTypeFromString(s string) LinkType

LinkTypeFromString returns the numerical link type associated with a string description. If the string is not recognized, an Unset link type is returned. The matching is case-insensitive.

func (LinkType) MarshalText added in v0.7.0 

func (l LinkType) MarshalText() ([]byte, error)

func (LinkType) String added in v0.5.0 

func (l LinkType) String() string

func (*LinkType) UnmarshalText added in v0.7.0 

func (l *LinkType) UnmarshalText(data []byte) error

type Loader added in v0.7.0 

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

Loader can be used to reload the topology transparently. The default object is not usable and the loaded should be constructed with the NewLoader function.

func NewLoader added in v0.7.0 

func NewLoader(cfg LoaderCfg) (*Loader, error)

NewLoader creates a topology loader from the given configuration. This method tries to load the file initially and if that doesn't succeeds an error is returned.

func (*Loader) CA added in v0.7.0 

func (l *Loader) CA() bool

func (*Loader) ControlServiceAddress added in v0.7.0 

func (l *Loader) ControlServiceAddress(id string) *net.UDPAddr

func (*Loader) ControlServiceAddresses added in v0.7.0 

func (l *Loader) ControlServiceAddresses() []*net.UDPAddr

func (*Loader) Core added in v0.7.0 

func (l *Loader) Core() bool

func (*Loader) Gateways added in v0.7.0 

func (l *Loader) Gateways() ([]GatewayInfo, error)

TODO(lukedirtwalker): remove error and simplify struct in the return type.

func (*Loader) Get deprecated added in v0.7.0 

func (l *Loader) Get() Topology

Get gets the instance of the topology.

Deprecated: New code should use accessor methods instead.

func (*Loader) GetUnderlay added in v0.7.0 

func (l *Loader) GetUnderlay(svc addr.HostSVC) (*net.UDPAddr, error)

TODO(lukedirtwalker): remove error / cleanup.

func (*Loader) HandleHTTP added in v0.7.0 

func (l *Loader) HandleHTTP(w http.ResponseWriter, r *http.Request)

func (*Loader) HiddenSegmentLookupAddresses added in v0.7.0 

func (l *Loader) HiddenSegmentLookupAddresses() ([]*net.UDPAddr, error)

TODO(lukedirtwalker): remove error.

func (*Loader) HiddenSegmentRegistrationAddresses added in v0.7.0 

func (l *Loader) HiddenSegmentRegistrationAddresses() ([]*net.UDPAddr, error)

TODO(lukedirtwalker): remove error.

func (*Loader) IA added in v0.7.0 

func (l *Loader) IA() addr.IA

func (*Loader) InterfaceIDs added in v0.7.0 

func (l *Loader) InterfaceIDs() []uint16

func (*Loader) InterfaceInfoMap added in v0.7.0 

func (l *Loader) InterfaceInfoMap() map[common.IFIDType]IFInfo

func (*Loader) MTU added in v0.7.0 

func (l *Loader) MTU() uint16

func (*Loader) Run added in v0.7.0 

func (l *Loader) Run(ctx context.Context) error

Run runs the topology reloader. It makes sure that the topology is reloaded when the configured signal channel is filled. A topology that can't be parsed or doesn't validate will be ignored.

func (*Loader) Subscribe added in v0.7.0 

func (l *Loader) Subscribe() *Subscription

Subscribe can be used to subscribe to updates.

func (*Loader) UnderlayNextHop added in v0.7.0 

func (l *Loader) UnderlayNextHop(ifID uint16) *net.UDPAddr

type LoaderCfg added in v0.7.0 

type LoaderCfg struct {
	// File is the file from which the topology should be loaded.
	File string
	// Reload is the channel on which reloads can be triggered.
	Reload <-chan struct{}
	// Validator is used to validate topology updates. If this field is not set,
	// update is permissible. If the validation is error a reload is discarded
	Validator Validator
	// Metrics are the metrics of the loader, if left empty no metrics are
	// reported.
	Metrics LoaderMetrics
}

LoaderCfg is the configuration for the topology loader.

type LoaderMetrics added in v0.7.0 

type LoaderMetrics struct {
	// ValidationErrors counts the amount of validation errors.
	ValidationErrors metrics.Counter
	// ReadErrors counts the amount of file read or parse errors.
	ReadErrors metrics.Counter
	// LastUpdate indicates the timestamp of the last successful update.
	LastUpdate metrics.Gauge
	// Updates counts the amount of successful updates.
	Updates metrics.Counter
}

LoaderMetrics are the metrics exposed by the topology loader. Individual values can be nil, which means they will not be exposed.

type RWTopology added in v0.5.0 

type RWTopology struct {
	Timestamp  time.Time
	IA         addr.IA
	Attributes []jsontopo.Attribute
	MTU        int

	BR        map[string]BRInfo
	BRNames   []string
	IFInfoMap IfInfoMap

	CS                        IDAddrMap
	DS                        IDAddrMap
	HiddenSegmentLookup       IDAddrMap
	HiddenSegmentRegistration IDAddrMap
	SIG                       map[string]GatewayInfo
}

RWTopology is the topology type for applications and libraries that need write access to AS topology information (e.g., discovery, topology reloaders).

The first section contains metadata about the topology. All of these fields should be self-explanatory. The unit of TTL is seconds, with the zero value indicating an infinite TTL.

The second section concerns the Border routers. BRNames is just a sorted slice of the names of the BRs in this topology. Its contents is exactly the same as the keys in the BR map.

The BR map points from border router names to BRInfo structs, which in turn are lists of IFID type slices, thus defines the IFIDs that belong to a particular border router. The IFInfoMap points from interface IDs to IFInfo structs.

The third section in RWTopology concerns the SCION-specific services in the topology. The structure is identical between the various elements. For each service, there is again a sorted slice of names of the servers that provide the service. Additionally, there is a map from those names to TopoAddr structs.

func NewRWTopology added in v0.5.0 

func NewRWTopology() *RWTopology

NewRWTopology creates new empty Topo object, including all possible service maps etc.

func RWTopologyFromJSONBytes added in v0.5.0 

func RWTopologyFromJSONBytes(b []byte) (*RWTopology, error)

RWTopologyFromJSONBytes extracts the topology from a JSON representation in raw byte format.

func RWTopologyFromJSONFile added in v0.5.0 

func RWTopologyFromJSONFile(path string) (*RWTopology, error)

RWTopologyFromJSONFile extracts the topology from a file containing the JSON representation of the topology.

func RWTopologyFromJSONTopology added in v0.5.0 

func RWTopologyFromJSONTopology(raw *jsontopo.Topology) (*RWTopology, error)

RWTopologyFromJSONTopology converts a parsed JSON struct topology to a topology usable by Go code.

func (*RWTopology) Active added in v0.5.0 

func (t *RWTopology) Active(now time.Time) bool

Active returns whether the topology is active at the point in time specified by the argument. A topology is active if now is after the timestamp.

func (*RWTopology) Copy added in v0.6.0 

func (t *RWTopology) Copy() *RWTopology

Copy creates a deep copy of the object.

func (*RWTopology) GetTopoAddr added in v0.5.0 

func (t *RWTopology) GetTopoAddr(id string, svc ServiceType) (*TopoAddr, error)

GetTopoAddr returns the address information for the process of the requested type with the requested ID.

type RouterValidator added in v0.7.0 

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

func (*RouterValidator) Validate added in v0.7.0 

func (v *RouterValidator) Validate(new, old *RWTopology) error

type ServiceNames added in v0.3.0 

type ServiceNames []string

ServiceNames is a slice of process names (e.g., "bs-1", "bs-2").

func (ServiceNames) GetRandom added in v0.3.0 

func (s ServiceNames) GetRandom() (string, error)

GetRandom returns a random entry, or an error if the slice is empty.

type ServiceType added in v0.6.0 

type ServiceType int

ServiceType describes the type of servce. 

const (
	Unknown ServiceType = iota
	Router
	Control
	Discovery
	Gateway
	HiddenSegmentLookup
	HiddenSegmentRegistration
)

Service types

func ServiceTypeFromString added in v0.6.0 

func ServiceTypeFromString(s string) ServiceType

ServiceTypeFromString parses the service type.

func (ServiceType) String added in v0.6.0 

func (t ServiceType) String() string

type Subscription added in v0.7.0 

type Subscription struct {
	Updates <-chan struct{}
	// contains filtered or unexported fields
}

Subscription is a subscription for topology updates. It should be Closed whenever it's no longer used. When the context of the Loader is cancelled the Subscription will no longer be served, but the subscription channel is not closed. It is the user responsibility to stop using the Subscription if the Loader context is cancelled.

func (*Subscription) Close added in v0.7.0 

func (s *Subscription) Close()

type TopoAddr 

type TopoAddr struct {
	SCIONAddress    *net.UDPAddr
	UnderlayAddress *net.UDPAddr
}

TopoAddr wraps the possible addresses of a SCION service and describes the underlay to be used for contacting said service.

func (*TopoAddr) String 

func (a *TopoAddr) String() string

func (*TopoAddr) UnderlayAddr added in v0.5.0 

func (a *TopoAddr) UnderlayAddr() *net.UDPAddr

UnderlayAddr returns the underlay address interpreted as a net.UDPAddr.

FIXME(scrye): This should be removed; applications should not need to look into the underlay concrete type.

type Topology added in v0.5.0 

type Topology interface {
	// IA returns the local ISD-AS number.
	IA() addr.IA
	// MTU returns the MTU of the local AS.
	MTU() uint16
	// Core returns whether the local AS is core.
	Core() bool
	// CA returns whether the local AS is a CA.
	CA() bool
	// InterfaceIDs returns all interface IDS from the local AS.
	InterfaceIDs() []common.IFIDType

	// PublicAddress gets the public address of a server with the requested type and name, and nil
	// if no such server exists.
	PublicAddress(svc addr.HostSVC, name string) *net.UDPAddr

	// Anycast returns the address for an arbitrary server of the requested type.
	Anycast(svc addr.HostSVC) (*net.UDPAddr, error)
	// Multicast returns all addresses for the requested type.
	Multicast(svc addr.HostSVC) ([]*net.UDPAddr, error)

	// UnderlayAnycast returns the underlay address for an arbitrary server of the requested type.
	UnderlayAnycast(svc addr.HostSVC) (*net.UDPAddr, error)
	// UnderlayMulticast returns all underlay addresses for the requested type.
	UnderlayMulticast(svc addr.HostSVC) ([]*net.UDPAddr, error)
	// UnderlayNextHop returns the internal underlay address of the router
	// containing the interface ID.
	UnderlayNextHop(ifID common.IFIDType) (*net.UDPAddr, bool)

	// MakeHostInfos returns the underlay addresses of all services for the specified service type.
	MakeHostInfos(st ServiceType) ([]*net.UDPAddr, error)

	// Gateways returns an array of all gateways.
	Gateways() ([]GatewayInfo, error)

	// BR returns information for a specific border router
	//
	// FIXME(scrye): Simplify return type and make it topology format agnostic.
	//
	// XXX(scrye): Return value is a shallow copy.
	BR(name string) (BRInfo, bool)
	// IFInfoMap returns the mapping between interface IDs an internal addresses.
	//
	// FIXME(scrye): Simplify return type and make it topology format agnostic.
	//
	// XXX(scrye): Return value is a shallow copy.
	IFInfoMap() IfInfoMap

	// BRNames returns the names of all BRs in the topology.
	//
	// FIXME(scrye): Remove this, callers shouldn't care about names.
	//
	// XXX(scrye): Return value is a shallow copy.
	BRNames() []string

	// SVCNames returns the names of all servers in the topology for the specified service.
	//
	// FIXME(scrye): Remove this, callers shouldn't care about names.
	//
	// XXX(scrye): Return value is a shallow copy.
	SVCNames(svc addr.HostSVC) ServiceNames

	// Writable returns a pointer to the underlying topology object. This is included for legacy
	// reasons and should never be used.
	//
	// FIXME(scrye): Remove this.
	//
	// XXX(scrye): Return value is a shallow copy.
	Writable() *RWTopology
}

Topology is the topology type for applications and libraries that only need read access to AS topology information. This is the case of most applications and libraries that use the topology file to discover information about the local AS. Libraries that need to edit the topology (e.g., a topology reloading library that computes a new topology file based on information found on disk) should instead use the writable topology type present in this package.

func FromJSONBytes added in v0.7.0 

func FromJSONBytes(raw []byte) (Topology, error)

func FromJSONFile added in v0.5.0 

func FromJSONFile(path string) (Topology, error)

FromJSONFile extracts the topology from a file containing the JSON representation of the topology.

func FromRWTopology added in v0.5.0 

func FromRWTopology(topo *RWTopology) Topology

FromRWTopology wraps the high level topology interface API around a raw topology object.

func NewTopology added in v0.5.0 

func NewTopology() Topology

NewTopology creates a new empty topology.

type Validator added in v0.7.0 

type Validator interface {
	// Validate checks that the topology update is valid. Note that old might be
	// nil.
	Validate(new, old *RWTopology) error
}

Validator is used to validate that the topology update is permissible.

Source Files

View all Source files

Directories

Path Synopsis
Package json encodes AS topology information via JSON.
 Package json encodes AS topology information via JSON.
Package mock_topology is a generated GoMock package.
 Package mock_topology is a generated GoMock package.

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.