websteps

package
v3.14.0 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Feb 23, 2022 License: GPL-3.0 Imports: 20 Imported by: 0

Documentation

Overview

Package websteps implements the websteps experiment.

Specifications:

- test helper: https://github.com/ooni/spec/blob/master/backends/th-007-websteps.md

- experiment: N/A.

We are currently implementing:

- version 202108.17.1114 of the test helper spec.

- version N/A of the experiment spec.

Index

Constants

This section is empty.

Variables

View Source 
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")
)
View Source 
var ErrNoConnReuse = errors.New("cannot reuse connection")
View Source 
var SupportedQUICVersions = map[string]bool{
	"h3": true,
}

SupportedQUICVersions are the H3 over QUIC versions we currently support

Functions

func DNSDo 

func DNSDo(ctx context.Context, config DNSConfig) ([]string, error)

DNSDo performs the DNS check.

func HTTPDo 

func HTTPDo(req *http.Request, transport http.RoundTripper) (*http.Response, []byte, error)

HTTPDo performs the HTTP check. Input: req *http.Request 

The same request than the one used by the Explore step.
This means that req contains the headers set by the original CtrlRequest, as well as,
in case of a redirect chain, additional headers that were added due to redirects

transport http.RoundTripper: 

The transport to use, either http.Transport, or http3.RoundTripper.

func NewDialerResolver 

func NewDialerResolver(resolver model.Resolver) model.Dialer

NewDialerResolver contructs a new dialer for TCP connections, with default, errorwrapping and resolve functionalities

func NewExperimentMeasurer 

func NewExperimentMeasurer(config Config) model.ExperimentMeasurer

NewExperimentMeasurer creates a new ExperimentMeasurer.

func NewQUICDialerResolver 

func NewQUICDialerResolver(resolver model.Resolver) model.QUICDialer

NewQUICDialerResolver creates a new QUICDialerResolver with default, errorwrapping and resolve functionalities

func NewRequest 

func NewRequest(ctx context.Context, URL *url.URL, headers http.Header) *http.Request

func NewSingleH3Transport 

func NewSingleH3Transport(qsess quic.EarlySession, tlscfg *tls.Config, qcfg *quic.Config) http.RoundTripper

NewSingleH3Transport creates an http3.RoundTripper.

func NewSingleTransport 

func NewSingleTransport(conn net.Conn) http.RoundTripper

NewSingleTransport creates a new HTTP transport with a single-use dialer.

func NewTransportWithDialer 

func NewTransportWithDialer(dialer model.Dialer, tlsConfig *tls.Config, handshaker model.TLSHandshaker) http.RoundTripper

NewSingleTransport creates a new HTTP transport with a custom dialer and handshaker.

func QUICDo 

func QUICDo(ctx context.Context, config QUICConfig) (quic.EarlySession, error)

QUICDo performs the QUIC check.

func TCPDo 

func TCPDo(ctx context.Context, config TCPConfig) (net.Conn, error)

TCPDo performs the TCP check.

func TLSDo 

func TLSDo(ctx context.Context, conn net.Conn, hostname string) (net.Conn, error)

TLSDo performs the TLS check.

Types

type Config 

type Config struct{}

Config contains the experiment config.

type CtrlRequest 

type CtrlRequest struct {
	// URL is the mandatory URL to measure.
	URL string `json:"url"`

	// Headers contains optional headers.
	Headers map[string][]string `json:"headers"`

	// Addrs contains the optional IP addresses resolved by the
	// probe for the domain inside URL.
	Addrs []string `json:"addrs"`
}

CtrlRequest is the request sent by the probe to the test helper.

type CtrlResponse 

type CtrlResponse struct {
	// URLs contains the URLs we should measure. These URLs
	// derive from CtrlRequest.URL.
	URLs []*URLMeasurement `json:"urls"`
}

CtrlResponse is the response from the test helper.

func Control 

func Control(
	ctx context.Context, sess model.ExperimentSession,
	thAddr string, resourcePath string, creq CtrlRequest) (out CtrlResponse, err error)

Control performs the control request and returns the response.

type DNSConfig 

type DNSConfig struct {
	Domain   string
	Resolver model.Resolver
}

type DNSMeasurement 

type DNSMeasurement struct {
	// Domain is the domain we wanted to resolve.
	Domain string `json:"domain"`

	// Failure is the error that occurred.
	Failure *string `json:"failure"`

	// Addrs contains the resolved addresses.
	Addrs []string `json:"addrs"`
}

DNSMeasurement is a DNS measurement.

type EndpointMeasurement 

type EndpointMeasurement struct {
	// Endpoint is the endpoint we're measuring.
	Endpoint string `json:"endpoint"`

	// Protocol is one of "http", "https", and "h3".
	Protocol string `json:"protocol"`

	// TCPConnect is the TCP connect measurement. This field
	// is only meaningful when protocol is "http" or "https."
	TCPConnect *TCPConnectMeasurement `json:"tcp_connect"`

	// QUICHandshake is the QUIC handshake measurement. This field
	// is only meaningful when the protocol is "h3".
	QUICHandshake *QUICHandshakeMeasurement `json:"quic_handshake"`

	// TLSHandshake is the TLS handshake measurement. This field
	// is only meaningful when the protocol is "https".
	TLSHandshake *TLSHandshakeMeasurement `json:"tls_handshake"`

	// HTTPRoundTrip is the related HTTP GET measurement.
	HTTPRoundTrip *HTTPRoundTripMeasurement `json:"http_round_trip"`
}

