webstepsx

Documentation

Overview

Package webstepsx contains a websteps implementation based on the internal/measurex package.

This implementation does not follow any existing spec rather we are modeling the spec on this one.

Index

• Variables
• func NewExperimentMeasurer(config Config) model.ExperimentMeasurer
• type Config
• type Measurer
  • func (mx *Measurer) ExperimentName() string
  • func (mx *Measurer) ExperimentVersion() string
  • func (mx *Measurer) GetSummaryKeys(measurement *model.Measurement) (interface{}, error)
  • func (mx *Measurer) Run(ctx context.Context, sess model.ExperimentSession, ...) error
  • func (mx *Measurer) RunAsync(ctx context.Context, sess model.ExperimentSession, input string, ...) (<-chan *model.ExperimentAsyncTestKeys, error)
• type SummaryKeys
• type THClient
  • func (c *THClient) Run(ctx context.Context, URL string) (*THServerResponse, error)
• type THClientCall
  • func (c *THClientCall) Call(ctx context.Context) (*THServerResponse, error)
• type THClientRequest
• type THHandler
  • func (h *THHandler) ServeHTTP(w http.ResponseWriter, req *http.Request)
• type THServerResponse
• type TestKeys

Variables

var (
	// ErrNoAvailableTestHelpers is emitted when there are no available test helpers.
	ErrNoAvailableTestHelpers = errors.New("no available helpers")

	// ErrNoInput indicates that no input was provided.
	ErrNoInput = errors.New("no input provided")

	// ErrInputIsNotAnURL indicates that the input is not an URL.
	ErrInputIsNotAnURL = errors.New("input is not an URL")

	// ErrUnsupportedInput indicates that the input URL scheme is unsupported.
	ErrUnsupportedInput = errors.New("unsupported input scheme")
)

Functions

func NewExperimentMeasurer

func NewExperimentMeasurer(config Config) model.ExperimentMeasurer

NewExperimentMeasurer creates a new ExperimentMeasurer.

Types

type Config

type Config struct{}

Config contains the experiment config.

type Measurer

type Measurer struct {
	Config Config
}

Measurer performs the measurement.

func (*Measurer) ExperimentName

func (mx *Measurer) ExperimentName() string

ExperimentName implements ExperimentMeasurer.ExperExperimentName.

func (*Measurer) ExperimentVersion

func (mx *Measurer) ExperimentVersion() string

ExperimentVersion implements ExperimentMeasurer.ExperExperimentVersion.

func (*Measurer) GetSummaryKeys

func (mx *Measurer) GetSummaryKeys(measurement *model.Measurement) (interface{}, error)

GetSummaryKeys implements model.ExperimentMeasurer.GetSummaryKeys.

func (*Measurer) Run

func (mx *Measurer) Run(ctx context.Context, sess model.ExperimentSession,
	measurement *model.Measurement, callbacks model.ExperimentCallbacks) error

Run implements ExperimentMeasurer.Run.

func (*Measurer) RunAsync

func (mx *Measurer) RunAsync(
	ctx context.Context, sess model.ExperimentSession, input string,
	callbacks model.ExperimentCallbacks) (<-chan *model.ExperimentAsyncTestKeys, error)

RunAsync implements ExperimentMeasurerAsync.RunAsync.

type SummaryKeys

type SummaryKeys struct {
	Accessible bool   `json:"accessible"`
	Blocking   string `json:"blocking"`
	IsAnomaly  bool   `json:"-"`
}

SummaryKeys contains summary keys for this experiment.

Note that this structure is part of the ABI contract with probe-cli therefore we should be careful when changing it.

type THClient

type THClient struct {
	// DNSServers is the MANDATORY list of DNS-over-UDP
	// servers to use to discover endpoints locally.
	DNServers []*measurex.ResolverInfo

	// HTTPClient is the MANDATORY HTTP client to
	// use for contacting the TH.
	HTTPClient measurex.HTTPClient

	// ServerURL is the MANDATORY URL of the TH HTTP endpoint.
	ServerURL string
}

THClient is the high-level API to invoke the TH. This API should be used by command line clients.

func (*THClient) Run

func (c *THClient) Run(ctx context.Context, URL string) (*THServerResponse, error)

Run calls the TH and returns the response or an error.

Arguments:

- ctx is the context with timeout/deadline/cancellation

- URL is the URL the TH server should measure for us

Algorithm:

- use DNSServers to discover extra endpoints for the target URL

- call the TH using the HTTPClient and the ServerURL

- return response or error.

type THClientCall

type THClientCall struct {
	// Endpoints contains the MANDATORY endpoints we discovered.
	Endpoints []*measurex.Endpoint

	// HTTPClient is the MANDATORY HTTP client to
	// use for contacting the TH.
	HTTPClient measurex.HTTPClient

	// Header contains the MANDATORY request headers.
	Header http.Header

	// THURL is the MANDATORY test helper URL.
	THURL string

	// TargetURL is the MANDATORY URL to measure.
	TargetURL string

	// UserAgent is the OPTIONAL user-agent to use.
	UserAgent string
}

THClientCall allows to perform a single TH client call. Make sure you fill all the fields marked as MANDATORY before use.

func (*THClientCall) Call

func (c *THClientCall) Call(ctx context.Context) (*THServerResponse, error)

Call performs the specified TH call and returns either a response or an error.

type THClientRequest

type THClientRequest struct {
	// Endpoints is a list of endpoints to measure.
	Endpoints []*measurex.Endpoint

	// URL is the URL we want to measure.
	URL string

	// HTTPRequestHeaders contains the request headers.
	HTTPRequestHeaders http.Header
}

THClientRequest is the request received by the test helper.

type THHandler

type THHandler struct{}

THHandler implements the test helper API.

This handler exposes a unique HTTP endpoint that you need to mount to the desired path when creating the server.

The canonical mount point for the HTTP endpoint is /api/v1/websteps.

Accepted methods and request body:

- we only accept POST;

- we expect a THClientRequest as the body.

Status code and response body:

- on success, status is 200 and THServerResponse is the body;

- on failure, status is 400 and there is no body.

func (*THHandler) ServeHTTP

func (h *THHandler) ServeHTTP(w http.ResponseWriter, req *http.Request)

ServerHTTP implements http.Handler.ServeHTTP.

type THServerResponse

type THServerResponse = measurex.THMeasurement

THServerResponse is the response from the test helper.

type TestKeys

type TestKeys struct {
	*measurex.ArchivalURLMeasurement
}

TestKeys contains the experiment's test keys.