model

type ArchivalBinaryData []byte

type ArchivalDNSAnswer struct {
	ASN        int64   `json:"asn,omitempty"`
	ASOrgName  string  `json:"as_org_name,omitempty"`
	AnswerType string  `json:"answer_type"`
	Hostname   string  `json:"hostname,omitempty"`
	IPv4       string  `json:"ipv4,omitempty"`
	IPv6       string  `json:"ipv6,omitempty"`
	TTL        *uint32 `json:"ttl"`
}

type ArchivalDNSLookupResult struct {
	Answers          []ArchivalDNSAnswer `json:"answers"`
	Engine           string              `json:"engine"`
	Failure          *string             `json:"failure"`
	GetaddrinfoError int64               `json:"getaddrinfo_error,omitempty"`
	Hostname         string              `json:"hostname"`
	QueryType        string              `json:"query_type"`
	RawResponse      []byte              `json:"raw_response,omitempty"`
	Rcode            int64               `json:"rcode,omitempty"`
	ResolverHostname *string             `json:"resolver_hostname"`
	ResolverPort     *string             `json:"resolver_port"`
	ResolverAddress  string              `json:"resolver_address"`
	T0               float64             `json:"t0,omitempty"`
	T                float64             `json:"t"`
	Tags             []string            `json:"tags"`
	TransactionID    int64               `json:"transaction_id,omitempty"`
}

type ArchivalExtSpec struct {
	Name string // extension name
	V    int64  // extension version
}

type ArchivalHTTPHeader [2]ArchivalScrubbedMaybeBinaryString

type ArchivalHTTPRequest struct {
	Body            ArchivalScrubbedMaybeBinaryString            `json:"body"`
	BodyIsTruncated bool                                         `json:"body_is_truncated"`
	HeadersList     []ArchivalHTTPHeader                         `json:"headers_list"`
	Headers         map[string]ArchivalScrubbedMaybeBinaryString `json:"headers"`
	Method          string                                       `json:"method"`
	Tor             ArchivalHTTPTor                              `json:"tor"`
	Transport       string                                       `json:"x_transport"`
	URL             string                                       `json:"url"`
}

type ArchivalHTTPRequestResult struct {
	Network       string               `json:"network,omitempty"`
	Address       string               `json:"address,omitempty"`
	ALPN          string               `json:"alpn,omitempty"`
	Failure       *string              `json:"failure"`
	Request       ArchivalHTTPRequest  `json:"request"`
	Response      ArchivalHTTPResponse `json:"response"`
	T0            float64              `json:"t0,omitempty"`
	T             float64              `json:"t"`
	Tags          []string             `json:"tags"`
	TransactionID int64                `json:"transaction_id,omitempty"`
}

type ArchivalHTTPResponse struct {
	Body            ArchivalScrubbedMaybeBinaryString            `json:"body"`
	BodyIsTruncated bool                                         `json:"body_is_truncated"`
	Code            int64                                        `json:"code"`
	HeadersList     []ArchivalHTTPHeader                         `json:"headers_list"`
	Headers         map[string]ArchivalScrubbedMaybeBinaryString `json:"headers"`

	// The following fields are not serialised but are useful to simplify
	// analysing the measurements in telegram, whatsapp, etc.
	Locations []string `json:"-"`
}

type ArchivalHTTPTor struct {
	ExitIP   *string `json:"exit_ip"`
	ExitName *string `json:"exit_name"`
	IsTor    bool    `json:"is_tor"`
}

type ArchivalNetworkEvent struct {
	Address       string   `json:"address,omitempty"`
	Failure       *string  `json:"failure"`
	NumBytes      int64    `json:"num_bytes,omitempty"`
	Operation     string   `json:"operation"`
	Proto         string   `json:"proto,omitempty"`
	T0            float64  `json:"t0,omitempty"`
	T             float64  `json:"t"`
	TransactionID int64    `json:"transaction_id,omitempty"`
	Tags          []string `json:"tags,omitempty"`
}

type ArchivalOpenVPNHandshakeResult struct {
	Endpoint       string                 `json:"endpoint"`
	Failure        *string                `json:"failure"`
	HandshakeTime  float64                `json:"handshake_time,omitempty"`
	IP             string                 `json:"ip"`
	Port           int                    `json:"port"`
	Transport      string                 `json:"transport"`
	Provider       string                 `json:"provider"`
	OpenVPNOptions ArchivalOpenVPNOptions `json:"openvpn_options"`
	T0             float64                `json:"t0,omitempty"`
	T              float64                `json:"t"`
	Tags           []string               `json:"tags"`
	TransactionID  int64                  `json:"transaction_id,omitempty"`
}

type ArchivalOpenVPNOptions struct {
	Auth        string `json:"auth,omitempty"`
	Cipher      string `json:"cipher,omitempty"`
	Compression string `json:"compression,omitempty"`
}

type ArchivalScrubbedMaybeBinaryString string

type ArchivalTCPConnectResult struct {
	IP            string                   `json:"ip"`
	Port          int                      `json:"port"`
	Status        ArchivalTCPConnectStatus `json:"status"`
	T0            float64                  `json:"t0,omitempty"`
	T             float64                  `json:"t"`
	Tags          []string                 `json:"tags"`
	TransactionID int64                    `json:"transaction_id,omitempty"`
}

type ArchivalTCPConnectStatus struct {
	Blocked *bool   `json:"blocked,omitempty"`
	Failure *string `json:"failure"`
	Success bool    `json:"success"`
}

type ArchivalTLSOrQUICHandshakeResult struct {
	Network            string               `json:"network"`
	Address            string               `json:"address"`
	CipherSuite        string               `json:"cipher_suite"`
	Failure            *string              `json:"failure"`
	SoError            *string              `json:"so_error,omitempty"`
	NegotiatedProtocol string               `json:"negotiated_protocol"`
	NoTLSVerify        bool                 `json:"no_tls_verify"`
	PeerCertificates   []ArchivalBinaryData `json:"peer_certificates"`
	ServerName         string               `json:"server_name"`
	OuterServerName    string               `json:"outer_server_name,omitempty"`
	ECHConfig          string               `json:"echconfig,omitempty"`
	T0                 float64              `json:"t0,omitempty"`
	T                  float64              `json:"t"`
	Tags               []string             `json:"tags"`
	TLSVersion         string               `json:"tls_version"`
	TransactionID      int64                `json:"transaction_id,omitempty"`
}

type DNSDecoder interface {
	// DecodeResponse decodes a DNS response message.
	//
	// Arguments:
	//
	// - data is the raw reply
	//
	// This function fails if we cannot parse data as a DNS
	// message or the message is not a response.
	//
	// Regarding the returned response, remember that the Rcode
	// MAY still be nonzero (this method does not treat a nonzero
	// Rcode as an error when parsing the response).
	DecodeResponse(data []byte, query DNSQuery) (DNSResponse, error)
}

