model

type ArchivalBinaryData struct {
	Format string `json:"format"`
	Data   []byte `json:"data"`
}

type ArchivalDNSAnswer struct {
	ALPN       string  `json:"alpn,omitempty"`
	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"`
	NS         string  `json:"ns,omitempty"`
	TTL        *uint32 `json:"ttl,omitempty"`
}

type ArchivalDNSLookupResult struct {
	Answers          []ArchivalDNSAnswer `json:"answers"`
	Engine           string              `json:"engine"`
	Failure          *string             `json:"failure"`
	Hostname         string              `json:"hostname"`
	QueryType        string              `json:"query_type"`
	RawQuery         *ArchivalBinaryData `json:"raw_query,omitempty"`
	RawReply         *ArchivalBinaryData `json:"raw_reply,omitempty"`
	ResolverHostname *string             `json:"resolver_hostname,omitempty"`
	ResolverPort     *string             `json:"resolver_port,omitempty"`
	ResolverAddress  string              `json:"resolver_address,omitempty"`
	Started          float64             `json:"started"`
	T                float64             `json:"t"`
}

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

type ArchivalHTTPBody = ArchivalMaybeBinaryData

type ArchivalHTTPBodyOrTLSH struct {
	// Body is the real body
	Body ArchivalHTTPBody

	// Flags contains flags controlling the serialization
	Flags int64

	// TLSH is the hash
	TLSH string
}

type ArchivalHTTPBodyTLSH struct {
	Format string `json:"format"`
	Data   string `json:"data"`
}

type ArchivalHTTPHeader struct {
	Key   string
	Value ArchivalMaybeBinaryData
}

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

type ArchivalHTTPRequestResult struct {
	Failure  *string              `json:"failure"`
	Request  ArchivalHTTPRequest  `json:"request"`
	Response ArchivalHTTPResponse `json:"response"`
	Started  float64              `json:"started"`
	T        float64              `json:"t"`
}

type ArchivalHTTPResponse struct {
	Body            ArchivalHTTPBodyOrTLSH             `json:"body"`
	BodyLength      int64                              `json:"body_length"`
	BodyIsTruncated bool                               `json:"body_is_truncated"`
	BodyTLSH        string                             `json:"body_tlsh"`
	Code            int64                              `json:"code"`
	HeadersList     []ArchivalHTTPHeader               `json:"headers_list"`
	Headers         map[string]ArchivalMaybeBinaryData `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 ArchivalMaybeBinaryData struct {
	Value []byte
}

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"`
	Started   float64  `json:"started"`
	T         float64  `json:"t"`
	Tags      []string `json:"tags,omitempty"`
}

type ArchivalTCPConnectResult struct {
	IP      string                   `json:"ip"`
	Port    int                      `json:"port"`
	Status  ArchivalTCPConnectStatus `json:"status"`
	Started float64                  `json:"started"`
	T       float64                  `json:"t"`
}

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

type ArchivalTLSOrQUICHandshakeResult struct {
	Address            string                    `json:"address"`
	CipherSuite        string                    `json:"cipher_suite"`
	Failure            *string                   `json:"failure"`
	NegotiatedProtocol string                    `json:"negotiated_protocol"`
	NoTLSVerify        bool                      `json:"no_tls_verify"`
	PeerCertificates   []ArchivalMaybeBinaryData `json:"peer_certificates"`
	Proto              string                    `json:"proto"`
	ServerName         string                    `json:"server_name"`
	Started            float64                   `json:"started"`
	T                  float64                   `json:"t"`
	Tags               []string                  `json:"tags"`
	TLSVersion         string                    `json:"tls_version"`
}

type DNSDecoder interface {
	// DecodeLookupHost decodes an A or AAAA reply.
	//
	// Arguments:
	//
	// - qtype is the query type (e.g., dns.TypeAAAA)
	//
	// - data contains the reply bytes read from a DNSTransport
	//
	// - queryID is the original query ID
	//
	// Returns:
	//
	// - on success, a list of IP addrs inside the reply and a nil error
	//
	// - on failure, a nil list and an error.
	//
	// Note that this function will return an error if there is no
	// IP address inside of the reply.
	//
	// Note that the error returned by this function is not wrapped and
	// it is your responsiblity to wrap it if needed.
	DecodeLookupHost(qtype uint16, data []byte, queryID uint16) ([]string, error)

	// DecodeLookupHTTPS decodes an HTTPS reply.
	//
	// The argument is the reply as read by the DNSTransport.
	//
	// On success, this function returns an HTTPSSvc structure and
	// a nil error. On failure, the HTTPSSvc pointer is nil and
	// the error points to the error that occurred.
	//
	// This function will return an error if the HTTPS reply does not
	// contain at least a valid ALPN entry. It will not return
	// an error, though, when there are no IPv4/IPv6 hints in the reply.
	//
	// Note that the error returned by this function is not wrapped and
	// it is your responsiblity to wrap it if needed.
	DecodeLookupHTTPS(data []byte, queryID uint16) (*HTTPSSvc, error)

	// DecodeLookupNS is like DecodeLookupHTTPS but for NS queries.
	DecodeLookupNS(data []byte, queryID uint16) ([]*net.NS, error)

	// DecodeLookupPTR is like DecodeLookupNS but for PTR queries.
	DecodeLookupPTR(data []byte, queryID uint16) ([]string, error)

	// ParseReply parses a reply without decoding it. This function
	// will ONLY return error if data is not a valid DNS message. In
	// particular, it WILL NOT return any error that depends on the
	// Rcode. That is, if the Rcode is NXDOMAIN, this function
	// will still return success anyway. To map NXDOMAIN and other
	// errors, you need to use DecodeReplyLookup{Host,HTTPS}.
	//
	// Note that the error returned by this function is not wrapped and
	// it is your responsiblity to wrap it if needed.
	ParseReply(data []byte) (*dns.Msg, error)

	// ParseReplyForQueryID parses a reply for the specific queryID. This
	// function is like ParseReply but also ensures that the reply we parse
	// has the same query ID of the query we sent.
	ParseReplyForQueryID(data []byte, queryID uint16) (*dns.Msg, error)

	// ParseQuery parses a DNS query.
	ParseQuery(data []byte) (*dns.Msg, error)

	// DecodeReplyLookupHost is like DecodeLookupHost but acts
	// on an already parsed reply rather than on data.
	//
	// Note that the error returned by this function is not wrapped and
	// it is your responsiblity to wrap it if needed.
	DecodeReplyLookupHost(qtype uint16, reply *dns.Msg) ([]string, error)

	// DecodeReplyLookupHTTPS is like DecodeLookupHTTPS but acts
	// on an already parsed reply rather than on data.
	//
	// Note that the error returned by this function is not wrapped and
	// it is your responsiblity to wrap it if needed.
	DecodeReplyLookupHTTPS(reply *dns.Msg) (*HTTPSSvc, error)

	// DecodeReplyLookupNS is like DecodeReplyLookupHTTPS but for NS queries.
	DecodeReplyLookupNS(reply *dns.Msg) ([]*net.NS, error)

	// DecodeReplyLookupPTR is like DecodeReplyLookupNS but for PTR queries.
	DecodeReplyLookupPTR(reply *dns.Msg) ([]string, error)
}

