netxlite

package
v3.14.1 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: 29 Imported by: 0

Documentation

Overview

Package netxlite contains network extensions.

This package is the basic networking building block that you should be using every time you need networking.

It implements interfaces defined in the internal/model package.

You should consider checking the tutorial explaining how to use this package for network measurements: https://github.com/ooni/probe-cli/tree/master/internal/tutorial/netxlite.

Naming and history

Previous versions of this package were called netx. Compared to such versions this package is lightweight because it does not contain code to perform the measurements, hence its name.

Design

We want to potentially be able to observe each low-level operation separately, even though this is not done by this package. This is the use case where we are performing measurements.

We also want to be able to use this package in a more casual way without having to compose each operation separately. This, instead, is the use case where we're communicating with the OONI backend.

We want to optionally provide detailed logging of every operation, thus users can use `-v` to obtain OONI logs.

We also want to mock any underlying dependency for testing.

We also want to map errors to OONI failures, which are described by https://github.com/ooni/spec/blob/master/data-formats/df-007-errors.md.

We want to have reasonable watchdog timeouts for each operation.

Operations

This package implements the following operations:

1. establishing a TCP connection;

2. performing a domain name resolution with the "system" resolver (i.e., getaddrinfo on Unix) or custom DNS transports (e.g., DoT, DoH);

3. performing the TLS handshake;

4. performing the QUIC handshake;

5. dialing with TCP, TLS, and QUIC (where in this context dialing means combining domain name resolution and "connecting");

6. performing HTTP, HTTP2, and HTTP3 round trips.

Operations 1, 2, 3, and 4 are used when we perform measurements, while 5 and 6 are mostly used when speaking with our backend.

Index

Constants

View Source 
const (
	DNSNoSuchHostSuffix        = "no such host"
	DNSServerMisbehavingSuffix = "server misbehaving"
	DNSNoAnswerSuffix          = "no answer from DNS server"
)

We use these strings to string-match errors in the standard library and map such errors to OONI failures.

View Source 
const (
	FailureAddressFamilyNotSupported   = "address_family_not_supported"
	FailureAddressInUse                = "address_in_use"
	FailureAddressNotAvailable         = "address_not_available"
	FailureAlreadyConnected            = "already_connected"
	FailureBadAddress                  = "bad_address"
	FailureBadFileDescriptor           = "bad_file_descriptor"
	FailureConnectionAborted           = "connection_aborted"
	FailureConnectionAlreadyClosed     = "connection_already_closed"
	FailureConnectionAlreadyInProgress = "connection_already_in_progress"
	FailureConnectionRefused           = "connection_refused"
	FailureConnectionReset             = "connection_reset"
	FailureDNSBogonError               = "dns_bogon_error"
	FailureDNSNXDOMAINError            = "dns_nxdomain_error"
	FailureDNSNoAnswer                 = "dns_no_answer"
	FailureDNSNonRecoverableFailure    = "dns_non_recoverable_failure"
	FailureDNSRefusedError             = "dns_refused_error"
	FailureDNSServerMisbehaving        = "dns_server_misbehaving"
	FailureDNSTemporaryFailure         = "dns_temporary_failure"
	FailureDestinationAddressRequired  = "destination_address_required"
	FailureEOFError                    = "eof_error"
	FailureGenericTimeoutError         = "generic_timeout_error"
	FailureHostUnreachable             = "host_unreachable"
	FailureInterrupted                 = "interrupted"
	FailureInvalidArgument             = "invalid_argument"
	FailureJSONParseError              = "json_parse_error"
	FailureMessageSize                 = "message_size"
	FailureNetworkDown                 = "network_down"
	FailureNetworkReset                = "network_reset"
	FailureNetworkUnreachable          = "network_unreachable"
	FailureNoBufferSpace               = "no_buffer_space"
	FailureNoProtocolOption            = "no_protocol_option"
	FailureNotASocket                  = "not_a_socket"
	FailureNotConnected                = "not_connected"
	FailureOperationWouldBlock         = "operation_would_block"
	FailurePermissionDenied            = "permission_denied"
	FailureProtocolNotSupported        = "protocol_not_supported"
	FailureQUICIncompatibleVersion     = "quic_incompatible_version"
	FailureSSLFailedHandshake          = "ssl_failed_handshake"
	FailureSSLInvalidCertificate       = "ssl_invalid_certificate"
	FailureSSLInvalidHostname          = "ssl_invalid_hostname"
	FailureSSLUnknownAuthority         = "ssl_unknown_authority"
	FailureTimedOut                    = "timed_out"
	FailureWrongProtocolType           = "wrong_protocol_type"
)

This enumeration lists the failures defined at https://github.com/ooni/spec/blob/master/data-formats/df-007-errors.md. Please, refer to that document for more information.

