dslx

package
v3.22.0 Latest Latest
Warning

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

 Go to latest Published: May 22, 2024 License: GPL-3.0 Imports: 18 Imported by: 0

Documentation

Overview

Package dslx implements a domain specific language for writing network experiments.

See https://github.com/ooni/probe-cli/blob/master/docs/design/dd-005-dslx.md for the design document explaining why we introduced this package.

Index

Constants

This section is empty.

Variables

View Source 
var ErrDNSLookupParallel = errors.New("dslx: DNSLookupParallel failed")

ErrDNSLookupParallel indicates that DNSLookupParallel failed.

View Source 
var ErrSkip = errors.New("dslx: error already processed by a previous stage")

ErrSkip is an error that indicates that we already processed an error emitted by a previous stage, so we are using this error to avoid counting the original error more than once when computing statistics, e.g., in *Stats.

Functions

func ApplyAsync deprecated 

func ApplyAsync[A, B any](
	ctx context.Context,
	fx Func[A, B],
	input A,
) <-chan *Maybe[B]

ApplyAsync is equivalent to calling Apply but returns a channel.

Deprecated: use Matrix instead.

func Collect 

func Collect[T any](c <-chan T) (v []T)

Collect collects all the elements inside a channel under the assumption that the channel will be closed to signal EOF.

func Map deprecated 

func Map[A, B any](
	ctx context.Context,
	parallelism Parallelism,
	fx Func[A, B],
	inputs <-chan A,
) <-chan *Maybe[B]

Map applies fx to the list of elements produced by a generator channel.

Arguments:

- ctx is the context;

