netx

Documentation

Overview

Package netx contains code to perform network measurements.

This library derives from https://github.com/ooni/netx and contains the original code we wrote for performing measurements in Go. Over time, most of the original code has been refactored away inside:

* model/netx.go: definition of interfaces and structs

* netxlite: low-level network library

* bytecounter: support for counting bytes sent and received

* multierror: representing multiple errors using a single error

* tracex: support for measuring using tracing

This refactoring of netx (called "the netx pivot") has been described in https://github.com/ooni/probe-cli/pull/396. We described the design, implementation, and pain points of the pre-pivot netx library in https://github.com/ooni/probe-engine/issues/359. In turn, https://github.com/ooni/netx/blob/master/DESIGN.md contains the original design document for the netx library.

Measuring using tracing means that we use ordinary stdlib-like objects such as model.Dialer and model.HTTPTransport. Then, we'll extract results from a tracex.Saver to determine the result of the measurement. The most notable user of this library is experiment/urlgetter, which implements a flexible URL-getting library.

Tracing has its own set of limitations, so while we're still using it for implementing many experiments, we're also tinkering with step-by-step approaches where we break down operations in more basic building blocks, e.g., DNS resolution and fetching URL given an hostname, a protocol (e.g., QUIC or HTTPS), and an endpoint.

While we're experimenting with alternative approaches, we also want to keep this library running and stable. New code will probably not be implemented here rather in step-by-step libraries.

New experiments that can be written in terms of netxlite and tracex SHOULD NOT use netx. Existing experiment using netx MAY be rewritten using just netxlite and tracex when feasible.

Additionally, new code that does not need to perform measurements SHOULD NOT use netx and SHOULD instead use netxlite.

See docs/design/dd-002-nets.md in the probe-cli repository for the design document describing this package.

This package is now frozen. Please, use measurexlite for new code. See https://github.com/ooni/probe-cli/blob/master/docs/design/dd-003-step-by-step.md for details about this.

Index

• func NewDNSClient(config Config, URL string) (model.Resolver, error)
• func NewDNSClientWithOverrides(config Config, URL, hostOverride, SNIOverride, TLSVersion string) (model.Resolver, error)
• func NewDialer(config Config) model.Dialer
• func NewHTTPTransport(config Config) model.HTTPTransport
• func NewQUICDialer(config Config) model.QUICDialer
• func NewResolver(config Config) model.Resolver
• func NewTLSDialer(config Config) model.TLSDialer
• type Config

Functions

func NewDNSClient

func NewDNSClient(config Config, URL string) (model.Resolver, error)

NewDNSClient creates a new DNS client. The config argument is used to create the underlying Dialer and/or HTTP transport, if needed. The URL argument describes the kind of client that we want to make:

- if the URL is `doh://google` or `doh://cloudflare` or the URL starts with `https://`, then we create a DoH client.

- if the URL is “ or `system:///`, then we create a system client, i.e. a client using the system resolver.

- if the URL starts with `udp://`, then we create a client using a resolver that uses the specified UDP endpoint.

We return error if the URL does not parse or the URL scheme does not fall into one of the cases described above.

If config.ResolveSaver is not nil and we're creating an underlying resolver where this is possible, we will also save events.

func NewDNSClientWithOverrides

func NewDNSClientWithOverrides(config Config, URL, hostOverride, SNIOverride,
	TLSVersion string) (model.Resolver, error)

NewDNSClientWithOverrides creates a new DNS client, similar to NewDNSClient, with the option to override the default Hostname and SNI.

func NewDialer

func NewDialer(config Config) model.Dialer

NewDialer creates a new Dialer from the specified config.

func NewHTTPTransport

func NewHTTPTransport(config Config) model.HTTPTransport

NewHTTPTransport creates a new HTTPRoundTripper from the given Config.

func NewQUICDialer

func NewQUICDialer(config Config) model.QUICDialer

NewQUICDialer creates a new QUICDialer using the given Config.

func NewResolver

func NewResolver(config Config) model.Resolver

NewResolver creates a new resolver from the specified config.

func NewTLSDialer

func NewTLSDialer(config Config) model.TLSDialer

NewTLSDialer creates a new TLSDialer from the specified config.

Types

type Config

type Config struct {
	BaseResolver        model.Resolver       // default: system resolver
	BogonIsError        bool                 // default: bogon is not error
	ByteCounter         *bytecounter.Counter // default: no explicit byte counting
	CacheResolutions    bool                 // default: no caching
	ContextByteCounting bool                 // default: no implicit byte counting
	DNSCache            map[string][]string  // default: cache is empty
	Dialer              model.Dialer         // default: dialer.DNSDialer
	FullResolver        model.Resolver       // default: base resolver + goodies
	QUICDialer          model.QUICDialer     // default: quicdialer.DNSDialer
	HTTP3Enabled        bool                 // default: disabled
	Logger              model.Logger         // default: no logging
	ProxyURL            *url.URL             // default: no proxy
	ReadWriteSaver      *tracex.Saver        // default: not saving I/O events
	Saver               *tracex.Saver        // default: not saving non-I/O events
	TLSConfig           *tls.Config          // default: attempt using h2
	TLSDialer           model.TLSDialer      // default: dialer.TLSDialer
}

Config contains configuration for creating new transports, dialers, etc. When any field of Config is nil/empty, we will use a suitable default.