View Source 
const (
	ECONNREFUSED    = unix.ECONNREFUSED
	ECONNRESET      = unix.ECONNRESET
	EHOSTUNREACH    = unix.EHOSTUNREACH
	ETIMEDOUT       = unix.ETIMEDOUT
	EAFNOSUPPORT    = unix.EAFNOSUPPORT
	EADDRINUSE      = unix.EADDRINUSE
	EADDRNOTAVAIL   = unix.EADDRNOTAVAIL
	EISCONN         = unix.EISCONN
	EFAULT          = unix.EFAULT
	EBADF           = unix.EBADF
	ECONNABORTED    = unix.ECONNABORTED
	EALREADY        = unix.EALREADY
	EDESTADDRREQ    = unix.EDESTADDRREQ
	EINTR           = unix.EINTR
	EINVAL          = unix.EINVAL
	EMSGSIZE        = unix.EMSGSIZE
	ENETDOWN        = unix.ENETDOWN
	ENETRESET       = unix.ENETRESET
	ENETUNREACH     = unix.ENETUNREACH
	ENOBUFS         = unix.ENOBUFS
	ENOPROTOOPT     = unix.ENOPROTOOPT
	ENOTSOCK        = unix.ENOTSOCK
	ENOTCONN        = unix.ENOTCONN
	EWOULDBLOCK     = unix.EWOULDBLOCK
	EACCES          = unix.EACCES
	EPROTONOSUPPORT = unix.EPROTONOSUPPORT
	EPROTOTYPE      = unix.EPROTOTYPE
)

This enumeration provides a canonical name for every system-call error we support. Note: this list is system dependent. You're currently looking at the list of errors for linux.

View Source 
const (
	// ResolveOperation is the operation where we resolve a domain name.
	ResolveOperation = "resolve"

	// ConnectOperation is the operation where we do a TCP connect.
	ConnectOperation = "connect"

	// TLSHandshakeOperation is the TLS handshake.
	TLSHandshakeOperation = "tls_handshake"

	// QUICHandshakeOperation is the handshake to setup a QUIC connection.
	QUICHandshakeOperation = "quic_handshake"

	// QUICListenOperation is when we open a listening UDP conn for QUIC.
	QUICListenOperation = "quic_listen"

	// HTTPRoundTripOperation is the HTTP round trip.
	HTTPRoundTripOperation = "http_round_trip"

	// CloseOperation is when we close a socket.
	CloseOperation = "close"

	// ReadOperation is when we read from a socket.
	ReadOperation = "read"

	// WriteOperation is when we write to a socket.
	WriteOperation = "write"

	// ReadFromOperation is when we read from an UDP socket.
	ReadFromOperation = "read_from"

	// WriteToOperation is when we write to an UDP socket.
	WriteToOperation = "write_to"

	// UnknownOperation is when we cannot determine the operation.
	UnknownOperation = "unknown"

	// TopLevelOperation is used when the failure happens at top level. This
	// happens for example with urlgetter with a cancelled context.
	TopLevelOperation = "top_level"
)

Operations that we measure. They are the possible values of the ErrWrapper.Operation field.

Variables

View Source 
var (
	ErrOODNSNoSuchHost  = fmt.Errorf("ooniresolver: %s", DNSNoSuchHostSuffix)
	ErrOODNSRefused     = errors.New("ooniresolver: refused")
	ErrOODNSMisbehaving = fmt.Errorf("ooniresolver: %s", DNSServerMisbehavingSuffix)
	ErrOODNSNoAnswer    = fmt.Errorf("ooniresolver: %s", DNSNoAnswerSuffix)
)

These errors are returned by custom DNSTransport instances (e.g., DNSOverHTTPS and DNSOverUDP). Their suffix matches the equivalent unexported errors used by the Go standard library.

View Source 
var (
	DefaultDialer        = &dialerSystem{}
	DefaultTLSHandshaker = defaultTLSHandshaker
	NewConnUTLS          = newConnUTLS
	DefaultResolver      = &resolverSystem{}
)

These vars export internal names to legacy ooni/probe-cli code.

Deprecated: do not use these names in new code.

View Source 
var ErrDNSBogon = errors.New("dns: detected bogon address")

ErrDNSBogon indicates that we found a bogon address. Code that filters for DNS bogons MUST use this error.

View Source 
var ErrInvalidTLSVersion = errors.New("invalid TLS version")

ErrInvalidTLSVersion indicates that you passed us a string that does not represent a valid TLS version.

View Source 
var ErrNoConnReuse = errors.New("cannot reuse connection")

ErrNoConnReuse is the type of error returned when you create a "single use" dialer or a "single use" TLS dialer and you dial more than once, which is not supported by such a dialer.

View Source 
var ErrNoDNSTransport = errors.New("operation requires a DNS transport")

ErrNoDNSTransport is the error returned when you attempt to perform a DNS operation that requires a custom DNSTransport (e.g., DNSOverHTTPS) but you are using the "system" resolver instead.

