// -=-=- StartHere -=-=-
//
// # Chapter I: using the system resolver
//
// In this chapter we explain how to measure DNS resolutions performed
// using the system resolver. *En passant*, we will also introduce you to
// the `Measurer`, which we will use for the rest of the tutorial.
//
// (This file is auto-generated. Do not edit it directly! To apply
// changes you need to modify `./internal/tutorial/measurex/chapter01/main.go`.)
//
// ## The system resolver
//
// We define "system resolver" as the DNS resolver implemented by the C
// library. On Unix, the most popular interface to such a resolver is
// the `getaddrinfo(3)` C library function.
//
// Most OONI experiments (also known as nettests) use the system
// resolver to map domain names to IP addresses. The advantage of
// the system resolver is that it's provided by the system. So,
// it should _generally_ work. Also, it is the resolver that the
// user of the system will use every day, therefore its results
// should be representative (even though the rise of DNS over
// HTTPS embedded in browsers may make this statement less solid
// than it were ten years ago).
//
// The disadvantage of the system resolver is that we do not
// know how it is configured. Say the user has configured a
// DNS over TLS resolver; then the measurements may miss censorship
// that we would otherwise see if using a custom DNS resolver.
//
// Now that we have justified why the system resolver is
// important for OONI, let us perform some measurements with it.
//
// We will first write a simple `main.go` file that shows how to use
// this functionality. Then, we will show some runs of this file, and
// we will comment the output that we see.
//
// ## main.go
//
// We declare the package and import useful packages. The most
// important package we're importing here is, of course, `internal/measurex`.
//
// ```Go
package main
import (
"context"
"encoding/json"
"flag"
"fmt"
"time"
"github.com/ooni/probe-cli/v3/internal/measurex"
"github.com/ooni/probe-cli/v3/internal/runtimex"
)
func main() {
// ```
// ### Setup
//
// We define command line flags useful to test this program. We use
// the `flags` package for that. We want the user to be able to configure
// both the domain name to resolve and the resolution timeout.
//
// ```Go
domain := flag.String("domain", "example.com", "domain to resolve")
timeout := flag.Duration("timeout", 60*time.Second, "timeout to use")
// ```
//
// We call `flag.Parse` to parse the CLI flags.
//
// ```Go
flag.Parse()
// ```
//
// We create a context and we attach a timeout to it. (This is a pretty
// standard way of configuring a timeout in Go.)
//
// ```Go
ctx, cancel := context.WithTimeout(context.Background(), *timeout)
defer cancel()
// ```
//
// ### Creating a Measurer
//
// Now we create a `Measurer`.
//
// ```Go
mx := measurex.NewMeasurerWithDefaultSettings()
// ```
//
// The `Measurer` is a concrete type that contains many fields
// requiring initialization. For this reason, we provide a factory
// that creates one with default settings. The expected usage
// pattern is that you do not modify a `Measurer`'s field after
// initialization. Modifying them while the `Measurer` is in
// use could, in fact, lead to races.
//
// Let's now invoke the system resolver to resolve `*domain`!
//
// ### Invoking the system resolver
//
// We call the `LookupHostSystem` method of the `Measurer`. The
// arguments are the Context, that in this case carries the timeout
// we configured above, and the domain to resolve.
//
// The call itself is named `LookupHost` because this is the name
// used by the Go function that performs a domain lookup.
//
// Under the hood, `mx.LookupHostSystem` will eventually call
// `(*net.Resolver).LookupHost`. In turn, in the common case on
// Unix, this function will eventually call `getaddrinfo(3)`.
//
// ```Go
m := mx.LookupHostSystem(ctx, *domain)
// ```
//
// The return value of `(*net.Resolver).LookupHost` is either a
// list of IP addresses or an error. Our `LookupHostSystem` method,
// instead, returns a `*measurex.DNSMeasurement` type.
//
// This is probably a good moment to remind you of Go's
// built in help system. We could include a definition of the
// `DNSMeasurement` structure, but since this definition is
// just a comment in the main.go file, it might age badly.
//
// Instead, if you run
//
// ```
// go doc ./internal/measurex.DNSMeasurement
// ```
//
// You get the current definition. As you can see, this type
// is basically just a wrapper around `Measurement`. Now,
// checking the docs of `Measurement` with
//
// ```
// go doc ./internal/measurex.Measurement
// ```
//
// we can see a container of events
// classified by event type. In our case, because we're
// doing a `LookupHost`, we should have at least one entry
// inside of the `Measurement.LookupHost` field.
//
// This entry is of type `DNSLookupEvent`. Let us check
// together the definition of this type:
//
// ```
// go doc ./internal/measurex.DNSLookupEvent
// ```
//
// If you are familiar with [the OONI data format specs](
// https://github.com/ooni/spec/tree/master/data-formats), you
// should probably recognize that this structure is the Go
// representation of the `df-002-dnst` data format.
//
// In fact, every event field inside of a `Measurement`
// should serialize nicely to JSON to one of the OONI data
// formats.
//
// ### Printing the measurement
//
// Because there is a close relationship between the
// events inside a `Measurement` and the JSON OONI data
// format, in the remainder of this program we're
// going to serialize the `Measurement` to JSON and
// print it to the standard output.
//
// Rather than serializing the raw `Measurement` struct,
// we first convert it to the "archival" format. This is the
// data format specified at [ooni/spec](https://github.com/ooni/spec/tree/master/data-formats).
//
// ```Go
data, err := json.Marshal(measurex.NewArchivalDNSMeasurement(m))
runtimex.PanicOnError(err, "json.Marshal failed")
fmt.Printf("%s\n", string(data))
// ```
//
// As a final note, the `PanicOnError` is here because the
// message `m` *can* be marshalled to JSON. It still feels a
// bit better having an assertion for our assumptions than
// outrightly ignoring the error code. (We tend to use such
// a convention quite frequently in the OONI codebase.)
//
// ```Go
}
// ```
//
// ## Running the example program
//
// Let us run the program with default arguments first. You can do
// this operation by running:
//
// ```bash
// go run -race ./internal/tutorial/measurex/chapter01 | jq
// ```
//
// Where `jq` is being used to make the output more presentable.
//
// If you do that you obtain some logging messages, which are out of
// the scope of this tutorial, and the following JSON:
//
// ```JSON
// {
// "domain": "example.com",
// "queries": [
// {
// "answers": [
// {
// "answer_type": "A",
// "ipv4": "93.184.216.34"
// }
// ],
// "engine": "system",
// "failure": null,
// "hostname": "example.com",
// "query_type": "A",
// "resolver_address": "",
// "t": 0.002996459,
// "started": 9.8e-05,
// "oddity": ""
// },
// {
// "answers": [
// {
// "answer_type": "AAAA",
// "ivp6": "2606:2800:220:1:248:1893:25c8:1946"
// }
// ],
// "engine": "system",
// "failure": null,
// "hostname": "example.com",
// "query_type": "AAAA",
// "resolver_address": "",
// "t": 0.002996459,
// "started": 9.8e-05,
// "oddity": ""
// }
// ]
// }
// ```
//
// This JSON [implements the df-002-dnst](https://github.com/ooni/spec/blob/master/data-formats/df-002-dnst.md)
// OONI data format.
//
// You see that we have two messages here. OONI splits a DNS
// resolution performed using the system resolver into two "fake"
// DNS resolutions for A and AAAA. (Under the hood, this is
// what the system resolver would most likely do.)
//
// The most important fields are:
//
// - _engine_, indicating that we are using the "system" resolver;
//
// - _hostname_, meaning that we wanted to resolve the "example.com" domain;
//
// - _answers_, which contains a list of answers;
//
// - _t_, which is the time when the LookupHost operation completed.
//
// ### NXDOMAIN measurement
//
// Let us now change the domain to resolve to be `antani.ooni.org` (a
// nonexisting domain), which we can do by running this command:
//
// ```bash
// go run -race ./internal/tutorial/measurex/chapter01 -domain antani.ooni.org | jq
// ```
//
// This is the output JSON:
//
// ```JSON
// {
// "domain": "antani.ooni.org",
// "queries": [
// {
// "answers": null,
// "engine": "system",
// "failure": "dns_nxdomain_error",
// "hostname": "antani.ooni.org",
// "query_type": "A",
// "resolver_address": "",
// "t": 0.072963834,
// "started": 0.000125417,
// "oddity": "dns.lookup.nxdomain"
// },
// {
// "answers": null,
// "engine": "system",
// "failure": "dns_nxdomain_error",
// "hostname": "antani.ooni.org",
// "query_type": "AAAA",
// "resolver_address": "",
// "t": 0.072963834,
// "started": 0.000125417,
// "oddity": "dns.lookup.nxdomain"
// }
// ]
// }
// ```
//
// So we see a failure that says there was indeed an NXDOMAIN
// error and we also see a field named `oddity`.
//
// What is an oddity? We define oddity something unexpected thay
// may be explained by censorship as well as by a transient failure
// or other normal network conditions. (In this case, the result
// is perfectly normal since we're looking up a nonexistent domain.)
//
// The difference between failure and oddity is that the failure
// indicates the error that occurred, while the oddity classifies
// the error in the context of the operation during which it
// occurred. (In this case the difference is subtle, but we'll
// have a better example later, when we'll see what happens on timeout.)
//
// Failures are specified in
// [df-007-errors](https://github.com/ooni/spec/blob/master/data-formats/df-007-errors.md).
// Inside the `internal/netxlite/errorsx`
// package, there is code that maps Go errors to failures. (The
// `netxlite` package is the fundamental network package we use, on
// top of which `measurex` is written.)
//
// ### Measurement with timeout
//
// Let us now try with an insanely low timeout:
//
// ```bash
// go run -race ./internal/tutorial/measurex/chapter01 -timeout 250us | jq
// ```
//
// To get this JSON:
//
// ```JSON
// {
// "domain": "example.com",
// "queries": [
// {
// "answers": null,
// "engine": "system",
// "failure": "generic_timeout_error",
// "hostname": "example.com",
// "query_type": "A",
// "resolver_address": "",
// "t": 0.000489167,
// "started": 9.2583e-05,
// "oddity": "dns.lookup.timeout"
// },
// {
// "answers": null,
// "engine": "system",
// "failure": "generic_timeout_error",
// "hostname": "example.com",
// "query_type": "AAAA",
// "resolver_address": "",
// "t": 0.000489167,
// "started": 9.2583e-05,
// "oddity": "dns.lookup.timeout"
// }
// ]
// }
// ```
//
// You should now better see the difference between a failure and
// an oddity. The context timeout maps to a `generic_timeout_error` while
// the oddity clearly indicates the timeout happens during a DNS
// lookup. As we mentioned above, the failure is just an error while
// an oddity is an error put in context.
//
// ## Conclusions
//
// This is it. We have seen how to measure with the system resolver and we have
// also seen which easy-to-provoke errors we can get.
//
// -=-=- StopHere -=-=-