Documentation
¶
Overview ¶
Package itopo stores the static and dynamic topology. Client packages that grab a reference with Get are guaranteed to receive a stable snapshot of the topology. The returned value is the topology that is currently active.
There are two types of topologies, the static and the dynamic topology. For more information see lib/discovery.
Initialization ¶
The package must be initialized with Init. In subsequent updates through SetStatic or SetDynamic, the new topology is checked whether it is compatible with the previous version. The rules differ between services.
If the dynamic topology is set, the initializing client should start the periodic cleaner to evict expired dynamic topologies.
Updates ¶
The update of the topology is only valid if a set of constraints is met. The constraints differ between dynamic and static topology, and also between the initialized service type.
In a static topology update, when the diff is empty, the static topology is only updated if it expires later than the current static. Otherwise, SetStatic succeeds and indicates that the in-memory copy has not been updated.
A static topology update can force the dynamic topology to be dropped, if it does no longer meet the constraints.
Constraints ¶
The topology is split into five parts. An update is valid under the constraints, if the constraints for each part are met.
Immutable: This part may not differ from the initial static topology.
Mutable: This part may differ from the initial static topology. It may also differ between the currently active static and dynamic topology.
Semi-Mutable: This part may differ between static topology versions. However, it may not differ between the current dynamic and static topology. If an update to the static topology modifies this part, the dynamic topology is dropped.
Time: This part is ignored when validating the constraints. It is used to determine if a topology shall be updated if there are no differences in the other parts.
Ignored: This part is always ignored.
Default Topology Split ¶
The topology file for default initialization (calling Init) is split into immutable, mutable, time and ignored.
ISD_AS Immutable Core Immutable Overlay Immutable MTU Immutable Service Entries Mutable BorderRouter Entries Mutable Timestamp Time TTL Time TimestampHuman Ignored
Service Topology Split ¶
The topology file for services is split into immutable, mutable, time and ignored.
ISD_AS Immutable Core Immutable Overlay Immutable MTU Immutable OwnSvcType[OwnID] Immutable // The service entry for the initialized element. Service Entries Mutable // Except OwnSvcType[OwnID]. BorderRouter Entries Mutable Timestamp Time TTL Time TimestampHuman Ignored
Border Router Topology Split ¶
The topology file for border routers is split into immutable, semi-mutable, mutable, time and ignored.
ISD_AS Immutable Core Immutable Overlay Immutable MTU Immutable BorderRouters[OwnId][InternalAddrs] Immutable // Internal address of initialized router. BorderRouters[OwnId][CtrlAddr] Immutable // Control address of initialized router. BorderRouters[OwnId][Interfaces] Semi-Mutable // Interfaces of initialized router. Service Entries Mutable BorderRouter Entries Mutable // Except BorderRouters[OwnId]. Timestamp Time TTL Time TimestampHuman Ignored
Callbacks ¶
The client package can register callbacks to be notified about certain events.
Index ¶
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func Init ¶ added in v0.4.0
func Init(id string, svc proto.ServiceType, clbks Callbacks)
Init initializes itopo with the particular validator. A topology must be initialized by calling SetStatic.
func SetDynamic ¶ added in v0.4.0
SetDynamic atomically sets the dynamic topology. The returned topology is a pointer to the currently active topology at the end of the function call. It might differ from the input topology. The second return value indicates whether the in-memory copy of the dynamic topology has been updated.
Types ¶
type Callbacks ¶ added in v0.4.0
type Callbacks struct {
// CleanDynamic is called whenever dynamic topology is dropped due to expiration.
CleanDynamic func()
// DropDynamic is called whenever dynamic topology is dropped due to static update.
DropDynamic func()
// UpdateStatic is called whenever the pointer to static topology is updated.
UpdateStatic func()
}
Callbacks are callbacks to respond to specific topology update events.
type ServiceType ¶ added in v0.4.0
type ServiceType string
type Topology ¶ added in v0.4.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
// 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.
//
// FIXME(scrye): See whether this or its snet variant below can be removed.
PublicAddress(svc addr.HostSVC, name string) *addr.AppAddr
// SPublicAddress gets the public address of a server with the requested type and name, and nil
// if no such server exists.
//
// FIXME(scrye): See whether this or its app variant above can be removed.
SPublicAddress(svc addr.HostSVC, name string) *snet.Addr
// Exists returns true if the service and name are present in the topology file.
Exists(svc addr.HostSVC, name string) bool
// BindAddress gets the bind address of a server with the requested type and name, and nil
// if no such server exists.
//
// FIXME(scrye): See whether this or its snet variant below can be removed.
BindAddress(svc addr.HostSVC, name string) *addr.AppAddr
// BindAddress gets the bind address of a server with the requested type and name, and nil
// if no such server exists.
//
// FIXME(scrye): See whether this or its app variant above can be removed.
SBindAddress(svc addr.HostSVC, name string) *snet.Addr
// SBRAddress returns the internal public address of the BR with the specified name.
SBRAddress(name string) *snet.Addr
// OverlayAnycast returns the overlay address for an arbitrary server of the requested type.
OverlayAnycast(svc addr.HostSVC) (*overlay.OverlayAddr, error)
// OverlayMulticast returns all overlay addresses for the requested type.
OverlayMulticast(svc addr.HostSVC) ([]*overlay.OverlayAddr, error)
// OverlayByName returns the overlay address of the server name of the requested type.
//
// FIXME(scrye): This isn't really needed. We should also get rid of it.
OverlayByName(svc addr.HostSVC, name string) (*overlay.OverlayAddr, error)
// OverlayNextHop2 returns the internal overlay address of the router containing the ID. The
// return value is encoded as an overlay address.
//
// FIXME(scrye): Remove either this or the other method. A single return type should be
// supported.
OverlayNextHop2(ifID common.IFIDType) (*overlay.OverlayAddr, bool)
// OverlayNextHop returns the internal overlay address of the router containing the interface
// ID. The return value is encoded as a SCIOND host info struct.
//
// XXX(scrye): Return value is a shallow copy.
OverlayNextHop(ifID common.IFIDType) (hostinfo.Host, bool)
// MakeHostInfos returns the overlay addresses of all services for the specified service type.
//
// XXX(scrye): The return values are shallow copies.
MakeHostInfos(st proto.ServiceType) []hostinfo.Host
// 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) (topology.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() topology.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) []string
// Raw 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.
Raw() *topology.Topo
// Overlay returns the overlay running in the current AS.
//
// FIXME(scrye): Remove this.
Overlay() overlay.Type
// DS returns the discovery servers in the topology.
//
// FIXME(scrye): Simplify return type and make it topology format agnostic.
//
// XXX(scrye): Return value is a shallow copy.
DS() topology.IDAddrMap
}
func Get ¶ added in v0.4.0
func Get() Topology
Get atomically gets the pointer to the current topology.
func LoadFromFile ¶ added in v0.4.0
func NewTopology ¶ added in v0.4.0
func NewTopology() Topology
NewTopology creates a new empty topology.
func NewTopologyFromRaw ¶ added in v0.4.0
NewTopologyFromRaw wraps the high level topology interface API around a raw topology object.
func SetStatic ¶ added in v0.4.0
SetStatic atomically sets the static topology. Whether semi-mutable fields are allowed to change can be specified using semiMutAllowed. The returned topology is a pointer to the currently active topology at the end of the function call. It might differ from the input topology (same contents as existing static, or dynamic set and still valid). The second return value indicates whether the in-memory copy of the static topology has been updated.
type Transaction ¶ added in v0.4.0
type Transaction struct {
// contains filtered or unexported fields
}
Transaction allows to get a view on which topology will be active without committing to the topology update yet.
func BeginSetDynamic ¶ added in v0.4.0
func BeginSetDynamic(dynamic *topology.Topo) (Transaction, error)
BeginSetDynamic checks whether setting the dynamic topology is permissible. The returned transaction provides a view on which topology would be active, if committed.
func BeginSetStatic ¶ added in v0.4.0
func BeginSetStatic(static *topology.Topo, semiMutAllowed bool) (Transaction, error)
BeginSetStatic checks whether setting the static topology is permissible. The returned transaction provides a view on which topology would be active, if committed.
func (*Transaction) Commit ¶ added in v0.4.0
func (tx *Transaction) Commit() error
Commit commits the change. An error is returned, if the static topology changed in the meantime.
func (*Transaction) Get ¶ added in v0.4.0
func (tx *Transaction) Get() *topology.Topo
Get returns the topology that will be active if the transaction is committed.
func (*Transaction) IsUpdate ¶ added in v0.4.0
func (tx *Transaction) IsUpdate() bool
IsUpdate indicates whether the transaction will cause an update.
Source Files
Directories