tracex

package
v3.24.0 Latest Latest
Warning

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

 Go to latest Published: Nov 25, 2024 License: GPL-3.0 Imports: 17 Imported by: 0

Documentation

Overview

Package tracex performs measurements using tracing. To use tracing means that we'll wrap netx data types (e.g., a Dialer) with equivalent data types saving events into a Saver data struture. Then we will use the data types normally (e.g., call the Dialer's DialContet method and then use the resulting connection). When done, we will extract the trace containing all the events that occurred from the saver and process it to determine what happened during the measurement itself.

This package is now frozen. Please, use measurexlite for new code. See https://github.com/ooni/probe-cli/blob/master/docs/design/dd-003-step-by-step.md for details about this.

Index

Constants

This section is empty.

Variables

View Source 
var (
	ExtDNS          = model.ArchivalExtDNS
	ExtNetevents    = model.ArchivalExtNetevents
	ExtHTTP         = model.ArchivalExtHTTP
	ExtTCPConnect   = model.ArchivalExtTCPConnect
	ExtTLSHandshake = model.ArchivalExtTLSHandshake
	ExtTunnel       = model.ArchivalExtTunnel
)

Compatibility variables. Most experiments still use these names.

Functions

func NewFailedOperation 

func NewFailedOperation(err error) *string

NewFailedOperation creates a failed operation string from the given error.

func NewFailure 

func NewFailure(err error) *string

NewFailure creates a failure nullable string from the given error. This function is equivalent to NewFailureStr(err).ToFailure().

func ResolverNetworkAdaptNames 

func ResolverNetworkAdaptNames(input string) string

ResolverNetworkAdaptNames makes sure we map the netxlite.StdlibResolverGolangNetResolver and netxlite.StdlibResolverGetaddrinfo resolver names to netxlite.StdlibResolverSystem. You MUST call this function when your resolver splits the "stdlib" resolver results into two fake AAAA and A queries rather than faking a single ANY query.

See https://github.com/ooni/spec/pull/257 for more information.

Types

type DNSAnswerEntry 

type DNSAnswerEntry = model.ArchivalDNSAnswer

Compatibility types. Most experiments still use these names.

type DNSQueryEntry 

type DNSQueryEntry = model.ArchivalDNSLookupResult

Compatibility types. Most experiments still use these names.

func NewDNSQueriesList 

func NewDNSQueriesList(begin time.Time, events []Event) (out []DNSQueryEntry)

NewDNSQueriesList returns a list of DNS queries.

type DNSTransportSaver 

type DNSTransportSaver struct {
	// DNSTransport is the underlying DNS transport.
	DNSTransport model.DNSTransport

	// Saver saves events.
	Saver *Saver
}

DNSTransportSaver is a DNS transport that saves events.

func (*DNSTransportSaver) Address 

func (txp *DNSTransportSaver) Address() string

func (*DNSTransportSaver) CloseIdleConnections 

func (txp *DNSTransportSaver) CloseIdleConnections()

func (*DNSTransportSaver) Network 

func (txp *DNSTransportSaver) Network() string

func (*DNSTransportSaver) RequiresPadding 

func (txp *DNSTransportSaver) RequiresPadding() bool

func (*DNSTransportSaver) RoundTrip 

func (txp *DNSTransportSaver) RoundTrip(
	ctx context.Context, query model.DNSQuery) (model.DNSResponse, error)

RoundTrip implements RoundTripper.RoundTrip

type DialerConnSaver 

type DialerConnSaver struct {
	// Dialer is the underlying dialer
	Dialer model.Dialer

	// Saver saves events
	Saver *Saver
}

DialerConnSaver wraps the returned connection such that we collect all the read/write events that occur.

func (*DialerConnSaver) CloseIdleConnections 

func (d *DialerConnSaver) CloseIdleConnections()

func (*DialerConnSaver) DialContext 

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

DialContext implements Dialer.DialContext

type DialerSaver 

type DialerSaver struct {
	// Dialer is the underlying dialer,
	Dialer model.Dialer

	// Saver saves events.
	Saver *Saver
}

DialerSaver saves events occurring during the dial

func (*DialerSaver) CloseIdleConnections 

func (d *DialerSaver) CloseIdleConnections()

func (*DialerSaver) DialContext 

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

DialContext implements Dialer.DialContext

