endpoint

Documentation

Index

• Constants
• Variables
• type ClientInfo
• type ConnectInfo
• type DNSEndpoint
  • func (e *DNSEndpoint) Equal(e2 Endpoint) bool
  • func (e *DNSEndpoint) Exchange(ctx context.Context, payload, buf []byte) (n int, err error)
  • func (e *DNSEndpoint) Protocol() Protocol
  • func (e *DNSEndpoint) String() string
• type DOHEndpoint
  • func (e *DOHEndpoint) Equal(e2 Endpoint) bool
  • func (e *DOHEndpoint) Exchange(ctx context.Context, payload, buf []byte) (n int, err error)
  • func (e *DOHEndpoint) Protocol() Protocol
  • func (e *DOHEndpoint) RoundTrip(req *http.Request) (resp *http.Response, err error)
  • func (e *DOHEndpoint) String() string
• type Endpoint
  • func MustNew(server string) Endpoint
  • func New(server string) (Endpoint, error)
• type Manager
  • func (m *Manager) Do(ctx context.Context, action func(e Endpoint) error) error
  • func (m *Manager) Test(ctx context.Context) error
• type Protocol
  • func (p Protocol) String() string
• type Provider
• type ProviderFunc
  • func (p ProviderFunc) GetEndpoints(ctx context.Context) ([]Endpoint, error)
• type SourceHTTPSSVCProvider
  • func (p *SourceHTTPSSVCProvider) GetEndpoints(ctx context.Context) ([]Endpoint, error)
• type SourceURLProvider
  • func (p *SourceURLProvider) GetEndpoints(ctx context.Context) ([]Endpoint, error)
  • func (p *SourceURLProvider) String() string
• type StaticProvider
  • func (p StaticProvider) GetEndpoints(ctx context.Context) ([]Endpoint, error)
• type Tester

Constants

const (
	// DefaultErrorThreshold defines the default value for Manager ErrorThreshold.
	DefaultErrorThreshold = 10

	// DefaultMinTestInterval defines the default value for Manager MinTestInterval.
	DefaultMinTestInterval = 2 * time.Hour
)

Variables

var TestDomain = "probe-test.dns.nextdns.io."

Types

type ClientInfo

type ClientInfo struct {
	ID    string
	IP    string
	Model string
	Name  string
}

type ConnectInfo

type ConnectInfo struct {
	Connect      bool
	ServerAddr   string
	ConnectTimes map[string]time.Duration
	Protocol     string
	TLSTime      time.Duration
	TLSVersion   string
}

type DNSEndpoint

type DNSEndpoint struct {
	// Addr use to contact the DNS server.
	Addr string
}

func (*DNSEndpoint) Equal

func (e *DNSEndpoint) Equal(e2 Endpoint) bool

func (*DNSEndpoint) Exchange

func (e *DNSEndpoint) Exchange(ctx context.Context, payload, buf []byte) (n int, err error)

func (*DNSEndpoint) Protocol

func (e *DNSEndpoint) Protocol() Protocol

func (*DNSEndpoint) String

func (e *DNSEndpoint) String() string

type DOHEndpoint

type DOHEndpoint struct {
	// Hostname use to contact the DoH server. If Bootstrap is provided,
	// Hostname is only used for TLS verification.
	Hostname string

	// Path to use with DoH HTTP requests. If empty, the path received in the
	// request by Transport is left untouched.
	Path string

	// Bootstrap is the IPs to use to contact the DoH server. When provided, no
	// DNS request is necessary to contact the DoH server. The fastest IP is
	// used.
	Bootstrap []string `json:"ips"`

	// ALPN is the list of alpn-id declared to be supported by the endpoint
	// through HTTPSSVC or Alt-Svc. If missing, h2 is assumed.
	ALPN []string
	// contains filtered or unexported fields
}

Endpoint represents a DoH server endpoint.

func (*DOHEndpoint) Equal

func (e *DOHEndpoint) Equal(e2 Endpoint) bool

func (*DOHEndpoint) Exchange

func (e *DOHEndpoint) Exchange(ctx context.Context, payload, buf []byte) (n int, err error)

func (*DOHEndpoint) Protocol

func (e *DOHEndpoint) Protocol() Protocol

func (*DOHEndpoint) RoundTrip

func (e *DOHEndpoint) RoundTrip(req *http.Request) (resp *http.Response, err error)

func (*DOHEndpoint) String

func (e *DOHEndpoint) String() string

type Endpoint

type Endpoint interface {
	fmt.Stringer

	// Protocol returns the protocol used by this endpoint to transport DNS.
	Protocol() Protocol

	// Equal returns true if e represent the same endpoint.
	Equal(e Endpoint) bool

	// Send a DNS payload and get the response in buf.
	Exchange(ctx context.Context, payload, buf []byte) (n int, err error)
}

