websteps

Documentation

Overview

Package websteps implements the websteps test helper.

See the https://github.com/ooni/spec/blob/master/backends/th-007-websteps.md related specification document.

This implementation uses version 202108.17.1114 of the spec.

Index

• Variables
• type Config
• type ControlResponse
  • func Measure(ctx context.Context, creq *CtrlRequest, config *Config) (*ControlResponse, error)
• type CtrlRequest
• type DNSMeasurement
• type DefaultExplorer
  • func (e *DefaultExplorer) Explore(URL *url.URL, headers map[string][]string) ([]*RoundTrip, error)
• type DefaultGenerator
  • func (g *DefaultGenerator) Generate(ctx context.Context, rts []*RoundTrip, clientResolutions []string) ([]*URLMeasurement, error)
  • func (g *DefaultGenerator) GenerateH3Endpoint(ctx context.Context, rt *RoundTrip, endpoint string) *EndpointMeasurement
  • func (g *DefaultGenerator) GenerateHTTPEndpoint(ctx context.Context, rt *RoundTrip, endpoint string) *EndpointMeasurement
  • func (g *DefaultGenerator) GenerateHTTPSEndpoint(ctx context.Context, rt *RoundTrip, endpoint string) *EndpointMeasurement
  • func (g *DefaultGenerator) GenerateURL(ctx context.Context, rt *RoundTrip, clientResolutions []string) *URLMeasurement
• type DefaultInitChecker
  • func (i *DefaultInitChecker) InitialChecks(URL string) (*url.URL, error)
• type EndpointMeasurement
• type Explorer
• type Generator
• type HTTPRequestMeasurement
• type HTTPResponseMeasurement
• type HTTPRoundTripMeasurement
• type Handler
  • func (h *Handler) ServeHTTP(w http.ResponseWriter, req *http.Request)
• type InitChecker
• type RoundTrip
• type TCPConnectMeasurement
• type TLSHandshakeMeasurement
• type URLMeasurement

Variables

var (
	DNSDo  = websteps.DNSDo
	TCPDo  = websteps.TCPDo
	QUICDo = websteps.QUICDo
	TLSDo  = websteps.TLSDo
	HTTPDo = websteps.HTTPDo
)

the testhelper uses the same network operations as websteps

var (
	// ErrInvalidURL indicates that the URL is invalid.
	ErrInvalidURL = errors.New("the URL is invalid")

	// ErrUnsupportedScheme indicates that we don't support the scheme.
	ErrUnsupportedScheme = errors.New("unsupported scheme")

	// ErrNoSuchHost indicates that the DNS resolution failed.
	ErrNoSuchHost = errors.New("no such host")
)

Errors returned by Preresolve.

var ErrInternalServer = errors.New("internal server error")

var ErrNoH3Location = errors.New("no h3 location found")

Types

type Config

type Config struct {
	// contains filtered or unexported fields
}

Config contains the building blocks of the testhelper algorithm

type ControlResponse

type ControlResponse = websteps.CtrlResponse

func Measure

func Measure(ctx context.Context, creq *CtrlRequest, config *Config) (*ControlResponse, error)

Measure performs the three consecutive steps of the testhelper algorithm:

1. InitialChecks

2. Explore

3. Generate

type CtrlRequest

type CtrlRequest = websteps.CtrlRequest

type DNSMeasurement

type DNSMeasurement = websteps.DNSMeasurement

type DefaultExplorer

type DefaultExplorer struct {
	// contains filtered or unexported fields
}

DefaultExplorer is the default Explorer.

func (*DefaultExplorer) Explore

func (e *DefaultExplorer) Explore(URL *url.URL, headers map[string][]string) ([]*RoundTrip, error)

Explore returns a list of round trips sorted so that the first round trip is the first element in the list, and so on. Explore uses the URL and the optional headers provided by the CtrlRequest.

type DefaultGenerator

type DefaultGenerator struct {
	// contains filtered or unexported fields
}