type Event 

type Event interface {
	// Value returns the event value
	Value() *EventValue

	// Name returns the event name
	Name() string
}

Event is one of the events within a trace.

type EventConnectOperation 

type EventConnectOperation struct {
	V *EventValue
}

EventConnectOperation contains information about the connect operation.

func (*EventConnectOperation) Name 

func (ev *EventConnectOperation) Name() string

func (*EventConnectOperation) Value 

func (ev *EventConnectOperation) Value() *EventValue

type EventDNSRoundTripDone 

type EventDNSRoundTripDone struct {
	V *EventValue
}

EventDNSRoundTripDone is the end of a DNS round trip.

func (*EventDNSRoundTripDone) Name 

func (ev *EventDNSRoundTripDone) Name() string

func (*EventDNSRoundTripDone) Value 

func (ev *EventDNSRoundTripDone) Value() *EventValue

type EventDNSRoundTripStart 

type EventDNSRoundTripStart struct {
	V *EventValue
}

EventDNSRoundTripStart is the start of a DNS round trip.

func (*EventDNSRoundTripStart) Name 

func (ev *EventDNSRoundTripStart) Name() string

func (*EventDNSRoundTripStart) Value 

func (ev *EventDNSRoundTripStart) Value() *EventValue

type EventHTTPTransactionDone 

type EventHTTPTransactionDone struct {
	V *EventValue
}

EventHTTPTransactionDone is the end of an HTTP transaction.

func (*EventHTTPTransactionDone) Name 

func (ev *EventHTTPTransactionDone) Name() string

func (*EventHTTPTransactionDone) Value 

func (ev *EventHTTPTransactionDone) Value() *EventValue

type EventHTTPTransactionStart 

type EventHTTPTransactionStart struct {
	V *EventValue
}

EventHTTPTransactionStart is the beginning of an HTTP transaction.

func (*EventHTTPTransactionStart) Name 

func (ev *EventHTTPTransactionStart) Name() string

func (*EventHTTPTransactionStart) Value 

func (ev *EventHTTPTransactionStart) Value() *EventValue

type EventQUICHandshakeDone 

type EventQUICHandshakeDone struct {
	V *EventValue
}

EventQUICHandshakeDone is the end of a QUIC handshake.

func (*EventQUICHandshakeDone) Name 

func (ev *EventQUICHandshakeDone) Name() string

func (*EventQUICHandshakeDone) Value 

func (ev *EventQUICHandshakeDone) Value() *EventValue

type EventQUICHandshakeStart 

type EventQUICHandshakeStart struct {
	V *EventValue
}

EventQUICHandshakeStart is the start of a QUIC handshake.

func (*EventQUICHandshakeStart) Name 

func (ev *EventQUICHandshakeStart) Name() string

func (*EventQUICHandshakeStart) Value 

func (ev *EventQUICHandshakeStart) Value() *EventValue

type EventReadFromOperation 

type EventReadFromOperation struct {
	V *EventValue
}

EventReadFromOperation summarizes the ReadFrom operation.

func (*EventReadFromOperation) Name 

func (ev *EventReadFromOperation) Name() string

func (*EventReadFromOperation) Value 

func (ev *EventReadFromOperation) Value() *EventValue

type EventReadOperation 

type EventReadOperation struct {
	V *EventValue
}

EventReadOperation contains information about a read operation.

func (*EventReadOperation) Name 

func (ev *EventReadOperation) Name() string

func (*EventReadOperation) Value 

func (ev *EventReadOperation) Value() *EventValue

type EventResolveDone 

type EventResolveDone struct {
	V *EventValue
}

EventResolveDone is the end of a DNS lookup operation.

func (*EventResolveDone) Name 

func (ev *EventResolveDone) Name() string

func (*EventResolveDone) Value 

func (ev *EventResolveDone) Value() *EventValue

type EventResolveStart 

type EventResolveStart struct {
	V *EventValue
}

EventResolveStart is the beginning of a DNS lookup operation.

func (*EventResolveStart) Name 

func (ev *EventResolveStart) Name() string

func (*EventResolveStart) Value 

func (ev *EventResolveStart) Value() *EventValue

type EventTLSHandshakeDone 

type EventTLSHandshakeDone struct {
	V *EventValue
}

EventTLSHandshakeDone is the end of the TLS handshake.