View Source 
var ErrNoDialer = errors.New("no configured dialer")

ErrNoDialer is the type of error returned by "null" dialers when you attempt to dial with them.

View Source 
var ErrNoResolver = errors.New("no configured resolver")

ErrNoResolver is the type of error returned by "without resolver" dialer when asked to dial for and endpoint containing a domain name, since they can only dial for endpoints containing IP addresses.

View Source 
var ErrNoTLSDialer = errors.New("no configured TLS dialer")

ErrNoTLSDialer is the type of error returned by "null" TLS dialers when you attempt to dial with them.

View Source 
var ErrNotTLSConn = errors.New("not a TLSConn")

ErrNotTLSConn occur when an interface accepts a net.Conn but internally needs a TLSConn and you pass a net.Conn that doesn't implement TLSConn to such an interface.

View Source 
var ErrUTLSHandshakePanic = errors.New("utls: handshake panic")

ErrUTLSHandshakePanic indicates that there was panic handshaking when we were using the yawning/utls library for parroting. See https://github.com/ooni/probe/issues/1770 for more information.

View Source 
var TProxy model.UnderlyingNetworkLibrary = &TProxyStdlib{}

TProxy is the fundamental variable controlling how netxlite creates net.Conn and model.UDPLikeConn, as well as how it uses the stdlib resolver. By modifying this variable, you can effectively transparently proxy netxlite (and hence OONI) activities to other services. This is quite convenient when performing quality assurance tests.

Functions

func ConfigureTLSVersion 

func ConfigureTLSVersion(config *tls.Config, version string) error

ConfigureTLSVersion configures the correct TLS version into a *tls.Config or returns ErrInvalidTLSVersion.

Recognized strings: TLSv1.3, TLSv1.2, TLSv1.1, TLSv1.0.

func CopyContext 

func CopyContext(ctx context.Context, dst io.Writer, src io.Reader) (int64, error)

CopyContext is like io.Copy but may terminate earlier when the context expires. This function has the same caveats of ReadAllContext regarding the temporary leaking of the background I/O goroutine.

As of Go 1.17.6, CopyContext additionally deals with wrapped io.EOF correctly, while io.Copy does not. See https://github.com/ooni/probe/issues/1965.

func IsBogon added in v3.14.0 

func IsBogon(address string) bool

IsBogon returns whether if an IP address is bogon. Passing to this function a non-IP address causes it to return true.

func NewDefaultCertPool 

func NewDefaultCertPool() *x509.CertPool

NewDefaultCertPool returns the default x509 certificate pool that we bundle from Mozilla. It's safe to modify the returned value: every invocation returns a distinct *x509.CertPool instance.

func NewDialerWithResolver 

func NewDialerWithResolver(logger model.DebugLogger, resolver model.Resolver) model.Dialer

NewDialerWithResolver calls WrapDialer for the stdlib dialer.

func NewDialerWithoutResolver 

func NewDialerWithoutResolver(logger model.DebugLogger) model.Dialer

NewDialerWithoutResolver calls NewDialerWithResolver with a "null" resolver.

The returned dialer fails with ErrNoResolver if passed a domain name.

func NewHTTP3Transport 

func NewHTTP3Transport(
	logger model.DebugLogger, dialer model.QUICDialer, tlsConfig *tls.Config) model.HTTPTransport

NewHTTP3Transport creates a new HTTPTransport using http3. The dialer argument MUST NOT be nil. If the tlsConfig argument is nil, then the code will use the default TLS configuration.

func NewHTTPClientStdlib added in v3.14.0 

func NewHTTPClientStdlib(logger model.DebugLogger) model.HTTPClient

NewHTTPClientStdlib creates a new HTTPClient that uses the standard library for TLS and DNS resolutions.

func NewHTTPTransport 

func NewHTTPTransport(logger model.DebugLogger, dialer model.Dialer, tlsDialer model.TLSDialer) model.HTTPTransport

NewHTTPTransport combines NewOOHTTPBaseTransport and WrapHTTPTransport.

This factory and NewHTTPTransportStdlib are the recommended ways of creating a new HTTPTransport.

func NewHTTPTransportStdlib 

func NewHTTPTransportStdlib(logger model.DebugLogger) model.HTTPTransport

NewHTTPTransportStdlib creates a new HTTPTransport using the stdlib for DNS resolutions and TLS.

This factory calls NewHTTPTransport with suitable dialers.

This factory and NewHTTPTransport are the recommended ways of creating a new HTTPTransport.

func NewNullDialer 

func NewNullDialer() model.Dialer

NewNullDialer returns a dialer that always fails with ErrNoDialer.

func NewNullTLSDialer 

func NewNullTLSDialer() model.TLSDialer

NewNullTLSDialer returns a TLS dialer that always fails with ErrNoTLSDialer.

