v2

Documentation

Overview

Package v2 defines the request API for the location service.

While well provisioned, the M-Lab Platform is finite. On occasion, due to peak usage, local service outages, or abnormal client behavior the location service must decline to schedule new user requests. This is necesssary to safegaurd measurement quality of your measurements and those of others. The v2 API classifies user requests into three priorities.

API-key | Access Token | Priority
--------------------------------------------------------
YES     | YES          | API-Key, High Availability Pool
YES     | NO           | API-Key, Best Effort Pool
NO      | NO           | Global Best Effort Pool

For highest priority access to the platform, register an API key and use the NearestResult.NextRequest.URL when provided.

Index

• type Error
  • func NewError(typ, title string, status int) *Error
• type Location
• type MonitoringResult
• type NearestResult
• type NextRequest
• type Target

Types

type Error

type Error struct {
	// RFC7807 Fields for "Problem Details".
	Type     string `json:"type"`
	Title    string `json:"title"`
	Status   int    `json:"status"`
	Detail   string `json:"detail,omitempty"`
	Instance string `json:"instance,omitempty"`
}

Error describes an error condition that prevents the server from completing a NearestResult.

func NewError

func NewError(typ, title string, status int) *Error

NewError creates a new api Error for a NearestResult.

type Location

type Location struct {
	City    string `json:"city"`
	Country string `json:"country"`
}

Location contains metadata about the geographic location of a target machine.

type MonitoringResult

type MonitoringResult struct {
	// Error contains information about request failures.
	Error *Error `json:"error,omitempty"`

	// AccessToken is the access token used in Target URLs. Some applications
	// may use this value instead of specific Target.URLs.
	AccessToken string `json:"access_token"`

	// Target contains service URLs for monitoring the service on the target
	// machine.
	// TODO (kinkade): Remove this field once all monitoring clients are using
	// the Results field below.
	Target *Target `json:"target,omitempty"`

	// Results is array of Targets matching the client request. In the case of
	// monitoring requests this array will only contain a single element, but we
	// leave it as an array so that the response of monitoring requests matches
	// the response of normal locate requests so that clients can treat data
	// from either request the same.
	Results []Target `json:"results,omitempty"`
}

MonitoringResult contains one Target with a single-purpose access-token useful only for monitoring services on the target machine.

type NearestResult

type NearestResult struct {
	// Error contains information about request failures.
	Error *Error `json:"error,omitempty"`

	// NextRequest defines the earliest time that a client should make a new
	// request using the included URL.
	//
	// Under normal circumstances, NextRequest is provided *with* Results. The
	// next request time is sampled from an exponential distribution such that
	// inter-request times are memoryless. Under abnormal circumstances, such as
	// high single-client request rates or target capacity exhaustion, the next
	// request is provided *without* Results.
	//
	// Non-interactive or batch clients SHOULD schedule measurements with this
	// value. All clients SHOULD NOT make additional requests more often than
	// NextRequest. The server MAY reject requests indefinitely when clients do
	// not respect this limit.
	NextRequest *NextRequest `json:"next_request,omitempty"`

	// Results contains an array of Targets matching the client request.
	Results []Target `json:"results,omitempty"`
}

NearestResult is returned by the location service in response to query requests.

type NextRequest

type NextRequest struct {
	// NotBefore defines the time after which the URL will become valid. This
	// value is the same time used in "nbf" field of the underlying JSON Web
	// Token (JWT) claim. To show this equivalence, we use the same name.
	NotBefore time.Time `json:"nbf"`

	// Expires defines the time after which the URL will be invalid. Expires will
	// always be greater than NotBefore. This value is the same time used in the
	// "exp" field of the underlying JWT claim.
	Expires time.Time `json:"exp"`

	// URL should be used to make the next request to the location service.
	URL string `json:"url"`
}

NextRequest contains a URL for scheduling the next request. The URL embeds an access token that will be valid after `NotBefore`. The access token will remain valid until it `Expires`. If a client uses an expired URL, the request will be handled as if no access token were provided, i.e. using a lower priority class.

type Target

type Target struct {
	// Machine is the FQDN of the machine hosting the measurement service.
	Machine string `json:"machine"`

	// Location contains metadata about the geographic location of the target machine.
	Location *Location `json:"location,omitempty"`

	// URLs contains measurement service resource names and the complete URL for
	// running a measurement.
	//
	// A measurement service may support multiple resources (e.g. upload,
	// download, etc). Each key is a resource name and the value is a complete
	// URL with protocol, service name, port, and parameters fully specified.
	URLs map[string]string `json:"urls"`
}

Target contains information needed to run a measurement to a measurement service on a single M-Lab machine. Measurement services may support multiple resources. A Target contains at least one measurement service resource in URLs.