type DNSEncoder interface {
	// EncodeQuery transforms its arguments into a serialized DNS query.
	//
	// 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.
	//
	// On success, this function returns a valid byte array, the query ID
	// and a nil error. On failure, only the error matters.
	EncodeQuery(domain string, qtype uint16, padding bool) ([]byte, uint16, error)

	// EncodeReply encodes a reply for the given query given some addresses.
	EncodeReply(query *dns.Msg, addresses []string) (*dns.Msg, error)
}

type DNSTransport interface {
	// RoundTrip sends a DNS query and receives the reply.
	RoundTrip(ctx context.Context, query []byte) (reply []byte, err 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 DebugLogger interface {
	// Debug emits a debug message.
	Debug(msg string)

	// Debugf formats and emits a debug message.
	Debugf(format string, v ...interface{})
}

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

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

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
}

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

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

	// CloseIdleConnections closes idle connections.
	CloseIdleConnections()
}

type InfoLogger interface {
	// An InfoLogger is also a DebugLogger.
	DebugLogger

	// Info emits an informational message.
	Info(msg string)

	// Infof formats and emits an informational message.
	Infof(format string, v ...interface{})
}

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 Logger interface {
	// A Logger is also an InfoLogger.
	InfoLogger

	// Warn emits a warning message.
	Warn(msg string)

	// Warnf formats and emits a warning message.
	Warnf(format string, v ...interface{})
}

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 MeasurementTarget `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 probe-engine 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 MeasurementTarget string

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 NewDefaultCertPool();
	//
	// - set NextProtos to []string{"h3"}.
	//
	// Typically, you want to pass `&quic.Config{}` as quicConfig.
	DialContext(ctx context.Context, network, address string,
		tlsConfig *tls.Config, quicConfig *quic.Config) (quic.EarlySession, error)

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

type Resolver interface {
	// LookupHost behaves like net.Resolver.LookupHost.
	LookupHost(ctx context.Context, hostname string) (addrs []string, err error)

	// Network returns the resolver type (e.g., system, dot, doh).
	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)

	// LookupPTR issues a PTR query for a domain. To perform a reverse DNS lookup
	// you need to reverse the IP addr first using miekg/dns.ReverseAddr.
	LookupPTR(ctx context.Context, domain string) ([]string, error)
}

type SimpleDialer interface {
	// DialContext behaves like net.Dialer.DialContext.
	DialContext(ctx context.Context, network, address string) (net.Conn, error)
}

type TLSConn = oohttp.TLSConn

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

	// DialTLSContext dials a TLS connection. This method will always return
	// to you a oohttp.TLSConn, so you can always safely cast to it.
	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 NewDefaultCertPool();
	//
	// - set NextProtos to []string{"h2", "http/1.1"} for HTTPS
	// and []string{"dot"} for DNS-over-TLS.
	//
	// QUIRK: The returned connection will always implement the TLSConn interface
	// exposed by ooni/oohttp. A future version of this interface may instead
	// return directly a TLSConn to avoid unconditional castings.
	Handshake(ctx context.Context, conn net.Conn, tlsConfig *tls.Config) (
		net.Conn, tls.ConnectionState, error)
}

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 UnderlyingNetworkLibrary interface {
	// ListenUDP creates a new model.UDPLikeConn conn.
	ListenUDP(network string, laddr *net.UDPAddr) (UDPLikeConn, error)

	// LookupHost lookups a domain using the stdlib resolver.
	LookupHost(ctx context.Context, domain string) ([]string, error)

	// NewSimpleDialer returns a new SimpleDialer.
	NewSimpleDialer(timeout time.Duration) SimpleDialer
}