netx

package module
v0.0.0-...-11e21a6 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Mar 6, 2020 License: BSD-3-Clause Imports: 6 Imported by: 0

README

github.com/ooni/netx

⚠️: As of 2020-03-06, netx has been merged into ooni/probe-engine. You should import github.com/ooni/probe-engine/netx rather than github.com/ooni/netx. We thought it was easier to keep netx and probe-engine separate, but it turned out this was increasingly slowing us down, so we decided to merge them.

Build Status Coverage Status Go Report Card

OONI extensions to the net and net/http packages. This code is used by ooni/probe-engine as a low level library to collect network, DNS, and HTTP events occurring during OONI measurements.

API documentation

This library contains replacements for commonly used standard library interfaces that facilitate seamless network measurements. By using such replacements, as opposed to standard library interfaces, we can:

  • save the timing of HTTP events (e.g. received response headers)
  • save the timing and result of every Connect, Read, Write, Close operation
  • save the timing and result of the TLS handshake (including certificates)

By default, this library uses the system resolver. In addition, it is possible to configure alternative DNS transports and remote servers. We support DNS over UDP, DNS over TCP, DNS over TLS (DoT), and DNS over HTTPS (DoH). When using an alternative transport, we are also able to intercept and save DNS messages, as well as any other interaction with the remote server (e.g., the result of the TLS handshake for DoT and DoH).

github.com/ooni/netx/modelx

GoDoc

The base package, that defines everything that other packages will use, and chiefly the measurement model.

github.com/ooni/netx/httpx

GoDoc

Implements a http.Client replacement that saves the timing and results of HTTP and network events.

github.com/ooni/netx

GoDoc

Implements net.Dialer and net.Resolver replacements that saves the timing and the details of network events.

Other packages

There are other utility and internal packages. Their documentation is reachable from the netx online documentation.

Build, run tests, run example commands

You need Go >= 1.13. We use Go modules.

To run tests:

GO111MODULE=on go test -v -race ./...

To build the example commands:

GO111MODULE=on go build -v ./cmd/...

All commands will provide terse help messages when run with -help. When run without arguments they run against default input suitable to show at a first glance their functionality.

Documentation

Overview

Package netx contains OONI's net extensions.

This package provides a replacement for net.Dialer that can Dial, DialContext, and DialTLS. During its lifecycle this modified Dialer will emit network level events on a channel.

⚠️: This package is not maintained anymore. Use github.com/ooni/probe-engine/netx as a drop-in replacement for github.com/ooni/netx.

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

func ChainResolvers 

func ChainResolvers(primary, secondary modelx.DNSResolver) modelx.DNSResolver

ChainResolvers chains a primary and a secondary resolver such that we can fallback to the secondary if primary is broken.

func NewResolver 

func NewResolver(handler modelx.Handler, network, address string) (modelx.DNSResolver, error)

NewResolver is a standalone Dialer.NewResolver

func NewResolverWithoutHandler 

func NewResolverWithoutHandler(network, address string) (modelx.DNSResolver, error)

NewResolverWithoutHandler creates a standalone Resolver

Types

type Dialer 

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

Dialer performs measurements while dialing.

func NewDialer 

func NewDialer(handler modelx.Handler) *Dialer

NewDialer returns a new Dialer instance.

func NewDialerWithoutHandler 

func NewDialerWithoutHandler() *Dialer

NewDialerWithoutHandler returns a new Dialer instance.

func (*Dialer) ConfigureDNS 

func (d *Dialer) ConfigureDNS(network, address string) error

ConfigureDNS configures the DNS resolver. The network argument selects the type of resolver. The address argument indicates the resolver address and depends on the network.

This functionality is not goroutine safe. You should only change the DNS settings before starting to use the Dialer.

The following is a list of all the possible network values:

- "": behaves exactly like "system"

- "system": this indicates that Go should use the system resolver and prevents us from seeing any DNS packet. The value of the address parameter is ignored when using "system". If you do not ConfigureDNS, this is the default resolver used.

- "udp": indicates that we should send queries using UDP. In this case the address is a host, port UDP endpoint.

- "tcp": like "udp" but we use TCP.

- "dot": we use DNS over TLS (DoT). In this case the address is the domain name of the DoT server.

- "doh": we use DNS over HTTPS (DoH). In this case the address is the URL of the DoH server.

For example: 

d.ConfigureDNS("system", "")
d.ConfigureDNS("udp", "8.8.8.8:53")
d.ConfigureDNS("tcp", "8.8.8.8:53")
d.ConfigureDNS("dot", "dns.quad9.net")
d.ConfigureDNS("doh", "https://cloudflare-dns.com/dns-query")

func (*Dialer) Dial 

func (d *Dialer) Dial(network, address string) (net.Conn, error)

Dial creates a TCP or UDP connection. See net.Dial docs.

func (*Dialer) DialContext 

func (d *Dialer) DialContext(
	ctx context.Context, network, address string,
) (net.Conn, error)

DialContext is like Dial but the context allows to interrupt a pending connection attempt at any time.

func (*Dialer) DialTLS 