func NewOOHTTPBaseTransport 

func NewOOHTTPBaseTransport(dialer model.Dialer, tlsDialer model.TLSDialer) model.HTTPTransport

NewOOHTTPBaseTransport creates an HTTPTransport using the given dialers.

The returned transport will gracefully handle TLS connections created using gitlab.com/yawning/utls.git, if the TLS dialer is a dialer using such library for TLS operations.

The returned transport will not have a configured proxy, not even the proxy configurable from the environment.

The returned transport will disable transparent decompression of compressed response bodies (and will not automatically ask for such compression, though you can always do that manually).

The returned transport will configure TCP and TLS connections created using its dialer and TLS dialer to always have a read watchdog timeout to address https://github.com/ooni/probe/issues/1609.

The returned transport will always enforce 1 connection per host and we cannot get rid of this QUIRK requirement because it is necessary to perform sane measurements with tracing. We will be able to possibly relax this requirement after we change the way in which we perform measurements.

This is a low level factory. Consider not using it directly.

func NewQUICDialerWithResolver 

func NewQUICDialerWithResolver(listener model.QUICListener,
	logger model.DebugLogger, resolver model.Resolver) model.QUICDialer

NewQUICDialerWithResolver returns a QUICDialer using the given QUICListener to create listening connections and the given Resolver to resolve domain names (if needed).

Properties of the dialer:

1. logs events using the given logger;

2. resolves domain names using the givern resolver;

3. when using a resolver, _may_ attempt multiple dials in parallel (happy eyeballs) and _may_ return an aggregate error to the caller;

4. wraps errors;

5. has a configured connect timeout;

6. if a dialer wraps a resolver, the dialer will forward the CloseIdleConnection call to its resolver (which is instrumental to manage a DoH resolver connections properly).

func NewQUICDialerWithoutResolver 

func NewQUICDialerWithoutResolver(listener model.QUICListener, logger model.DebugLogger) model.QUICDialer

NewQUICDialerWithoutResolver is like NewQUICDialerWithResolver except that there is no configured resolver. So, if you pass in an address containing a domain name, the dial will fail with the ErrNoResolver failure.

func NewQUICListener 

func NewQUICListener() model.QUICListener

NewQUICListener creates a new QUICListener using the standard library to create listening UDP sockets.

func NewResolverStdlib 

func NewResolverStdlib(logger model.DebugLogger) model.Resolver

NewResolverStdlib creates a new Resolver by combining WrapResolver with an internal "system" resolver type.

func NewResolverUDP 

func NewResolverUDP(logger model.DebugLogger, dialer model.Dialer, address string) model.Resolver

NewResolverUDP creates a new Resolver using DNS-over-UDP.

Arguments:

- logger is the logger to use

- dialer is the dialer to create and connect UDP conns

- address is the server address (e.g., 1.1.1.1:53)

func NewSingleUseDialer 

func NewSingleUseDialer(conn net.Conn) model.Dialer

NewSingleUseDialer returns a "single use" dialer. The first dial will succed and return conn regardless of the network and address arguments passed to DialContext. Any subsequent dial returns ErrNoConnReuse.

func NewSingleUseQUICDialer 

func NewSingleUseQUICDialer(sess quic.EarlySession) model.QUICDialer

NewSingleUseQUICDialer is like NewSingleUseDialer but for QUIC.

func NewSingleUseTLSDialer 

func NewSingleUseTLSDialer(conn TLSConn) model.TLSDialer

NewSingleUseTLSDialer is like NewSingleUseDialer but takes in input a TLSConn rather than a net.Conn.

func NewTLSDialer 

func NewTLSDialer(dialer model.Dialer, handshaker model.TLSHandshaker) model.TLSDialer

NewTLSDialer creates a new TLS dialer using the given dialer and handshaker.

func NewTLSDialerWithConfig 

func NewTLSDialerWithConfig(d model.Dialer, h model.TLSHandshaker, c *tls.Config) model.TLSDialer

NewTLSDialerWithConfig is like NewTLSDialer with an optional config.

func NewTLSHandshakerStdlib 

func NewTLSHandshakerStdlib(logger model.DebugLogger) model.TLSHandshaker

NewTLSHandshakerStdlib creates a new TLS handshaker using the go standard library to manage TLS.

The handshaker guarantees:

1. logging

2. error wrapping

func NewTLSHandshakerUTLS 

func NewTLSHandshakerUTLS(logger model.DebugLogger, id *utls.ClientHelloID) model.TLSHandshaker

NewTLSHandshakerUTLS creates a new TLS handshaker using gitlab.com/yawning/utls for TLS.

The id is the address of something like utls.HelloFirefox_55.

The handshaker guarantees:

1. logging

2. error wrapping

Passing a nil `id` will make this function panic.

func ReadAllContext 

func ReadAllContext(ctx context.Context, r io.Reader) ([]byte, error)