type DNSEncoder interface {
	// Encode transforms its arguments into a serialized DNS query.
	//
	// Every time you call Encode, you get a new DNSQuery value
	// using a query ID selected at random.
	//
	// Serialization to bytes is lazy to acommodate DNS transports that
	// do not need to serialize and send bytes, e.g., getaddrinfo.
	//
	// You serialize to bytes using DNSQuery.Bytes. This operation MAY fail
	// if the domain name cannot be packed into a DNS message (e.g., it is
	// too long to fit into the message).
	//
	// Arguments:
	//
	// - domain is the domain for the query (e.g., x.org);
	//
	// - qtype is the query type (e.g., dns.TypeA);
	//
	// - padding is whether to add padding to the query.
	//
	// This function will transform the domain into an FQDN is it's not
	// already expressed in the FQDN format.
	Encode(domain string, qtype uint16, padding bool) DNSQuery
}

type DNSQuery interface {
	// Domain is the domain we're querying for.
	Domain() string

	// Type is the query type.
	Type() uint16

	// Bytes serializes the query to bytes. This function may fail if we're not
	// able to correctly encode the domain into a query message.
	//
	// The value returned by this function WILL be memoized after the first call,
	// so you SHOULD create a new DNSQuery if you need to retry a query.
	Bytes() ([]byte, error)

	// ID returns the query ID.
	ID() uint16
}

type DNSResponse interface {
	// Query is the query associated with this response.
	Query() DNSQuery

	// Bytes returns the bytes from which we parsed the query.
	Bytes() []byte

	// Rcode returns the response's Rcode.
	Rcode() int

	// DecodeHTTPS returns information gathered from all the HTTPS
	// records found inside of this response.
	DecodeHTTPS() (*HTTPSSvc, error)

	// DecodeLookupHost returns the addresses in the response matching
	// the original query type (one of A and AAAA).
	DecodeLookupHost() ([]string, error)

	// DecodeNS returns all the NS entries in this response.
	DecodeNS() ([]*net.NS, error)

	// DecodeCNAME returns the first CNAME entry in this response.
	DecodeCNAME() (string, error)
}

type DNSTransport interface {
	// RoundTrip sends a DNS query and receives the reply.
	RoundTrip(ctx context.Context, query DNSQuery) (DNSResponse, error)

	// RequiresPadding returns whether this transport needs padding.
	RequiresPadding() bool

	// Network is the network of the round tripper (e.g. "dot").
	Network() string

	// Address is the address of the round tripper (e.g. "1.1.1.1:853").
	Address() string

	// CloseIdleConnections closes idle connections, if any.
	CloseIdleConnections()
}

type DatabaseMeasurement struct {
	ID               int64          `db:"measurement_id,omitempty"`
	TestName         string         `db:"test_name"`
	StartTime        time.Time      `db:"measurement_start_time"`
	Runtime          float64        `db:"measurement_runtime"` // Fractional number of seconds
	IsDone           bool           `db:"measurement_is_done"`
	IsUploaded       bool           `db:"measurement_is_uploaded"`
	IsFailed         bool           `db:"measurement_is_failed"`
	FailureMsg       sql.NullString `db:"measurement_failure_msg,omitempty"`
	IsUploadFailed   bool           `db:"measurement_is_upload_failed"`
	UploadFailureMsg sql.NullString `db:"measurement_upload_failure_msg,omitempty"`
	IsRerun          bool           `db:"measurement_is_rerun"`
	ReportID         sql.NullString `db:"report_id,omitempty"`
	URLID            sql.NullInt64  `db:"url_id,omitempty"` // Used to reference URL
	MeasurementID    sql.NullInt64  `db:"collector_measurement_id,omitempty"`
	IsAnomaly        sql.NullBool   `db:"is_anomaly,omitempty"`
	// FIXME we likely want to support JSON. See: https://github.com/upper/db/issues/462
	TestKeys            string         `db:"test_keys"`
	ResultID            int64          `db:"result_id"`
	ReportFilePath      sql.NullString `db:"report_file_path,omitempty"`
	MeasurementFilePath sql.NullString `db:"measurement_file_path,omitempty"`
}

type DatabaseMeasurementURLNetwork struct {
	DatabaseMeasurement `db:",inline"`
	DatabaseNetwork     `db:",inline"`
	DatabaseResult      `db:",inline"`
	DatabaseURL         `db:",inline"`
}

type DatabaseNetwork struct {
	ID          int64  `db:"network_id,omitempty"`
	NetworkName string `db:"network_name"`
	NetworkType string `db:"network_type"`
	IP          string `db:"ip"`
	ASN         uint   `db:"asn"`
	CountryCode string `db:"network_country_code"`
}

type DatabaseResult struct {
	ID             int64     `db:"result_id,omitempty"`
	TestGroupName  string    `db:"test_group_name"`
	StartTime      time.Time `db:"result_start_time"`
	NetworkID      int64     `db:"network_id"`     // Used to include a Network
	Runtime        float64   `db:"result_runtime"` // Runtime is expressed in fractional seconds
	IsViewed       bool      `db:"result_is_viewed"`
	IsDone         bool      `db:"result_is_done"`
	IsUploaded     bool      `db:"result_is_uploaded"`
	DataUsageUp    float64   `db:"result_data_usage_up"`
	DataUsageDown  float64   `db:"result_data_usage_down"`
	MeasurementDir string    `db:"measurement_dir"`
}

type DatabaseResultNetwork struct {
	DatabaseResult  `db:",inline"`
	DatabaseNetwork `db:",inline"`
	AnomalyCount    uint64 `db:"anomaly_count"`
	TotalCount      uint64 `db:"total_count"`
	TestKeys        string `db:"test_keys"`
}

type DatabaseURL struct {
	ID           sql.NullInt64  `db:"url_id,omitempty"`
	URL          sql.NullString `db:"url"`
	CategoryCode sql.NullString `db:"category_code"`
	CountryCode  sql.NullString `db:"url_country_code"`
}

type DebugLogger = logmodel.DebugLogger

type Dialer interface {
	// A Dialer is also a SimpleDialer.
	SimpleDialer

	// CloseIdleConnections closes idle connections, if any.
	CloseIdleConnections()
}

type DialerWrapper interface {
	WrapDialer(d Dialer) Dialer
}

type Experiment interface {
	// KibiBytesReceived accounts for the KibiBytes received by the experiment.
	KibiBytesReceived() float64

	// KibiBytesSent is like KibiBytesReceived but for the bytes sent.
	KibiBytesSent() float64

	// Name returns the experiment name.
	Name() string

	// ReportID returns the open report's ID, if we have opened a report
	// successfully before, or an empty string, otherwise.
	ReportID() string

	// MeasureWithContext measures the given experiment target.
	//
	// Return value: either a non-nil measurement and a nil error
	// or a nil measurement and a non-nil error.
	MeasureWithContext(ctx context.Context, target ExperimentTarget) (measurement *Measurement, err error)

	// SubmitAndUpdateMeasurementContext submits a measurement and updates the
	// fields whose value has changed as part of the submission.
	SubmitAndUpdateMeasurementContext(
		ctx context.Context, measurement *Measurement) (string, error)

	// OpenReportContext will open a report using the given context
	// to possibly limit the lifetime of this operation.
	OpenReportContext(ctx context.Context) error
}

