dslx

package
v0.25.0 Latest Latest
Warning

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

 Go to latest Published: Jun 8, 2023 License: GPL-3.0 Imports: 16 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

This section is empty.

Functions

func ApplyAsync 

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

ApplyAsync is equivalent to calling Apply but returns a channel.

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 FirstError 

func FirstError[T any](entries ...*Maybe[T]) (string, error)

FirstError returns the first error and failed operation in a list of *Maybe[T].

func FirstErrorExcludingBrokenIPv6Errors 

func FirstErrorExcludingBrokenIPv6Errors[T any](entries ...*Maybe[T]) (string, error)

FirstErrorExcludingBrokenIPv6Errors returns the first error and failed operation in a list of *Maybe[T] excluding errors known to be linked with IPv6 issues.

func Map 

func Map[A, B any](
	ctx context.Context,
	parallelism Parallelism,
	fx Func[A, *Maybe[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.

func ParallelAsync 

func ParallelAsync[A, B any](
	ctx context.Context,
	parallelism Parallelism,
	input A,
	funcs <-chan Func[A, *Maybe[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.

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 

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.

type ConnPool 

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

ConnPool tracks established connections. The zero value of this struct is ready to use.

func (*ConnPool) Close 

func (p *ConnPool) Close() error

Close closes all the tracked connections in reverse order. This method is safe for use by multiple goroutines.

func (*ConnPool) MaybeTrack 

func (p *ConnPool) MaybeTrack(c io.Closer)

MaybeTrack tracks the given connection if not nil. This method is safe for use by multiple goroutines.

type Counter 

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

Counter allows to count how many times a Func[T, *Maybe[T]] is invoked.

func NewCounter 

func NewCounter[T any]() *Counter[T]

NewCounter generates an instance of *Counter

func (*Counter[T]) Func 

func (c *Counter[T]) Func() Func[T, *Maybe[T]]

Func returns a Func[T, *Maybe[T]] that updates the counter.

func (*Counter[T]) Value 

func (c *Counter[T]) Value() int64

Value returns the counter's value.

type DNSLookupOption 

type DNSLookupOption func(*DomainToResolve)

DNSLookupOption is an option you can pass to NewDomainToResolve.

func DNSLookupOptionIDGenerator 

func DNSLookupOptionIDGenerator(value *atomic.Int64) DNSLookupOption

DNSLookupOptionIDGenerator configures a specific ID generator. See DomainToResolve docs for more information.

func DNSLookupOptionLogger 

func DNSLookupOptionLogger(value model.Logger) DNSLookupOption

DNSLookupOptionLogger configures a specific logger. See DomainToResolve docs for more information.

func DNSLookupOptionTags 

func DNSLookupOptionTags(value ...string) DNSLookupOption

DNSLookupOptionTags allows to set tags to tag observations.

func DNSLookupOptionZeroTime 

func DNSLookupOptionZeroTime(value time.Time) DNSLookupOption

DNSLookupOptionZeroTime configures the measurement's zero time. See DomainToResolve docs for more information.

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

	// IDGenerator is the MANDATORY ID generator. We will use this field
	// to assign unique IDs to distinct sub-measurements. The default
	// construction implemented by NewDomainToResolve creates a new generator
	// that starts counting from zero, leading to the first trace having
	// one as its index.
	IDGenerator *atomic.Int64

	// Logger is the MANDATORY logger to use. The default construction
	// implemented by NewDomainToResolve uses model.DiscardLogger.
	Logger model.Logger

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

	// ZeroTime is the MANDATORY zero time of the measurement. We will
	// use this field as the zero value to compute relative elapsed times
	// when generating measurements. The default construction by
	// NewDomainToResolve initializes this field with the current time.
	ZeroTime time.Time
}

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

	// IDGenerator is MANDATORY the ID generator to use.
	IDGenerator *atomic.Int64

	// Logger is the MANDATORY logger to use.
	Logger model.Logger

	// Network is the MANDATORY endpoint network.
	Network string

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

	// ZeroTime is the MANDATORY zero time of the measurement.
	ZeroTime time.Time
}

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 EndpointOptionIDGenerator 

func EndpointOptionIDGenerator(value *atomic.Int64) EndpointOption

EndpointOptionIDGenerator allows to set the ID generator.

func EndpointOptionLogger 

func EndpointOptionLogger(value model.Logger) EndpointOption

EndpointOptionLogger allows to set the logger.

func EndpointOptionTags 

func EndpointOptionTags(value ...string) EndpointOption

EndpointOptionTags allows to set tags to tag observations.

func EndpointOptionZeroTime 

func EndpointOptionZeroTime(value time.Time) EndpointOption

EndpointOptionZeroTime allows to set the zero time.

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 A) 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, *Maybe[T1]],
	f1 Func[T1, *Maybe[T2]],
	f2 Func[T2, *Maybe[T3]],
	f3 Func[T3, *Maybe[T4]],
	f4 Func[T4, *Maybe[T5]],
	f5 Func[T5, *Maybe[T6]],
	f6 Func[T6, *Maybe[T7]],
	f7 Func[T7, *Maybe[T8]],
	f8 Func[T8, *Maybe[T9]],
	f9 Func[T9, *Maybe[T10]],
) Func[T0, *Maybe[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, *Maybe[T1]],
	f1 Func[T1, *Maybe[T2]],
	f2 Func[T2, *Maybe[T3]],
	f3 Func[T3, *Maybe[T4]],
	f4 Func[T4, *Maybe[T5]],
	f5 Func[T5, *Maybe[T6]],
	f6 Func[T6, *Maybe[T7]],
	f7 Func[T7, *Maybe[T8]],
	f8 Func[T8, *Maybe[T9]],
	f9 Func[T9, *Maybe[T10]],
	f10 Func[T10, *Maybe[T11]],
) Func[T0, *Maybe[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, *Maybe[T1]],
	f1 Func[T1, *Maybe[T2]],
	f2 Func[T2, *Maybe[T3]],
	f3 Func[T3, *Maybe[T4]],
	f4 Func[T4, *Maybe[T5]],
	f5 Func[T5, *Maybe[T6]],
	f6 Func[T6, *Maybe[T7]],
	f7 Func[T7, *Maybe[T8]],
	f8 Func[T8, *Maybe[T9]],
	f9 Func[T9, *Maybe[T10]],
	f10 Func[T10, *Maybe[T11]],
	f11 Func[T11, *Maybe[T12]],
) Func[T0, *Maybe[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, *Maybe[T1]],
	f1 Func[T1, *Maybe[T2]],
	f2 Func[T2, *Maybe[T3]],
	f3 Func[T3, *Maybe[T4]],
	f4 Func[T4, *Maybe[T5]],
	f5 Func[T5, *Maybe[T6]],
	f6 Func[T6, *Maybe[T7]],
	f7 Func[T7, *Maybe[T8]],
	f8 Func[T8, *Maybe[T9]],
	f9 Func[T9, *Maybe[T10]],
	f10 Func[T10, *Maybe[T11]],
	f11 Func[T11, *Maybe[T12]],
	f12 Func[T12, *Maybe[T13]],
) Func[T0, *Maybe[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, *Maybe[T1]],
	f1 Func[T1, *Maybe[T2]],
	f2 Func[T2, *Maybe[T3]],
	f3 Func[T3, *Maybe[T4]],
	f4 Func[T4, *Maybe[T5]],
	f5 Func[T5, *Maybe[T6]],
	f6 Func[T6, *Maybe[T7]],
	f7 Func[T7, *Maybe[T8]],
	f8 Func[T8, *Maybe[T9]],
	f9 Func[T9, *Maybe[T10]],
	f10 Func[T10, *Maybe[T11]],
	f11 Func[T11, *Maybe[T12]],
	f12 Func[T12, *Maybe[T13]],
	f13 Func[T13, *Maybe[T14]],
) Func[T0, *Maybe[T14]]

Compose14 composes N=14 functions.

func Compose2 

func Compose2[A, B, C any](f Func[A, *Maybe[B]], g Func[B, *Maybe[C]]) Func[A, *Maybe[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, *Maybe[T1]],
	f1 Func[T1, *Maybe[T2]],
	f2 Func[T2, *Maybe[T3]],
) Func[T0, *Maybe[T3]]

Compose3 composes N=3 functions.

func Compose4 

func Compose4[
	T0 any,
	T1 any,
	T2 any,
	T3 any,
	T4 any,
](
	f0 Func[T0, *Maybe[T1]],
	f1 Func[T1, *Maybe[T2]],
	f2 Func[T2, *Maybe[T3]],
	f3 Func[T3, *Maybe[T4]],
) Func[T0, *Maybe[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, *Maybe[T1]],
	f1 Func[T1, *Maybe[T2]],
	f2 Func[T2, *Maybe[T3]],
	f3 Func[T3, *Maybe[T4]],
	f4 Func[T4, *Maybe[T5]],
) Func[T0, *Maybe[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, *Maybe[T1]],
	f1 Func[T1, *Maybe[T2]],
	f2 Func[T2, *Maybe[T3]],
	f3 Func[T3, *Maybe[T4]],
	f4 Func[T4, *Maybe[T5]],
	f5 Func[T5, *Maybe[T6]],
) Func[T0, *Maybe[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, *Maybe[T1]],
	f1 Func[T1, *Maybe[T2]],
	f2 Func[T2, *Maybe[T3]],
	f3 Func[T3, *Maybe[T4]],
	f4 Func[T4, *Maybe[T5]],
	f5 Func[T5, *Maybe[T6]],
	f6 Func[T6, *Maybe[T7]],
) Func[T0, *Maybe[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, *Maybe[T1]],
	f1 Func[T1, *Maybe[T2]],
	f2 Func[T2, *Maybe[T3]],
	f3 Func[T3, *Maybe[T4]],
	f4 Func[T4, *Maybe[T5]],
	f5 Func[T5, *Maybe[T6]],
	f6 Func[T6, *Maybe[T7]],
	f7 Func[T7, *Maybe[T8]],
) Func[T0, *Maybe[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, *Maybe[T1]],
	f1 Func[T1, *Maybe[T2]],
	f2 Func[T2, *Maybe[T3]],
	f3 Func[T3, *Maybe[T4]],
	f4 Func[T4, *Maybe[T5]],
	f5 Func[T5, *Maybe[T6]],
	f6 Func[T6, *Maybe[T7]],
	f7 Func[T7, *Maybe[T8]],
	f8 Func[T8, *Maybe[T9]],
) Func[T0, *Maybe[T9]]

Compose9 composes N=9 functions.

func DNSLookupGetaddrinfo 

func DNSLookupGetaddrinfo() Func[*DomainToResolve, *Maybe[*ResolvedAddresses]]

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

func DNSLookupUDP 

func DNSLookupUDP(resolver string) Func[*DomainToResolve, *Maybe[*ResolvedAddresses]]

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

func HTTPRequest 

func HTTPRequest(options ...HTTPRequestOption) Func[*HTTPTransport, *Maybe[*HTTPResponse]]

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

func HTTPRequestOverQUIC 

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

HTTPRequestOverQUIC returns a Func that issues HTTP requests over QUIC.

func HTTPRequestOverTCP 

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

HTTPRequestOverTCP returns a Func that issues HTTP requests over TCP.

func HTTPRequestOverTLS 

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

HTTPRequestOverTLS returns a Func that issues HTTP requests over TLS.

func HTTPTransportQUIC 

func HTTPTransportQUIC() Func[*QUICConnection, *Maybe[*HTTPTransport]]

HTTPTransportQUIC converts a QUIC connection into an HTTP transport.

func HTTPTransportTCP 

func HTTPTransportTCP() Func[*TCPConnection, *Maybe[*HTTPTransport]]

HTTPTransportTCP converts a TCP connection into an HTTP transport.

func HTTPTransportTLS 

func HTTPTransportTLS() Func[*TLSConnection, *Maybe[*HTTPTransport]]

HTTPTransportTLS converts a TLS connection into an HTTP transport.

func QUICHandshake 

func QUICHandshake(pool *ConnPool, options ...QUICHandshakeOption) Func[
	*Endpoint, *Maybe[*QUICConnection]]

QUICHandshake returns a function performing QUIC handshakes.

func TCPConnect 

func TCPConnect(pool *ConnPool) Func[*Endpoint, *Maybe[*TCPConnection]]

TCPConnect returns a function that establishes TCP connections.

func TLSHandshake 

func TLSHandshake(pool *ConnPool, options ...TLSHandshakeOption) Func[
	*TCPConnection, *Maybe[*TLSConnection]]

TLSHandshake returns a function performing TSL handshakes.

type HTTPRequestOption 

type HTTPRequestOption func(*httpRequestFunc)

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

	// IDGenerator is the MANDATORY ID generator.
	IDGenerator *atomic.Int64

	// Logger is the MANDATORY logger to use.
	Logger model.Logger

	// 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 *measurexlite.Trace

	// ZeroTime is the MANDATORY zero time of the measurement.
	ZeroTime time.Time
}

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

