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 ooniprobe 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 model.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 model.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.