hhfm

Documentation

Overview

Package hhfm contains the HTTP Header Field Manipulation network experiment.

See https://github.com/ooni/spec/blob/master/nettests/ts-006-header-field-manipulation.md

Index

• Variables
• func NewExperimentMeasurer(config Config) model.ExperimentMeasurer
• func NewHTTPResponse(resp *http.Response, data []byte) (out tracex.HTTPResponse)
• func NewRequestEntryList(req *http.Request, headers map[string]string) (out []tracex.RequestEntry)
• func Transact(txp Transport, req *http.Request, callbacks model.ExperimentCallbacks) (*http.Response, []byte, error)
• type Config
• type Conn
  • func (c Conn) Write(b []byte) (int, error)
• type Dialer
  • func (d Dialer) DialContext(ctx context.Context, network, address string) (net.Conn, error)
• type JSONHeaders
• type Measurer
  • func (m Measurer) ExperimentName() string
  • func (m Measurer) ExperimentVersion() string
  • func (m Measurer) GetSummaryKeys(measurement *model.Measurement) (interface{}, error)
  • func (m Measurer) Run(ctx context.Context, sess model.ExperimentSession, ...) error
• type SummaryKeys
• type Tampering
• type TestKeys
  • func (tk *TestKeys) FillTampering(req *http.Request, jsonHeaders JSONHeaders, headers map[string]string)
• type Transport

Variables

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

	// ErrInvalidHelperType is emitted when the helper type is invalid.
	ErrInvalidHelperType = errors.New("invalid helper type")
)

Functions

func NewExperimentMeasurer

func NewExperimentMeasurer(config Config) model.ExperimentMeasurer

NewExperimentMeasurer creates a new ExperimentMeasurer.

func NewHTTPResponse

func NewHTTPResponse(resp *http.Response, data []byte) (out tracex.HTTPResponse)

NewHTTPResponse creates a new tracex.HTTPResponse given a specific *http.Response instance and its body.

func NewRequestEntryList

func NewRequestEntryList(req *http.Request, headers map[string]string) (out []tracex.RequestEntry)

NewRequestEntryList creates a new []tracex.RequestEntry given a specific *http.Request and headers with random case.

func Transact

func Transact(txp Transport, req *http.Request,
	callbacks model.ExperimentCallbacks) (*http.Response, []byte, error)

Transact performs the HTTP transaction which consists of performing the HTTP round trip and then reading the body.

Types

type Config

type Config struct{}

Config contains the experiment config.

type Conn

type Conn struct {
	net.Conn
	Headers map[string]string
}

Conn is a connection where headers in the outgoing request are transformed according to a transform table.

func (Conn) Write

func (c Conn) Write(b []byte) (int, error)

Write implements Conn.Write.

type Dialer

type Dialer struct {
	Dialer  model.SimpleDialer // used for testing
	Headers map[string]string
}

Dialer is a dialer that performs headers transformations.

Because Golang will canonicalize header names, we need to reintroduce the random capitalization when emitting the request.

This implementation rests on the assumption that we shall use the same connection just once, which is guarantee by the implementation of HHFM above. If using this code elsewhere, make sure that you guarantee that the connection is used for a single request and that such a request does not contain any body.

func (Dialer) DialContext

func (d Dialer) DialContext(ctx context.Context, network, address string) (net.Conn, error)

DialContext dials a specific connection and arranges such that headers in the outgoing request are transformed.

type JSONHeaders

type JSONHeaders struct {
	HeadersDict map[string][]string `json:"headers_dict"`
	RequestLine string              `json:"request_line"`
}

JSONHeaders contains the response from the backend server.

Here we're defining only the fields we care about.

type Measurer

type Measurer struct {
	Config    Config
	Transport Transport // for testing
}

Measurer performs the measurement.

func (Measurer) ExperimentName

func (m Measurer) ExperimentName() string

ExperimentName implements ExperimentMeasurer.ExperiExperimentName.

func (Measurer) ExperimentVersion

func (m Measurer) ExperimentVersion() string

ExperimentVersion implements ExperimentMeasurer.ExperimentVersion.

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 SummaryKeys

type SummaryKeys struct {
	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 Tampering

type Tampering struct {
	HeaderFieldName           bool     `json:"header_field_name"`
	HeaderFieldNumber         bool     `json:"header_field_number"`
	HeaderFieldValue          bool     `json:"header_field_value"`
	HeaderNameCapitalization  bool     `json:"header_name_capitalization"`
	HeaderNameDiff            []string `json:"header_name_diff"`
	RequestLineCapitalization bool     `json:"request_line_capitalization"`
	Total                     bool     `json:"total"`
}

Tampering describes the detected forms of tampering.

The meaning of these fields is described in the specification.

type TestKeys

type TestKeys struct {
	Agent      string                `json:"agent"`
	Failure    *string               `json:"failure"`
	Requests   []tracex.RequestEntry `json:"requests"`
	SOCKSProxy *string               `json:"socksproxy"`
	Tampering  Tampering             `json:"tampering"`
}

TestKeys contains the experiment test keys.

Here we are emitting for the same set of test keys that are produced by the MK implementation.

func (*TestKeys) FillTampering

func (tk *TestKeys) FillTampering(
	req *http.Request, jsonHeaders JSONHeaders, headers map[string]string)

FillTampering fills the tampering structure in the TestKeys based on the value of other fields of the TestKeys, the original HTTP request, the response from the test helper, and the headers with modified capitalisation.

type Transport

type Transport interface {
	RoundTrip(req *http.Request) (*http.Response, error)
	CloseIdleConnections()
}

Transport is the definition of http.RoundTripper used by this package.