topology

Documentation

Overview

The topology package wraps two versions of the topology. The first is RawTopo (in raw.go), which closely matches the JSON format. It is mainly used for loading the topology from disk. The second data structure is Topo. It is used by Go code directly and thus has a different structure and stricter types.

Since the RawTopo format is pretty self-explanatory, we will focus on the Topo structure here.

The basic layout is as follows:

type Topo struct {
    Timestamp      int64
    TimestampHuman string
    ISD_AS         addr.IA
    Overlay        overlay.Type
    MTU            int
    Core           bool

    BR             map[string]BRInfo
    BRNames        []string
    // This maps Interface IDs to internal addresses. Clients use this to
    // figure out which internal BR address they have to send their traffic to
    // if they want to use a given (external) interface.
    IFInfoMap map[common.IFIDType]IFInfo

    BS      map[string]TopoAddr
    BSNames []string
    CS      map[string]TopoAddr
    CSNames []string
    PS      map[string]TopoAddr
    PSNames []string
    SB      map[string]TopoAddr
    SBNames []string
    RS      map[string]TopoAddr
    RSNames []string
    DS      map[string]TopoAddr
    DSNames []string

    ZK map[int]TopoAddr
}

The first section contains metadata about the topology. All of these fields should be self-explanatory.

The second section concerns the Border routers. BRNames is just a sorted slice of the names of the BRs in this topolgy. 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. This mapping thus defines which IFIDs belong to a particular border router. The IFInfoMap points from interface IDs to IFInfo structs:

type IFInfo struct {
    BRName          string
    InternalAddr    *TopoAddr
    Overlay         overlay.Type
    Local           *TopoAddr
    Remote          *AddrInfo
    RemoteIFID      common.IFIDType
    Bandwidth       int
    ISD_AS          addr.IA
    LinkType        proto.LinkType
    MTU             int
}

This struct describes a border router link to another AS, including the internal address applications should send traffic for the link to (InternalAddr) and inoformation about the link itself and the remote side of it.

The third section in Topo 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:

type TopoAddr struct {
    IPv4    *topoAddrInt
    IPv6    *topoAddrInt
    Overlay overlay.Type
}

This structure wraps the possible addresses of a SCION service and describes the overlay to be used for contacting said service.

The two sub-structures for IPv4 and IPv6 only differ in the type of addresses they can contain and look like this:

type topoAddrInt struct {
    pubIP       net.IP
    pubL4Port   int
    bindIP      net.IP
    bindL4Port  int
    OverlayPort int
}

Since Go can handle both v4 and v6 addresses in net.IP, no indirection is needed.

On top of these two structures, there is also AddrInfo:

type AddrInfo struct {
    Overlay     overlay.Type
    IP          net.IP
    L4Port      int
    OverlayPort int
}

This struct is used to point to a specific endpoint, i.e. it does not distinguish bind and public ports and can only hold either an IPv4 or an IPv6 address.

Index

• Constants
• func LinkTypeFromString(s string) (proto.LinkType, error)
• func StripBind(rt *RawTopo)
• func StripServices(rt *RawTopo)
• type BRInfo
• type IFInfo
  • func (i IFInfo) String() string
• type RawAddrInfo
  • func (rai RawAddrInfo) String() string
  • func (s *RawAddrInfo) ToTopoAddr(ot overlay.Type) (t *TopoAddr, err error)
• type RawAddrPort
  • func (a RawAddrPort) String() string
• type RawAddrPortOverlay
  • func (a RawAddrPortOverlay) String() string
• type RawBRInfo
  • func (b RawBRInfo) String() string
• type RawBRIntf
• type RawTopo
  • func LoadRaw(b common.RawBytes) (*RawTopo, error)
  • func LoadRawFromFile(path string) (*RawTopo, error)
• type Topo
  • func Load(b common.RawBytes) (*Topo, error)
  • func LoadFromFile(path string) (*Topo, error)
  • func NewTopo() *Topo
  • func TopoFromRaw(raw *RawTopo) (*Topo, error)
  • func (t *Topo) GetRandomServer(serviceType proto.ServiceType) (*addr.AppAddr, error)
  • func (t *Topo) GetTopoAddr(serviceType proto.ServiceType, id string) *TopoAddr
