model

Documentation

Overview

Package model is a subset of probe-cli's internal/model package.

Index

• Constants
• Variables
• func ErrorToStringOrOK(err error) string
• type ArchivalBinaryData
  • func NewArchivalBinaryData(data []byte) (out *ArchivalBinaryData)
• type ArchivalDNSAnswer
• type ArchivalDNSLookupResult
• type ArchivalExtSpec
  • func (spec ArchivalExtSpec) AddTo(m *Measurement)
• type ArchivalHTTPBody
• type ArchivalHTTPBodyOrTLSH
  • func (b ArchivalHTTPBodyOrTLSH) MarshalJSON() ([]byte, error)
• type ArchivalHTTPBodyTLSH
• type ArchivalHTTPHeader
  • func (hh ArchivalHTTPHeader) MarshalJSON() ([]byte, error)
  • func (hh *ArchivalHTTPHeader) UnmarshalJSON(d []byte) error
• type ArchivalHTTPRequest
• type ArchivalHTTPRequestResult
• type ArchivalHTTPResponse
• type ArchivalHTTPTor
• type ArchivalMaybeBinaryData
  • func (hb ArchivalMaybeBinaryData) MarshalJSON() ([]byte, error)
  • func (hb *ArchivalMaybeBinaryData) UnmarshalJSON(d []byte) error
• type ArchivalNetworkEvent
• type ArchivalTCPConnectResult
• type ArchivalTCPConnectStatus
• type ArchivalTLSOrQUICHandshakeResult
• type DNSDecoder
• type DNSEncoder
• type DNSTransport
• type DebugLogger
• type Dialer
• type HTTPClient
• type HTTPSSvc
• type HTTPTransport
• type InfoLogger
• type KeyValueStore
• type Logger
• type Measurement
  • func (m *Measurement) AddAnnotation(key, value string)
  • func (m *Measurement) AddAnnotations(input map[string]string)
  • func (m *Measurement) MaybeRewriteTestKeys(currentIP string, marshal func(interface{}) ([]byte, error)) error
  • func (m *Measurement) Scrub(probeIP string) (err error)
• type MeasurementTarget
  • func (t MeasurementTarget) MarshalJSON() ([]byte, error)
• type QUICDialer
• type Resolver
• type SimpleDialer
• type TLSConn
• type TLSDialer
• type TLSHandshaker
• type UDPLikeConn
• type UDPListener
• type UnderlyingNetworkLibrary

Constants

const (
	// ArchivalHTTPBodySerializeTLSH indicates that we don't want
	// to serialize the body, rather we just want the TLSH.
	ArchivalHTTPBodySerializeTLSH = 1 << iota
)

const (
	// DefaultProbeIP is the default probe IP.
	DefaultProbeIP = "127.0.0.1"
)

const Scrubbed = `[scrubbed]`

Scrubbed is the string that replaces IP addresses.

Variables

var (
	// ArchivalExtDNS is the version of df-002-dnst.md
	ArchivalExtDNS = ArchivalExtSpec{Name: "dnst", V: 0}

	// ArchivalExtNetevents is the version of df-008-netevents.md
	ArchivalExtNetevents = ArchivalExtSpec{Name: "netevents", V: 0}

	// ArchivalExtHTTP is the version of df-001-httpt.md
	ArchivalExtHTTP = ArchivalExtSpec{Name: "httpt", V: 0}

	// ArchivalExtTCPConnect is the version of df-005-tcpconnect.md
	ArchivalExtTCPConnect = ArchivalExtSpec{Name: "tcpconnect", V: 0}

	// ArchivalExtTLSHandshake is the version of df-006-tlshandshake.md
	ArchivalExtTLSHandshake = ArchivalExtSpec{Name: "tlshandshake", V: 0}

	// ArchivalExtTunnel is the version of df-009-tunnel.md
	ArchivalExtTunnel = ArchivalExtSpec{Name: "tunnel", V: 0}
)