EndpointMeasurement is an HTTP measurement where we are using a specific TCP/TLS/QUIC endpoint to get the URL.

The specification describes this data structure as the sum of three distinct types: HTTPEndpointMeasurement for "http", HTTPSEndpointMeasurement for "https", and H3EndpointMeasurement for "h3". We don't have sum types here, therefore we use the Protocol field to indicate which fields are meaningful.

type HTTPRequestMeasurement 

type HTTPRequestMeasurement struct {
	// Method is the request method.
	Method string `json:"method"`

	// URL is the request URL.
	URL string `json:"url"`

	// Headers contains request headers.
	Headers http.Header `json:"headers"`
}

HTTPRequestMeasurement contains request data.

type HTTPResponseMeasurement 

type HTTPResponseMeasurement struct {
	// BodyLength contains the body length in bytes.
	BodyLength int64 `json:"body_length"`

	// Failure is the error that occurred.
	Failure *string `json:"failure"`

	// Headers contains response headers.
	Headers http.Header `json:"headers"`

	// StatusCode is the response status code.
	StatusCode int64 `json:"status_code"`
}

HTTPResponseMeasurement contains response data.

type HTTPRoundTripMeasurement 

type HTTPRoundTripMeasurement struct {
	// Request contains request data.
	Request *HTTPRequestMeasurement `json:"request"`

	// Response contains response data.
	Response *HTTPResponseMeasurement `json:"response"`
}

HTTPRoundTripMeasurement contains a measured HTTP request and the corresponding response.

type Measurer 

type Measurer struct {
	Config Config
}

Measurer performs the measurement.

func (Measurer) ExperimentName 

func (m Measurer) ExperimentName() string

ExperimentName implements ExperimentMeasurer.ExperExperimentName.

func (Measurer) ExperimentVersion 

func (m Measurer) ExperimentVersion() string

ExperimentVersion implements ExperimentMeasurer.ExperExperimentVersion.

func (Measurer) GetSummaryKeys 

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

GetSummaryKeys implements model.ExperimentMeasurer.GetSummaryKeys.

func (Measurer) Run 

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

Run implements ExperimentMeasurer.Run.

type QUICConfig 

type QUICConfig struct {
	Endpoint   string
	QUICDialer model.QUICDialer
	Resolver   model.Resolver
	TLSConf    *tls.Config
}

type QUICHandshakeMeasurement 

type QUICHandshakeMeasurement = TLSHandshakeMeasurement

QUICHandshakeMeasurement is a QUIC handshake measurement.

type RoundTripInfo 

type RoundTripInfo struct {
	// Proto is the protocol used, it can be "h2", "http/1.1", "h3".
	Proto string

	// Request is the original HTTP request. Headers also include cookies.
	Request *http.Request

	// Response is the HTTP response.
	Response *http.Response

	// SortIndex is the index using for sorting round trips.
	SortIndex int
}

RoundTripInfo contains info on a specific round trip. This data structure is not part of the test helper protocol. We use it _inside_ the test helper to describe the discovery phase where we gather all the URLs that can derive from a given URL.

type SingleDialer 

type SingleDialer struct {
	sync.Mutex
	// contains filtered or unexported fields
}

func (*SingleDialer) DialContext 

func (s *SingleDialer) DialContext(ctx context.Context, network string, addr string) (net.Conn, error)

type SingleDialerH3 

type SingleDialerH3 struct {
	sync.Mutex
	// contains filtered or unexported fields
}

func (*SingleDialerH3) Dial 

func (s *SingleDialerH3) Dial(network, addr string, tlsCfg *tls.Config, cfg *quic.Config) (quic.EarlySession, error)

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 TCPConfig 

type TCPConfig struct {
	Dialer   model.Dialer
	Endpoint string
	Resolver model.Resolver
}

type TCPConnectMeasurement 

type TCPConnectMeasurement struct {
	// Failure is the error that occurred.
	Failure *string `json:"failure"`
}

TCPConnectMeasurement is a TCP connect measurement.

type TLSHandshakeMeasurement 

type TLSHandshakeMeasurement struct {
	// Failure is the error that occurred.
	Failure *string `json:"failure"`
}

TLSHandshakeMeasurement is a TLS handshake measurement.

type TestKeys 

type TestKeys struct {
	Agent           string `json:"agent"`
	ClientResolver  string `json:"client_resolver"`
	URLMeasurements []*URLMeasurement
}

TestKeys contains webconnectivity test keys.

type URLMeasurement 

type URLMeasurement struct {
	// URL is the URL to which this measurement refers.
	URL string `json:"url"`

	// DNS contains the domain names resolved by the test helper.
	DNS *DNSMeasurement `json:"dns"`

	// Endpoints contains endpoint measurements.
	Endpoints []*EndpointMeasurement `json:"endpoints"`

	// RoundTrip is the related round trip. This field MUST NOT be
	// exported as JSON, since it's only used internally by the test
	// helper and it's completely ignored by the probe.
	RoundTrip *RoundTripInfo `json:"-"`
}

URLMeasurement contains all the URLs measured by the test helper.

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.