• type TopoAddr
  • func TopoAddrFromRAI(s *RawAddrInfo, ot overlay.Type) (*TopoAddr, error)
  • func (t *TopoAddr) BindAddr(ot overlay.Type) *addr.AppAddr
  • func (t *TopoAddr) BindOrPublic(ot overlay.Type) *addr.AppAddr
  • func (t *TopoAddr) Equal(o *TopoAddr) bool
  • func (t *TopoAddr) OverlayAddr(ot overlay.Type) *overlay.OverlayAddr
  • func (t *TopoAddr) PublicAddr(ot overlay.Type) *addr.AppAddr
  • func (t *TopoAddr) String() string

Constants

const (
	ErrInvalidPub        = "Invalid public IP address in topology"
	ErrInvalidBind       = "Invalid bind IP address in topology"
	ErrTooManyPubV4      = "Too many public IPv4 addresses"
	ErrTooManyPubV6      = "Too many public IPv6 addresses"
	ErrTooManyBindV4     = "Too many bind IPv4 addresses"
	ErrTooManyBindV6     = "Too many bind IPv6 addresses"
	ErrBindWithoutPubV4  = "Bind IPv4 address without any public IPv4 address"
	ErrBindWithoutPubV6  = "Bind IPv6 address without any public IPv6 address"
	ErrExactlyOnePub     = "Overlay requires exactly one public address"
	ErrAtLeastOnePub     = "Overlay requires at least one public address"
	ErrOverlayPort       = "Overlay port set for non-UDP overlay"
	ErrBindAddrEqPubAddr = "Bind address equal to Public address"
)

const (
	ErrorOpen    = "Unable to open topology"
	ErrorParse   = "Unable to parse topology from JSON"
	ErrorConvert = "Unable to convert RawTopo to Topo"
)

const (
	CoreLinkName   = "CORE"
	ParentLinkName = "PARENT"
	ChildLinkName  = "CHILD"
	PeerLinkName   = "PEER"
)

const CfgName = "topology.json"

Functions

func LinkTypeFromString

func LinkTypeFromString(s string) (proto.LinkType, error)

func StripBind

func StripBind(rt *RawTopo)

func StripServices

func StripServices(rt *RawTopo)

Types

type BRInfo

type BRInfo struct {
	IFIDs []common.IFIDType
}

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 IFInfo

type IFInfo struct {
	BRName       string
	InternalAddr *TopoAddr
	Overlay      overlay.Type
	Local        *TopoAddr
	Remote       *overlay.OverlayAddr
	RemoteIFID   common.IFIDType
	Bandwidth    int
	ISD_AS       addr.IA
	LinkType     proto.LinkType
	MTU          int
}

func (IFInfo) String

func (i IFInfo) String() string

type RawAddrInfo

type RawAddrInfo struct {
	Public []RawAddrPortOverlay
	Bind   []RawAddrPort `json:",omitempty"`
}

func (RawAddrInfo) String

func (rai RawAddrInfo) String() string

func (*RawAddrInfo) ToTopoAddr

func (s *RawAddrInfo) ToTopoAddr(ot overlay.Type) (t *TopoAddr, err error)

type RawAddrPort

type RawAddrPort struct {
	Addr   string
	L4Port int
}

func (RawAddrPort) String

func (a RawAddrPort) String() string

type RawAddrPortOverlay

type RawAddrPortOverlay struct {
	RawAddrPort
	OverlayPort int `json:",omitempty"`
}

Since Public addresses may be associated with an Overlay port, extend the structure used for Bind addresses.

func (RawAddrPortOverlay) String

func (a RawAddrPortOverlay) String() string

type RawBRInfo

type RawBRInfo struct {
	InternalAddr *RawAddrInfo
	Interfaces   map[common.IFIDType]RawBRIntf
}

func (RawBRInfo) String

func (b RawBRInfo) String() string

type RawBRIntf

type RawBRIntf struct {
	Overlay   string       `json:",omitempty"`
	Bind      *RawAddrPort `json:",omitempty"`
	Public    *RawAddrPort `json:",omitempty"`
	Remote    *RawAddrPort `json:",omitempty"`
	Bandwidth int
	ISD_AS    string
	LinkTo    string
	MTU       int
}

