sessionresolver

Documentation

Overview

Package sessionresolver contains the resolver used by the session. 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 the lowest priority at the beginning 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 KVStore
• type Logger
• type Resolver
  • func (r *Resolver) Address() string
  • func (r *Resolver) CloseIdleConnections()
  • func (r *Resolver) LookupHost(ctx context.Context, hostname string) ([]string, error)
  • func (r *Resolver) Network() string
  • func (r *Resolver) Stats() 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 KVStore

type KVStore interface {
	// Get gets the value for the given key.
	Get(key string) ([]byte, error)

	// Set sets the value of the given key.
	Set(key string, value []byte) error
}

KVStore is a generic key-value store. We use it to store on disk persistent state used by this package.

type Logger

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

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

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

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

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

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

Logger defines the common logger interface.

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 KVStore

	// Logger is the optional logger you want us to use
	// to emit log messages.
	Logger 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.

You should create an instance of this structure and use it in internal/engine/session.go.

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) 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) Network

func (r *Resolver) Network() string

Network implements Resolver.Network.

func (*Resolver) Stats

func (r *Resolver) Stats() string

Stats returns stats about the session resolver.