Endpoint represents a DNS server endpoint.

func MustNew

func MustNew(server string) Endpoint

MustNew is like New but panics on error.

func New

func New(server string) (Endpoint, error)

New is a convenient method to build a Endpoint.

Supported format for server are:

• DoH: https://doh.server.com/path
• DoH: https://doh.server.com/path#1.2.3.4 // with bootstrap
• DNS53: 1.2.3.4
• DNS53: 1.2.3.4:5353

type Manager

type Manager struct {
	// Providers is a list of Endpoint providers listed in order of preference.
	// The first working provided is selected on each call to Test or internal
	// test performed on error or opportunistically.
	//
	// Calling Test with an empty Providers list will result in a panic.
	Providers []Provider

	// InitEndpoint defines the endpoint to use before Providers returned a
	// working endpoint.
	InitEndpoint Endpoint

	// ErrorThreshold is the number of consecutive errors with a endpoint
	// requires to trigger a test to fallback on another endpoint. If zero,
	// DefaultErrorThreshold is used.
	ErrorThreshold int

	// MinTestInterval is the minimum interval to keep between two opportunistic
	// tests. Opportunistic tests are scheduled only when a DNS request attempt
	// is performed and the last test happened at list TestMinInterval age.
	MinTestInterval time.Duration

	// GetMinTestInterval returns the MinTestInterval to use for e. If
	// GetMinTestInterval returns 0 or is unset, MinTestInterval is used.
	GetMinTestInterval func(e Endpoint) time.Duration

	// TestEndpoint specifies a custom tester for e. If not defined or nil
	// returned, Test is called on e.
	EndpointTester func(e Endpoint) Tester

	// OnChange is called whenever the active endpoint changes.
	OnChange func(e Endpoint)

	// OnConnect is called whenever an endpoint connects (for connected
	// endpoints).
	OnConnect func(*ConnectInfo)

	// OnError is called each time a test on e failed, forcing Manager to
	// fallback to the next endpoint. If e is nil, the error happended on the
	// Provider.
	OnError func(e Endpoint, err error)

	// OnProviderError is called when a provider returns an error.
	OnProviderError func(p Provider, err error)
	// contains filtered or unexported fields
}

func (*Manager) Do

func (m *Manager) Do(ctx context.Context, action func(e Endpoint) error) error

func (*Manager) Test

func (m *Manager) Test(ctx context.Context) error

Test forces a test of the endpoints returned by the providers and call OnChange with the newly selected endpoint if different.

type Protocol

type Protocol int

const (
	ProtocolDOH Protocol = iota
	ProtocolDNS
)

func (Protocol) String

func (p Protocol) String() string

type Provider

type Provider interface {
	GetEndpoints(ctx context.Context) ([]Endpoint, error)
}

Provider is a type responsible for producing a list of Endpoint.

type ProviderFunc

type ProviderFunc func(ctx context.Context) ([]Endpoint, error)

func (ProviderFunc) GetEndpoints

func (p ProviderFunc) GetEndpoints(ctx context.Context) ([]Endpoint, error)

type SourceHTTPSSVCProvider

type SourceHTTPSSVCProvider struct {
	Hostname string
	Source   Endpoint
}

func (*SourceHTTPSSVCProvider) GetEndpoints

func (p *SourceHTTPSSVCProvider) GetEndpoints(ctx context.Context) ([]Endpoint, error)

GetEndpoints implements the Provider interface.

type SourceURLProvider

type SourceURLProvider struct {
	// SourceURL is a URL pointing to a JSON resource listing one or more
	// Endpoints.
	SourceURL string

	// Client is the http.Client to use to fetch SourceURL. If not defined,
	// http.DefaultClient is used.
	Client *http.Client
	// contains filtered or unexported fields
}

SourceURLProvider loads a list of endpoints from a remote URL.

func (*SourceURLProvider) GetEndpoints

func (p *SourceURLProvider) GetEndpoints(ctx context.Context) ([]Endpoint, error)

GetEndpoints implements the Provider interface.

func (*SourceURLProvider) String

func (p *SourceURLProvider) String() string

type StaticProvider

type StaticProvider []Endpoint

StaticProvider wraps a Endpoint slice to adapt it to the Provider interface.

func (StaticProvider) GetEndpoints

func (p StaticProvider) GetEndpoints(ctx context.Context) ([]Endpoint, error)

GetEndpoints implements the Provider interface.

type Tester

type Tester func(ctx context.Context, testDomain string) error