type ExperimentArgs struct {
	// Callbacks contains MANDATORY experiment callbacks.
	Callbacks ExperimentCallbacks

	// Measurement is the MANDATORY measurement in which the experiment
	// must write the results of the measurement.
	Measurement *Measurement

	// Session is the MANDATORY session the experiment can use.
	Session ExperimentSession

	// Target is the OPTIONAL target we're measuring.
	//
	// Only richer-input-aware experiments use this field. These experiments
	// SHOULD be defensive and handle the case where this field is nil.
	Target ExperimentTarget
}

type ExperimentBuilder interface {
	// Interruptible tells you whether this is an interruptible experiment. This kind
	// of experiments (e.g. ndt7) may be interrupted mid way.
	Interruptible() bool

	// InputPolicy returns the experiment input policy.
	InputPolicy() InputPolicy

	// Options returns information about the experiment's options.
	Options() (map[string]ExperimentOptionInfo, error)

	// SetOptionAny sets an option whose value is an any value. We will use reasonable
	// heuristics to convert the any value to the proper type of the field whose name is
	// contained by the key variable. If we cannot convert the provided any value to
	// the proper type, then this function returns an error.
	SetOptionAny(key string, value any) error

	// SetOptionsAny sets options from a map[string]any. See the documentation of
	// the SetOptionAny method for more information.
	SetOptionsAny(options map[string]any) error

	// SetOptionsJSON uses the given [json.RawMessage] to initialize fields
	// of the configuration for running the experiment. The [json.RawMessage], if
	// not empty, MUST contain a serialization of the experiment config's
	// type. An empty [json.RawMessage] will silently be ignored.
	SetOptionsJSON(value json.RawMessage) error

	// SetCallbacks sets the experiment's interactive callbacks.
	SetCallbacks(callbacks ExperimentCallbacks)

	// NewExperiment creates the [Experiment] instance.
	NewExperiment() Experiment

	// NewTargetLoader creates the [ExperimentTargetLoader] instance.
	NewTargetLoader(config *ExperimentTargetLoaderConfig) ExperimentTargetLoader
}

type ExperimentCallbacks interface {
	// OnProgress provides information about the experiment's progress.
	//
	// The prog field is a number between 0.0 and 1.0 representing progress, where
	// 0.0 corresponds to 0% and 1.0 corresponds to 100%.
	OnProgress(prog float64, message string)
}

type ExperimentInputProcessor interface {
	Run(ctx context.Context) error
}

type ExperimentMeasurer interface {
	// ExperimentName returns the experiment name.
	ExperimentName() string

	// ExperimentVersion returns the experiment version.
	ExperimentVersion() string

	// Run runs the experiment with the specified context, session,
	// measurement, and experiment calbacks. This method should only
	// return an error in case the experiment could not run (e.g.,
	// a required input is missing). Otherwise, the code should just
	// set the relevant OONI error inside of the measurement and
	// return nil. This is important because the caller WILL NOT submit
	// the measurement if this method returns an error.
	Run(ctx context.Context, args *ExperimentArgs) error
}

type ExperimentOptionInfo struct {
	// Doc contains the documentation.
	Doc string

	// Type contains the type.
	Type string

	// Value contains the current option value.
	Value any
}

type ExperimentSession interface {
	// GetTestHelpersByName returns a list of test helpers with the given name.
	GetTestHelpersByName(name string) ([]OOAPIService, bool)

	// DefaultHTTPClient returns the default HTTPClient used by the session.
	DefaultHTTPClient() HTTPClient

	// FetchOpenVPNConfig returns vpn config as a serialized JSON or an error.
	FetchOpenVPNConfig(ctx context.Context, provider, cc string) (*OOAPIVPNProviderConfig, error)

	// FetchPsiphonConfig returns psiphon's config as a serialized JSON or an error.
	FetchPsiphonConfig(ctx context.Context) ([]byte, error)

	// FetchTorTargets returns the targets for the Tor experiment or an error.
	FetchTorTargets(ctx context.Context, cc string) (map[string]OOAPITorTarget, error)

	// Logger returns the logger used by the session.
	Logger() Logger

	// ProbeCC returns the country code.
	ProbeCC() string

	// ResolverIP returns the resolver's IP.
	ResolverIP() string

	// TempDir returns the session's temporary directory.
	TempDir() string

	// TorArgs returns the arguments we should pass to tor when executing it.
	TorArgs() []string

	// TorBinary returns the path of the tor binary.
	TorBinary() string

	// TunnelDir is the directory where to store tunnel information.
	TunnelDir() string

	// UserAgent returns the user agent we should be using when we're fine
	// with identifying ourselves as ooniprobe.
	UserAgent() string
}

type ExperimentTarget interface {
	// Category returns the github.com/citizenlab/test-lists category
	// code for this piece of richer input.
	//
	// Return [DefaultCategoryCode] if there's no applicable category code.
	Category() string

	// Country returns the country code for this
	// piece of richer input.
	//
	// Return [DefaultCountryCode] if there's not applicable country code.
	Country() string

	// Input returns the experiment input, which is typically a URL.
	Input() string

	// Options transforms the options contained by this target
	// into a []string containing options as they were provided
	// using the command line `-O option=value` syntax.
	//
	// This method MUST NOT serialize all the options whose name
	// starts with the "Safe" prefix. This method MUST skip serializing
	// sensitive options, non-scalar options, and zero value options.
	//
	// Consider using the [experimentconfig] package to serialize.
	Options() []string

	// String MUST return the experiment input.
	//
	// Implementation note: previously existing code often times treated
	// the input as a string and, crucially, printed it using %s. To be
	// robust with respect to introducing richer input, we would like the
	// code to print in output the same value as before, which possibly
	// is processed by the desktop app. This is the reason why we are
	// introducing an explicit String() method and why we say that this
	// method MUST return the experiment input.
	String() string
}

type ExperimentTargetLoader interface {
	Load(ctx context.Context) ([]ExperimentTarget, error)
}

type ExperimentTargetLoaderConfig struct {
	// CheckInConfig contains OPTIONAL options for the CheckIn API. If not set, then we'll create a
	// default config. If set but there are fields inside it that are not set, then we will set them
	// to a default value.
	CheckInConfig *OOAPICheckInConfig

	// Session is the MANDATORY current measurement session.
	Session ExperimentTargetLoaderSession

	// StaticInputs contains OPTIONAL input to be added
	// to the resulting input list if possible.
	StaticInputs []string

	// SourceFiles contains OPTIONAL files to read input
	// from. Each file should contain a single input string
	// per line. We will fail if any file is unreadable
	// as well as if any file is empty.
	SourceFiles []string
}

type ExperimentTargetLoaderSession interface {
	// CheckIn invokes the check-in API.
	CheckIn(ctx context.Context, config *OOAPICheckInConfig) (*OOAPICheckInResult, error)

	// FetchOpenVPNConfig fetches the OpenVPN experiment configuration.
	FetchOpenVPNConfig(ctx context.Context, provider, cc string) (*OOAPIVPNProviderConfig, error)

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

	// ProbeCC returns the probe country code.
	ProbeCC() string
}

type GeoIPASNLookupper interface {
	LookupASN(ip string) (asn uint, org string, err error)
}

type GeoIPASNLookupperFunc func(ip string, dbPath string) (asn uint, org string, err error)

type HTTPClient interface {
	Do(req *http.Request) (*http.Response, error)
	CloseIdleConnections()
}

