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
- type AppPathSet
- type IAKey
- type PR
- 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
- type PathPredicate
- type SyncPaths
- 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 )
Variables ¶
This section is empty.
Functions ¶
This section is empty.
Types ¶
type AppPath ¶
type AppPath struct {
Entry *sciond.PathReplyEntry
}
AppPath contains a SCIOND path entry.
type AppPathSet ¶
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 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 ¶
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 ¶
Revoke asynchronously informs SCIOND about a revocation and flushes any paths containing the revoked IFID.
func (*PR) UnwatchFilter ¶
func (r *PR) UnwatchFilter(src, dst *addr.ISD_AS, filter *PathPredicate) error
UnwatchFilter deletes a previously registered filter.
func (*PR) Watch ¶
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 ¶
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 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.
Source Files