- parallelism is the number of goroutines to use (we'll use a single goroutine if parallelism is < 1);

- fx is the function to apply;

- inputs receives arguments on which to apply fx. We expect this channel to be closed to signal EOF to the background workers.

The return value is the channel generating fx(a) for every a in inputs. This channel will also be closed to signal EOF to the consumer.

Deprecated: use Matrix instead.

func Matrix 

func Matrix[A, B any](ctx context.Context, N Parallelism, inputs []A, functions []Func[A, B]) <-chan *Maybe[B]

Matrix invokes each function on each input using N goroutines and streams the results to a channel.

func ParallelAsync deprecated 

func ParallelAsync[A, B any](
	ctx context.Context,
	parallelism Parallelism,
	input A,
	funcs <-chan Func[A, B],
) <-chan *Maybe[B]

ParallelAsync is like Parallel but deals with channels. We assume the input channel will be closed to signal EOF. We will close the output channel to signal EOF to the consumer.

Deprecated: use Matrix instead.

func StreamList 

func StreamList[T any](ts ...T) <-chan T

StreamList creates a channel out of static values. This function will close the channel when it has streamed all the available elements.

func Zip 

func Zip[T any](sources ...<-chan T) <-chan T

Zip zips together results from many channels under the assumption that each channel will be closed when it has streamed all elements.

func ZipAndCollect 

func ZipAndCollect[T any](sources ...<-chan T) []T

ZipAndCollect is syntactic sugar for Collect(Zip(sources...)).

Types

type AddressSet 

type AddressSet struct {
	// M is the map we use to represent the set.
	M map[string]bool
}

AddressSet is a set of IP addresses. The zero value struct is invalid, please initialize M or use NewAddressSet.

func NewAddressSet 

func NewAddressSet(dns ...*Maybe[*ResolvedAddresses]) *AddressSet

NewAddressSet creates a new address set from optional addresses resolved by DNS.

func (*AddressSet) Add 

func (as *AddressSet) Add(addrs ...string) *AddressSet

Add MUTATES the set to add a (possibly-new) address to the set and returns the same set to the caller allowing for chaining calls.

func (*AddressSet) RemoveBogons 

func (as *AddressSet) RemoveBogons() *AddressSet

RemoveBogons MUTATES the set to remove bogons from the set and returns the same set to the caller allowing for chaining calls.

func (*AddressSet) ToEndpoints deprecated 

func (as *AddressSet) ToEndpoints(
	network EndpointNetwork, port EndpointPort, options ...EndpointOption) (v []*Endpoint)

ToEndpoints transforms this set of IP addresses to a list of endpoints. We will combine each IP address with the network and the port to construct an endpoint and we will also apply any additional option to each endpoint.

Deprecated: use MakeEndpoint instead.

func (*AddressSet) Uniq 

func (as *AddressSet) Uniq() (uniq []string)

Uniq returns the unique addresses.

type DNSLookupOption 

type DNSLookupOption func(*DomainToResolve)

DNSLookupOption is an option you can pass to NewDomainToResolve.

func DNSLookupOptionTags 

func DNSLookupOptionTags(value ...string) DNSLookupOption

DNSLookupOptionTags allows to set tags to tag observations.

type DomainName 

type DomainName string

DomainName is a domain name to resolve.

type DomainToResolve 

type DomainToResolve struct {
	// Domain is the MANDATORY domain name to lookup.
	Domain string

	// Tags contains OPTIONAL tags to tag observations.
	Tags []string
}

DomainToResolve is the input for DNS lookup functions.

You should construct this type using the NewDomainToResolve constructor as well as DNSLookupOption options to fill optional values. If you want to construct this type manually, please make sure you initialize all the variables marked as MANDATORY.

func NewDomainToResolve 

func NewDomainToResolve(domain DomainName, options ...DNSLookupOption) *DomainToResolve

NewDomainToResolve creates input for performing DNS lookups. The only mandatory argument is the domain name to resolve. You can also supply optional values by passing options to this function.

type Endpoint 

type Endpoint struct {
	// Address is the MANDATORY endpoint address.
	Address string

	// Domain is the OPTIONAL domain used to resolve the endpoints' IP address.
	Domain string

	// Network is the MANDATORY endpoint network.
	Network string

	// Tags contains OPTIONAL tags for tagging observations.
	Tags []string
}

Endpoint is a network endpoint along with configuration for measuring it. You should construct from an AddressSet or using NewEndpoint. Otherwise, make sure you initialize all the fields marked as MANDATORY.

func NewEndpoint 

func NewEndpoint(
	network EndpointNetwork, address EndpointAddress, options ...EndpointOption) *Endpoint

NewEndpoint creates a new network endpoint (i.e., a three tuple composed of a network protocol, an IP address, and a port).

Arguments:

- network is either "tcp" or "udp";

- address is the NewEndpoint address represented as an IP address followed by ":" followed by a port. IPv6 addresses must be quoted (e.g., "[::1]:80");

- options contains additional options.

type EndpointAddress 

type EndpointAddress string

EndpointAddress is the endpoint address.

type EndpointNetwork 

type EndpointNetwork string

EndpointNetwork is the network of the endpoint

type EndpointOption 

type EndpointOption func(*Endpoint)

EndpointOption is an option you can use to construct EndpointState.

func EndpointOptionDomain 

func EndpointOptionDomain(value string) EndpointOption

EndpointOptionDomain allows to set the domain.

func EndpointOptionTags 

func EndpointOptionTags(value ...string) EndpointOption

EndpointOptionTags allows to set tags to tag observations.

type EndpointPort 

type EndpointPort uint16

EndpointPort is the port for an endpoint.

type Func 

type Func[A, B any] interface {
	Apply(ctx context.Context, a *Maybe[A]) *Maybe[B]
}

Func is a function f: (context.Context, A) -> B.

func Compose10 

func Compose10[
	T0 any,
	T1 any,
	T2 any,
	T3 any,
	T4 any,
	T5 any,
	T6 any,
	T7 any,
	T8 any,
	T9 any,
	T10 any,
](
	f0 Func[T0, T1],
	f1 Func[T1, T2],
	f2 Func[T2, T3],
	f3 Func[T3, T4],
	f4 Func[T4, T5],
	f5 Func[T5, T6],
	f6 Func[T6, T7],
	f7 Func[T7, T8],
	f8 Func[T8, T9],
	f9 Func[T9, T10],
) Func[T0, T10]

Compose10 composes N=10 functions.

func Compose11 

func Compose11[
	T0 any,
	T1 any,
	T2 any,
	T3 any,
	T4 any,
	T5 any,
	T6 any,
	T7 any,
	T8 any,
	T9 any,
	T10 any,
	T11 any,
](
	f0 Func[T0, T1],
	f1 Func[T1, T2],
	f2 Func[T2, T3],
	f3 Func[T3, T4],
	f4 Func[T4, T5],
	f5 Func[T5, T6],
	f6 Func[T6, T7],
	f7 Func[T7, T8],
	f8 Func[T8, T9],
	f9 Func[T9, T10],
	f10 Func[T10, T11],
) Func[T0, T11]

Compose11 composes N=11 functions.

func Compose12 

func Compose12[
	T0 any,
	T1 any,
	T2 any,
	T3 any,
	T4 any,
	T5 any,
	T6 any,
	T7 any,
	T8 any,
	T9 any,
	T10 any,
	T11 any,
	T12 any,
](
	f0 Func[T0, T1],
	f1 Func[T1, T2],
	f2 Func[T2, T3],
	f3 Func[T3, T4],
	f4 Func[T4, T5],
	f5 Func[T5, T6],
	f6 Func[T6, T7],
	f7 Func[T7, T8],
	f8 Func[T8, T9],
	f9 Func[T9, T10],
	f10 Func[T10, T11],
	f11 Func[T11, T12],
) Func[T0, T12]

Compose12 composes N=12 functions.

func Compose13 

func Compose13[
	T0 any,
	T1 any,
	T2 any,
	T3 any,
	T4 any,
	T5 any,
	T6 any,
	T7 any,
	T8 any,
	T9 any,
	T10 any,
	T11 any,
	T12 any,
	T13 any,
](
	f0 Func[T0, T1],
	f1 Func[T1, T2],
	f2 Func[T2, T3],
	f3 Func[T3, T4],
	f4 Func[T4, T5],
	f5 Func[T5, T6],
	f6 Func[T6, T7],
	f7 Func[T7, T8],
	f8 Func[T8, T9],
	f9 Func[T9, T10],
	f10 Func[T10, T11],
	f11 Func[T11, T12],
	f12 Func[T12, T13],
) Func[T0, T13]

Compose13 composes N=13 functions.

func Compose14 

func Compose14[
	T0 any,
	T1 any,
	T2 any,
	T3 any,
	T4 any,
	T5 any,
	T6 any,
	T7 any,
	T8 any,
	T9 any,
	T10 any,
	T11 any,
	T12 any,
	T13 any,
	T14 any,
](
	f0 Func[T0, T1],
	f1 Func[T1, T2],
	f2 Func[T2, T3],
	f3 Func[T3, T4],
	f4 Func[T4, T5],
	f5 Func[T5, T6],
	f6 Func[T6, T7],
	f7 Func[T7, T8],
	f8 Func[T8, T9],
	f9 Func[T9, T10],
	f10 Func[T10, T11],
	f11 Func[T11, T12],
	f12 Func[T12, T13],
	f13 Func[T13, T14],
) Func[T0, T14]

Compose14 composes N=14 functions.

func Compose2 

func Compose2[A, B, C any](f Func[A, B], g Func[B, C]) Func[A, C]

Compose2 composes two operations such as TCPConnect and TLSHandshake.

func Compose3 

func Compose3[
	T0 any,
	T1 any,
	T2 any,
	T3 any,
](
	f0 Func[T0, T1],
	f1 Func[T1, T2],
	f2 Func[T2, T3],
) Func[T0, T3]

Compose3 composes N=3 functions.

func Compose4 

func Compose4[
	T0 any,
	T1 any,
	T2 any,
	T3 any,
	T4 any,
](
	f0 Func[T0, T1],
	f1 Func[T1, T2],
	f2 Func[T2, T3],
	f3 Func[T3, T4],
) Func[T0, T4]

Compose4 composes N=4 functions.

func Compose5 

func Compose5[
	T0 any,
	T1 any,
	T2 any,
	T3 any,
	T4 any,
	T5 any,
](
	f0 Func[T0, T1],
	f1 Func[T1, T2],
	f2 Func[T2, T3],
	f3 Func[T3, T4],
	f4 Func[T4, T5],
) Func[T0, T5]

Compose5 composes N=5 functions.

func Compose6 

func Compose6[
	T0 any,
	T1 any,
	T2 any,
	T3 any,
	T4 any,
	T5 any,
	T6 any,
](
	f0 Func[T0, T1],
	f1 Func[T1, T2],
	f2 Func[T2, T3],
	f3 Func[T3, T4],
	f4 Func[T4, T5],
	f5 Func[T5, T6],
) Func[T0, T6]

Compose6 composes N=6 functions.

func Compose7 

func Compose7[
	T0 any,
	T1 any,
	T2 any,
	T3 any,
	T4 any,
	T5 any,
	T6 any,
	T7 any,
](
	f0 Func[T0, T1],
	f1 Func[T1, T2],
	f2 Func[T2, T3],
	f3 Func[T3, T4],
	f4 Func[T4, T5],
	f5 Func[T5, T6],
	f6 Func[T6, T7],
) Func[T0, T7]

Compose7 composes N=7 functions.

func Compose8 

func Compose8[
	T0 any,
	T1 any,
	T2 any,
	T3 any,
	T4 any,
	T5 any,
	T6 any,
	T7 any,
	T8 any,
](
	f0 Func[T0, T1],
	f1 Func[T1, T2],
	f2 Func[T2, T3],
	f3 Func[T3, T4],
	f4 Func[T4, T5],
	f5 Func[T5, T6],
	f6 Func[T6, T7],
	f7 Func[T7, T8],
) Func[T0, T8]

Compose8 composes N=8 functions.

func Compose9 

func Compose9[
	T0 any,
	T1 any,
	T2 any,
	T3 any,
	T4 any,
	T5 any,
	T6 any,
	T7 any,
	T8 any,
	T9 any,
](
	f0 Func[T0, T1],
	f1 Func[T1, T2],
	f2 Func[T2, T3],
	f3 Func[T3, T4],
	f4 Func[T4, T5],
	f5 Func[T5, T6],
	f6 Func[T6, T7],
	f7 Func[T7, T8],
	f8 Func[T8, T9],
) Func[T0, T9]

Compose9 composes N=9 functions.

func DNSLookupGetaddrinfo 

func DNSLookupGetaddrinfo(rt Runtime) Func[*DomainToResolve, *ResolvedAddresses]

DNSLookupGetaddrinfo returns a function that resolves a domain name to IP addresses using libc's getaddrinfo function.

func DNSLookupParallel 

func DNSLookupParallel(fxs ...Func[*DomainToResolve, *ResolvedAddresses]) Func[*DomainToResolve, *ResolvedAddresses]

DNSLookupParallel runs DNS lookups in parallel. On success, this function returns a unique list of IP addresses aggregated from all resolvers. On failure, this function returns ErrDNSLookupParallel. You can always obtain the individual errors by processing observations or by creating a per-DNS-resolver pipeline.

func DNSLookupUDP 

func DNSLookupUDP(rt Runtime, endpoint string) Func[*DomainToResolve, *ResolvedAddresses]

DNSLookupUDP returns a function that resolves a domain name to IP addresses using the given DNS-over-UDP resolver.

func Discard 

func Discard[T any]() Func[T, Void]

Discard transforms any type to Void.

func HTTPConnectionQUIC 

func HTTPConnectionQUIC(rt Runtime) Func[*QUICConnection, *HTTPConnection]

HTTPConnectionQUIC converts a QUIC connection into an HTTP connection.

func HTTPConnectionTCP 

func HTTPConnectionTCP(rt Runtime) Func[*TCPConnection, *HTTPConnection]

HTTPConnectionTCP converts a TCP connection into an HTTP connection.

func HTTPConnectionTLS 

func HTTPConnectionTLS(rt Runtime) Func[*TLSConnection, *HTTPConnection]

HTTPConnectionTLS converts a TLS connection into an HTTP connection.

func HTTPRequest 

func HTTPRequest(rt Runtime, options ...HTTPRequestOption) Func[*HTTPConnection, *HTTPResponse]

HTTPRequest issues an HTTP request using a transport and returns a response.

func HTTPRequestOverQUIC 

func HTTPRequestOverQUIC(rt Runtime, options ...HTTPRequestOption) Func[*QUICConnection, *HTTPResponse]

HTTPRequestOverQUIC returns a Func that issues HTTP requests over QUIC.

func HTTPRequestOverTCP 

func HTTPRequestOverTCP(rt Runtime, options ...HTTPRequestOption) Func[*TCPConnection, *HTTPResponse]

HTTPRequestOverTCP returns a Func that issues HTTP requests over TCP.

func HTTPRequestOverTLS 

func HTTPRequestOverTLS(rt Runtime, options ...HTTPRequestOption) Func[*TLSConnection, *HTTPResponse]

HTTPRequestOverTLS returns a Func that issues HTTP requests over TLS.

func MakeEndpoint 

func MakeEndpoint(network EndpointNetwork, port EndpointPort, options ...EndpointOption) Func[*ResolvedAddress, *Endpoint]

MakeEndpoint returns a Func that creates an *Endpoint given *ResolvedAddress.

func MeasureResolvedAddresses 

func MeasureResolvedAddresses(fxs ...Func[*ResolvedAddress, Void]) Func[*ResolvedAddresses, Void]

MeasureResolvedAddresses returns a Func that measures the resolved addresses provided as the input argument using each of the provided functions.

func QUICHandshake 

func QUICHandshake(rt Runtime, options ...TLSHandshakeOption) Func[*Endpoint, *QUICConnection]

QUICHandshake returns a function performing QUIC handshakes.

func TCPConnect 

func TCPConnect(rt Runtime) Func[*Endpoint, *TCPConnection]

TCPConnect returns a function that establishes TCP connections.

func TLSHandshake 

func TLSHandshake(rt Runtime, options ...TLSHandshakeOption) Func[*TCPConnection, *TLSConnection]

TLSHandshake returns a function performing TSL handshakes.

type FuncAdapter 

type FuncAdapter[A, B any] func(ctx context.Context, a *Maybe[A]) *Maybe[B]

FuncAdapter adapts a func to be a Func.

func (FuncAdapter[A, B]) Apply 

func (fa FuncAdapter[A, B]) Apply(ctx context.Context, a *Maybe[A]) *Maybe[B]

Apply implements Func.

type HTTPConnection 

type HTTPConnection struct {
	// Address is the MANDATORY address we're connected to.
	Address string

	// Domain is the OPTIONAL domain from which the address was resolved.
	Domain string

	// Network is the MANDATORY network used by the underlying conn.
	Network string

	// Scheme is the MANDATORY URL scheme to use.
	Scheme string

	// TLSNegotiatedProtocol is the OPTIONAL negotiated protocol.
	TLSNegotiatedProtocol string

	// Trace is the MANDATORY trace we're using.
	Trace Trace

	// Transport is the MANDATORY HTTP transport we're using.
	Transport model.HTTPTransport
}

HTTPConnection is an HTTP connection bound to a TCP, TLS or QUIC connection that would use such a connection only and for any input URL. You generally use [HTTPTransportTCP], [HTTPTransportTLS] or [HTTPTransportQUIC] to create a new instance; if you want to initialize manually, make sure you init the fields marked as MANDATORY.

type HTTPRequestOption 

type HTTPRequestOption func(req *http.Request)

HTTPRequestOption is an option you can pass to HTTPRequest.

func HTTPRequestOptionAccept 

func HTTPRequestOptionAccept(value string) HTTPRequestOption

HTTPRequestOptionAccept sets the Accept header.

func HTTPRequestOptionAcceptLanguage 

func HTTPRequestOptionAcceptLanguage(value string) HTTPRequestOption

HTTPRequestOptionAcceptLanguage sets the Accept header.

func HTTPRequestOptionHost 

func HTTPRequestOptionHost(value string) HTTPRequestOption

HTTPRequestOptionHost sets the Host header.

func HTTPRequestOptionMethod 

func HTTPRequestOptionMethod(value string) HTTPRequestOption

HTTPRequestOptionHost sets the request method.

func HTTPRequestOptionReferer 

func HTTPRequestOptionReferer(value string) HTTPRequestOption

HTTPRequestOptionReferer sets the Referer header.

func HTTPRequestOptionURLPath 

func HTTPRequestOptionURLPath(value string) HTTPRequestOption

HTTPRequestOptionURLPath sets the URL path.

func HTTPRequestOptionUserAgent 

func HTTPRequestOptionUserAgent(value string) HTTPRequestOption

HTTPRequestOptionUserAgent sets the UserAgent header.

type HTTPResponse 

type HTTPResponse struct {
	// Address is the MANDATORY address we're connected to.
	Address string

	// Domain is the OPTIONAL domain from which we determined Address.
	Domain string

	// HTTPRequest is the possibly-nil HTTP request.
	HTTPRequest *http.Request

	// HTTPResponse is the HTTP response or nil if Err != nil.
	HTTPResponse *http.Response

	// HTTPResponseBodySnapshot is the response body or nil if Err != nil.
	HTTPResponseBodySnapshot []byte

	// Network is the MANDATORY network we're connected to.
	Network string

	// Trace is the MANDATORY trace we're using. The trace is drained
	// when you call the Observations method.
	Trace Trace
}

HTTPResponse is the response generated by an HTTP requests. Generally obtained by HTTPRequest().Apply. To init manually, init at least MANDATORY fields.

type Maybe 

type Maybe[State any] struct {
	// Error is either the error that occurred or nil.
	Error error

	// State contains state passed between function calls. You should
	// only access State when Error is nil and Skipped is false.
	State State
}

Maybe is the result of an operation implemented by this package that may fail such as TCPConnect or TLSHandshake.

func NewMaybeWithError 

func NewMaybeWithError[State any](err error) *Maybe[State]

NewMaybeWithError constructs a Maybe containing the given error.

func NewMaybeWithValue 

func NewMaybeWithValue[State any](value State) *Maybe[State]

NewMaybeWithValue constructs a Maybe containing the given value.

func Parallel deprecated 

func Parallel[A, B any](
	ctx context.Context,
	parallelism Parallelism,
	input A,
	fn ...Func[A, B],
) []*Maybe[B]

Parallel executes f1...fn in parallel over the same input.

Arguments:

- ctx is the context;

- parallelism is the number of goroutines to use (we'll use a single goroutine if parallelism is < 1);

- input is the input;

- fn is the list of functions.

The return value is the list [fx(a)] for every fx in fn.

Deprecated: use Matrix instead.

type MinimalRuntime 

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

MinimalRuntime is a minimal Runtime implementation.

func NewMinimalRuntime 

func NewMinimalRuntime(logger model.Logger, zeroTime time.Time, options ...MinimalRuntimeOption) *MinimalRuntime

NewMinimalRuntime creates a minimal Runtime implementation.

This Runtime implementation does not collect any *Observations.

func (*MinimalRuntime) Close 

func (p *MinimalRuntime) Close() error

Close implements Runtime.

func (*MinimalRuntime) IDGenerator 

func (p *MinimalRuntime) IDGenerator() *atomic.Int64

IDGenerator implements Runtime.

func (*MinimalRuntime) Logger 

func (p *MinimalRuntime) Logger() model.Logger

Logger implements Runtime.

func (*MinimalRuntime) MaybeTrackConn 

func (p *MinimalRuntime) MaybeTrackConn(conn io.Closer)

MaybeTrackConn implements Runtime.

func (*MinimalRuntime) NewTrace 

func (p *MinimalRuntime) NewTrace(index int64, zeroTime time.Time, tags ...string) Trace

NewTrace implements Runtime.

func (*MinimalRuntime) Observations 

func (p *MinimalRuntime) Observations() *Observations

Observations implements Runtime.

func (*MinimalRuntime) SaveObservations 

func (p *MinimalRuntime) SaveObservations(obs ...*Observations)

SaveObservations implements Runtime.

func (*MinimalRuntime) ZeroTime 

func (p *MinimalRuntime) ZeroTime() time.Time

ZeroTime implements Runtime.

type MinimalRuntimeOption 

type MinimalRuntimeOption func(rt *MinimalRuntime)

MinimalRuntimeOption is an option for configuring the *MinimalRuntime.

func MinimalRuntimeOptionMeasuringNetwork 

func MinimalRuntimeOptionMeasuringNetwork(netx model.MeasuringNetwork) MinimalRuntimeOption

MinimalRuntimeOptionMeasuringNetwork configures the model.MeasuringNetwork to use.

type Observations 

type Observations struct {
	// NetworkEvents contains I/O events.
	NetworkEvents []*model.ArchivalNetworkEvent `json:"network_events"`

	// Queries contains the DNS queries results.
	Queries []*model.ArchivalDNSLookupResult `json:"queries"`

	// Requests contains HTTP request results.
	Requests []*model.ArchivalHTTPRequestResult `json:"requests"`

	// TCPConnect contains the TCP connect results.
	TCPConnect []*model.ArchivalTCPConnectResult `json:"tcp_connect"`

	// TLSHandshakes contains the TLS handshakes results.
	TLSHandshakes []*model.ArchivalTLSOrQUICHandshakeResult `json:"tls_handshakes"`

	// QUICHandshakes contains the QUIC handshakes results.
	QUICHandshakes []*model.ArchivalTLSOrQUICHandshakeResult `json:"quic_handshakes"`
}

Observations is the skeleton shared by most OONI measurements where we group observations by type using standard test keys.

func NewObservations 

func NewObservations() *Observations

NewObservations initializes all measurements to empty arrays and returns the Observations skeleton.

type Operation 

type Operation[A, B any] func(ctx context.Context, a A) (B, error)

Operation adapts a golang function to behave like a Func.

func (Operation[A, B]) Apply 

func (op Operation[A, B]) Apply(ctx context.Context, a *Maybe[A]) *Maybe[B]

Apply implements Func.

type Parallelism 

type Parallelism int

Parallelism is the type used to specify parallelism.

type QUICConnection 

type QUICConnection struct {
	// Address is the MANDATORY address we tried to connect to.
	Address string

	// QUICConn is the established QUIC conn.
	QUICConn quic.EarlyConnection

	// Domain is the OPTIONAL domain we resolved.
	Domain string

	// Network is the MANDATORY network we tried to use when connecting.
	Network string

	// TLSConfig is the config we used to establish a QUIC connection and will
	// be needed when constructing an HTTP/3 transport.
	TLSConfig *tls.Config

	// TLSState is the possibly-empty TLS connection state.
	TLSState tls.ConnectionState

	// Trace is the MANDATORY trace we're using.
	Trace Trace
}

QUICConnection is an established QUIC connection. If you initialize manually, init at least the ones marked as MANDATORY.

type ResolvedAddress 

type ResolvedAddress struct {
	// Address is the address that was resolved.
	Address string

	// Domain is the domain from which we resolved the address.
	Domain string
}

ResolvedAddress is a single address resolved using a DNS lookup function.

type ResolvedAddresses 

type ResolvedAddresses struct {
	// Addresses contains the nonempty resolved addresses.
	Addresses []string

	// Domain is the domain we resolved. We inherit this field
	// from the value inside the DomainToResolve.
	Domain string
}

ResolvedAddresses contains the results of DNS lookups. To initialize this struct manually, follow specific instructions for each field.

func (*ResolvedAddresses) Flatten 

func (ra *ResolvedAddresses) Flatten() (out []*ResolvedAddress)

Flatten transforms a ResolvedAddresses into a slice of zero or more ResolvedAddress.

type Runtime 

type Runtime interface {
	// Close closes all the connection tracked using MaybeTrackConn.
	Close() error

	// IDGenerator returns an atomic counter used to generate
	// separate unique IDs for each trace.
	IDGenerator() *atomic.Int64

	// Logger returns the base logger to use.
	Logger() model.Logger

	// MaybeTrackConn tracks a connection such that it is closed
	// when you call the Runtime's Close method.
	MaybeTrackConn(conn io.Closer)

	// NewTrace creates a [Trace] instance. Note that each [Runtime]
	// creates its own [Trace] type. A [Trace] is not guaranteed to collect
	// [*Observations]. For example, [NewMinimalRuntime] creates a [Runtime]
	// that does not collect any [*Observations].
	NewTrace(index int64, zeroTime time.Time, tags ...string) Trace

	// Observations returns the [*Observations] saved so far and clears our
	// internal copy such that the next call to this method only returns
	// the [*Observations] saved since the previous call.
	//
	// You can safely call this method from multiple goroutine contexts.
	Observations() *Observations

	// SaveObservations saves [*Observations] inside the [Runtime]. You can
	// get the saved [*Observations] by calling Observations.
	//
	// You can safely call this method from multiple goroutine contexts.
	SaveObservations(obs ...*Observations)

	// ZeroTime returns the runtime's "zero" time, which is used as the
	// starting point to generate observation's delta times.
	ZeroTime() time.Time
}

Runtime is the runtime in which we execute the DSL.

type RuntimeMeasurexLite 

type RuntimeMeasurexLite struct {
	*MinimalRuntime
	// contains filtered or unexported fields
}

RuntimeMeasurexLite uses measurexlite to collect [*Observations.]

func NewRuntimeMeasurexLite 

func NewRuntimeMeasurexLite(logger model.Logger, zeroTime time.Time, options ...RuntimeMeasurexLiteOption) *RuntimeMeasurexLite

NewRuntimeMeasurexLite creates a Runtime using measurexlite to collect *Observations.

func (*RuntimeMeasurexLite) NewTrace 

func (p *RuntimeMeasurexLite) NewTrace(index int64, zeroTime time.Time, tags ...string) Trace

NewTrace implements Runtime.

type RuntimeMeasurexLiteOption 

type RuntimeMeasurexLiteOption func(rt *RuntimeMeasurexLite)

RuntimeMeasurexLiteOption is an option for initializing a *RuntimeMeasurexLite.

func RuntimeMeasurexLiteOptionMeasuringNetwork 

func RuntimeMeasurexLiteOptionMeasuringNetwork(netx model.MeasuringNetwork) RuntimeMeasurexLiteOption

RuntimeMeasurexLiteOptionMeasuringNetwork allows to configure which model.MeasuringNetwork to use.

type Stats 

type Stats[T any] struct {
	// contains filtered or unexported fields
}

Stats measures the number of successes and failures.

The zero value is invalid; use NewStats.

func NewStats 

func NewStats[T any]() *Stats[T]

NewStats creates a *Stats instance.

func (*Stats[T]) Export 

func (s *Stats[T]) Export() (out map[string]int64)

Export exports the current stats without clearing the internally used map such that statistics accumulate over time and never reset for the *Stats lifecycle.

func (*Stats[T]) Observer 

func (s *Stats[T]) Observer() Func[T, T]

Observer returns a Func that observes the results of the previous pipeline stage. This function converts any error that it sees to ErrSkip. This function does not account for ErrSkip, meaning that you will never see ErrSkip in the stats returned by Stats.Export.

type TCPConnection 

type TCPConnection struct {
	// Address is the MANDATORY address we tried to connect to.
	Address string

	// Conn is the established connection.
	Conn net.Conn

	// Domain is the OPTIONAL domain from which we resolved the Address.
	Domain string

	// Network is the MANDATORY network we tried to use when connecting.
	Network string

	// Trace is the MANDATORY trace we're using.
	Trace Trace
}

TCPConnection is an established TCP connection. If you initialize manually, init at least the ones marked as MANDATORY.

type TLSConnection 

type TLSConnection struct {
	// Address is the MANDATORY address we tried to connect to.
	Address string

	// Conn is the established TLS conn.
	Conn netxlite.TLSConn

	// Domain is the OPTIONAL domain we resolved.
	Domain string

	// Network is the MANDATORY network we tried to use when connecting.
	Network string

	// TLSState is the possibly-empty TLS connection state.
	TLSState tls.ConnectionState

	// Trace is the MANDATORY trace we're using.
	Trace Trace
}

TLSConnection is an established TLS connection. If you initialize manually, init at least the ones marked as MANDATORY.

type TLSHandshakeOption 

type TLSHandshakeOption func(config *tls.Config)

TLSHandshakeOption is an option you can pass to TLSHandshake.

func TLSHandshakeOptionInsecureSkipVerify 

func TLSHandshakeOptionInsecureSkipVerify(value bool) TLSHandshakeOption

TLSHandshakeOptionInsecureSkipVerify controls whether TLS verification is enabled.

func TLSHandshakeOptionNextProto 

func TLSHandshakeOptionNextProto(value []string) TLSHandshakeOption

TLSHandshakeOptionNextProto allows to configure the ALPN protocols.

func TLSHandshakeOptionRootCAs 

func TLSHandshakeOptionRootCAs(value *x509.CertPool) TLSHandshakeOption

TLSHandshakeOptionRootCAs allows to configure custom root CAs.

func TLSHandshakeOptionServerName 

func TLSHandshakeOptionServerName(value string) TLSHandshakeOption

TLSHandshakeOptionServerName allows to configure the SNI to use.

type Trace 

type Trace interface {
	// CloneBytesReceivedMap returns a clone of the internal bytes received map. The key of the
	// map is a string following the "EPNT_ADDRESS PROTO" pattern where the "EPNT_ADDRESS" contains
	// the endpoint address and "PROTO" is "tcp" or "udp".
	CloneBytesReceivedMap() (out map[string]int64)

	// DNSLookupsFromRoundTrip returns all the DNS lookup results collected so far.
	DNSLookupsFromRoundTrip() (out []*model.ArchivalDNSLookupResult)

	// Index returns the unique index used by this trace.
	Index() int64

	// NewDialerWithoutResolver is equivalent to netxlite.Netx.NewDialerWithoutResolver
	// except that it returns a model.Dialer that uses this trace.
	//
	// Caveat: the dialer wrappers are there to implement the
	// model.MeasuringNetwork interface, but they're not used by this function.
	NewDialerWithoutResolver(dl model.DebugLogger, wrappers ...model.DialerWrapper) model.Dialer

	// NewParallelUDPResolver returns a possibly-trace-ware parallel UDP resolver
	NewParallelUDPResolver(logger model.DebugLogger, dialer model.Dialer, address string) model.Resolver

	// NewQUICDialerWithoutResolver is equivalent to
	// netxlite.Netx.NewQUICDialerWithoutResolver except that it returns a
	// model.QUICDialer that uses this trace.
	//
	// Caveat: the dialer wrappers are there to implement the
	// model.MeasuringNetwork interface, but they're not used by this function.
	NewQUICDialerWithoutResolver(listener model.UDPListener,
		dl model.DebugLogger, wrappers ...model.QUICDialerWrapper) model.QUICDialer

	// NewTLSHandshakerStdlib is equivalent to netxlite.Netx.NewTLSHandshakerStdlib
	// except that it returns a model.TLSHandshaker that uses this trace.
	NewTLSHandshakerStdlib(dl model.DebugLogger) model.TLSHandshaker

	// NetworkEvents returns all the network events collected so far.
	NetworkEvents() (out []*model.ArchivalNetworkEvent)

	// NewStdlibResolver returns a possibly-trace-ware system resolver.
	NewStdlibResolver(logger model.DebugLogger) model.Resolver

	// NewUDPListener implements model.MeasuringNetwork.
	NewUDPListener() model.UDPListener

	// QUICHandshakes collects all the QUIC handshake results collected so far.
	QUICHandshakes() (out []*model.ArchivalTLSOrQUICHandshakeResult)

	// TCPConnects collects all the TCP connect results collected so far.
	TCPConnects() (out []*model.ArchivalTCPConnectResult)

	// TLSHandshakes collects all the TLS handshake results collected so far.
	TLSHandshakes() (out []*model.ArchivalTLSOrQUICHandshakeResult)

	// Tags returns the trace tags.
	Tags() []string

	// TimeSince is equivalent to Trace.TimeNow().Sub(t0).
	TimeSince(t0 time.Time) time.Duration

	// ZeroTime returns the "zero" time of this trace.
	ZeroTime() time.Time
}

Trace collects *Observations using tracing. Specific implementations of this interface may be engineered to collect no *Observations for efficiency (i.e., when you don't care about collecting *Observations but you still want to use this package).

type Void 

type Void struct{}

Void is the empty data structure.

Source Files

View all Source files

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.