var ErrInvalidProbeIP = errors.New("model: invalid probe IP")

ErrInvalidProbeIP indicates that we're dealing with a string that is not the valid serialization of an IP address.

Functions

func ErrorToStringOrOK

func ErrorToStringOrOK(err error) string

ErrorToStringOrOK emits "ok" on "<nil>"" values for success.

Types

type ArchivalBinaryData

type ArchivalBinaryData struct {
	Format string `json:"format"`
	Data   []byte `json:"data"`
}

ArchivalBinaryData is the representation of a binary string.

func NewArchivalBinaryData

func NewArchivalBinaryData(data []byte) (out *ArchivalBinaryData)

NewArchivalBinaryData converts []byte to ArchivalBinaryData.

type ArchivalDNSAnswer

type ArchivalDNSAnswer struct {
	ALPN       string  `json:"alpn,omitempty"`
	ASN        int64   `json:"asn,omitempty"`
	ASOrgName  string  `json:"as_org_name,omitempty"`
	AnswerType string  `json:"answer_type"`
	Hostname   string  `json:"hostname,omitempty"`
	IPv4       string  `json:"ipv4,omitempty"`
	IPv6       string  `json:"ipv6,omitempty"`
	NS         string  `json:"ns,omitempty"`
	TTL        *uint32 `json:"ttl,omitempty"`
}

ArchivalDNSAnswer is a DNS answer.

type ArchivalDNSLookupResult

type ArchivalDNSLookupResult struct {
	Answers          []ArchivalDNSAnswer `json:"answers"`
	Engine           string              `json:"engine"`
	Failure          *string             `json:"failure"`
	Hostname         string              `json:"hostname"`
	QueryType        string              `json:"query_type"`
	RawQuery         *ArchivalBinaryData `json:"raw_query,omitempty"`
	RawReply         *ArchivalBinaryData `json:"raw_reply,omitempty"`
	ResolverHostname *string             `json:"resolver_hostname,omitempty"`
	ResolverPort     *string             `json:"resolver_port,omitempty"`
	ResolverAddress  string              `json:"resolver_address,omitempty"`
	Started          float64             `json:"started"`
	T                float64             `json:"t"`
}

ArchivalDNSLookupResult is the result of a DNS lookup.

See https://github.com/ooni/spec/blob/master/data-formats/df-002-dnst.md.

type ArchivalExtSpec

type ArchivalExtSpec struct {
	Name string // extension name
	V    int64  // extension version
}

ArchivalExtSpec describes a data format extension

func (ArchivalExtSpec) AddTo

func (spec ArchivalExtSpec) AddTo(m *Measurement)

AddTo adds the current ExtSpec to the specified measurement

type ArchivalHTTPBody

type ArchivalHTTPBody = ArchivalMaybeBinaryData

ArchivalHTTPBody is an HTTP body. As an implementation note, this type must be an alias for the MaybeBinaryValue type, otherwise the specific serialisation mechanism implemented by MaybeBinaryValue is not working.

type ArchivalHTTPBodyOrTLSH

type ArchivalHTTPBodyOrTLSH struct {
	// Body is the real body
	Body ArchivalHTTPBody

	// Flags contains flags controlling the serialization
	Flags int64

	// TLSH is the hash
	TLSH string
}

ArchivalHTTPBodyOrTLSH is a type that serializes either the whole body or just the body hash depending on flags.

func (ArchivalHTTPBodyOrTLSH) MarshalJSON

func (b ArchivalHTTPBodyOrTLSH) MarshalJSON() ([]byte, error)

MarshalJSON implements a custom JSON marshalling policy.

type ArchivalHTTPBodyTLSH

type ArchivalHTTPBodyTLSH struct {
	Format string `json:"format"`
	Data   string `json:"data"`
}

ArchivalHTTPBodyTLSH is the hash serialization.

type ArchivalHTTPHeader

type ArchivalHTTPHeader struct {
	Key   string
	Value ArchivalMaybeBinaryData
}