type HTTPSSvc struct {
	// ALPN contains the ALPNs inside the HTTPS reply.
	ALPN []string

	// IPv4 contains the IPv4 hints (which may be empty).
	IPv4 []string

	// IPv6 contains the IPv6 hints (which may be empty).
	IPv6 []string

	// Encrypted ClientHello config decoded from base64 to bytes
	// (which may be empty).
	Ech []byte
}

type HTTPTransport interface {
	// Network returns the network used by the transport, which
	// should be one of "tcp" and "udp".
	Network() string

	// RoundTrip performs the HTTP round trip.
	RoundTrip(req *http.Request) (*http.Response, error)

	// CloseIdleConnections closes idle connections.
	CloseIdleConnections()
}

type InfoLogger = logmodel.InfoLogger

type InputPolicy string

type KeyValueStore interface {
	// Get gets the value of the given key or returns an
	// error if there is no such key or we cannot read
	// from the key-value store.
	Get(key string) (value []byte, err error)

	// Set sets the value of the given key and returns
	// whether the operation was successful or not.
	Set(key string, value []byte) (err error)
}

type LocationASN struct {
	ASNumber     uint
	Organization string
}

type LocationProvider interface {
	ProbeASN() uint
	ProbeASNString() string
	ProbeCC() string
	ProbeIP() string
	ProbeNetworkName() string
	ResolverIP() string
}

type Logger = logmodel.Logger

type Measurement struct {
	// Annotations contains results annotations
	Annotations map[string]string `json:"annotations,omitempty"`

	// DataFormatVersion is the version of the data format
	DataFormatVersion string `json:"data_format_version"`

	// Extensions contains information about the extensions included
	// into the test_keys of this measurement.
	Extensions map[string]int64 `json:"extensions,omitempty"`

	// ID is the locally generated measurement ID
	ID string `json:"id,omitempty"`

	// Input is the measurement input
	Input MeasurementInput `json:"input"`

	// InputHashes contains input hashes
	InputHashes []string `json:"input_hashes,omitempty"`

	// MeasurementStartTime is the time when the measurement started
	MeasurementStartTime string `json:"measurement_start_time"`

	// MeasurementStartTimeSaved is the moment in time when we
	// started the measurement. This is not included into the JSON
	// and is only used within the ./internal pkg as a "zero" time.
	MeasurementStartTimeSaved time.Time `json:"-"`

	// Options contains command line options
	Options []string `json:"options,omitempty"`

	// ProbeASN contains the probe autonomous system number
	ProbeASN string `json:"probe_asn"`

	// ProbeCC contains the probe country code
	ProbeCC string `json:"probe_cc"`

	// ProbeCity contains the probe city
	ProbeCity string `json:"probe_city,omitempty"`

	// ProbeIP contains the probe IP
	ProbeIP string `json:"probe_ip,omitempty"`

	// ProbeNetworkName contains the probe network name
	ProbeNetworkName string `json:"probe_network_name"`

	// ReportID contains the report ID
	ReportID string `json:"report_id"`

	// ResolverASN is the ASN of the resolver
	ResolverASN string `json:"resolver_asn"`

	// ResolverIP is the resolver IP
	ResolverIP string `json:"resolver_ip"`

	// ResolverNetworkName is the network name of the resolver.
	ResolverNetworkName string `json:"resolver_network_name"`

	// SoftwareName contains the software name
	SoftwareName string `json:"software_name"`

	// SoftwareVersion contains the software version
	SoftwareVersion string `json:"software_version"`

	// TestHelpers contains the test helpers. It seems this structure is more
	// complex than we would like. In particular, using a map from string to
	// string does not fit into the web_connectivity use case. Hence, for now
	// we're going to represent this using interface{}. In going forward we
	// may probably want to have more uniform test helpers.
	TestHelpers map[string]interface{} `json:"test_helpers,omitempty"`

	// TestKeys contains the real test result. This field is opaque because
	// each experiment will insert here a different structure.
	TestKeys interface{} `json:"test_keys"`

	// TestName contains the test name
	TestName string `json:"test_name"`

	// MeasurementRuntime contains the measurement runtime. The JSON name
	// is test_runtime because this is the name expected by the OONI backend
	// even though that name is clearly a misleading one.
	MeasurementRuntime float64 `json:"test_runtime"`

	// TestStartTime contains the test start time
	TestStartTime string `json:"test_start_time"`

	// TestVersion contains the test version
	TestVersion string `json:"test_version"`
}

type MeasurementInput string

type MeasurementSummaryKeys interface {
	// Anomaly returns whether there was a measurement anomaly.
	Anomaly() bool
}

type MeasurementSummaryKeysProvider interface {
	MeasurementSummaryKeys() MeasurementSummaryKeys
}

type MeasuringNetwork interface {
	// NewDialerWithoutResolver creates a [Dialer] with error wrapping and without an attached
	// resolver, meaning that you MUST pass TCP or UDP endpoint addresses to this dialer.
	//
	// The [DialerWrapper] arguments wraps the returned dialer in such a way that we can implement
	// the legacy [netx] package. New code MUST NOT use this functionality, which we'd like to remove ASAP.
	NewDialerWithoutResolver(dl DebugLogger, w ...DialerWrapper) Dialer

	// NewParallelDNSOverHTTPSResolver creates a new DNS-over-HTTPS resolver with error wrapping.
	NewParallelDNSOverHTTPSResolver(logger DebugLogger, URL string) Resolver

	// NewParallelUDPResolver creates a new Resolver using DNS-over-UDP
	// that performs parallel A/AAAA lookups during LookupHost.
	//
	// The address argument is the UDP endpoint address (e.g., 1.1.1.1:53, [::1]:53).
	NewParallelUDPResolver(logger DebugLogger, dialer Dialer, address string) Resolver

	// NewQUICDialerWithoutResolver creates a [QUICDialer] with error wrapping and without an attached
	// resolver, meaning that you MUST pass UDP endpoint addresses to this dialer.
	//
	// The [QUICDialerWrapper] arguments wraps the returned dialer in such a way
	// that we can implement the legacy [netx] package. New code MUST NOT
	// use this functionality, which we'd like to remove ASAP.
	NewQUICDialerWithoutResolver(
		listener UDPListener, logger DebugLogger, w ...QUICDialerWrapper) QUICDialer

	// NewStdlibResolver creates a new Resolver with error wrapping using
	// getaddrinfo or &net.Resolver{} depending on `-tags netgo`.
	NewStdlibResolver(logger DebugLogger) Resolver

	// NewTLSHandshakerStdlib creates a new TLSHandshaker with error wrapping
	// that is using the go standard library to manage TLS.
	NewTLSHandshakerStdlib(logger DebugLogger) TLSHandshaker

	// NewTLSHandshakerUTLS creates a new TLS handshaker using
	// gitlab.com/yawning/utls for TLS that implements error wrapping.
	//
	// The id is the address of something like utls.HelloFirefox_55.
	//
	// Passing a nil `id` will make this function panic.
	NewTLSHandshakerUTLS(logger DebugLogger, id *utls.ClientHelloID) TLSHandshaker

	// NewUDPListener creates a new UDPListener with error wrapping.
	NewUDPListener() UDPListener
}

