pathmgr

Documentation

Overview

Package pathmgr implements an asynchronous Path Resolver for SCION Paths.

A new resolver can be instantiated by calling `New`. There are two types of supported path queries, simple or periodic.

Simple path queries are issued via 'Query'; they return an AppPathSet of valid paths.

Periodic path queries are added via 'Watch', which returns a pointer to a thread-safe SyncPaths object; calling Load on the object returns the data associated with the watch, which includes the set of paths. When updating paths, the resolver will atomically change the value within the SyncPaths object. The data can be accessed by calling Load again.

An example of how this package can be used can be found in the associated infra test file.

If the connection to SCIOND fails, the resolver automatically attempts to reestablish the connection. During this period, paths are not expired. Paths will be transparently refreshed after reconnecting to SCIOND.

Index

• Constants
• type AppPath
  • func (ap *AppPath) Copy() *AppPath
  • func (ap *AppPath) Key() PathKey
• type AppPathSet
  • func NewAppPathSet(reply *sciond.PathReply) AppPathSet
  • func (aps AppPathSet) Add(entry *sciond.PathReplyEntry) *AppPath
  • func (aps AppPathSet) Copy() AppPathSet
  • func (aps AppPathSet) GetAppPath(pref PathKey) *AppPath
  • func (aps AppPathSet) String() string
• type IAKey
  • func (k IAKey) String() string
• type PR
  • func New(srvc sciond.Service, timers *Timers, logger log.Logger) (*PR, error)
  • func (r *PR) Query(src, dst *addr.ISD_AS) AppPathSet
  • func (r *PR) QueryFilter(src, dst *addr.ISD_AS, filter *PathPredicate) AppPathSet
  • func (r *PR) Revoke(revInfo common.RawBytes)
  • func (r *PR) Unwatch(src, dst *addr.ISD_AS) error
  • func (r *PR) UnwatchFilter(src, dst *addr.ISD_AS, filter *PathPredicate) error
  • func (r *PR) Watch(src, dst *addr.ISD_AS) (*SyncPaths, error)
  • func (r *PR) WatchFilter(src, dst *addr.ISD_AS, filter *PathPredicate) (*SyncPaths, error)
• type PathKey
  • func (pk PathKey) String() string
• type PathPredicate
  • func NewPathPredicate(expr string) (*PathPredicate, error)
  • func (pp *PathPredicate) Eval(path *sciond.PathReplyEntry) bool
  • func (pp *PathPredicate) MarshalJSON() ([]byte, error)
  • func (pp *PathPredicate) String() string
  • func (pp *PathPredicate) UnmarshalJSON(b []byte) error
• type SyncPaths
  • func NewSyncPaths() *SyncPaths
  • func (sp *SyncPaths) Load() *SyncPathsData
• type SyncPathsData
• type Timers

Constants

const (
	// Default wait time after a successful path lookup (for periodic lookups)
	DefaultNormalRefire = time.Minute
	// Default wait time after a failed path lookup (for periodic lookups)
	DefaultErrorRefire = time.Second
	// Default time after which a path is considered stale
	DefaultMaxAge = 6 * time.Hour
)

Types

type AppPath

type AppPath struct {
	Entry *sciond.PathReplyEntry
}

AppPath contains a SCIOND path entry.

func (*AppPath) Copy

func (ap *AppPath) Copy() *AppPath

func (*AppPath) Key

func (ap *AppPath) Key() PathKey

Key returns a unique PathKey that can be used for map indexing.

type AppPathSet

type AppPathSet map[PathKey]*AppPath

AppPathSet represents a set of SCIOND path entries, keyed by AppPath.Key().

func NewAppPathSet

func NewAppPathSet(reply *sciond.PathReply) AppPathSet

NewAppPathSet creates a new set of paths from a SCIOND path reply.

func (AppPathSet) Add

func (aps AppPathSet) Add(entry *sciond.PathReplyEntry) *AppPath

Add converts the SCIOND path entry to an AppPath and adds it to the set.

func (AppPathSet) Copy

func (aps AppPathSet) Copy() AppPathSet

func (AppPathSet) GetAppPath

func (aps AppPathSet) GetAppPath(pref PathKey) *AppPath

GetAppPath returns an AppPath from the set. It first tries to find a path with key pref; if one cannot be found, an arbitrary one is returned.

func (AppPathSet) String

func (aps AppPathSet) String() string

type IAKey

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

func (IAKey) String

func (k IAKey) String() string

type PR

type PR struct {
	// Lookup, reconnect and Register acquire this lock as separate goroutines
	sync.Mutex

	log.Logger
	// contains filtered or unexported fields
}

func New

func New(srvc sciond.Service, timers *Timers, logger log.Logger) (*PR, error)