ArchivalHTTPHeader is a single HTTP header.

func (ArchivalHTTPHeader) MarshalJSON

func (hh ArchivalHTTPHeader) MarshalJSON() ([]byte, error)

MarshalJSON marshals a single HTTP header to a tuple where the first element is a string and the second element is maybe-binary data.

func (*ArchivalHTTPHeader) UnmarshalJSON

func (hh *ArchivalHTTPHeader) UnmarshalJSON(d []byte) error

UnmarshalJSON is the opposite of MarshalJSON.

type ArchivalHTTPRequest

type ArchivalHTTPRequest struct {
	Body            ArchivalHTTPBody                   `json:"body"`
	BodyIsTruncated bool                               `json:"body_is_truncated"`
	HeadersList     []ArchivalHTTPHeader               `json:"headers_list"`
	Headers         map[string]ArchivalMaybeBinaryData `json:"headers"`
	Method          string                             `json:"method"`
	Tor             ArchivalHTTPTor                    `json:"tor"`
	Transport       string                             `json:"x_transport"`
	URL             string                             `json:"url"`
}

ArchivalHTTPRequest contains an HTTP request.

Headers are a map in Web Connectivity data format but we have added support for a list since January 2020.

type ArchivalHTTPRequestResult

type ArchivalHTTPRequestResult struct {
	Failure  *string              `json:"failure"`
	Request  ArchivalHTTPRequest  `json:"request"`
	Response ArchivalHTTPResponse `json:"response"`
	Started  float64              `json:"started"`
	T        float64              `json:"t"`
}

ArchivalHTTPRequestResult is the result of sending an HTTP request.

See https://github.com/ooni/spec/blob/master/data-formats/df-001-httpt.md.

type ArchivalHTTPResponse

type ArchivalHTTPResponse struct {
	Body            ArchivalHTTPBodyOrTLSH             `json:"body"`
	BodyLength      int64                              `json:"body_length"`
	BodyIsTruncated bool                               `json:"body_is_truncated"`
	BodyTLSH        string                             `json:"body_tlsh"`
	Code            int64                              `json:"code"`
	HeadersList     []ArchivalHTTPHeader               `json:"headers_list"`
	Headers         map[string]ArchivalMaybeBinaryData `json:"headers"`

	// The following fields are not serialised but are useful to simplify
	// analysing the measurements in telegram, whatsapp, etc.
	Locations []string `json:"-"`
}

ArchivalHTTPResponse contains an HTTP response.

Headers are a map in Web Connectivity data format but we have added support for a list since January 2020.

type ArchivalHTTPTor

type ArchivalHTTPTor struct {
	ExitIP   *string `json:"exit_ip"`
	ExitName *string `json:"exit_name"`
	IsTor    bool    `json:"is_tor"`
}

ArchivalHTTPTor contains Tor information.

type ArchivalMaybeBinaryData

type ArchivalMaybeBinaryData struct {
	Value []byte
}

ArchivalMaybeBinaryData is a possibly binary string. We use this helper class to define a custom JSON encoder that allows us to choose the proper representation depending on whether the Value field is valid UTF-8 or not.

See https://github.com/ooni/spec/blob/master/data-formats/df-001-httpt.md#maybebinarydata

func (ArchivalMaybeBinaryData) MarshalJSON

func (hb ArchivalMaybeBinaryData) MarshalJSON() ([]byte, error)

MarshalJSON marshals a string-like to JSON following the OONI spec that says that UTF-8 content is represented as string and non-UTF-8 content is instead represented using `{"format":"base64","data":"..."}`.

func (*ArchivalMaybeBinaryData) UnmarshalJSON

func (hb *ArchivalMaybeBinaryData) UnmarshalJSON(d []byte) error

UnmarshalJSON is the opposite of MarshalJSON.

type ArchivalNetworkEvent

