archival

Documentation

Overview

Package implements a Saver type that saves network, TCP, DNS, and TLS events. Given a Saver, you can export a Trace. Given a Trace you can obtain data in the OONI archival data format.

Index

• type DNSLookupEvent
• type DNSRoundTripEvent
• type HTTPRoundTripEvent
• type NetworkEvent
• type QUICTLSHandshakeEvent
• type Saver
  • func NewSaver() *Saver
  • func (s *Saver) DNSRoundTrip(ctx context.Context, txp model.DNSTransport, query []byte) ([]byte, error)
  • func (s *Saver) DialContext(ctx context.Context, dialer model.Dialer, network, address string) (net.Conn, error)
  • func (s *Saver) HTTPRoundTrip(txp model.HTTPTransport, maxBodySnapshotSize int64, req *http.Request) (*http.Response, error)
  • func (s *Saver) LookupHTTPS(ctx context.Context, reso model.Resolver, domain string) (*model.HTTPSSvc, error)
  • func (s *Saver) LookupHost(ctx context.Context, reso model.Resolver, domain string) ([]string, error)
  • func (as *Saver) MoveOutTrace() *Trace
  • func (s *Saver) QUICDialContext(ctx context.Context, dialer model.QUICDialer, network, address string, ...) (quic.EarlySession, error)
  • func (s *Saver) Read(conn net.Conn, buf []byte) (int, error)
  • func (s *Saver) ReadFrom(pconn model.UDPLikeConn, buf []byte) (int, net.Addr, error)
  • func (s *Saver) TLSHandshake(ctx context.Context, thx model.TLSHandshaker, conn net.Conn, ...) (net.Conn, tls.ConnectionState, error)
  • func (s *Saver) Write(conn net.Conn, buf []byte) (int, error)
  • func (s *Saver) WriteTo(pconn model.UDPLikeConn, buf []byte, addr net.Addr) (int, error)
• type Trace
  • func (t *Trace) NewArchivalDNSLookupResultList(begin time.Time) (out []model.ArchivalDNSLookupResult)
  • func (t *Trace) NewArchivalHTTPRequestResultList(begin time.Time) (out []model.ArchivalHTTPRequestResult)
  • func (t *Trace) NewArchivalNetworkEventList(begin time.Time) (out []model.ArchivalNetworkEvent)
  • func (t *Trace) NewArchivalTCPConnectResultList(begin time.Time) (out []model.ArchivalTCPConnectResult)
  • func (t *Trace) NewArchivalTLSHandshakeResultList(begin time.Time) (out []model.ArchivalTLSOrQUICHandshakeResult)

Types

type DNSLookupEvent

type DNSLookupEvent struct {
	ALPNs           []string
	Addresses       []string
	Domain          string
	Failure         error
	Finished        time.Time
	LookupType      string
	ResolverAddress string
	ResolverNetwork string
	Started         time.Time
}

DNSLookupEvent contains the results of a DNS lookup.

type DNSRoundTripEvent

type DNSRoundTripEvent struct {
	Address  string
	Failure  error
	Finished time.Time
	Network  string
	Query    []byte
	Reply    []byte
	Started  time.Time
}

DNSRoundTripEvent contains the result of a DNS round trip.

type HTTPRoundTripEvent

type HTTPRoundTripEvent struct {
	Failure                 error
	Finished                time.Time
	Method                  string
	RequestHeaders          http.Header
	ResponseBody            []byte
	ResponseBodyIsTruncated bool
	ResponseBodyLength      int64
	ResponseHeaders         http.Header
	Started                 time.Time
	StatusCode              int64
	Transport               string
	URL                     string
}

HTTPRoundTripEvent contains an HTTP round trip.

type NetworkEvent

type NetworkEvent struct {
	Count      int
	Failure    error
	Finished   time.Time
	Network    string
	Operation  string
	RemoteAddr string
	Started    time.Time
}

NetworkEvent contains a network event. This kind of events are generated by Dialer, QUICDialer, Conn, QUICConn.

type QUICTLSHandshakeEvent

type QUICTLSHandshakeEvent struct {
	ALPN            []string
	CipherSuite     string
	Failure         error
	Finished        time.Time
	NegotiatedProto string
	Network         string
	PeerCerts       [][]byte
	RemoteAddr      string
	SNI             string
	SkipVerify      bool
	Started         time.Time
	TLSVersion      string
}

QUICTLSHandshakeEvent contains a QUIC or TLS handshake event.

type Saver

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

Saver allows to save network, DNS, QUIC, TLS, HTTP events.

You MUST use NewSaver to create a new instance.

func NewSaver

func NewSaver() *Saver

NewSaver creates a new Saver instance.

You MUST use this function to create a Saver.

func (*Saver) DNSRoundTrip

func (s *Saver) DNSRoundTrip(ctx context.Context, txp model.DNSTransport, query []byte) ([]byte, error)

DNSRoundTrip implements ArchivalSaver.DNSRoundTrip.

func (*Saver) DialContext

func (s *Saver) DialContext(ctx context.Context,
	dialer model.Dialer, network, address string) (net.Conn, error)

