nuvolari

README

Nuvolari

Package nuvolari implements a NDTv7 client. NDTv7 is a non backwards compatible redesign of the NDT protocol. In particular we redesigned the NDT protocol (NDP) to work natively and only over WebSocket and TLS, so to remove the complexity induced by trying to be backward compatible with NDT's original implementation.

This package is called nuvolari because it is the companion package of the NDT7 server implementation, included in m-lab/ndt-cloud. You can translate "cloud" to "nuvola" in Italian. Also Tazio Nuvolari was a fast and brave Formula One driver in the late fourties and we aim for this implementation to be also fast to read and efficient. Also Nuvolari was basso di statura (i.e. not so high) and also my surname means "not so high", hence the package name sounds perfect.

This is the package's anthem:

.

Documentation

Overview

Package nuvolari implements a NDTv7 client.

Index

• Constants
• type Client
  • func NewClient(settings Settings) (Client, error)
  • func (cl Client) Download(ctx context.Context) chan Event
• type EvKey
• type Event
• type FailureRecord
• type LogLevel
• type LogRecord
• type MeasurementRecord
• type Settings

Constants

const (
	// LogEvent indicates an event containing a log message
	LogEvent = EvKey("log")
	// MeasurementEvent indicates an event containing some measurements
	MeasurementEvent = EvKey("ndt7.measurement")
	// FailureEvent indicates an event containing an error
	FailureEvent = EvKey("measurement.failure")
)

const (
	// LogWarning indicates a warning message
	LogWarning = LogLevel("warning")
	// LogInfo indicates an informational message
	LogInfo = LogLevel("info")
	// LogDebug indicates a debug message
	LogDebug = LogLevel("debug")
)

Types

type Client

type Client struct {
	// Dialer is a WebSocket dialer. The default configuration should be good
	// in most cases. However, for testing purposes you MAY want to disable
	// TLS certificate verification by setting a custom TSLClientConfig field.
	Dialer websocket.Dialer

	// URL is the URL to use. The only required field is Host. If the Scheme
	// is empty, we will use "wss". If the Path is empty, we will use
	// the canonical path for the selected subtest (e.g. "/ndt/v7/download"
	// for the download subtest). If the Query is empty we will send no
	// query. To configure the maximum duration, you can add a "duration" value
	// to the query string (see cmd/nuvolari-server/main.go).
	URL url.URL
}

Client is a NDT7 client.

func NewClient

func NewClient(settings Settings) (Client, error)

NewClient creates a new client given specific |settings|.

func (Client) Download

func (cl Client) Download(ctx context.Context) chan Event

Download runs a NDT7 download test. The |ctx| context allows the caller to interrupt the download early by cancelling the context.

type EvKey

type EvKey string

EvKey uniquely identifies an event.

type Event

type Event struct {
	Key   EvKey       `json:"key"`   // Tells you the kind of the event
	Value interface{} `json:"value"` // Opaque event value
}

Event is the structure of a generic event

type FailureRecord

type FailureRecord struct {
	Failure string `json:"failure"` // The error that occurred
}

FailureRecord is the structure of a failure event

type LogLevel

type LogLevel string

LogLevel indicates the severity of a log message

type LogRecord

type LogRecord struct {
	LogLevel LogLevel `json:"log_level"` // Message severity
	Message  string   `json:"message"`   // The message
}

LogRecord is the structure of a log event

type MeasurementRecord

type MeasurementRecord struct {
	ndt7.Measurement      // The measurement
	IsLocal          bool `json:"is_local"` // Whether it is a local measurement
}

MeasurementRecord is the structure of a measurement event

type Settings

type Settings struct {
	// Adaptive indicates whether the server is allowed to terminate the
	// download early if BBR converges before the configured duration.
	Adaptive bool `json:"adaptive"`

	// DisableTLS indicates whether we should disable TLS.
	DisableTLS bool `json:"disable_tls"`

	// Duration indicates an optional duration expressed in seconds.
	Duration int `json:"duration"`

	// Hostname is the hostname of the NDT7 server.
	Hostname string `json:"hostname"`

	// Port is the port of the NDT7 server.
	Port string `json:"port"`

	// SkipTLSVerify indicates whether we should skip TLS verify.
	SkipTLSVerify bool `json:"skip_tls_verify"`
}

Settings contains the NDT7 Client settings. This structure is serializable to JSON and allows to configure a Client from bindings.