type ArchivalNetworkEvent struct {
	Address   string   `json:"address,omitempty"`
	Failure   *string  `json:"failure"`
	NumBytes  int64    `json:"num_bytes,omitempty"`
	Operation string   `json:"operation"`
	Proto     string   `json:"proto,omitempty"`
	Started   float64  `json:"started"`
	T         float64  `json:"t"`
	Tags      []string `json:"tags,omitempty"`
}

ArchivalNetworkEvent is a network event. It contains all the possible fields and most fields are optional. They are only added when it makes sense for them to be there _and_ we have data to show.

See https://github.com/ooni/spec/blob/master/data-formats/df-008-netevents.md.

type ArchivalTCPConnectResult

type ArchivalTCPConnectResult struct {
	IP      string                   `json:"ip"`
	Port    int                      `json:"port"`
	Status  ArchivalTCPConnectStatus `json:"status"`
	Started float64                  `json:"started"`
	T       float64                  `json:"t"`
}

ArchivalTCPConnectResult contains the result of a TCP connect.

See https://github.com/ooni/spec/blob/master/data-formats/df-005-tcpconnect.md.

type ArchivalTCPConnectStatus

type ArchivalTCPConnectStatus struct {
	Blocked *bool   `json:"blocked,omitempty"`
	Failure *string `json:"failure"`
	Success bool    `json:"success"`
}

ArchivalTCPConnectStatus is the status of ArchivalTCPConnectResult.

type ArchivalTLSOrQUICHandshakeResult

type ArchivalTLSOrQUICHandshakeResult struct {
	Address            string                    `json:"address"`
	CipherSuite        string                    `json:"cipher_suite"`
	Failure            *string                   `json:"failure"`
	NegotiatedProtocol string                    `json:"negotiated_protocol"`
	NoTLSVerify        bool                      `json:"no_tls_verify"`
	PeerCertificates   []ArchivalMaybeBinaryData `json:"peer_certificates"`
	Proto              string                    `json:"proto"`
	ServerName         string                    `json:"server_name"`
	Started            float64                   `json:"started"`
	T                  float64                   `json:"t"`
	Tags               []string                  `json:"tags"`
	TLSVersion         string                    `json:"tls_version"`
}

ArchivalTLSOrQUICHandshakeResult is the result of a TLS or QUIC handshake.

See https://github.com/ooni/spec/blob/master/data-formats/df-006-tlshandshake.md

type DNSDecoder

