speedtest

README

speedtest

A Go client for speedtest.net

Documentation

Overview

Package speedtest is a client for the speedtest.net bandwidth measuring service. This package is not affiliated, connected, or associated with speedtest.net in any way. For information about speedtest.net, visit: http://www.speedtest.net/

This package is hosted on GitHub: http://www.github.com/johnsto/speedtest

This package implements only one part of speedtest.net's functionality, namely the testing of your connection's upload and download bandwidth by way of HTTP requests made to one of the service's many global testing servers. It does not currently report the results back to the speedtest.net API.

Unlike speedtest.net, no attempt is made to ping servers to find the nearest one. The 'nearest' server is selected using the geographic locations returned by the speedtest.net API and may not always be physically correct.

A CLI is provided, which is the simplest and easiest way to measure your connection's bandwidth.

Below is a simple example of how you might test bandwidth against the first server reported by the service:

import "fmt"
import . "github.com/johnsto/speedtest"
import "net/http"
import "time"

func main() {
	// Fetch server list
	settings, _ := FetchSettings()
	// Configure benchmark
	benchmark := NewDownloadBenchmark(http.DefaultClient, settings.Servers[0])
	// Run benchmark
	rate := RunBenchmark(benchmark, 4, 16, time.Second * 10)
	// Print result (bps)
	fmt.Println(NiceRate(rate))
}

For a more detailed example, see speedtest-cli/cli.go

The algorithms used by this package differs from that used by the original service. There are no guarantees about whether the approach used here is more or less accurate, but my own measurements showed the results to be broadly representative of line speed.

Both upload and download testing send/receive as much data as they can within a given time period, increasing the number of concurrent requests as necessary. Data is read/written in 16kb chunks, and the amount of data transferred is logged into an array indexed by time, to a resolution of 100ms. Once all transfers are complete, the array is scanned to find the second in which cumulative data transfer was highest, and this value is combined with the median transfer rate over the period to provide an estimated speed.

This approach is designed to produce a value close to the peak speed of the line. In contrast, a mean average will typically underestimate due to the overheads of the testing process.

Index

• Variables
• func Distance(lat1 float64, lon1 float64, lat2 float64, lon2 float64) float64
• func Fetch(url string) ([]byte, error)
• func MaximalSumWindow(data []int, size int) int
• func MedianSumWindow(data []int, size int) int
• func NiceRate(rate int) string
• func RunBenchmark(b Benchmark, threads int, maxThreads int, duration time.Duration) int
• type Benchmark
• type CallbackWriter
  • func NewCallbackWriter(callback func(n int) error) CallbackWriter
  • func (b CallbackWriter) Write(p []byte) (n int, err error)
• type Client
• type Config
  • func FetchConfig() (Config, error)
• type DownloadBenchmark
  • func NewDownloadBenchmark(client http.Client, server Server) DownloadBenchmark
  • func (b DownloadBenchmark) Run(fn func(n int) error) error
• type JunkReader
  • func NewJunkReader(size int) JunkReader
  • func (r *JunkReader) Read(p []byte) (n int, err error)
• type Server
• type Servers
  • func (s Servers) Len() int
  • func (s Servers) SortByDistance()
  • func (s Servers) SortByID()
  • func (s Servers) Swap(i, j int)
• type Settings
  • func FetchSettings() (Settings, error)
  • func (settings Settings) UpdateDistances(lat float64, lon float64)
• type UploadBenchmark
  • func NewUploadBenchmark(client http.Client, server Server) UploadBenchmark
  • func (b UploadBenchmark) Run(fn func(n int) error) error

Variables

var ErrTimeExpired = errors.New("time expired")

ErrTimeExpired is returned by readers/writers if they were halted due to exceeding the duration of the benchmark.

Functions

func Distance

func Distance(lat1 float64, lon1 float64, lat2 float64, lon2 float64) float64

Distance calculates the distance between two geographical positions

func Fetch

func Fetch(url string) ([]byte, error)

Fetch GETs a URL and returns the response body

func MaximalSumWindow

func MaximalSumWindow(data []int, size int) int

MaximalSumWindow finds the the largest sum of sequential values for the given window size.

e.g. f([1, 3, 5, 2, 4], 1) = 5 as 5 is the largest single value in the list. f([1, 3, 5, 2, 4], 2) = 8 as (3 + 5) is 8, and no two other consecutive numbers can produce a larger sum.

This function is used to get a reasonable best estimate of a sustained maximum within a set of data.

func MedianSumWindow

func MedianSumWindow(data []int, size int) int

MedianSumWindow calculates a median sum of the given window size within the given data.

func NiceRate

func NiceRate(rate int) string

NiceRate represents a value measured in bytes/sec as bps, kbps or mbps as appropriate.