func (*EventTLSHandshakeDone) Name 

func (ev *EventTLSHandshakeDone) Name() string

func (*EventTLSHandshakeDone) Value 

func (ev *EventTLSHandshakeDone) Value() *EventValue

type EventTLSHandshakeStart 

type EventTLSHandshakeStart struct {
	V *EventValue
}

EventTLSHandshakeStart is the beginning of the TLS handshake.

func (*EventTLSHandshakeStart) Name 

func (ev *EventTLSHandshakeStart) Name() string

func (*EventTLSHandshakeStart) Value 

func (ev *EventTLSHandshakeStart) Value() *EventValue

type EventValue 

type EventValue struct {
	Addresses                   []string      `json:",omitempty"`
	Address                     string        `json:",omitempty"`
	DNSQuery                    []byte        `json:",omitempty"`
	DNSResponse                 []byte        `json:",omitempty"`
	Data                        []byte        `json:",omitempty"`
	Duration                    time.Duration `json:",omitempty"`
	Err                         FailureStr    `json:",omitempty"`
	HTTPMethod                  string        `json:",omitempty"`
	HTTPRequestHeaders          http.Header   `json:",omitempty"`
	HTTPResponseHeaders         http.Header   `json:",omitempty"`
	HTTPResponseBody            []byte        `json:",omitempty"`
	HTTPResponseBodyIsTruncated bool          `json:",omitempty"`
	HTTPStatusCode              int           `json:",omitempty"`
	HTTPURL                     string        `json:",omitempty"`
	Hostname                    string        `json:",omitempty"`
	NoTLSVerify                 bool          `json:",omitempty"`
	NumBytes                    int           `json:",omitempty"`
	Proto                       string        `json:",omitempty"`
	TLSServerName               string        `json:",omitempty"`
	TLSCipherSuite              string        `json:",omitempty"`
	TLSNegotiatedProto          string        `json:",omitempty"`
	TLSNextProtos               []string      `json:",omitempty"`
	TLSPeerCerts                [][]byte      `json:",omitempty"`
	TLSVersion                  string        `json:",omitempty"`
	Time                        time.Time     `json:",omitempty"`
	Transport                   string        `json:",omitempty"`
}

Event is one of the events within a trace

type EventWriteOperation 

type EventWriteOperation struct {
	V *EventValue
}

EventWriteOperation contains information about a write operation.

func (*EventWriteOperation) Name 

func (ev *EventWriteOperation) Name() string

func (*EventWriteOperation) Value 

func (ev *EventWriteOperation) Value() *EventValue

type EventWriteToOperation 

type EventWriteToOperation struct {
	V *EventValue
}

EventWriteToOperation summarizes the WriteTo operation.

func (*EventWriteToOperation) Name 

func (ev *EventWriteToOperation) Name() string

func (*EventWriteToOperation) Value 

func (ev *EventWriteToOperation) Value() *EventValue

type ExtSpec 

type ExtSpec = model.ArchivalExtSpec

Compatibility types. Most experiments still use these names.

type FailureStr 

type FailureStr string

FailureStr is the string representation of an error. The empty string represents the absence of any error.

func NewFailureStr 

func NewFailureStr(err error) FailureStr

NewFailureStr creates a FailureStr from an error. If the error is not already an ErrWrapper, it's converted to an ErrWrapper. If the ErrWrapper's Failure is not empty, we return that. Otherwise we return a string indicating that an ErrWrapper has an empty failure (should not happen).

func (FailureStr) IsNil 

func (fs FailureStr) IsNil() bool

IsNil returns whether this FailureStr is nil. Technically speaking, the failure cannot be nil, but an empty string is equivalent to nil after we convert using ToFailure(). Also, this type is often called Err, Error, or Failure. So, the resulting code actually reads correct.

func (FailureStr) IsNotNil 

func (fs FailureStr) IsNotNil() bool

IsNotNil is the opposite of IsNil. Technically speaking, the failure cannot be nil, but an empty string is equivalent to nil after we convert using ToFailure(). Also, this type is often called Err, Error, or Failure. So, the resulting code actually reads correct.

func (FailureStr) ToFailure 

func (fs FailureStr) ToFailure() (out *string)

ToFailure converts a FailureStr to a OONI failure (i.e., a string on error and nil in case of success).

type HTTPRequest 

