engineresolver

Documentation

Overview

Package engineresolver contains the resolver used by the OONI engine. This resolver will try to figure out which is the best service for running domain name resolutions and will consistently use it.

Occasionally this code will also swap the best resolver with other ~good resolvers to give them a chance to perform.

The penalty/reward mechanism is strongly derivative, so the code should adapt ~quickly to changing network conditions. Occasionally, we will have longer resolutions when trying out other resolvers.

At the beginning we randomize the known resolvers so that we do not have any preferential ordering. The initial resolutions may be slower if there are many issues with resolvers.

The system resolver is given intermediate priority at the beginning (i.e., 0.5) but it will of course be the most popular resolver if anything else is failing us. (We will still occasionally probe for other working resolvers and increase their score on success.)

We also support a socks5 proxy. When such a proxy is configured, the code WILL skip http3 resolvers AS WELL AS the system resolver, in an attempt to avoid leaking your queries.

Index

• Variables
• type Resolver
  • func (r *Resolver) Address() string
  • func (r *Resolver) CloseIdleConnections()
  • func (r *Resolver) LookupHTTPS(ctx context.Context, domain string) (*model.HTTPSSvc, error)
  • func (r *Resolver) LookupHost(ctx context.Context, hostname string) ([]string, error)
  • func (r *Resolver) LookupNS(ctx context.Context, domain string) ([]*net.NS, error)
  • func (r *Resolver) Network() string

Variables

var ErrLookupHost = errors.New("sessionresolver: LookupHost failed")

ErrLookupHost indicates that LookupHost failed.

var ErrNilKVStore = errors.New("sessionresolver: kvstore is nil")

ErrNilKVStore indicates that the KVStore is nil.

Types

type Resolver

type Resolver struct {
	// ByteCounter is the OPTIONAL byte counter. It will count
	// the bytes used by any child resolver except for the
	// system resolver, whose bytes ARE NOT counted. If this
	// field is not set, then we won't count the bytes.
	ByteCounter *bytecounter.Counter

	// KVStore is the MANDATORY key-value store where you
	// want us to write statistics about which resolver is
	// working better in your network.
	KVStore model.KeyValueStore

	// Logger is the OPTIONAL logger you want us to use
	// to emit log messages.
	Logger model.Logger

	// ProxyURL is the OPTIONAL URL of the socks5 proxy
	// we should be using. If not set, then we WON'T use
	// any proxy. If set, then we WON'T use any http3
	// based resolvers and we WON'T use the system resolver.
	ProxyURL *url.URL
	// contains filtered or unexported fields
}

Resolver is the session resolver. Resolver will try to use a bunch of DoT/DoH resolvers before falling back to the system resolver. The relative priorities of the resolver are stored onto the KVStore such that we can remember them and therefore we can generally give preference to underlying DoT/DoH resolvers that work better.

Make sure you fill the mandatory fields (indicated below) before using this data structure.

You MUST NOT modify public fields of this structure once it has been created, because that MAY lead to data races.

func (*Resolver) Address

func (r *Resolver) Address() string

Address implements Resolver.Address.

func (*Resolver) CloseIdleConnections

func (r *Resolver) CloseIdleConnections()

CloseIdleConnections closes the idle connections, if any. This function is guaranteed to be idempotent.

func (*Resolver) LookupHTTPS

func (r *Resolver) LookupHTTPS(ctx context.Context, domain string) (*model.HTTPSSvc, error)

LookupHTTPS implements Resolver.LookupHTTPS.

func (*Resolver) LookupHost

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

LookupHost implements Resolver.LookupHost. This function returns a multierror.Union error on failure, so you can see individual errors and get a better picture of what's been going wrong.

func (*Resolver) LookupNS

func (r *Resolver) LookupNS(ctx context.Context, domain string) ([]*net.NS, error)

LookupNS implements Resolver.LookupNS.

func (*Resolver) Network

func (r *Resolver) Network() string

Network implements Resolver.Network.