discovery

Documentation

Overview

Package discovery provides library support to query the discovery service for topology files.

The discovery service serves topology files for its own AS. Clients can use it to fetch an initial topology file, or to update their topology. The topology files are served in two different modes and two different privilege versions. Non privileged entities should only get the necessary information of the topology.

Modes

Static: The topology file in static mode is updated infrequently. It contains a subset of all available service instances which have stable addresses and availability.

Dynamic: The topology file in dynamic mode is updated frequently. Service instances are dynamically added and removed based on their status. This allows ASes to dynamically start and stop instances.

Files

There are two privilege versions of the topology file. The endhost version is intended for end hosts and non-privileged entities. The full version is only intended for privileged entities that need all topology information.

Endhost: The endhost version of the topology file contains all the information necessary for end hosts. Unnecessary information is stripped from the file (e.g. border router interface addresses or beacon service addresses).

Full: The full version of the topology file contains all the information. This file is only accessible by privileged entities (e.g infrastructure elements).

Default: When the default version of the topology file is requested, the discovery service decides which version to serve based on the privilege of the requester.

Paths

The topology files are fetched with a simple http get request. The path is dependent on the mode and file version:

static  && default:  /discovery/v1/static/default.json
static  && endhost:  /discovery/v1/static/endhost.json
static  && full:     /discovery/v1/static/full.json
dynamic && default:  /discovery/v1/dynamic/default.json
dynamic && endhost:  /discovery/v1/dynamic/endhost.json
dynamic && full:     /discovery/v1/dynamic/full.json

Index

• Constants
• func FetchTopo(ctx context.Context, params FetchParams, ds *addr.AppAddr, client *http.Client) (*topology.Topo, error)
• func FetchTopoRaw(ctx context.Context, params FetchParams, ds *addr.AppAddr, client *http.Client) (*topology.Topo, common.RawBytes, error)
• func Path(mode Mode, file File) string
• type FetchParams
• type Fetcher
• type File
• type InstanceInfo
• type InstancePool
• type Mode

Constants

const (
	// Base is the base path for the topology file url. It is supposed to be used
	// as Base/<mode>/<file>. For example, the dynamic and full topology has the url
	// "discovery/v1/dynamic/full.json"
	Base = "discovery/v1"
)

Functions

func FetchTopo

func FetchTopo(ctx context.Context, params FetchParams, ds *addr.AppAddr,
	client *http.Client) (*topology.Topo, error)

FetchTopo fetches the topology with the specified parameters from the discovery service. If client is nil, the default http client is used.

func FetchTopoRaw

func FetchTopoRaw(ctx context.Context, params FetchParams, ds *addr.AppAddr,
	client *http.Client) (*topology.Topo, common.RawBytes, error)

FetchTopoRaw fetches the topology with the specified parameters from the discovery service. If client is nil, the default http client is used. Both the topology and the raw response body are returned.

func Path

func Path(mode Mode, file File) string

Path creates the route to the topology file based on the mode and file.

Types

type FetchParams

type FetchParams struct {
	// Mode indicates whether the static or the dynamic topology is requested.
	Mode Mode
	// File indicates whether the full, endhost or default topology is requested.
	File File
	// Https indicates whether https should be used.
	Https bool
}

FetchParams contains the parameters for fetching the topology from the discovery service.

type Fetcher

type Fetcher interface {
	periodic.Task
	// UpdateInstances updates the discovery service instances for the fetcher.
	// It can be used to notify fetcher in case a new topology file has been
	// received from sources other than the discovery service
	// (e.g. through sighup reloading)
	UpdateInstances(topology.IDAddrMap) error
}

Fetcher is a periodic task that fetches topology form the discovery service.

type File

type File string

const (
	// Full is the full topology file, including all service information.
	Full File = "full.json"
	// Endhost is a stripped down topology file for non-privileged entities.
	Endhost File = "endhost.json"
	// Default is a topology file whose content is based on the privilege of
	// the requester.
	Default File = "default.json"
)

type InstanceInfo

type InstanceInfo interface {
	fmt.Stringer
	// Update updates the address.
	Update(*addr.AppAddr)
	// Key returns the key of the instance.
	Key() string
	// Addr returns the address of the instance.
	Addr() *addr.AppAddr
	// FailCount returns a number indicating how often
	// the instance has failed.
	FailCount() int
	// Fail adds to the fail count. This should be called by
	// the client when it fails to reach the instance.
	Fail()
}

InstanceInfo provides the information for a single discovery service instance.

type InstancePool

type InstancePool interface {
	// Update updates the pool based on a new discovery service map.
	Update(topology.IDAddrMap) error
	// Choose returns the info for the best discovery service instance
	// according to the pool.
	Choose() (InstanceInfo, error)
}

InstancePool keeps a pool of known discovery service instances.

type Mode

type Mode string

const (
	// Dynamic indicates the dynamic mode.
	Dynamic Mode = "dynamic"
	// Static indicates the static mode.
	Static Mode = "static"
)