type HTTPRequest = model.ArchivalHTTPRequest

Compatibility types. Most experiments still use these names.

type HTTPResponse 

type HTTPResponse = model.ArchivalHTTPResponse

Compatibility types. Most experiments still use these names.

type HTTPTransportSaver 

type HTTPTransportSaver struct {
	// HTTPTransport is the MANDATORY underlying HTTP transport.
	HTTPTransport model.HTTPTransport

	// Saver is the MANDATORY saver to use.
	Saver *Saver

	// SnapshotSize is the OPTIONAL maximum body snapshot size (if not set, we'll
	// use 1<<17, which we've been using since the ooni/netx days)
	SnapshotSize int64
}

HTTPTransportSaver is a RoundTripper that saves events related to the HTTP transaction

func (*HTTPTransportSaver) CloseIdleConnections 

func (txp *HTTPTransportSaver) CloseIdleConnections()

func (*HTTPTransportSaver) Network 

func (txp *HTTPTransportSaver) Network() string

func (*HTTPTransportSaver) RoundTrip 

func (txp *HTTPTransportSaver) RoundTrip(req *http.Request) (*http.Response, error)

HTTPRoundTrip performs the round trip with the given transport and the given arguments and saves the results into the saver.

The maxBodySnapshotSize argument controls the maximum size of the body snapshot that we collect along with the HTTP round trip.

type NetworkEvent 

type NetworkEvent = model.ArchivalNetworkEvent

Compatibility types. Most experiments still use these names.

func NewNetworkEventsList 

func NewNetworkEventsList(begin time.Time, events []Event) (out []NetworkEvent)

NewNetworkEventsList returns a list of network events.

type QUICDialerSaver 

type QUICDialerSaver struct {
	// QUICDialer is the wrapped dialer
	QUICDialer model.QUICDialer

	// Saver saves events
	Saver *Saver
}

QUICDialerSaver saves events occurring during the QUIC handshake.

func (*QUICDialerSaver) CloseIdleConnections 

func (h *QUICDialerSaver) CloseIdleConnections()

func (*QUICDialerSaver) DialContext 

func (h *QUICDialerSaver) DialContext(ctx context.Context,
	host string, tlsCfg *tls.Config, cfg *quic.Config) (quic.EarlyConnection, error)

DialContext implements QUICDialer.DialContext

type RequestEntry 

type RequestEntry = model.ArchivalHTTPRequestResult

Compatibility types. Most experiments still use these names.

func NewRequestList 

func NewRequestList(begin time.Time, events []Event) (out []RequestEntry)

NewRequestList returns the list for "requests"

type ResolverSaver 

type ResolverSaver struct {
	// Resolver is the underlying resolver.
	Resolver model.Resolver

	// Saver saves events.
	Saver *Saver
}

ResolverSaver is a resolver that saves events.

func (*ResolverSaver) Address 

func (r *ResolverSaver) Address() string

func (*ResolverSaver) CloseIdleConnections 

func (r *ResolverSaver) CloseIdleConnections()

func (*ResolverSaver) LookupHTTPS 

func (r *ResolverSaver) LookupHTTPS(ctx context.Context, domain string) (*model.HTTPSSvc, error)

func (*ResolverSaver) LookupHost 

func (r *ResolverSaver) LookupHost(ctx context.Context, hostname string) ([]string, error)

LookupHost implements Resolver.LookupHost

func (*ResolverSaver) LookupNS 

func (r *ResolverSaver) LookupNS(ctx context.Context, domain string) ([]*net.NS, error)

func (*ResolverSaver) Network 

func (r *ResolverSaver) Network() string

type Saver 

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

The Saver saves a trace. The zero value of this type is valid and can be used without initialization.

func (*Saver) MaybeWrapHTTPTransport 

func (s *Saver) MaybeWrapHTTPTransport(txp model.HTTPTransport, snapshotSize int64) model.HTTPTransport

MaybeWrapHTTPTransport wraps the HTTPTransport to save events if this Saver is not nil and otherwise just returns the given HTTPTransport. The snapshotSize argument is the maximum response body snapshot size to save per response.

func (*Saver) NewConnectObserver 

func (s *Saver) NewConnectObserver() model.DialerWrapper

NewConnectObserver returns a DialerWrapper that observes the connect event. This function will return nil, which is a valid DialerWrapper for netxlite.WrapDialer, if Saver is nil.