type DNSDecoder interface {
	// DecodeLookupHost decodes an A or AAAA reply.
	//
	// Arguments:
	//
	// - qtype is the query type (e.g., dns.TypeAAAA)
	//
	// - data contains the reply bytes read from a DNSTransport
	//
	// - queryID is the original query ID
	//
	// Returns:
	//
	// - on success, a list of IP addrs inside the reply and a nil error
	//
	// - on failure, a nil list and an error.
	//
	// Note that this function will return an error if there is no
	// IP address inside of the reply.
	//
	// Note that the error returned by this function is not wrapped and
	// it is your responsiblity to wrap it if needed.
	DecodeLookupHost(qtype uint16, data []byte, queryID uint16) ([]string, error)

	// DecodeLookupHTTPS decodes an HTTPS reply.
	//
	// The argument is the reply as read by the DNSTransport.
	//
	// On success, this function returns an HTTPSSvc structure and
	// a nil error. On failure, the HTTPSSvc pointer is nil and
	// the error points to the error that occurred.
	//
	// This function will return an error if the HTTPS reply does not
	// contain at least a valid ALPN entry. It will not return
	// an error, though, when there are no IPv4/IPv6 hints in the reply.
	//
	// Note that the error returned by this function is not wrapped and
	// it is your responsiblity to wrap it if needed.
	DecodeLookupHTTPS(data []byte, queryID uint16) (*HTTPSSvc, error)

	// DecodeLookupNS is like DecodeLookupHTTPS but for NS queries.
	DecodeLookupNS(data []byte, queryID uint16) ([]*net.NS, error)

	// DecodeLookupPTR is like DecodeLookupNS but for PTR queries.
	DecodeLookupPTR(data []byte, queryID uint16) ([]string, error)

	// ParseReply parses a reply without decoding it. This function
	// will ONLY return error if data is not a valid DNS message. In
	// particular, it WILL NOT return any error that depends on the
	// Rcode. That is, if the Rcode is NXDOMAIN, this function
	// will still return success anyway. To map NXDOMAIN and other
	// errors, you need to use DecodeReplyLookup{Host,HTTPS}.
	//
	// Note that the error returned by this function is not wrapped and
	// it is your responsiblity to wrap it if needed.
	ParseReply(data []byte) (*dns.Msg, error)

	// ParseReplyForQueryID parses a reply for the specific queryID. This
	// function is like ParseReply but also ensures that the reply we parse
	// has the same query ID of the query we sent.
	ParseReplyForQueryID(data []byte, queryID uint16) (*dns.Msg, error)

	// ParseQuery parses a DNS query.
	ParseQuery(data []byte) (*dns.Msg, error)

	// DecodeReplyLookupHost is like DecodeLookupHost but acts
	// on an already parsed reply rather than on data.
	//
	// Note that the error returned by this function is not wrapped and
	// it is your responsiblity to wrap it if needed.
	DecodeReplyLookupHost(qtype uint16, reply *dns.Msg) ([]string, error)

	// DecodeReplyLookupHTTPS is like DecodeLookupHTTPS but acts
	// on an already parsed reply rather than on data.
	//
	// Note that the error returned by this function is not wrapped and
	// it is your responsiblity to wrap it if needed.
	DecodeReplyLookupHTTPS(reply *dns.Msg) (*HTTPSSvc, error)

	// DecodeReplyLookupNS is like DecodeReplyLookupHTTPS but for NS queries.
	DecodeReplyLookupNS(reply *dns.Msg) ([]*net.NS, error)

	// DecodeReplyLookupPTR is like DecodeReplyLookupNS but for PTR queries.
	DecodeReplyLookupPTR(reply *dns.Msg) ([]string, error)
}

The DNSDecoder decodes DNS replies.

type DNSEncoder

type DNSEncoder interface {
	// EncodeQuery transforms its arguments into a serialized DNS query.
	//
	// Arguments:
	//
	// - domain is the domain for the query (e.g., x.org);
	//
	// - qtype is the query type (e.g., dns.TypeA);
	//
	// - padding is whether to add padding to the query.
	//
	// On success, this function returns a valid byte array, the query ID
	// and a nil error. On failure, only the error matters.
	EncodeQuery(domain string, qtype uint16, padding bool) ([]byte, uint16, error)

	// EncodeReply encodes a reply for the given query given some addresses.
	EncodeReply(query *dns.Msg, addresses []string) (*dns.Msg, error)
}

The DNSEncoder encodes DNS queries to bytes

type DNSTransport

type DNSTransport interface {
	// RoundTrip sends a DNS query and receives the reply.
	RoundTrip(ctx context.Context, query []byte) (reply []byte, err error)

	// RequiresPadding returns whether this transport needs padding.
	RequiresPadding() bool

	// Network is the network of the round tripper (e.g. "dot").
	Network() string

	// Address is the address of the round tripper (e.g. "1.1.1.1:853").
	Address() string

	// CloseIdleConnections closes idle connections, if any.
	CloseIdleConnections()
}

DNSTransport represents an abstract DNS transport.

type DebugLogger

type DebugLogger interface {
	// Debug emits a debug message.
	Debug(msg string)

	// Debugf formats and emits a debug message.
	Debugf(format string, v ...interface{})
}

DebugLogger is a logger emitting only debug messages.

type Dialer

type Dialer interface {
	// A Dialer is also a SimpleDialer.
	SimpleDialer

	// CloseIdleConnections closes idle connections, if any.
	CloseIdleConnections()
}