ReadAllContext is like io.ReadAll but reads r in a background goroutine. This function will return earlier if the context is cancelled. In which case we will continue reading from the reader in the background goroutine, and we will discard the result. To stop the long-running goroutine, close the connection bound to the reader. Until such a connection is closed, you're leaking the backround goroutine and doing I/O.

As of Go 1.17.6, ReadAllContext additionally deals with wrapped io.EOF correctly, while io.ReadAll does not. See https://github.com/ooni/probe/issues/1965.

func TLSCipherSuiteString 

func TLSCipherSuiteString(value uint16) string

TLSCipherSuiteString returns the TLS cipher suite as a string. If value is zero, we return the empty string. If we don't know the mapping from the value to a cipher suite name, we return `TLS_CIPHER_SUITE_UNKNOWN_ddd` where `ddd` is the numeric value passed to this function.

func TLSVersionString 

func TLSVersionString(value uint16) string

TLSVersionString returns a TLS version string. If value is zero, we return the empty string. If the value is unknown, we return `TLS_VERSION_UNKNOWN_ddd` where `ddd` is the numeric value passed to this function.

func WrapDialer 

func WrapDialer(logger model.DebugLogger, resolver model.Resolver, dialer model.Dialer) model.Dialer

WrapDialer creates a new Dialer that wraps the given Dialer. The returned Dialer has the following properties:

1. logs events using the given logger;

2. resolves domain names using the givern resolver;

3. when the resolver is not a "null" resolver, each available enpoint is tried sequentially. On error, the code will return what it believes to be the most representative error in the pack. Most often, the first error that occurred. Choosing the error to return using this logic is a QUIRK that we owe to the original implementation of netx. We cannot change this behavior until we refactor legacy code using it.