func (d *Dialer) DialTLS(network, address string) (conn net.Conn, err error)

DialTLS is like Dial, but creates TLS connections.

func (*Dialer) DialTLSContext 

func (d *Dialer) DialTLSContext(
	ctx context.Context, network, address string,
) (net.Conn, error)

DialTLSContext is like DialTLS, but with context

func (*Dialer) ForceSkipVerify 

func (d *Dialer) ForceSkipVerify() error

ForceSkipVerify forces to skip certificate verification

func (*Dialer) ForceSpecificSNI 

func (d *Dialer) ForceSpecificSNI(sni string) error

ForceSpecificSNI forces using a specific SNI.

func (*Dialer) NewResolver 

func (d *Dialer) NewResolver(network, address string) (modelx.DNSResolver, error)

NewResolver returns a new resolver using the same handler of this Dialer. The arguments have the same meaning of ConfigureDNS. The returned resolver will not be used by this Dialer, and will not use this Dialer as well. The fact that it's a method of Dialer rather than an independent method is an historical oddity. There is also a standalone NewResolver factory and you should probably use it.

func (*Dialer) SetCABundle 

func (d *Dialer) SetCABundle(path string) error

SetCABundle configures the dialer to use a specific CA bundle. This function is not goroutine safe. Make sure you call it before starting to use this specific dialer.

func (*Dialer) SetResolver 

func (d *Dialer) SetResolver(r modelx.DNSResolver)

SetResolver is a more flexible way of configuring a resolver that should perhaps be used instead of ConfigureDNS.

Source Files

View all Source files

Directories

Path Synopsis
cmd
dnslookup command
dnslookup performs a DNS lookup.
 dnslookup performs a DNS lookup.
httpdo command
httpdo performs a HTTP request
 httpdo performs a HTTP request
tlsconnect command
tlsconnect performs a TLS connect.
 tlsconnect performs a TLS connect.
Package handlers contains default modelx.Handler handlers.
 Package handlers contains default modelx.Handler handlers.
Package httpx contains OONI's net/http extensions.
 Package httpx contains OONI's net/http extensions.
Package internal contains internal code.
 Package internal contains internal code.
connid
Package connid contains code to generate the connectionID
 Package connid contains code to generate the connectionID
dialer
Package dialer contains the dialer's API.
 Package dialer contains the dialer's API.
dialer/connx
Package connx contains net.Conn extensions
 Package connx contains net.Conn extensions
dialer/dialerbase
Package dialerbase contains the base dialer functionality.
 Package dialerbase contains the base dialer functionality.
dialer/dnsdialer
Package dnsdialer contains a dialer with DNS lookups.
 Package dnsdialer contains a dialer with DNS lookups.
dialer/tlsdialer
Package tlsdialer contains the TLS dialer
 Package tlsdialer contains the TLS dialer
dialid
errwrapper
Package errwrapper contains our error wrapper
 Package errwrapper contains our error wrapper
httptransport
Package httptransport contains HTTP transport extensions.
 Package httptransport contains HTTP transport extensions.
httptransport/bodytracer
Package bodytracer contains the HTTP body tracer.
 Package bodytracer contains the HTTP body tracer.
httptransport/tracetripper
Package tracetripper contains the tracing round tripper
 Package tracetripper contains the tracing round tripper
httptransport/transactioner
Package transactioner contains the transaction assigning round tripper
 Package transactioner contains the transaction assigning round tripper
resolver
Package resolver contains code to create a resolver
 Package resolver contains code to create a resolver
resolver/bogondetector
Package bogondetector contains code to determine if an IP is private/bogon.
 Package bogondetector contains code to determine if an IP is private/bogon.
resolver/brokenresolver
Package brokenresolver is a broken resolver
 Package brokenresolver is a broken resolver
resolver/chainresolver
Package chainresolver allows to chain two resolvers
 Package chainresolver allows to chain two resolvers
resolver/dnstransport/dnsoverhttps
Package dnsoverhttps implements DNS over HTTPS.
 Package dnsoverhttps implements DNS over HTTPS.
resolver/dnstransport/dnsovertcp
Package dnsovertcp implements DNS over TCP.
 Package dnsovertcp implements DNS over TCP.
resolver/dnstransport/dnsoverudp
Package dnsoverudp implements DNS over UDP.
 Package dnsoverudp implements DNS over UDP.
resolver/ooniresolver
Package ooniresolver is OONI's DNS resolver.
 Package ooniresolver is OONI's DNS resolver.
resolver/parentresolver
Package parentresolver contains the parent resolver
 Package parentresolver contains the parent resolver
resolver/systemresolver
Package systemresolver contains the system resolver
 Package systemresolver contains the system resolver
transactionid
Package transactionid contains code to share the transactionID
 Package transactionid contains code to share the transactionID
Package modelx contains the data modelx.
 Package modelx contains the data modelx.
x
logger
Package logger is a handler that emits logs.
 Package logger is a handler that emits logs.
porcelain
Package porcelain contains useful high level functionality.
 Package porcelain contains useful high level functionality.

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.