type OOAPICheckInConfig struct {
	// Charging indicate whether the phone is charging.
	Charging bool `json:"charging"`

	// OnWiFi indicate if the phone is connected to a WiFi.
	OnWiFi bool `json:"on_wifi"`

	// Platform of the probe.
	Platform string `json:"platform"`

	// ProbeASN is the probe ASN.
	ProbeASN string `json:"probe_asn"`

	// ProbeCC is the probe country code.
	ProbeCC string `json:"probe_cc"`

	// RunType indicated whether the run is "timed" or "manual".
	RunType RunType `json:"run_type"`

	// SoftwareName of the probe.
	SoftwareName string `json:"software_name"`

	// SoftwareVersion of the probe.
	SoftwareVersion string `json:"software_version"`

	// WebConnectivity contains WebConnectivity information.
	WebConnectivity OOAPICheckInConfigWebConnectivity `json:"web_connectivity"`
}

type OOAPICheckInConfigWebConnectivity struct {
	// CategoryCodes contains an array of category codes
	CategoryCodes []string `json:"category_codes"`
}

type OOAPICheckInInfoWebConnectivity struct {
	// ReportID is the report ID the probe should use.
	ReportID string `json:"report_id"`

	// URLs contains the URL to measure.
	URLs []OOAPIURLInfo `json:"urls"`
}

type OOAPICheckInResult struct {
	// Conf contains configuration.
	Conf OOAPICheckInResultConfig `json:"conf"`

	// ProbeASN contains the probe's ASN.
	ProbeASN string `json:"probe_asn"`

	// ProbeCC contains the probe's CC.
	ProbeCC string `json:"probe_cc"`

	// Tests contains information about nettests.
	Tests OOAPICheckInResultNettests `json:"tests"`

	// UTCTime contains the time in UTC.
	UTCTime time.Time `json:"utc_time"`

	// V is the version.
	V int64 `json:"v"`
}

type OOAPICheckInResultConfig struct {
	// Features contains feature flags.
	Features map[string]bool `json:"features"`

	// TestHelpers contains test-helpers information.
	TestHelpers map[string][]OOAPIService `json:"test_helpers"`
}

type OOAPICheckInResultNettests struct {
	// WebConnectivity contains WebConnectivity related information.
	WebConnectivity *OOAPICheckInInfoWebConnectivity `json:"web_connectivity"`
}

type OOAPICheckReportIDResponse struct {
	Error string `json:"error"`
	Found bool   `json:"found"`
	V     int64  `json:"v"`
}

type OOAPICollectorOpenResponse struct {
	// BackendVersion is the backend version.
	BackendVersion string `json:"backend_version"`

	// ReportID is the report ID.
	ReportID string `json:"report_id"`

	// SupportedFormats contains supported formats.
	SupportedFormats []string `json:"supported_formats"`
}

type OOAPICollectorUpdateRequest struct {
	// Format is the Content's data format
	Format string `json:"format"`

	// Content is the actual report
	Content any `json:"content"`
}

type OOAPICollectorUpdateResponse struct {
	// MeasurementUID is the measurement UID.
	MeasurementUID string `json:"measurement_uid"`
}

type OOAPILoginAuth struct {
	Expire time.Time `json:"expire"`
	Token  string    `json:"token"`
}

type OOAPILoginCredentials struct {
	Username string `json:"username"`
	Password string `json:"password"`
}

type OOAPIMeasurementMeta struct {
	// Fields returned by the API server whenever we are
	// calling /api/v1/measurement_meta.
	Anomaly              bool      `json:"anomaly"`
	CategoryCode         string    `json:"category_code"`
	Confirmed            bool      `json:"confirmed"`
	Failure              bool      `json:"failure"`
	Input                *string   `json:"input"`
	MeasurementStartTime time.Time `json:"measurement_start_time"`
	ProbeASN             int64     `json:"probe_asn"`
	ProbeCC              string    `json:"probe_cc"`
	ReportID             string    `json:"report_id"`
	Scores               string    `json:"scores"`
	TestName             string    `json:"test_name"`
	TestStartTime        time.Time `json:"test_start_time"`

	// This field is only included if the user has specified
	// the config.Full option, otherwise it's empty.
	RawMeasurement string `json:"raw_measurement"`
}

type OOAPIMeasurementMetaConfig struct {
	// ReportID is the mandatory report ID.
	ReportID string

	// Full indicates whether we also want the full measurement body.
	Full bool

	// Input is the optional input.
	Input string
}

type OOAPIProbeMetadata struct {
	AvailableBandwidth string   `json:"available_bandwidth,omitempty"`
	DeviceToken        string   `json:"device_token,omitempty"`
	Language           string   `json:"language,omitempty"`
	NetworkType        string   `json:"network_type,omitempty"`
	Platform           string   `json:"platform"`
	ProbeASN           string   `json:"probe_asn"`
	ProbeCC            string   `json:"probe_cc"`
	ProbeFamily        string   `json:"probe_family,omitempty"`
	ProbeTimezone      string   `json:"probe_timezone,omitempty"`
	SoftwareName       string   `json:"software_name"`
	SoftwareVersion    string   `json:"software_version"`
	SupportedTests     []string `json:"supported_tests"`
}

type OOAPIRegisterRequest struct {
	OOAPIProbeMetadata
	Password string `json:"password"`
}

type OOAPIRegisterResponse struct {
	ClientID string `json:"client_id"`
}

type OOAPIReportTemplate struct {
	// DataFormatVersion is unconditionally set to DefaultDataFormatVersion
	// and you don't need to be concerned about it.
	DataFormatVersion string `json:"data_format_version"`

	// Format is unconditionally set to `json` and you don't need
	// to be concerned about it.
	Format string `json:"format"`

	// ProbeASN is the probe's autonomous system number (e.g. `AS1234`)
	ProbeASN string `json:"probe_asn"`

	// ProbeCC is the probe's country code (e.g. `IT`)
	ProbeCC string `json:"probe_cc"`

	// SoftwareName is the app name (e.g. `measurement-kit`)
	SoftwareName string `json:"software_name"`

	// SoftwareVersion is the app version (e.g. `0.9.1`)
	SoftwareVersion string `json:"software_version"`

	// TestName is the test name (e.g. `ndt`)
	TestName string `json:"test_name"`

	// TestStartTime contains the test start time
	TestStartTime string `json:"test_start_time"`

	// TestVersion is the test version (e.g. `1.0.1`)
	TestVersion string `json:"test_version"`
}

type OOAPIService struct {
	// Address is the address of the server.
	Address string `json:"address"`

	// Type is the type of the service.
	Type string `json:"type"`

	// Front is the front to use with "cloudfront" type entries.
	Front string `json:"front,omitempty"`
}

type OOAPITorTarget struct {
	// Address is the address of the target.
	Address string `json:"address"`

	// Name is the name of the target.
	Name string `json:"name"`

	// Params contains optional params for, e.g., pluggable transports.
	Params map[string][]string `json:"params"`

	// Protocol is the protocol to use with the target.
	Protocol string `json:"protocol"`

	// Source is the source from which we fetched this specific
	// target. Whenever the source is non-empty, we will treat
	// this specific target as a private target.
	Source string `json:"source"`
}