DialContext dials with the given dialer with the given arguments and stores the dial result inside of this saver.

func (*Saver) HTTPRoundTrip

func (s *Saver) HTTPRoundTrip(
	txp model.HTTPTransport, maxBodySnapshotSize int64,
	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.

func (*Saver) LookupHTTPS

func (s *Saver) LookupHTTPS(ctx context.Context, reso model.Resolver, domain string) (*model.HTTPSSvc, error)

LookupHTTPS performs an HTTPSSvc-record lookup using the given resolver and saves the results into the saver.

func (*Saver) LookupHost

func (s *Saver) LookupHost(ctx context.Context, reso model.Resolver, domain string) ([]string, error)

LookupHost performs a host lookup with the given resolver and saves the results into the saver.

func (*Saver) MoveOutTrace

func (as *Saver) MoveOutTrace() *Trace

MoveOutTrace moves the current trace out of the saver and creates a new empty trace inside it.

func (*Saver) QUICDialContext

func (s *Saver) QUICDialContext(ctx context.Context, dialer model.QUICDialer,
	network, address string, tlsConfig *tls.Config, quicConfig *quic.Config) (quic.EarlySession, error)

QUICDialContext dials a QUIC session using the given dialer and saves the results inside of the saver.

func (*Saver) Read

func (s *Saver) Read(conn net.Conn, buf []byte) (int, error)

Read reads from the given conn and stores the results in the saver.

func (*Saver) ReadFrom

func (s *Saver) ReadFrom(pconn model.UDPLikeConn, buf []byte) (int, net.Addr, error)

ReadFrom performs ReadFrom with the given pconn and saves the operation's results inside the saver.

func (*Saver) TLSHandshake

func (s *Saver) TLSHandshake(ctx context.Context, thx model.TLSHandshaker,
	conn net.Conn, config *tls.Config) (net.Conn, tls.ConnectionState, error)

TLSHandshake performs a TLS handshake with the given handshaker and saves the results into the saver.

func (*Saver) Write

func (s *Saver) Write(conn net.Conn, buf []byte) (int, error)

Write writes to the given conn and stores the results into the saver.

func (*Saver) WriteTo

func (s *Saver) WriteTo(pconn model.UDPLikeConn, buf []byte, addr net.Addr) (int, error)

WriteTo performs WriteTo with the given pconn and saves the operation's results inside the saver.

type Trace

type Trace struct {
	// DNSLookupHTTPS contains DNSLookupHTTPS events.
	DNSLookupHTTPS []*DNSLookupEvent

	// DNSLookupHost contains DNSLookupHost events.
	DNSLookupHost []*DNSLookupEvent

	// DNSRoundTrip contains DNSRoundTrip events.
	DNSRoundTrip []*DNSRoundTripEvent

	// HTTPRoundTrip contains HTTPRoundTrip round trip events.
	HTTPRoundTrip []*HTTPRoundTripEvent

	// Network contains network events.
	Network []*NetworkEvent

	// QUICHandshake contains QUICHandshake handshake events.
	QUICHandshake []*QUICTLSHandshakeEvent

	// TLSHandshake contains TLSHandshake handshake events.
	TLSHandshake []*QUICTLSHandshakeEvent
}

Trace contains the events.

func (*Trace) NewArchivalDNSLookupResultList

func (t *Trace) NewArchivalDNSLookupResultList(begin time.Time) (out []model.ArchivalDNSLookupResult)

NewArchivalDNSLookupResultList builds a DNS lookups list in the OONI archival data format out of the results saved inside the trace.

func (*Trace) NewArchivalHTTPRequestResultList

func (t *Trace) NewArchivalHTTPRequestResultList(begin time.Time) (out []model.ArchivalHTTPRequestResult)

NewArchivalHTTPRequestResultList builds an HTTP requests list in the OONI archival data format out of the results saved inside the trace.

This function will sort the emitted list of requests such that the last request that happened in time is the first one to be emitted. If the measurement code performs related requests sequentially (which is a kinda a given because you cannot follow a redirect before reading the previous request), then the result is sorted how the OONI pipeline expects it to be.

func (*Trace) NewArchivalNetworkEventList

func (t *Trace) NewArchivalNetworkEventList(begin time.Time) (out []model.ArchivalNetworkEvent)

NewArchivalNetworkEventList builds a network events list in the OONI archival data format out of the results saved inside the trace.

func (*Trace) NewArchivalTCPConnectResultList

func (t *Trace) NewArchivalTCPConnectResultList(begin time.Time) (out []model.ArchivalTCPConnectResult)

NewArchivalTCPConnectResultList builds a TCP connect list in the OONI archival data format out of the results saved inside the trace.

func (*Trace) NewArchivalTLSHandshakeResultList

func (t *Trace) NewArchivalTLSHandshakeResultList(begin time.Time) (out []model.ArchivalTLSOrQUICHandshakeResult)

NewArchivalTLSHandshakeResultList builds a TLS handshakes list in the OONI archival data format out of the results saved inside the trace.