type HTTPTransport 

type HTTPTransport 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

	// IDGenerator is the MANDATORY ID generator.
	IDGenerator *atomic.Int64

	// Logger is the MANDATORY logger to use.
	Logger model.Logger

	// 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 *measurexlite.Trace

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

	// ZeroTime is the MANDATORY zero time of the measurement.
	ZeroTime time.Time
}

HTTPTransport is an HTTP transport 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 Maybe 

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

	// Observations contains the collected observations.
	Observations []*Observations

	// Operation contains the name of this operation.
	Operation string

	// 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 Parallel 

func Parallel[A, B any](
	ctx context.Context,
	parallelism Parallelism,
	input A,
	fn ...Func[A, *Maybe[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.

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 ExtractObservations 

func ExtractObservations[T any](rs ...*Maybe[T]) (out []*Observations)

ExtractObservations extracts observations from a list of Maybe.

func NewObservations 

func NewObservations() *Observations

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

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

	// IDGenerator is the MANDATORY ID generator to use.
	IDGenerator *atomic.Int64

	// Logger is the MANDATORY logger to use.
	Logger model.Logger

	// 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 *measurexlite.Trace

	// ZeroTime is the MANDATORY zero time of the measurement.
	ZeroTime time.Time
}

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

type QUICHandshakeOption 

type QUICHandshakeOption func(*quicHandshakeFunc)

QUICHandshakeOption is an option you can pass to QUICHandshake.

func QUICHandshakeOptionInsecureSkipVerify 

func QUICHandshakeOptionInsecureSkipVerify(value bool) QUICHandshakeOption

QUICHandshakeOptionInsecureSkipVerify controls whether QUIC verification is enabled.

func QUICHandshakeOptionRootCAs 

func QUICHandshakeOptionRootCAs(value *x509.CertPool) QUICHandshakeOption

QUICHandshakeOptionRootCAs allows to configure custom root CAs.

func QUICHandshakeOptionServerName 

func QUICHandshakeOptionServerName(value string) QUICHandshakeOption

QUICHandshakeOptionServerName allows to configure the SNI to use.

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

	// IDGenerator is the ID generator. We inherit this field
	// from the value inside the DomainToResolve.
	IDGenerator *atomic.Int64

	// Logger is the logger to use. We inherit this field
	// from the value inside the DomainToResolve.
	Logger model.Logger

	// Trace is the trace we're currently using. This struct is
	// created by the various Apply functions using values inside
	// the DomainToResolve to initialize the Trace.
	Trace *measurexlite.Trace

	// ZeroTime is the zero time of the measurement. We inherit this field
	// from the value inside the DomainToResolve.
	ZeroTime time.Time
}

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

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

	// IDGenerator is the MANDATORY ID generator.
	IDGenerator *atomic.Int64

	// Logger is the MANDATORY logger to use.
	Logger model.Logger

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

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

	// ZeroTime is the MANDATORY zero time of the measurement.
	ZeroTime time.Time
}

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

	// IDGenerator is the MANDATORY ID generator to use.
	IDGenerator *atomic.Int64

	// Logger is the MANDATORY logger to use.
	Logger model.Logger

	// 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 *measurexlite.Trace

	// ZeroTime is the MANDATORY zero time of the measurement.
	ZeroTime time.Time
}

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

type TLSHandshakeOption 

type TLSHandshakeOption func(*tlsHandshakeFunc)

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.

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.