type OOAPIURLInfo struct {
	// CategoryCode is the URL's category (e.g., FEXP, POLT, HUMR).
	CategoryCode string `json:"category_code"`

	// CountryCode is the URL's ISO country code or ZZ for global URLs.
	CountryCode string `json:"country_code"`

	// URL is the string-serialized URL.
	URL string `json:"url"`
}

type OOAPIVPNConfig struct {
	// CA is the Certificate Authority for the endpoints by this provider.
	CA string `json:"ca"`

	// Cert is a valid certificate, for providers that use x509 certificate authentication.
	Cert string `json:"cert,omitempty"`

	// Key is a valid key, for providers that use x509 certificate authentication.
	Key string `json:"key,omitempty"`

	// Username is a valid username, for providers that use password authentication.
	Username string `json:"username,omitempty"`

	// Password is a valid password, for providers that use password authentication.
	Password string `json:"password,omitempty"`
}

type OOAPIVPNProviderConfig struct {
	// Provider is the label for this provider.
	Provider string `json:"provider,omitempty"`

	// Config is the provider-specific VPN Config.
	Config *OOAPIVPNConfig `json:"config"`

	// Inputs is an array of valid endpoints for this provider.
	Inputs []string `json:"endpoints"`

	// DateUpdated is when the credential set was last updated in the server database.
	DateUpdated time.Time `json:"date_updated"`
}

type PerformanceTestKeys struct {
	Upload   float64 `json:"upload"`
	Download float64 `json:"download"`
	Ping     float64 `json:"ping"`
	Bitrate  float64 `json:"median_bitrate"`
}

type PrinterCallbacks struct {
	Logger
}

type QUICDialer interface {
	// DialContext establishes a new QUIC session using the given
	// network and address. The tlsConfig and the quicConfig arguments
	// MUST NOT be nil. Returns either the session or an error.
	//
	// Recommended tlsConfig setup:
	//
	// - set ServerName to be the SNI;
	//
	// - set RootCAs to nil (which causes us to use the default cert pool);
	//
	// - set NextProtos to []string{"h3"}.
	//
	// Typically, you want to pass `&quic.Config{}` as quicConfig.
	DialContext(ctx context.Context, address string,
		tlsConfig *tls.Config, quicConfig *quic.Config) (quic.EarlyConnection, error)

	// CloseIdleConnections closes idle connections, if any.
	CloseIdleConnections()
}

type QUICDialerWrapper interface {
	WrapQUICDialer(qd QUICDialer) QUICDialer
}

type ReadableDatabase interface {
	// ListResults return the list of results
	//
	// Arguments:
	//
	// Returns either the complete and incomplete database results or an error
	ListResults() ([]DatabaseResultNetwork, []DatabaseResultNetwork, error)

	// ListMeasurements given a result ID
	//
	// Arguments:
	//
	// - resultID is the id of the result to search measurements from
	//
	// Returns the measurements under the given result or an error
	ListMeasurements(resultID int64) ([]DatabaseMeasurementURLNetwork, error)

	// GetMeasurementJSON returns a map[string]interface{} given a database and a measurementID
	//
	// Arguments:
	//
	// - msmtID is the measurement id to generate JSON
	//
	// Returns the measurement JSON or an error
	GetMeasurementJSON(msmtID int64) (map[string]interface{}, error)
}

type Resolver interface {
	// LookupHost resolves the given hostname to IP addreses. This function SHOULD handle the
	// case in which hostname is an IP address by returning a 1-element list containing the hostname,
	// for consistency with [net.Resolver] behaviour.
	LookupHost(ctx context.Context, hostname string) (addrs []string, err error)

	// Network returns the resolver type. It should be one of:
	//
	// - go: means we're using whatever resolver the Go stdlib uses
	// depending on the current build configuration;
	//
	// - system: means we've been compiled with `CGO_ENABLED=1`
	// so we can bypass the go resolver and call getaddrinfo directly;
	//
	// - udp: is a custom DNS-over-UDP resolver;
	//
	// - tcp: is a custom DNS-over-TCP resolver;
	//
	// - dot: is a custom DNS-over-TLS resolver;
	//
	// - doh: is a custom DNS-over-HTTPS resolver;
	//
	// - doh3: is a custom DNS-over-HTTP3 resolver.
	//
	// See https://github.com/ooni/probe/issues/2029#issuecomment-1140805266
	// for an explanation of why it would not be proper to call "netgo" the
	// resolver we get by default from the standard library.
	Network() string

	// Address returns the resolver address (e.g., 8.8.8.8:53).
	Address() string

	// CloseIdleConnections closes idle connections, if any.
	CloseIdleConnections()

	// LookupHTTPS issues an HTTPS query for a domain.
	LookupHTTPS(
		ctx context.Context, domain string) (*HTTPSSvc, error)

	// LookupNS issues a NS query for a domain.
	LookupNS(ctx context.Context, domain string) ([]*net.NS, error)
}

type RunType string

type Saver interface {
	SaveMeasurement(m *Measurement) error
}

type SimpleDialer interface {
	// DialContext creates a new TCP/UDP connection like [net.DialContext] would do.
	//
	// The endpoint is an endpoint like the ones accepted by [net.DialContext]. For example,
	// x.org:443, 130.192.91.211:443 and [::1]:443. Note that IPv6 addrs are quoted.
	//
	// This function MUST gracefully handle the case where the endpoint contains an IPv4
	// or IPv6 address by skipping DNS resolution and directly using the endpoint.
	//
	// See https://github.com/ooni/probe-cli/pull/1295#issuecomment-1731243994 for more
	// details on why DialContext MUST do that.
	DialContext(ctx context.Context, network, endpoint string) (net.Conn, error)
}

type Submitter interface {
	// Submit submits the measurement and updates its
	// report ID field in case of success.
	Submit(ctx context.Context, m *Measurement) (string, error)
}

type THDNSResult struct {
	Failure *string  `json:"failure"`
	Addrs   []string `json:"addrs"`
	ASNs    []int64  `json:"-"` // not visible from the JSON
}

type THHTTPRequestResult struct {
	BodyLength           int64             `json:"body_length"`
	DiscoveredH3Endpoint string            `json:"discovered_h3_endpoint"`
	Failure              *string           `json:"failure"`
	Title                string            `json:"title"`
	Headers              map[string]string `json:"headers"`
	StatusCode           int64             `json:"status_code"`
}

type THIPInfo struct {
	// ASN contains the address' AS number.
	ASN int64 `json:"asn"`

	// Flags contains flags describing this address.
	Flags int64 `json:"flags"`
}

type THRequest struct {
	HTTPRequest        string              `json:"http_request"`
	HTTPRequestHeaders map[string][]string `json:"http_request_headers"`
	TCPConnect         []string            `json:"tcp_connect"`

	// XQUICEnabled is a feature flag that tells the oohelperd to
	// conditionally enable QUIC measurements, which are otherwise
	// disabled by default. We will honour this flag during the
	// v3.17.x release cycle and possibly also for v3.18.x but we
	// will eventually enable QUIC for all clients.
	XQUICEnabled bool `json:"x_quic_enabled"`
}

