formats: document dns errors and resolver types (#242)

See ooni/probe-cli#765, where I identified I needed to sync up spec with probe-cli. ## Checklist - [x] I have read the [contribution guidelines](https://github.com/ooni/spec/blob/master/CONTRIBUTING.md) - [x] reference issue for this pull request: ooni/probe#2029 - [x] related ooni/probe-cli pull request: ooni/probe-cli#765 - [x] If I changed a spec, I also bumped its version number and/or date
ooni · May 30, 2022 · f51921d · f51921d
1 parent f647f9b
commit f51921d
Show file tree

Hide file tree

Showing 2 changed files with 48 additions and 12 deletions.
diff --git a/data-formats/df-002-dnst.md b/data-formats/df-002-dnst.md
@@ -46,7 +46,8 @@ be unique during a measurement session.
 
 - `engine` (`string`; optional): the specific engine used to perform
 the DNS query. If omitted implies `"system"`, which means that we are
-using in a way or another `getaddrinfo`.
+using in a way or another `getaddrinfo`. See also below for a list
+of available resolver engines.
 
 - `failure` (`string`; nullable): if there was an error, this field is
 a string indicating the error, otherwise it MUST be `null`.
@@ -74,6 +75,24 @@ measured in the moment in which `failure` is determined.
 - `transaction_id` (`int`; optional; since 2020-01-11): if present, this is the
 ID of the HTTP transaction that caused this query.
 
+### DNS resolver engines
+
+The following table documents the available DNS resolver engines.
+
+| Engine name | Description |
+| :---------- | ----------- |
+| system      | We are using getaddrinfo |
+| netgo       | We are using Golang's "netgo" DNS resolver |
+| udp         | Custom DNS-over-UDP resolver |
+| tcp         | Custom DNS-over-TCP resolver |
+| dot         | Custom DNS-over-TLS resolver |
+| doh         | Custom DNS-over-HTTPS resolver |
+
+Before 2022-05-29 (i.e., for `ooniprobe<3.16.0`), we did not distinguish
+between cases where we were using getaddrinfo and cases where we were
+using the netgo resolver (see [ooni/probe-cli#765](
+https://github.com/ooni/probe-cli/pull/765)).
+
 ## Answer
 
 ```JSON

diff --git a/data-formats/df-007-errors.md b/data-formats/df-007-errors.md
@@ -16,32 +16,49 @@ For clarity, we would look at the errors currently faced, separately
 from the legacy errors. Following are the errors emitted by
 ooni/probe-engine and/or Mesurement Kit.
 
+
 |            Error               |Flag(s)|Details|
-|:------------------------------:|:-----:|:-----:|
-|`null`                          |   -   |no error has occurred|
-|`"connection_refused"`          |MK, PE |ECONNREFUSED|
-|`"connection_reset"`            |MK, PE |ECONNRESET|
-|`"dns_bogon_error"`             |  PE   |detected bogon in DNS reply|
-|`"dns_nxdomain_error"`          |  PE   |NXDOMAIN in DNS reply|
+|:-------------------------------|:------|:------|
+|`null`                          |PL,MK,PE   |no error has occurred|
+|`"android_dns_cache_no_data"`   |  PE   |DNS lookup using `getaddrinfo` failed and we have no way of knowing why (see [ooni/probe#2029](https://github.com/ooni/probe/issues/2029#issuecomment-1140258729))|
+|`"connection_aborted"`          |MK, PE |`ECONNABORTED`|
+|`"connection_already_closed"`   |  PE   |I/O on socket interrupted by another thread closing the socket itself (you can generally ignore this error)|
+|`"connection_refused"`          |MK, PE |`ECONNREFUSED`|
+|`"connection_reset"`            |MK, PE |`ECONNRESET`|
+|`"dns_bogon_error"`             |  PE   |detected bogon in DNS response|
+|`"dns_no_answer"`               |  PE   |successful DNS response but no answer matching the query type (e.g., no `AAAA` record for domain)|
+|`"dns_non_recoverable_failure"` |  PE   |non-recoverable DNS lookup failure (mostly when using Windows' `getaddrinfo`)|
+|`"dns_nxdomain_error"`          |  PE   |`NXDOMAIN` Rcode in DNS response|
+|`"dns_reply_with_wrong_query_id"`| PE   |The DNS response ID doesn't match the query ID|
+|`"dns_refused_error"`           |  PE   |`Refused` RCode in DNS response|
+|`"dns_server_misbehaving"`      |  PE   |generic error indicating DNS failure without more specific reasons on the kind of failure|
+|`"dns_servfail_error"`          |  PE   |`Servfail` RCode in DNS response|
+|`"dns_temporary_failure"`       |  PE   |temporary DNS failure (mostly when using Windows' `getaddrinfo`)|
 |`"eof_error"`                   |MK, PE |unexpected EOF on connection|
 |`"http_request_failed"`         |MK, PE |HTTP request did not return a successful response code|
-|`"generic_timeout_error"`       |   -   |some timer has expired|
+|`"host_unreachable"`            |MK, PE |`EHOSTUNREACH`|
+|`"generic_timeout_error"`       |PL,MK,PE |error returned when a timeout expires|
 |`"http_unexpected_redirect_url"`|  PE   |we expected a specific redirect URL and instead we saw either no redirect URL or a different redirect URL|
 |`"http_unexpected_status_code"` |  PE   |we did not expected to see this status code (e.g. we expected a redirection and saw something else)|
 |`"interrupted"`                 |  PE   |the user interrupted us by cancelling the context|
 |`"json_parse_error"`            |MK, PE |parsing of a JSON failed|
+|`"network_down"`                |MK, PE |`ENETDOWN`|
+|`"network_reset"`               |MK, PE |`ENETRESET`|
+|`"network_unreachable"`         |MK, PE |`ENETUNREACH`|
+|`"quic_incompatible_version"`   |  PE   |QUIC version negotiation failed|
+|`"ssl_failed_handshake"`        |  PE   |TLS/QUIC handshake failed for unknown reasons|
 |`"ssl_invalid_hostname"`        |MK, PE |certificate not valid for SNI|
-|`"ssl_unknown_autority"`        |  PE   |cannot find CA validating certificate|
+|`"ssl_unknown_authority"`       |  PE   |cannot find CA validating certificate|
 |`"ssl_invalid_certificate"`     |MK, PE |e.g. certificate expired|
-|`"unknown_failure ..."`         |   -   |any other error|
+|`"unknown_failure ..."`         |PL,MK,PE |any other error|
 
 
 
 The ooni/probe-legacy contains mostly the legacy errors, listed below.
 
 
 |              Error                   |Details|
-|:------------------------------------:|:-----:|
+|:-------------------------------------|:------|
 |`"socks_error"`                       |Generic error in SOCKS code. <mark>Also an (MK) error</mark>|
 |`"address_family_not_supported_error"`|[socket.gaierror](https://docs.python.org/3.8/library/socket.html#socket.gaierror)|
 |`"connect_error"`                     |[t.i.e.ConnectError](https://twistedmatrix.com/documents/15.4.0/api/twisted.internet.error.ConnectError.html)||
@@ -62,4 +79,4 @@ The ooni/probe-legacy contains mostly the legacy errors, listed below.
 |`"socks_server_failure"`              |[txsocksx.errors.ServerFailure](https://github.com/habnabit/txsocksx/blob/59ac4e088ea064ae9ee44ac371df3ed46ca3b92f/txsocksx/errors.py)|
 |`"socks_ttl_expired"`                 |[txsocksx.errors.TTLExpired](https://github.com/habnabit/txsocksx/blob/59ac4e088ea064ae9ee44ac371df3ed46ca3b92f/txsocksx/errors.py)|
 |`"task_timed_out"`                    |a task has timed out|
-|`"tcp_timed_out_error"`               |[t.i.e.TCPTimedOutError](https://twistedmatrix.com/documents/15.4.0/api/twisted.internet.error.TCPTimedOutError.html)|
+|`"tcp_timed_out_error"`               |[t.i.e.TCPTimedOutError](https://twistedmatrix.com/documents/15.4.0/api/twisted.internet.error.TCPTimedOutError.html)|