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 spathmeta.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 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.IA) spathmeta.AppPathSet
  • func (r *PR) QueryFilter(src, dst addr.IA, filter *pktcls.ActionFilterPaths) spathmeta.AppPathSet
  • func (r *PR) Revoke(revInfo common.RawBytes)
  • func (r *PR) Sciond() sciond.Service
  • func (r *PR) Unwatch(src, dst addr.IA) error
  • func (r *PR) UnwatchFilter(src, dst addr.IA, filter *pktcls.ActionFilterPaths) error
  • func (r *PR) Watch(src, dst addr.IA) (*SyncPaths, error)
  • func (r *PR) WatchFilter(src, dst addr.IA, filter *pktcls.ActionFilterPaths) (*SyncPaths, 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 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.IA) spathmeta.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.IA, filter *pktcls.ActionFilterPaths) spathmeta.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) Sciond

func (r *PR) Sciond() sciond.Service

func (*PR) Unwatch

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

func (*PR) UnwatchFilter

func (r *PR) UnwatchFilter(src, dst addr.IA, filter *pktcls.ActionFilterPaths) error

UnwatchFilter deletes a previously registered filter.

func (*PR) Watch

func (r *PR) Watch(src, dst addr.IA) (*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.IA, filter *pktcls.ActionFilterPaths) (*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 SyncPaths

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

SyncPaths contains a concurrency-safe reference to an spathmeta.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 spathmeta.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         spathmeta.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.