type THResponse struct {
	TCPConnect    map[string]THTCPConnectResult   `json:"tcp_connect"`
	TLSHandshake  map[string]THTLSHandshakeResult `json:"tls_handshake,omitempty"`
	QUICHandshake map[string]THTLSHandshakeResult `json:"quic_handshake"`
	HTTPRequest   THHTTPRequestResult             `json:"http_request"`
	HTTP3Request  *THHTTPRequestResult            `json:"http3_request"` // optional!
	DNS           THDNSResult                     `json:"dns"`
	IPInfo        map[string]*THIPInfo            `json:"ip_info,omitempty"`
}

type THTCPConnectResult struct {
	Status  bool    `json:"status"`
	Failure *string `json:"failure"`
}

type THTLSHandshakeResult struct {
	ServerName string  `json:"server_name"`
	Status     bool    `json:"status"`
	Failure    *string `json:"failure"`
}

type TLSConn interface {
	// net.Conn is the underlying interface
	net.Conn

	// ConnectionState returns the ConnectionState according
	// to the standard library.
	ConnectionState() tls.ConnectionState

	// HandshakeContext performs an TLS handshake bounded
	// in time by the given context.
	HandshakeContext(ctx context.Context) error

	// NetConn returns the underlying net.Conn
	NetConn() net.Conn
}

type TLSDialer interface {
	// CloseIdleConnections closes idle connections, if any.
	CloseIdleConnections()

	// DialTLSContext dials a TLS connection. This method will always return
	// to you a [TLSConn], so you can always safely cast to it.
	//
	// The endpoint is an endpoint like the ones accepted by [net.DialContext]. For example,
	// x.org:443, 130.192.91.211:443 and [::1]:443. Note that IPv6 addrs are quoted.
	//
	// This function MUST gracefully handle the case where the endpoint contains an IPv4
	// or IPv6 address by skipping DNS resolution and directly using the endpoint.
	//
	// See https://github.com/ooni/probe-cli/pull/1295#issuecomment-1731243994 for more
	// details on why DialTLSContext MUST do that.
	DialTLSContext(ctx context.Context, network, address string) (net.Conn, error)
}

type TLSHandshaker interface {
	// Handshake creates a new TLS connection from the given connection and
	// the given config. This function DOES NOT take ownership of the connection
	// and it's your responsibility to close it on failure.
	//
	// Recommended tlsConfig setup:
	//
	// - set ServerName to be the SNI;
	//
	// - set RootCAs to nil (which causes us to use the default cert pool);
	//
	// - set NextProtos to []string{"h2", "http/1.1"} for HTTPS
	// and []string{"dot"} for DNS-over-TLS.
	Handshake(ctx context.Context, conn net.Conn, tlsConfig *tls.Config) (TLSConn, error)
}

type Trace interface {
	// TimeNow returns the current time. Normally, this should be the same
	// value returned by time.Now but you may want to manipulate the time
	// returned when testing to have deterministic tests. To this end, you
	// can use functionality exported by the ./internal/testingx pkg.
	TimeNow() time.Time

	// MaybeWrapNetConn possibly wraps a net.Conn with the caller trace. If there's no
	// desire to wrap the net.Conn, this function just returns the original net.Conn.
	//
	// Arguments:
	//
	// - conn is the non-nil underlying net.Conn to be wrapped
	MaybeWrapNetConn(conn net.Conn) net.Conn

	// MaybeWrapUDPLikeConn is like MaybeWrapNetConn but for UDPLikeConn.
	//
	// Arguments:
	//
	// - conn is the non-nil underlying UDPLikeConn to be wrapped
	MaybeWrapUDPLikeConn(conn UDPLikeConn) UDPLikeConn

	// OnDNSRoundTripForLookupHost is used with a DNSTransport and called
	// when the RoundTrip terminates.
	//
	// Arguments:
	//
	// - started is when we called transport.RoundTrip
	//
	// - reso is the parent resolver for the trace;
	//
	// - query is the non-nil DNS query we use for the RoundTrip
	//
	// - response is a valid DNS response, obtained after the RoundTrip;
	//
	// - addrs is the list of addresses obtained after the RoundTrip, which
	// is empty if the RoundTrip failed
	//
	// - err is the result of DNSLookup; either an error or nil
	//
	// - finished is the time right after the RoundTrip
	OnDNSRoundTripForLookupHost(started time.Time, reso Resolver, query DNSQuery,
		response DNSResponse, addrs []string, err error, finished time.Time)

	// OnDelayedDNSResponse is used with a DNSOverUDPTransport and called
	// when we get delayed, unexpected DNS responses.
	//
	// Arguments:
	//
	// - started is when we started reading the delayed response;
	//
	// - txp is the DNS transport used with the resolver;
	//
	// - query is the non-nil DNS query we use for the RoundTrip;
	//
	// - response is the non-nil valid DNS response, obtained after some delay;
	//
	// - addrs is the list of addresses obtained after decoding the delayed response,
	// which is empty if the response did not contain any addresses, which we
	// extract by calling the DecodeLookupHost method.
	//
	// - err is the result of DecodeLookupHost: either an error or nil;
	//
	// - finished is when we have read the delayed response.
	OnDelayedDNSResponse(started time.Time, txp DNSTransport, query DNSQuery,
		resp DNSResponse, addrs []string, err error, finsihed time.Time) error

	// OnConnectDone is called when connect terminates.
	//
	// Arguments:
	//
	// - started is when we called connect;
	//
	// - network is the network we're using (one of "tcp" and "udp");
	//
	// - domain is the domain for which we're calling connect. If the user called
	// connect for an IP address and a port, then domain will be an IP address;
	//
	// - remoteAddr is the TCP endpoint with which we are connecting: it will
	// consist of an IP address and a port (e.g., 8.8.8.8:443, [::1]:5421);
	//
	// - err is the result of connect: either an error or nil;
	//
	// - finished is when connect returned.
	//
	// The error passed to this function will always be wrapped such that the
	// string returned by Error is an OONI error.
	OnConnectDone(
		started time.Time, network, domain, remoteAddr string, err error, finished time.Time)

	// OnTLSHandshakeStart is called when the TLS handshake starts.
	//
	// Arguments:
	//
	// - now is the moment before we start the handshake;
	//
	// - remoteAddr is the TCP endpoint with which we are connecting: it will
	// consist of an IP address and a port (e.g., 8.8.8.8:443, [::1]:5421);
	//
	// - config is the non-nil TLS config we're using.
	OnTLSHandshakeStart(now time.Time, remoteAddr string, config *tls.Config)

	// OnTLSHandshakeDone is called when the TLS handshake terminates.
	//
	// Arguments:
	//
	// - started is when we started the handshake;
	//
	// - remoteAddr is the TCP endpoint with which we are connecting: it will
	// consist of an IP address and a port (e.g., 8.8.8.8:443, [::1]:5421);
	//
	// - config is the non-nil TLS config we're using;
	//
	// - state is the state of the TLS connection after the handshake, where all
	// fields are zero-initialized if the handshake failed;
	//
	// - err is the result of the handshake: either an error or nil;
	//
	// - finished is right after the handshake.
	//
	// The error passed to this function will always be wrapped such that the
	// string returned by Error is an OONI error.
	OnTLSHandshakeDone(started time.Time, remoteAddr string, config *tls.Config,
		state tls.ConnectionState, err error, finished time.Time)

	// OnQUICHandshakeStart is called before the QUIC handshake.
	//
	// Arguments:
	//
	// - now is the moment before we start the handshake;
	//
	// - remoteAddr is the QUIC endpoint with which we are connecting: it will
	// consist of an IP address and a port (e.g., 8.8.8.8:443, [::1]:5421);
	//
	// - config is the possibly-nil QUIC config we're using.
	OnQUICHandshakeStart(now time.Time, remoteAddr string, quicConfig *quic.Config)

	// OnQUICHandshakeDone is called after the QUIC handshake.
	//
	// Arguments:
	//
	// - started is when we started the handshake;
	//
	// - remoteAddr is the QUIC endpoint with which we are connecting: it will
	// consist of an IP address and a port (e.g., 8.8.8.8:443, [::1]:5421);
	//
	// - qconn is the QUIC connection we receive after the handshake: either
	// a valid quic.EarlyConnection or nil;
	//
	// - config is the non-nil TLS config we are using;
	//
	// - err is the result of the handshake: either an error or nil;
	//
	// - finished is right after the handshake.
	//
	// The error passed to this function will always be wrapped such that the
	// string returned by Error is an OONI error.
	OnQUICHandshakeDone(started time.Time, remoteAddr string, qconn quic.EarlyConnection,
		config *tls.Config, err error, finished time.Time)
}