Removing this quirk from the codebase is documented as TODO(https://github.com/ooni/probe/issues/1779).

4. wraps errors;

5. has a configured connect timeout;

6. if a dialer wraps a resolver, the dialer will forward the CloseIdleConnection call to its resolver (which is instrumental to manage a DoH resolver connections properly).

In general, do not use WrapDialer directly but try to use more high-level factories, e.g., NewDialerWithResolver.

func WrapHTTPClient 

func WrapHTTPClient(clnt model.HTTPClient) model.HTTPClient

WrapHTTPClient wraps an HTTP client to add error wrapping capabilities.

func WrapHTTPTransport 

func WrapHTTPTransport(logger model.DebugLogger, txp model.HTTPTransport) model.HTTPTransport

WrapHTTPTransport creates an HTTPTransport using the given logger and guarantees that returned errors are wrapped.

This is a low level factory. Consider not using it directly.

func WrapResolver 

func WrapResolver(logger model.DebugLogger, resolver model.Resolver) model.Resolver

WrapResolver creates a new resolver that wraps an existing resolver to add these properties:

1. handles IDNA;

2. performs logging;

3. short-circuits IP addresses like getaddrinfo does (i.e., resolving "1.1.1.1" yields []string{"1.1.1.1"};

4. wraps errors;

5. enforces reasonable timeouts ( see https://github.com/ooni/probe/issues/1726).

This is a low-level factory. Use only if out of alternatives.

Types

type AddressResolver deprecated 

type AddressResolver = resolverShortCircuitIPAddr

These types export internal names to legacy ooni/probe-cli code.

Deprecated: do not use these names in new code.

type Classifier 

type Classifier func(err error) string

Classifier is the type of the function that maps a Go error to a OONI failure string defined at https://github.com/ooni/spec/blob/master/data-formats/df-007-errors.md.

type DNSDecoderMiekg 

type DNSDecoderMiekg struct{}

DNSDecoderMiekg uses github.com/miekg/dns to implement the Decoder.

func (*DNSDecoderMiekg) DecodeHTTPS 

func (d *DNSDecoderMiekg) DecodeHTTPS(data []byte) (*model.HTTPSSvc, error)

func (*DNSDecoderMiekg) DecodeLookupHost 

func (d *DNSDecoderMiekg) DecodeLookupHost(qtype uint16, data []byte) ([]string, error)

type DNSEncoderMiekg 

type DNSEncoderMiekg struct{}

DNSEncoderMiekg uses github.com/miekg/dns to implement the Encoder.

func (*DNSEncoderMiekg) Encode 

func (e *DNSEncoderMiekg) Encode(domain string, qtype uint16, padding bool) ([]byte, error)

type DNSOverHTTPS 

type DNSOverHTTPS struct {
	// Client is the MANDATORY http client to use.
	Client model.HTTPClient

	// URL is the MANDATORY URL of the DNS-over-HTTPS server.
	URL string

	// HostOverride is OPTIONAL and allows to override the
	// Host header sent in every request.
	HostOverride string
}

DNSOverHTTPS is a DNS-over-HTTPS DNSTransport.

func NewDNSOverHTTPS 

func NewDNSOverHTTPS(client model.HTTPClient, URL string) *DNSOverHTTPS

NewDNSOverHTTPS creates a new DNSOverHTTPS instance.

Arguments:

- client in http.Client-like type (e.g., http.DefaultClient);

- URL is the DoH resolver URL (e.g., https://1.1.1.1/dns-query).

func NewDNSOverHTTPSWithHostOverride 

func NewDNSOverHTTPSWithHostOverride(
	client model.HTTPClient, URL, hostOverride string) *DNSOverHTTPS

NewDNSOverHTTPSWithHostOverride creates a new DNSOverHTTPS with the given Host header override.

func (*DNSOverHTTPS) Address 

func (t *DNSOverHTTPS) Address() string

Address returns the URL we're using for the DoH server.

func (*DNSOverHTTPS) CloseIdleConnections 

func (t *DNSOverHTTPS) CloseIdleConnections()

CloseIdleConnections closes idle connections, if any.

func (*DNSOverHTTPS) Network 

func (t *DNSOverHTTPS) Network() string

Network returns the transport network, i.e., "doh".

func (*DNSOverHTTPS) RequiresPadding 

func (t *DNSOverHTTPS) RequiresPadding() bool

RequiresPadding returns true for DoH according to RFC8467.

func (*DNSOverHTTPS) RoundTrip 

func (t *DNSOverHTTPS) RoundTrip(ctx context.Context, query []byte) ([]byte, error)

RoundTrip sends a query and receives a reply.

type DNSOverTCP 

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

DNSOverTCP is a DNS-over-{TCP,TLS} DNSTransport.

Bug: this implementation always creates a new connection for each query.

func NewDNSOverTCP 

func NewDNSOverTCP(dial DialContextFunc, address string) *DNSOverTCP

NewDNSOverTCP creates a new DNSOverTCP transport.

Arguments:

- dial is a function with the net.Dialer.DialContext's signature;

- address is the endpoint address (e.g., 8.8.8.8:53).

func NewDNSOverTLS 

func NewDNSOverTLS(dial DialContextFunc, address string) *DNSOverTCP

NewDNSOverTLS creates a new DNSOverTLS transport.

Arguments:

- dial is a function with the net.Dialer.DialContext's signature;

- address is the endpoint address (e.g., 8.8.8.8:853).

func (*DNSOverTCP) Address 

func (t *DNSOverTCP) Address() string

Address returns the upstream server endpoint (e.g., "1.1.1.1:853").

func (*DNSOverTCP) CloseIdleConnections 

func (t *DNSOverTCP) CloseIdleConnections()

CloseIdleConnections closes idle connections, if any.

func (*DNSOverTCP) Network 

func (t *DNSOverTCP) Network() string

Network returns the transport network, i.e., "dot" or "tcp".

func (*DNSOverTCP) RequiresPadding 

func (t *DNSOverTCP) RequiresPadding() bool

RequiresPadding returns true for DoT and false for TCP according to RFC8467.

func (*DNSOverTCP) RoundTrip 

func (t *DNSOverTCP) RoundTrip(ctx context.Context, query []byte) ([]byte, error)

RoundTrip sends a query and receives a reply.

type DNSOverUDP 

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

DNSOverUDP is a DNS-over-UDP DNSTransport.

func NewDNSOverUDP 

func NewDNSOverUDP(dialer model.Dialer, address string) *DNSOverUDP

NewDNSOverUDP creates a DNSOverUDP instance.

Arguments:

- dialer is any type that implements the Dialer interface;

- address is the endpoint address (e.g., 8.8.8.8:53).

func (*DNSOverUDP) Address 

func (t *DNSOverUDP) Address() string

Address returns the upstream server address.

func (*DNSOverUDP) CloseIdleConnections 

func (t *DNSOverUDP) CloseIdleConnections()

CloseIdleConnections closes idle connections, if any.

func (*DNSOverUDP) Network 

func (t *DNSOverUDP) Network() string

Network returns the transport network, i.e., "udp".

func (*DNSOverUDP) RequiresPadding 

func (t *DNSOverUDP) RequiresPadding() bool

RequiresPadding returns false for UDP according to RFC8467.

func (*DNSOverUDP) RoundTrip 

func (t *DNSOverUDP) RoundTrip(ctx context.Context, query []byte) ([]byte, error)

RoundTrip sends a query and receives a reply.

type DialContextFunc 

type DialContextFunc func(context.Context, string, string) (net.Conn, error)

DialContextFunc is the type of net.Dialer.DialContext.

type DialerLogger deprecated 

type DialerLogger = dialerLogger

These types export internal names to legacy ooni/probe-cli code.

Deprecated: do not use these names in new code.

type DialerResolver deprecated 

type DialerResolver = dialerResolver

These types export internal names to legacy ooni/probe-cli code.

Deprecated: do not use these names in new code.

type DialerSystem deprecated 

type DialerSystem = dialerSystem

These types export internal names to legacy ooni/probe-cli code.

Deprecated: do not use these names in new code.

type ErrWrapper 

type ErrWrapper struct {
	// Failure is the OONI failure string. The failure strings are
	// loosely backward compatible with Measurement Kit.
	//
	// This is either one of the FailureXXX strings or any other
	// string like `unknown_failure: ...`. The latter represents an
	// error that we have not yet mapped to a failure.
	Failure string

	// Operation is the operation that failed.
	//
	// If possible, the Operation string SHOULD be a _major_
	// operation. Major operations are:
	//
	// - ResolveOperation: resolving a domain name failed
	// - ConnectOperation: connecting to an IP failed
	// - TLSHandshakeOperation: TLS handshaking failed
	// - QUICHandshakeOperation: QUIC handshaking failed
	// - HTTPRoundTripOperation: other errors during round trip
	//
	// Because a network connection doesn't necessarily know
	// what is the current major operation we also have the
	// following _minor_ operations:
	//
	// - CloseOperation: CLOSE failed
	// - ReadOperation: READ failed
	// - WriteOperation: WRITE failed
	//
	// If an ErrWrapper referring to a major operation is wrapping
	// another ErrWrapper and such ErrWrapper already refers to
	// a major operation, then the new ErrWrapper should use the
	// child ErrWrapper major operation. Otherwise, it should use
	// its own major operation. This way, the topmost wrapper is
	// supposed to refer to the major operation that failed.
	Operation string

	// WrappedErr is the error that we're wrapping.
	WrappedErr error
}

ErrWrapper is our error wrapper for Go errors. The key objective of this structure is to properly set Failure, which is also returned by the Error() method, to be one of the OONI failure strings.

OONI failure strings are defined in the github.com/ooni/spec repo at https://github.com/ooni/spec/blob/master/data-formats/df-007-errors.md.

func NewErrWrapper 

func NewErrWrapper(c Classifier, op string, err error) *ErrWrapper

NewErrWrapper creates a new ErrWrapper using the given classifier, operation name, and underlying error.

This function panics if classifier is nil, or operation is the empty string or error is nil.

If the err argument has already been classified, the returned error wrapper will use the same classification string and will determine whether to keep the major operation as documented in the ErrWrapper.Operation documentation.

func NewTopLevelGenericErrWrapper 

func NewTopLevelGenericErrWrapper(err error) *ErrWrapper

NewTopLevelGenericErrWrapper wraps an error occurring at top level using ClassifyGenericError as classifier.

If the err argument has already been classified, the returned error wrapper will use the same classification string and failed operation of the original error.

func (*ErrWrapper) Error 

func (e *ErrWrapper) Error() string

Error returns the OONI failure string for this error.

func (*ErrWrapper) MarshalJSON 

func (e *ErrWrapper) MarshalJSON() ([]byte, error)

MarshalJSON converts an ErrWrapper to a JSON value.

func (*ErrWrapper) Unwrap 

func (e *ErrWrapper) Unwrap() error

Unwrap allows to access the underlying error.

type ErrorWrapperDialer deprecated added in v3.14.0 

type ErrorWrapperDialer = dialerErrWrapper

These types export internal names to legacy ooni/probe-cli code.

Deprecated: do not use these names in new code.

type ErrorWrapperQUICDialer deprecated added in v3.14.0 

type ErrorWrapperQUICDialer = quicDialerErrWrapper

These types export internal names to legacy ooni/probe-cli code.

Deprecated: do not use these names in new code.

type ErrorWrapperQUICListener deprecated added in v3.14.0 

type ErrorWrapperQUICListener = quicListenerErrWrapper

These types export internal names to legacy ooni/probe-cli code.

Deprecated: do not use these names in new code.

type ErrorWrapperResolver deprecated added in v3.14.0 

type ErrorWrapperResolver = resolverErrWrapper

These types export internal names to legacy ooni/probe-cli code.

Deprecated: do not use these names in new code.

type ErrorWrapperTLSHandshaker deprecated added in v3.14.0 

type ErrorWrapperTLSHandshaker = tlsHandshakerErrWrapper

These types export internal names to legacy ooni/probe-cli code.

Deprecated: do not use these names in new code.

type HTTPTransportLogger deprecated 

type HTTPTransportLogger = httpTransportLogger

These types export internal names to legacy ooni/probe-cli code.

Deprecated: do not use these names in new code.

type QUICDialerLogger deprecated 

type QUICDialerLogger = quicDialerLogger

These types export internal names to legacy ooni/probe-cli code.

Deprecated: do not use these names in new code.

type QUICDialerQUICGo deprecated 

type QUICDialerQUICGo = quicDialerQUICGo

These types export internal names to legacy ooni/probe-cli code.

Deprecated: do not use these names in new code.

type QUICDialerResolver deprecated 

type QUICDialerResolver = quicDialerResolver

These types export internal names to legacy ooni/probe-cli code.

Deprecated: do not use these names in new code.

type QUICListenerStdlib deprecated 

type QUICListenerStdlib = quicListenerStdlib

These types export internal names to legacy ooni/probe-cli code.

Deprecated: do not use these names in new code.

type ResolverIDNA deprecated 

type ResolverIDNA = resolverIDNA

These types export internal names to legacy ooni/probe-cli code.

Deprecated: do not use these names in new code.

type ResolverLogger deprecated 

type ResolverLogger = resolverLogger

These types export internal names to legacy ooni/probe-cli code.

Deprecated: do not use these names in new code.

type ResolverSystem deprecated 

type ResolverSystem = resolverSystem

These types export internal names to legacy ooni/probe-cli code.

Deprecated: do not use these names in new code.

type SerialResolver 

type SerialResolver struct {
	// Encoder is the MANDATORY encoder to use.
	Encoder model.DNSEncoder

	// Decoder is the MANDATORY decoder to use.
	Decoder model.DNSDecoder

	// NumTimeouts is MANDATORY and counts the number of timeouts.
	NumTimeouts *atomicx.Int64

	// Txp is the underlying DNS transport.
	Txp model.DNSTransport
}

SerialResolver uses a transport and sends performs a LookupHost operation in a serial fashion (query for A first, wait for response, then query for AAAA, and wait for response), hence its name.

You should probably use NewSerialResolver to create a new instance.

func NewSerialResolver 

func NewSerialResolver(t model.DNSTransport) *SerialResolver

NewSerialResolver creates a new SerialResolver instance.

func (*SerialResolver) Address 

func (r *SerialResolver) Address() string

Address returns the "address" of the underlying transport.

func (*SerialResolver) CloseIdleConnections 

func (r *SerialResolver) CloseIdleConnections()

CloseIdleConnections closes idle connections, if any.

func (*SerialResolver) LookupHTTPS 

func (r *SerialResolver) LookupHTTPS(
	ctx context.Context, hostname string) (*model.HTTPSSvc, error)

LookupHTTPS implements Resolver.LookupHTTPS.

func (*SerialResolver) LookupHost 

func (r *SerialResolver) LookupHost(ctx context.Context, hostname string) ([]string, error)

LookupHost performs an A lookup followed by an AAAA lookup for hostname.

func (*SerialResolver) Network 

func (r *SerialResolver) Network() string

Network returns the "network" of the underlying transport.

func (*SerialResolver) Transport 

func (r *SerialResolver) Transport() model.DNSTransport

Transport returns the transport being used.

type TLSConn 

type TLSConn = oohttp.TLSConn

TLSConn is the type of connection that oohttp expects from any library that implements TLS functionality. By using this kind of TLSConn we're able to use both the standard library and gitlab.com/yawning/utls.git to perform TLS operations. Note that the stdlib's tls.Conn implements this interface.

type TLSDialerLegacy deprecated 

type TLSDialerLegacy = tlsDialer

These types export internal names to legacy ooni/probe-cli code.

Deprecated: do not use these names in new code.

type TLSHandshakerConfigurable deprecated 

type TLSHandshakerConfigurable = tlsHandshakerConfigurable

These types export internal names to legacy ooni/probe-cli code.

Deprecated: do not use these names in new code.

type TLSHandshakerLogger deprecated 

type TLSHandshakerLogger = tlsHandshakerLogger

These types export internal names to legacy ooni/probe-cli code.

Deprecated: do not use these names in new code.

type TProxyStdlib added in v3.14.0 

type TProxyStdlib struct{}

TProxyStdlib is the default model.UnderlyingNetworkLibrary using the stdlib in the most obvious way for every functionality.

func (*TProxyStdlib) ListenUDP added in v3.14.0 

func (*TProxyStdlib) ListenUDP(network string, laddr *net.UDPAddr) (model.UDPLikeConn, error)

ListenUDP calls net.ListenUDP.

func (*TProxyStdlib) LookupHost added in v3.14.0 

func (*TProxyStdlib) LookupHost(ctx context.Context, domain string) ([]string, error)

LookupHost calls net.DefaultResolver.LookupHost.

func (*TProxyStdlib) NewSimpleDialer added in v3.14.0 

func (*TProxyStdlib) NewSimpleDialer(timeout time.Duration) model.SimpleDialer

NewSimpleDialer returns a &net.Dialer{Timeout: timeout} instance.

Source Files

View all Source files

Directories

Path Synopsis
Package filtering allows to implement self-censorship.
 Package filtering allows to implement self-censorship.
internal
gencertifi
generrno
Package quictesting contains code useful to test QUIC.
 Package quictesting contains code useful to test QUIC.

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.