DefaultGenerator is the default Generator.

func (*DefaultGenerator) Generate

func (g *DefaultGenerator) Generate(ctx context.Context, rts []*RoundTrip, clientResolutions []string) ([]*URLMeasurement, error)

Generate takes in input a list of round trips and outputs a list of connectivity measurements for each of them.

func (*DefaultGenerator) GenerateH3Endpoint

func (g *DefaultGenerator) GenerateH3Endpoint(ctx context.Context, rt *RoundTrip, endpoint string) *EndpointMeasurement

GenerateH3Endpoint performs an HTTP/3 Request by a) establishing a QUIC connection to the target (QUICDo), b) performing an HTTP GET request to the endpoint (HTTPDo). It returns an EndpointMeasurement.

func (*DefaultGenerator) GenerateHTTPEndpoint

func (g *DefaultGenerator) GenerateHTTPEndpoint(ctx context.Context, rt *RoundTrip, endpoint string) *EndpointMeasurement

GenerateHTTPEndpoint performs an HTTP Request by a) establishing a TCP connection to the target (TCPDo), b) performing an HTTP GET request to the endpoint (HTTPDo). It returns an EndpointMeasurement.

func (*DefaultGenerator) GenerateHTTPSEndpoint

func (g *DefaultGenerator) GenerateHTTPSEndpoint(ctx context.Context, rt *RoundTrip, endpoint string) *EndpointMeasurement

GenerateHTTPSEndpoint performs an HTTPS Request by a) establishing a TCP connection to the target (TCPDo), b) establishing a TLS connection to the target (TLSDo), c) performing an HTTP GET request to the endpoint (HTTPDo). It returns an EndpointMeasurement.

func (*DefaultGenerator) GenerateURL

func (g *DefaultGenerator) GenerateURL(ctx context.Context, rt *RoundTrip, clientResolutions []string) *URLMeasurement

GenerateURL returns a URLMeasurement.

type DefaultInitChecker

type DefaultInitChecker struct {
	// contains filtered or unexported fields
}

DefaultInitChecker is the default InitChecker.

func (*DefaultInitChecker) InitialChecks

func (i *DefaultInitChecker) InitialChecks(URL string) (*url.URL, error)

InitialChecks checks whether the URL is valid and whether the domain inside the URL is an existing one. If these preliminary checks fail, there's no point in continuing. If they succeed, InitialChecks returns the URL, if not an error.

type EndpointMeasurement

type EndpointMeasurement = websteps.EndpointMeasurement

type Explorer

type Explorer interface {
	Explore(URL *url.URL, headers map[string][]string) ([]*RoundTrip, error)
}

Explorer is the interface responsible for running Explore.

type Generator

type Generator interface {
	Generate(ctx context.Context, rts []*RoundTrip, clientResolutions []string) ([]*URLMeasurement, error)
}

Generator is the interface responsible for running Generate.

type HTTPRequestMeasurement

type HTTPRequestMeasurement = websteps.HTTPRequestMeasurement

type HTTPResponseMeasurement

type HTTPResponseMeasurement = websteps.HTTPResponseMeasurement

type HTTPRoundTripMeasurement

type HTTPRoundTripMeasurement = websteps.HTTPRoundTripMeasurement

type Handler

type Handler struct {
	Config *Config
}

Handler implements the websteps test helper HTTP API.

func (*Handler) ServeHTTP

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

ServeHTTP implements http.Handler.ServeHTTP.

type InitChecker

type InitChecker interface {
	InitialChecks(URL string) (*url.URL, error)
}

InitChecker is the interface responsible for running InitialChecks.

type RoundTrip

type RoundTrip = websteps.RoundTripInfo

type TCPConnectMeasurement

type TCPConnectMeasurement = websteps.TCPConnectMeasurement

type TLSHandshakeMeasurement

type TLSHandshakeMeasurement = websteps.TLSHandshakeMeasurement

type URLMeasurement

type URLMeasurement = websteps.URLMeasurement