Dialer is a SimpleDialer with the possibility of closing open connections.

type HTTPClient

type HTTPClient interface {
	Do(req *http.Request) (*http.Response, error)
	CloseIdleConnections()
}

HTTPClient is an http.Client-like interface.

type HTTPSSvc

type HTTPSSvc struct {
	// ALPN contains the ALPNs inside the HTTPS reply.
	ALPN []string

	// IPv4 contains the IPv4 hints (which may be empty).
	IPv4 []string

	// IPv6 contains the IPv6 hints (which may be empty).
	IPv6 []string
}

HTTPSSvc is the reply to an HTTPS DNS query.

type HTTPTransport

type HTTPTransport interface {
	// Network returns the network used by the transport, which
	// should be one of "tcp" and "quic".
	Network() string

	// RoundTrip performs the HTTP round trip.
	RoundTrip(req *http.Request) (*http.Response, error)

	// CloseIdleConnections closes idle connections.
	CloseIdleConnections()
}

HTTPTransport is an http.Transport-like structure.

type InfoLogger

type InfoLogger interface {
	// An InfoLogger is also a DebugLogger.
	DebugLogger

	// Info emits an informational message.
	Info(msg string)

	// Infof formats and emits an informational message.
	Infof(format string, v ...interface{})
}

InfoLogger is a logger emitting debug and infor messages.

type KeyValueStore

type KeyValueStore interface {
	// Get gets the value of the given key or returns an
	// error if there is no such key or we cannot read
	// from the key-value store.
	Get(key string) (value []byte, err error)

	// Set sets the value of the given key and returns
	// whether the operation was successful or not.
	Set(key string, value []byte) (err error)
}

KeyValueStore is a generic key-value store.

type Logger

type Logger interface {
	// A Logger is also an InfoLogger.
	InfoLogger

	// Warn emits a warning message.
	Warn(msg string)

	// Warnf formats and emits a warning message.
	Warnf(format string, v ...interface{})
}

Logger defines the common interface that a logger should have. It is out of the box compatible with `log.Log` in `apex/log`.

var DiscardLogger Logger = logDiscarder{}

DiscardLogger is the default logger that discards its input

type Measurement

type Measurement struct {
	// Annotations contains results annotations
	Annotations map[string]string `json:"annotations,omitempty"`

	// DataFormatVersion is the version of the data format
	DataFormatVersion string `json:"data_format_version"`

	// Extensions contains information about the extensions included
	// into the test_keys of this measurement.
	Extensions map[string]int64 `json:"extensions,omitempty"`

	// ID is the locally generated measurement ID
	ID string `json:"id,omitempty"`

	// Input is the measurement input
	Input MeasurementTarget `json:"input"`

	// InputHashes contains input hashes
	InputHashes []string `json:"input_hashes,omitempty"`

	// MeasurementStartTime is the time when the measurement started
	MeasurementStartTime string `json:"measurement_start_time"`

	// MeasurementStartTimeSaved is the moment in time when we
	// started the measurement. This is not included into the JSON
	// and is only used within probe-engine as a "zero" time.
	MeasurementStartTimeSaved time.Time `json:"-"`

	// Options contains command line options
	Options []string `json:"options,omitempty"`

	// ProbeASN contains the probe autonomous system number
	ProbeASN string `json:"probe_asn"`

	// ProbeCC contains the probe country code
	ProbeCC string `json:"probe_cc"`

	// ProbeCity contains the probe city
	ProbeCity string `json:"probe_city,omitempty"`

	// ProbeIP contains the probe IP
	ProbeIP string `json:"probe_ip,omitempty"`

	// ProbeNetworkName contains the probe network name
	ProbeNetworkName string `json:"probe_network_name"`

	// ReportID contains the report ID
	ReportID string `json:"report_id"`

	// ResolverASN is the ASN of the resolver
	ResolverASN string `json:"resolver_asn"`

	// ResolverIP is the resolver IP
	ResolverIP string `json:"resolver_ip"`

	// ResolverNetworkName is the network name of the resolver.
	ResolverNetworkName string `json:"resolver_network_name"`

	// SoftwareName contains the software name
	SoftwareName string `json:"software_name"`

	// SoftwareVersion contains the software version
	SoftwareVersion string `json:"software_version"`

	// TestHelpers contains the test helpers. It seems this structure is more
	// complex than we would like. In particular, using a map from string to
	// string does not fit into the web_connectivity use case. Hence, for now
	// we're going to represent this using interface{}. In going forward we
	// may probably want to have more uniform test helpers.
	TestHelpers map[string]interface{} `json:"test_helpers,omitempty"`

	// TestKeys contains the real test result. This field is opaque because
	// each experiment will insert here a different structure.
	TestKeys interface{} `json:"test_keys"`

	// TestName contains the test name
	TestName string `json:"test_name"`

	// MeasurementRuntime contains the measurement runtime. The JSON name
	// is test_runtime because this is the name expected by the OONI backend
	// even though that name is clearly a misleading one.
	MeasurementRuntime float64 `json:"test_runtime"`

	// TestStartTime contains the test start time
	TestStartTime string `json:"test_start_time"`

	// TestVersion contains the test version
	TestVersion string `json:"test_version"`
}