func (*Saver) NewReadWriteObserver 

func (s *Saver) NewReadWriteObserver() model.DialerWrapper

NewReadWriteObserver returns a DialerWrapper that observes the I/O events. This function will return nil, which is a valid DialerWrapper for netxlite.WrapDialer, if Saver is nil.

func (*Saver) Read 

func (s *Saver) Read() []Event

Read reads and returns events inside the trace. It advances the read pointer so you won't see such events again.

func (*Saver) WrapDNSTransport 

func (s *Saver) WrapDNSTransport(txp model.DNSTransport) model.DNSTransport

WrapDNSTransport wraps a model.DNSTransport with a SaverDNSTransport that will save the DNS round trip results into this Saver.

When this function is invoked on a nil Saver, it will directly return the original DNSTransport without any wrapping.

func (*Saver) WrapQUICDialer 

func (s *Saver) WrapQUICDialer(qd model.QUICDialer) model.QUICDialer

WrapQUICDialer wraps a model.QUICDialer with a QUICHandshakeSaver that will save the QUIC handshake results into this Saver.

When this function is invoked on a nil Saver, it will directly return the original QUICDialer without any wrapping.

func (*Saver) WrapResolver 

func (s *Saver) WrapResolver(r model.Resolver) model.Resolver

WrapResolver wraps a model.Resolver with a SaverResolver that will save the DNS lookup results into this Saver.

When this function is invoked on a nil Saver, it will directly return the original Resolver without any wrapping.

func (*Saver) WrapTLSHandshaker 

func (s *Saver) WrapTLSHandshaker(thx model.TLSHandshaker) model.TLSHandshaker

WrapTLSHandshaker wraps a model.TLSHandshaker with a SaverTLSHandshaker that will save the TLS handshake results into this Saver.

When this function is invoked on a nil Saver, it will directly return the original TLSHandshaker without any wrapping.

func (*Saver) WrapUDPListener 

func (s *Saver) WrapUDPListener(ql model.UDPListener) model.UDPListener

WrapUDPListener wraps a model.UDPDialer with a UDPListenerSaver that will save the QUIC I/O packet conn events into this Saver.

When this function is invoked on a nil Saver, it will directly return the original UDPListener without any wrapping.

func (*Saver) Write 

func (s *Saver) Write(ev Event)

Write adds the given event to the trace. A subsequent call to Read will read this event.

type TCPConnectEntry 

type TCPConnectEntry = model.ArchivalTCPConnectResult

Compatibility types. Most experiments still use these names.

func NewTCPConnectList 

func NewTCPConnectList(begin time.Time, events []Event) (out []TCPConnectEntry)

NewTCPConnectList creates a new TCPConnectList

type TCPConnectStatus 

type TCPConnectStatus = model.ArchivalTCPConnectStatus

Compatibility types. Most experiments still use these names.

type TLSHandshake 

type TLSHandshake = model.ArchivalTLSOrQUICHandshakeResult

Compatibility types. Most experiments still use these names.

func NewTLSHandshakesList 

func NewTLSHandshakesList(begin time.Time, events []Event) (out []TLSHandshake)

NewTLSHandshakesList creates a new TLSHandshakesList

type TLSHandshakerSaver 

type TLSHandshakerSaver struct {
	// TLSHandshaker is the underlying TLS handshaker.
	TLSHandshaker model.TLSHandshaker

	// Saver is the saver in which to save events.
	Saver *Saver
}

TLSHandshakerSaver saves events occurring during the TLS handshake.

func (*TLSHandshakerSaver) Handshake 

func (h *TLSHandshakerSaver) Handshake(
	ctx context.Context, conn net.Conn, config *tls.Config) (model.TLSConn, error)

Handshake implements model.TLSHandshaker.Handshake

type UDPListenerSaver 

type UDPListenerSaver struct {
	// UDPListener is the underlying UDPListener.
	UDPListener model.UDPListener

	// Saver is the underlying Saver.
	Saver *Saver
}

UDPListenerSaver is a UDPListener that also implements saving events.

func (*UDPListenerSaver) Listen 

func (qls *UDPListenerSaver) Listen(addr *net.UDPAddr) (model.UDPLikeConn, error)

Listen implements UDPListener.Listen.

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.