type RawTopo

type RawTopo struct {
	Timestamp          int64
	TimestampHuman     string
	ISD_AS             string
	Overlay            string
	MTU                int
	Core               bool
	BorderRouters      map[string]RawBRInfo   `json:",omitempty"`
	ZookeeperService   map[int]RawAddrPort    `json:",omitempty"`
	BeaconService      map[string]RawAddrInfo `json:",omitempty"`
	CertificateService map[string]RawAddrInfo `json:",omitempty"`
	PathService        map[string]RawAddrInfo `json:",omitempty"`
	SibraService       map[string]RawAddrInfo `json:",omitempty"`
	RainsService       map[string]RawAddrInfo `json:",omitempty"`
	DiscoveryService   map[string]RawAddrInfo `json:",omitempty"`
}

RawTopo is used to un/marshal from/to JSON and should usually not be used by Go code directly. Use Topo (from lib/topology/topology.go) instead.

func LoadRaw

func LoadRaw(b common.RawBytes) (*RawTopo, error)

func LoadRawFromFile

func LoadRawFromFile(path string) (*RawTopo, error)

type Topo

type Topo struct {
	Timestamp      time.Time
	TimestampHuman string // This can vary wildly in format and is only for informational purposes.
	ISD_AS         addr.IA
	Overlay        overlay.Type
	MTU            int
	Core           bool

	BR      map[string]BRInfo
	BRNames []string
	// This maps Interface IDs to internal addresses. Clients use this to
	// figure out which internal BR address they have to send their traffic to
	// if they want to use a given interface.
	IFInfoMap map[common.IFIDType]IFInfo

	BS      map[string]TopoAddr
	BSNames []string
	CS      map[string]TopoAddr
	CSNames []string
	PS      map[string]TopoAddr
	PSNames []string
	SB      map[string]TopoAddr
	SBNames []string
	RS      map[string]TopoAddr
	RSNames []string
	DS      map[string]TopoAddr
	DSNames []string

	ZK map[int]TopoAddr
}

Topo is the main struct encompassing topology information for use in Go code.

func Load

func Load(b common.RawBytes) (*Topo, error)

func LoadFromFile

func LoadFromFile(path string) (*Topo, error)

func NewTopo

func NewTopo() *Topo

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

func TopoFromRaw

func TopoFromRaw(raw *RawTopo) (*Topo, error)

Convert a JSON-filled RawTopo to a Topo usabled by Go code.

func (*Topo) GetRandomServer

func (t *Topo) GetRandomServer(serviceType proto.ServiceType) (*addr.AppAddr, error)

GetRandomServer returns the application address for a random service of type t; BS, PS, and CS are currently supported. Randomness is taken from the default source. If no server is found, an error is returned.

func (*Topo) GetTopoAddr

func (t *Topo) GetTopoAddr(serviceType proto.ServiceType, id string) *TopoAddr

GetTopoAddr is a helper method that returns the TopoAddress for a specific element ID of type t. nodeType must be one of BS, CS or PS. If the ID is not found, nil is returned.

type TopoAddr

type TopoAddr struct {
	IPv4    *pubBindAddr
	IPv6    *pubBindAddr
	Overlay overlay.Type
}

func TopoAddrFromRAI

func TopoAddrFromRAI(s *RawAddrInfo, ot overlay.Type) (*TopoAddr, error)

Create TopoAddr from RawAddrInfo, depending on supplied Overlay type

func (*TopoAddr) BindAddr

func (t *TopoAddr) BindAddr(ot overlay.Type) *addr.AppAddr

func (*TopoAddr) BindOrPublic

func (t *TopoAddr) BindOrPublic(ot overlay.Type) *addr.AppAddr

func (*TopoAddr) Equal

func (t *TopoAddr) Equal(o *TopoAddr) bool

func (*TopoAddr) OverlayAddr

func (t *TopoAddr) OverlayAddr(ot overlay.Type) *overlay.OverlayAddr

func (*TopoAddr) PublicAddr

func (t *TopoAddr) PublicAddr(ot overlay.Type) *addr.AppAddr

func (*TopoAddr) String

func (t *TopoAddr) String() string