hopannotation

Documentation

Overview

Package hopannotation handles hop annotation and archiving.

In the context of this package, a hop is synonymous with an IP address. This package uses the uuid-annotator (github.com/m-lab/uuid-annotator) to annotate hops. Each hop annotation consists of geolocation and Autonomous System Number (ASN) data according to MaxMind, IPinfo.io, and RouteViews databases.

Hop annotations are cached for a maximum of one day because the annotations can change. Each hop cache has a cache resetter goroutine that resets the cache every day at midnight.

A hop cache entry is an IP address plus the date in yyyymmdd format. (e.g., 100.116.79.252-2021-08-26). The purpose of the date suffix is to make sure that hop annotations of a traceroute that ran right before midnight do not prevent us from annotating the same hops today.

Index

• Variables
• type Config
• type HopAnnotation1
• type HopCache
  • func New(ctx context.Context, haCfg Config) (*HopCache, error)
  • func (hc *HopCache) Annotate(ctx context.Context, hops []string, traceStartTime time.Time) (map[string]*annotator.ClientAnnotations, []error)
  • func (hc *HopCache) Reset()
  • func (hc *HopCache) WriteAnnotations(annotations map[string]*annotator.ClientAnnotations, traceStartTime time.Time) []error

Variables

var (
	// ErrParseHopIP means a hop IP address could not be parsed.
	ErrParseHopIP = errors.New("failed to parse hop IP address")
	// ErrCreatePath means a directory path for hop annotations could not be created.
	ErrCreatePath = errors.New("failed to create directory path")
	// ErrMarshalAnnotation means a hop annotation could not be marshaled.
	ErrMarshalAnnotation = errors.New("failed to marshal annotation to json")
	// ErrWriteMarshal means a hop annotation could not be written to file.
	ErrWriteMarshal = errors.New("failed to write marshaled annotation")
)

Types

type Config

type Config struct {
	AnnotatorClient ipservice.Client
	OutputPath      string
}

Config contains configuration parameters of a hop cache. The parameters include the IP service to use and where to save the annotations.

type HopAnnotation1

type HopAnnotation1 struct {
	ID          string
	Timestamp   time.Time
	Annotations *annotator.ClientAnnotations
}

HopAnnotation1 is the datatype that is written to the hop annotation file.

type HopCache

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

HopCache is the cache of hop annotations.

func New

func New(ctx context.Context, haCfg Config) (*HopCache, error)

New returns a new HopCache that will use the provided ipservice.Client to obtain annotations. It also starts a goroutine that checks for the passage of the midnight every minute to reset the cache. The goroutine will terminate when the ctx is cancelled.

func (*HopCache) Annotate

func (hc *HopCache) Annotate(ctx context.Context, hops []string, traceStartTime time.Time) (map[string]*annotator.ClientAnnotations, []error)

Annotate annotates new hops found in the hops argument. It aggregates the errors and returns all of them instead of returning after encountering the first error.

func (*HopCache) Reset

func (hc *HopCache) Reset()

Reset creates a new empty hop cache that is a little bigger (25%) than the current cache. The current cache is retained as old cache to allow for active annotations to finish.

func (*HopCache) WriteAnnotations

func (hc *HopCache) WriteAnnotations(annotations map[string]*annotator.ClientAnnotations, traceStartTime time.Time) []error

WriteAnnotations writes out the annotations passed in. It writes out the annotations in parallel for speed. It aggregates the errors and returns all of them instead of returning after encountering the first error.