func RunBenchmark

func RunBenchmark(b Benchmark, threads int, maxThreads int, duration time.Duration) int

RunBenchmark runs the given benchmark for the given amount of time. It increases the number of threads up to the maximum as each one finishes. The returned value is the maximum number of bytes recorded from any contiguous 1 second window within the testing period.

Types

type Benchmark

type Benchmark interface {
	Run(func(n int) error) error
}

A Benchmark represents a specific bandwidth test.

type CallbackWriter

type CallbackWriter struct {
	Callback func(n int) error
}

A CallbackWriter is a Writer that calls a given callback for each Write. If the callback func returns an error, this is bubbled up from Write.

func NewCallbackWriter

func NewCallbackWriter(callback func(n int) error) CallbackWriter

NewCallbackWriter creates a CallbackWriter with the specified callback function.

func (CallbackWriter) Write

func (b CallbackWriter) Write(p []byte) (n int, err error)

Write writes data to the writer, returning the length of the output buffer, and any error returned by the callback.

type Client

type Client struct {
	IPAddress string  `xml:"ip,attr"`
	Lat       float64 `xml:"lat,attr"`
	Lon       float64 `xml:"lon,attr"`
	IspName   string  `xml:"isp,attr"`
}

Client encompasses client information provided by the speedtest.net API

type Config

type Config struct {
	XMLName xml.Name `xml:"settings"`
	Client  Client   `xml:"client"`
}

Config encompasses configuration data provided by the speedtest.net API

func FetchConfig

func FetchConfig() (Config, error)

FetchConfig fetches the recommended client configuration

type DownloadBenchmark

type DownloadBenchmark struct {
	Client  http.Client
	Server  Server
	BaseURL string
}

DownloadBenchmark represents a download bandwidth test.

func NewDownloadBenchmark

func NewDownloadBenchmark(client http.Client, server Server) DownloadBenchmark

NewDownloadBenchmark creates a new download benchmark with the given HTTP client and test server.

func (DownloadBenchmark) Run

func (b DownloadBenchmark) Run(fn func(n int) error) error

Run fetches a file, reporting the size of each downloaded chunk to the callback function, ending only on EOF or when the callback returns an error.

type JunkReader

type JunkReader struct {
	Data []byte
	Size int
	Pos  int
}

A JunkReader produces junk-ish data

func NewJunkReader

func NewJunkReader(size int) JunkReader

NewJunkReader creates a JunkReader that can be used to generate junk data of the specified size. A negative size is unbounded.

func (*JunkReader) Read

func (r *JunkReader) Read(p []byte) (n int, err error)

Read reads junk data into the specified buffer until the input buffer is filled or the reader is exhausted of data.

type Server

type Server struct {
	ID          int     `xml:"id,attr"`
	URL         string  `xml:"url,attr"`
	Lat         float64 `xml:"lat,attr"`
	Lon         float64 `xml:"lon,attr"`
	Name        string  `xml:"name,attr"`
	Country     string  `xml:"country,attr"`
	CountryCode string  `xml:"cc,attr"`
	Sponsor     string  `xml:"sponsor,attr"`
	// Distance is calculated locally from the client configuration
	Distance float64
}

Server encompasses a server definition returned by the speedtest.net API

type Servers

type Servers []Server

Servers represents a sortable list of servers

func (Servers) Len

func (s Servers) Len() int

Len returns the length

func (Servers) SortByDistance

func (s Servers) SortByDistance()

SortByDistance sorts the servers by their measured distance.

func (Servers) SortByID

func (s Servers) SortByID()

SortByID sorts their servers by their numerical ID.

func (Servers) Swap

func (s Servers) Swap(i, j int)

Swap swaps the items at the specified indexes

type Settings

type Settings struct {
	XMLName xml.Name `xml:"settings"`
	Servers Servers  `xml:"servers>server"`
}

Settings encompasses server settings data provided by the speedtest.net API

func FetchSettings

func FetchSettings() (Settings, error)

FetchSettings fetches the list of available servers

func (Settings) UpdateDistances

func (settings Settings) UpdateDistances(lat float64, lon float64)

UpdateDistances updates the Servers with the current latitude/longitude

type UploadBenchmark

type UploadBenchmark struct {
	Client http.Client
	Server Server
}

UploadBenchmark represents an upload bandwidth test.

func NewUploadBenchmark

func NewUploadBenchmark(client http.Client, server Server) UploadBenchmark

NewUploadBenchmark creates a new upload benchmark with the given HTTP client and test server.

func (UploadBenchmark) Run

func (b UploadBenchmark) Run(fn func(n int) error) error

Run performs an HTTP POST, uploading junk data and reporting the size of each uploaded chunk.