Measurement is a OONI measurement.

This structure is compatible with the definition of the base data format in https://github.com/ooni/spec/blob/master/data-formats/df-000-base.md.

func (*Measurement) AddAnnotation

func (m *Measurement) AddAnnotation(key, value string)

AddAnnotation adds a single annotations to m.Annotations.

func (*Measurement) AddAnnotations

func (m *Measurement) AddAnnotations(input map[string]string)

AddAnnotations adds the annotations from input to m.Annotations.

func (*Measurement) MaybeRewriteTestKeys

func (m *Measurement) MaybeRewriteTestKeys(
	currentIP string, marshal func(interface{}) ([]byte, error)) error

MaybeRewriteTestKeys is the function called by Scrub that ensures that m's serialization doesn't include the IP

func (*Measurement) Scrub

func (m *Measurement) Scrub(probeIP string) (err error)

Scrub scrubs the probeIP out of the measurement.

type MeasurementTarget

type MeasurementTarget string

MeasurementTarget is the target of a OONI measurement.

func (MeasurementTarget) MarshalJSON

func (t MeasurementTarget) MarshalJSON() ([]byte, error)

MarshalJSON serializes the MeasurementTarget.

type QUICDialer

type QUICDialer interface {
	// DialContext establishes a new QUIC session using the given
	// network and address. The tlsConfig and the quicConfig arguments
	// MUST NOT be nil. Returns either the session or an error.
	//
	// Recommended tlsConfig setup:
	//
	// - set ServerName to be the SNI;
	//
	// - set RootCAs to NewDefaultCertPool();
	//
	// - set NextProtos to []string{"h3"}.
	//
	// Typically, you want to pass `&quic.Config{}` as quicConfig.
	DialContext(ctx context.Context, network, address string,
		tlsConfig *tls.Config, quicConfig *quic.Config) (quic.EarlySession, error)

	// CloseIdleConnections closes idle connections, if any.
	CloseIdleConnections()
}

QUICDialer dials QUIC sessions.

type Resolver

type Resolver interface {
	// LookupHost behaves like net.Resolver.LookupHost.
	LookupHost(ctx context.Context, hostname string) (addrs []string, err error)

	// Network returns the resolver type (e.g., system, dot, doh).
	Network() string

	// Address returns the resolver address (e.g., 8.8.8.8:53).
	Address() string

	// CloseIdleConnections closes idle connections, if any.
	CloseIdleConnections()

	// LookupHTTPS issues an HTTPS query for a domain.
	LookupHTTPS(
		ctx context.Context, domain string) (*HTTPSSvc, error)

	// LookupNS issues a NS query for a domain.
	LookupNS(ctx context.Context, domain string) ([]*net.NS, error)

	// LookupPTR issues a PTR query for a domain. To perform a reverse DNS lookup
	// you need to reverse the IP addr first using miekg/dns.ReverseAddr.
	LookupPTR(ctx context.Context, domain string) ([]string, error)
}