type UDPLikeConn interface {
	// An UDPLikeConn is a net.PacketConn conn.
	net.PacketConn

	// SetReadBuffer allows setting the read buffer.
	SetReadBuffer(bytes int) error

	// SyscallConn returns a conn suitable for calling syscalls,
	// which is also instrumental to setting the read buffer.
	SyscallConn() (syscall.RawConn, error)
}

type UDPListener interface {
	// Listen creates a new listening UDPLikeConn.
	Listen(addr *net.UDPAddr) (UDPLikeConn, error)
}

type UnderlyingNetwork interface {
	// DefaultCertPool returns the underlying cert pool used by the
	// network extensions library. You MUST NOT use this function to
	// modify the default cert pool since this would lead to a data
	// race. Use [netxlite.netxlite.NewMozillaCertPool] if you wish to get
	// a copy of the default cert pool that you can modify.
	DefaultCertPool() *x509.CertPool

	// DialTimeout returns the default timeout to use for dialing.
	DialTimeout() time.Duration

	// DialContext is equivalent to net.Dialer.DialContext.
	DialContext(ctx context.Context, network, address string) (net.Conn, error)

	// GetaddrinfoLookupANY is like net.Resolver.LookupHost except that it
	// also returns to the caller the CNAME when it is available.
	GetaddrinfoLookupANY(ctx context.Context, domain string) ([]string, string, error)

	// GetaddrinfoResolverNetwork returns the resolver network.
	GetaddrinfoResolverNetwork() string

	// ListenTCP is equivalent to net.ListenTCP.
	ListenTCP(network string, addr *net.TCPAddr) (net.Listener, error)

	// ListenUDP is equivalent to net.ListenUDP.
	ListenUDP(network string, addr *net.UDPAddr) (UDPLikeConn, error)
}

type UploadedTotalCount struct {
	UploadedCount int64 `db:",inline"`
	TotalCount    int64 `db:",inline"`
}

type WritableDatabase interface {
	// CreateNetwork will create a new network in the network table
	//
	// Arguments:
	//
	// - loc: loc is the location provider used to instantiate the network
	//
	// Returns either a database network instance or an error
	CreateNetwork(loc LocationProvider) (*DatabaseNetwork, error)

	// CreateOrUpdateURL will create a new URL entry to the urls table if it doesn't
	// exists, otherwise it will update the category code of the one already in
	// there.
	//
	// Arguments:
	//
	// - urlStr is the URL string to create or update
	//
	// - categoryCode is the category code to update
	//
	// - countryCode is the country code to update
	//
	// Returns either the new URL id or an error
	CreateOrUpdateURL(urlStr string, categoryCode string, countryCode string) (int64, error)

	// CreateResult writes the Result to the database a returns a pointer
	// to the Result
	//
	// Arguments:
	//
	// - homePath is the home directory path to make the results directory
	//
	// - testGroupName is used to annotate the database the result
	//
	// - networkID is the id of the underlying network
	//
	// Returns either a database result instance or an error
	CreateResult(homePath string, testGroupName string, networkID int64) (*DatabaseResult, error)

	// UpdateUploadedStatus will check if all the measurements inside of a given result set have been
	// uploaded and if so will set the is_uploaded flag to true
	//
	// Arguments:
	//
	// - result is the database result to update
	//
	// Returns a non-nil error if update failed
	UpdateUploadedStatus(result *DatabaseResult) error

	// Finished marks the result as done and sets the runtime
	//
	// Arguments:
	//
	// - result is the database result to mark as done
	//
	// Returns a non-nil error if result could not be marked as done
	Finished(result *DatabaseResult) error

	// DeleteResult will delete a particular result and the relative measurement on
	// disk.
	//
	// Arguments:
	//
	// - resultID is the id of the database result to be deleted
	//
	// Returns a non-nil error if result could not be deleted
	DeleteResult(resultID int64) error

	// CreateMeasurement writes the measurement to the database a returns a pointer
	// to the Measurement
	//
	// Arguments:
	//
	// - reportID is the report id to annotate
	//
	// - testName is the experiment name to use
	//
	// - measurementDir is the measurement directory path
	//
	// - resultID is the result id to annotate
	//
	// - urlID is the id of the URL input
	//
	// Returns either a database measurement or an error
	CreateMeasurement(reportID sql.NullString, testName string, measurementDir string, idx int,
		resultID int64, urlID sql.NullInt64) (*DatabaseMeasurement, error)

	// AddTestKeys writes the summary to the measurement
	//
	// Arguments:
	//
	// - msmt is the database measurement to update
	//
	// - tk is the testkeys
	//
	// Returns a non-nil error if measurement update failed
	AddTestKeys(msmt *DatabaseMeasurement, tk MeasurementSummaryKeys) error

	// Done marks the measurement as completed
	//
	// Arguments:
	//
	// - msmt is the database measurement to update
	//
	// Returns a non-nil error if the measurement could not be marked as done
	Done(msmt *DatabaseMeasurement) error

	// UploadFailed writes the error string for the upload failure to the measurement
	//
	// Arguments:
	//
	// - msmt is the database measurement to update
	//
	// - failure is the error string to use
	//
	// Returns a non-nil error if the measurement update failed
	UploadFailed(msmt *DatabaseMeasurement, failure string) error

	// UploadSucceeded writes the error string for the upload failure to the measurement
	//
	// Arguments:
	//
	// - msmt is the database measurement to update
	//
	// Returns a non-nil error is measurement update failed
	UploadSucceeded(msmt *DatabaseMeasurement) error

	// Failed writes the error string to the measurement
	//
	// Arguments:
	//
	// - msmt is the database measurement to update
	//
	// - failure is the error string to use
	//
	// Returns a non-nil error if the measurement update failed
	Failed(msmt *DatabaseMeasurement, failure string) error
}