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.

Index

• Constants
• func StartPeriodic(params PollingParameters, ch chan sciond.PathReqFlags) *periodic.Runner
• type DefaultPollingPolicy
  • func (pp *DefaultPollingPolicy) Destroy()
  • func (pp *DefaultPollingPolicy) PollC() <-chan sciond.PathReqFlags
  • func (pp *DefaultPollingPolicy) PollNow()
  • func (pp *DefaultPollingPolicy) UpdateState(availablePaths spathmeta.AppPathSet)
• type Policy
• type PollingParameters
• type PollingPolicy
  • func NewPollingPolicy(haveFilter bool, timers Timers) PollingPolicy
• type Querier
• type Resolver
  • func New(conn sciond.Connector, timers Timers, pathCount uint16) Resolver
• type SyncPaths
  • func NewSyncPaths() *SyncPaths
  • func (sp *SyncPaths) Destroy()
  • func (sp *SyncPaths) Load() *SyncPathsData
  • func (sp *SyncPaths) Update(newAPS spathmeta.AppPathSet)
• type SyncPathsData
• type Timers
  • func (timers *Timers) GetWait(isError bool) time.Duration
• type WatchFactory
  • func NewWatchFactory(timers Timers) *WatchFactory
  • func (factory *WatchFactory) New(sp *SyncPaths, bq *queryConfig, pp PollingPolicy) *WatchReference
• type WatchReference
  • func (ref *WatchReference) Destroy()
  • func (ref *WatchReference) Run()
• type WatchRunner
  • func (w *WatchRunner) Run()
  • func (w *WatchRunner) Stop()

Constants

const (
	// DefaultNormalRefire is the wait time after a successful path lookup (for periodic lookups)
	DefaultNormalRefire = 10 * time.Second
	// DefaultErorrRefire is the wait time after a failed path lookup (for periodic lookups)
	DefaultErrorRefire = time.Second
	// DefaultQueryTimeout is the time allocated for a query to SCIOND
	DefaultQueryTimeout = 5 * time.Second
	// DefaultPathCount is the maximum number of paths returned to the user.
	DefaultPathCount = 5
)

Functions

func StartPeriodic

func StartPeriodic(params PollingParameters, ch chan sciond.PathReqFlags) *periodic.Runner

Types

type DefaultPollingPolicy

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

func (*DefaultPollingPolicy) Destroy

func (pp *DefaultPollingPolicy) Destroy()

func (*DefaultPollingPolicy) PollC

func (pp *DefaultPollingPolicy) PollC() <-chan sciond.PathReqFlags

func (*DefaultPollingPolicy) PollNow

func (pp *DefaultPollingPolicy) PollNow()

func (*DefaultPollingPolicy) UpdateState

func (pp *DefaultPollingPolicy) UpdateState(availablePaths spathmeta.AppPathSet)

type Policy

type Policy interface {
	Filter(pathpol.PathSet) pathpol.PathSet
}

Policy is used to filter paths

type PollingParameters

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

type PollingPolicy

type PollingPolicy interface {
	// UpdateState reconfigures the polling policy based on availablePaths.
	UpdateState(availablePaths spathmeta.AppPathSet)
	// PollNow triggers a new query now, irrespective of other timers.
	PollNow()
	// PollC returns the channel that is written to whenever the policy
	// dictates a new poll. Ticks are dropped if the channel is full.
	PollC() <-chan sciond.PathReqFlags
	// Destroy shuts down any running goroutines.
	Destroy()
}

PollingPolicy describes how SCIOND should be polled, taking into account various aspects such as number of paths and the existence of a filtering policy. The PollingPolicy decides when SCIOND should be queried next, and which flags to be set.

func NewPollingPolicy

func NewPollingPolicy(haveFilter bool, timers Timers) PollingPolicy

type Querier

type Querier interface {
	// Query returns a set of paths between src and dst.
	Query(ctx context.Context, src, dst addr.IA, flags sciond.PathReqFlags) spathmeta.AppPathSet
}

type Resolver

type Resolver interface {
	Querier
	// QueryFilter returns a set of paths between src and dst that satisfy
	// policy. A nil policy will not delete any paths.
	QueryFilter(ctx context.Context, src, dst addr.IA, policy Policy) spathmeta.AppPathSet
	// Watch returns an object that periodically polls for paths between src
	// and dst.
	//
	// The function blocks until the first answer from SCIOND is received. The
	// amount of time is dictated by ctx. 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.
	//
	// The asynchronous worker is not subject to ctx; thus, it has infinite
	// lifetime or until Destroy is called on the SyncPaths object.
	Watch(ctx context.Context, src, dst addr.IA) (*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.
	//
	// A nil filter will not delete any paths.
	WatchFilter(ctx context.Context, src, dst addr.IA, filter Policy) (*SyncPaths, error)
	// WatchCount returns the number of active watchers.
	WatchCount() int
	// RevokeRaw informs SCIOND of a revocation.
	RevokeRaw(ctx context.Context, rawSRevInfo common.RawBytes)
	// Revoke informs SCIOND of a revocation.
	Revoke(ctx context.Context, sRevInfo *path_mgmt.SignedRevInfo)
}

func New

func New(conn sciond.Connector, timers Timers, pathCount uint16) Resolver

New creates a new path management context.

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.

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) Destroy

func (sp *SyncPaths) Destroy()

func (*SyncPaths) Load

func (sp *SyncPaths) Load() *SyncPathsData

Load returns a SyncPathsData snapshot of the data within sp.

func (*SyncPaths) Update

func (sp *SyncPaths) Update(newAPS spathmeta.AppPathSet)

Update adds and removes paths in sp to match newAPS. If a path was added or removed, the modified timestamp is updated. The refresh timestamp is always updated. FIXME(scrye): Add SCIOND support s.t. the refresh timestamp is changed only when paths (including path metadata) change.

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
}

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

func (*Timers) GetWait

func (timers *Timers) GetWait(isError bool) time.Duration

type WatchFactory

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

WatchFactory creates and tracks path watches, i.e., path polling goroutines.

func NewWatchFactory

func NewWatchFactory(timers Timers) *WatchFactory

func (*WatchFactory) New

func (factory *WatchFactory) New(sp *SyncPaths, bq *queryConfig, pp PollingPolicy) *WatchReference

type WatchReference

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

WatchReference is a reference to an internal Watch managed by the PathManager. Call Run to start the goroutine associated with the watch, and call Destroy to stop it.

Calling Run after a reference has been destroyed will result in a no-op.

func (*WatchReference) Destroy

func (ref *WatchReference) Destroy()

func (*WatchReference) Run

func (ref *WatchReference) Run()

type WatchRunner

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

WatchRunner polls SCIOND in accordance to a polling policy, updating a concurrency-safe store of paths after every poll.

Call Stop to shut down the running goroutine. It is safe to call Stop multiple times from different goroutines.

func (*WatchRunner) Run

func (w *WatchRunner) Run()

func (*WatchRunner) Stop

func (w *WatchRunner) Stop()