Resolver performs domain name resolutions.

type SimpleDialer

type SimpleDialer interface {
	// DialContext behaves like net.Dialer.DialContext.
	DialContext(ctx context.Context, network, address string) (net.Conn, error)
}

SimpleDialer establishes network connections.

type TLSConn

type TLSConn = oohttp.TLSConn

TLSConn is the kind of TLS conn we use in ooniprobe.

type TLSDialer

type TLSDialer interface {
	// CloseIdleConnections closes idle connections, if any.
	CloseIdleConnections()

	// DialTLSContext dials a TLS connection. This method will always return
	// to you a oohttp.TLSConn, so you can always safely cast to it.
	DialTLSContext(ctx context.Context, network, address string) (net.Conn, error)
}

TLSDialer is a Dialer dialing TLS connections.

type TLSHandshaker

type TLSHandshaker interface {
	// Handshake creates a new TLS connection from the given connection and
	// the given config. This function DOES NOT take ownership of the connection
	// and it's your responsibility to close it on failure.
	//
	// Recommended tlsConfig setup:
	//
	// - set ServerName to be the SNI;
	//
	// - set RootCAs to NewDefaultCertPool();
	//
	// - set NextProtos to []string{"h2", "http/1.1"} for HTTPS
	// and []string{"dot"} for DNS-over-TLS.
	//
	// QUIRK: The returned connection will always implement the TLSConn interface
	// exposed by ooni/oohttp. A future version of this interface may instead
	// return directly a TLSConn to avoid unconditional castings.
	Handshake(ctx context.Context, conn net.Conn, tlsConfig *tls.Config) (
		net.Conn, tls.ConnectionState, error)
}

TLSHandshaker is the generic TLS handshaker.

type UDPLikeConn

type UDPLikeConn interface {
	// An UDPLikeConn is a net.PacketConn conn.
	net.PacketConn

	// SetReadBuffer allows setting the read buffer.
	SetReadBuffer(bytes int) error

	// SyscallConn returns a conn suitable for calling syscalls,
	// which is also instrumental to setting the read buffer.
	SyscallConn() (syscall.RawConn, error)
}

UDPLikeConn is a net.PacketConn with some extra functions required to convince the QUIC library (lucas-clemente/quic-go) to inflate the receive buffer of the connection.

The QUIC library will treat this connection as a "dumb" net.PacketConn, calling its ReadFrom and WriteTo methods as opposed to more efficient methods that are available under Linux and (maybe?) FreeBSD.

It seems fine to avoid performance optimizations, because they would complicate the implementation on our side and our use cases (blocking and heavy throttling) do not seem to require such optimizations.

See https://github.com/ooni/probe/issues/1754 for a more comprehensive discussion of UDPLikeConn.

type UDPListener

type UDPListener interface {
	// Listen creates a new listening UDPLikeConn.
	Listen(addr *net.UDPAddr) (UDPLikeConn, error)
}

UDPListener creates a bound UDP socket.

type UnderlyingNetworkLibrary

type UnderlyingNetworkLibrary interface {
	// ListenUDP creates a new model.UDPLikeConn conn.
	ListenUDP(network string, laddr *net.UDPAddr) (UDPLikeConn, error)

	// LookupHost lookups a domain using the stdlib resolver.
	LookupHost(ctx context.Context, domain string) ([]string, error)

	// NewSimpleDialer returns a new SimpleDialer.
	NewSimpleDialer(timeout time.Duration) SimpleDialer
}

UnderlyingNetworkLibrary defines the basic functionality from which the network extensions depend. By changing the default implementation of this interface, we can implement a wide array of tests, including self censorship tests.