New connects to SCIOND and spawns the asynchronous path resolver. Parameter timers can be used to customize path manager behavior; if any timer is left uninitialized, it is assigned the corresponding default value (see package constants). When a query for a path older than maxAge reaches the resolver, SCIOND is used to refresh the path. New returns with an error if a connection to SCIOND could not be established.

func (*PR) Query

func (r *PR) Query(src, dst *addr.ISD_AS) AppPathSet

Query returns a slice of paths between src and dst. If the paths are not found in the path resolver's cache, a query to SCIOND is issued and the function blocks until the reply is received.

func (*PR) QueryFilter

func (r *PR) QueryFilter(src, dst *addr.ISD_AS, filter *PathPredicate) AppPathSet

func (*PR) Revoke

func (r *PR) Revoke(revInfo common.RawBytes)

Revoke asynchronously informs SCIOND about a revocation and flushes any paths containing the revoked IFID.

func (*PR) Unwatch

func (r *PR) Unwatch(src, dst *addr.ISD_AS) error

func (*PR) UnwatchFilter

func (r *PR) UnwatchFilter(src, dst *addr.ISD_AS, filter *PathPredicate) error

UnwatchFilter deletes a previously registered filter.

func (*PR) Watch

func (r *PR) Watch(src, dst *addr.ISD_AS) (*SyncPaths, error)

Watch adds pair src-dst to the list of watched paths.

If this is the first call for the src-dst pair, the function blocks until an answer from SCIOND is received. Note that the resolver might asynchronously change the paths at any time. Calling Load on the returned object returns a reference to a structure containing the currently available paths.

On registration failure an error is returned.

func (*PR) WatchFilter

func (r *PR) WatchFilter(src, dst *addr.ISD_AS, filter *PathPredicate) (*SyncPaths, error)

WatchFilter returns a pointer to a SyncPaths object that contains paths from src to dst that adhere to the specified filter. On path changes the list is refreshed automatically.

WatchFilter also adds pair src-dst to the list of tracked paths (if it wasn't already tracked).

type PathKey

type PathKey string

Helper type for pretty printing of maps using paths as keys.

func (PathKey) String

func (pk PathKey) String() string

type PathPredicate

type PathPredicate struct {
	Match []sciond.PathInterface
}

A PathPredicate specifies which sequence of ASes and interfaces the packet must travel through; gaps in the matching are allowed. Wildcard ISDs, ASes and IFIDs are specified with 0. For example, a path filtering predicate that only allows paths which pass through ISD1 can be created with:

pp, err = NewPathPredicate("1-0#0")

To allow paths passing through ISD-AS 1-11 interface 27 and then ISD-AS 1-12 interface 95:

pp, err = NewPathPredicate("1-11#27,1-12#95")

func NewPathPredicate

func NewPathPredicate(expr string) (*PathPredicate, error)

func (*PathPredicate) Eval

func (pp *PathPredicate) Eval(path *sciond.PathReplyEntry) bool

func (*PathPredicate) MarshalJSON

func (pp *PathPredicate) MarshalJSON() ([]byte, error)

func (*PathPredicate) String

func (pp *PathPredicate) String() string

func (*PathPredicate) UnmarshalJSON

func (pp *PathPredicate) UnmarshalJSON(b []byte) error

type SyncPaths

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

SyncPaths contains a concurrency-safe reference to an AppPathSet that is continuously kept up to date by the path manager. Callers can safely `Load` the reference and use the paths within. At any moment, the path resolver can change the value of the reference within a SyncPaths to a different slice containing new paths. Calling code should reload the reference often to make sure the paths are fresh. Timestamp() can be called to get the time of the last write.

A SyncPaths must never be copied.

func NewSyncPaths

func NewSyncPaths() *SyncPaths

NewSyncPaths creates a new SyncPaths object and sets the timestamp to current time. A newly created SyncPaths contains a nil AppPathSet.

func (*SyncPaths) Load

func (sp *SyncPaths) Load() *SyncPathsData

Load returns a SyncPathsData snapshot of the data within sp.

type SyncPathsData

type SyncPathsData struct {
	APS         AppPathSet
	ModifyTime  time.Time
	RefreshTime time.Time
}

SyncPathsData is the atomic value inside a SyncPaths object. It provides a snapshot of a SyncPaths object. Callers must not change APS.

type Timers

type Timers struct {
	// Wait time after a successful path lookup (for periodic lookups)
	NormalRefire time.Duration
	// Wait time after a failed (error or empty) path lookup (for periodic lookups)
	ErrorRefire time.Duration
	// Duration after which a path is considered stale
	MaxAge time.Duration
}

Timers is used to customize the timers for a new Path Manager.