c/ooni-probe-cli
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

Edits to the measurex tutorial (#534)

Browse Source
This commit is contained in:
Arturo Filastò 2021-10-11 17:48:45 +02:00 committed by GitHub
parent 1ffb2db0ca
commit 46e00888ae
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
14 changed files with 58 additions and 58 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

8
internal/tutorial/measurex/chapter03/README.md
View File

@ -30,7 +30,7 @@ import (
)
func main() {
query := flag.String("query", "example.com", "domain to resolver")
query := flag.String("query", "example.com", "domain to resolve")
address := flag.String("address", "8.8.4.4:53", "DNS-over-UDP server address")
timeout := flag.Duration("timeout", 60*time.Second, "timeout to use")
flag.Parse()
@ -429,9 +429,9 @@ Here's the corresponding JSON:
}
```
We see that we do fail with a timeout (I have marked some of them
We see that we fail with a timeout (I have marked some of them
with comments inside the JSON). We see the timeout at three different
level of abstractions (from lower to higher abstraction): at the socket layer,
levels of abstractions (from lower to higher abstraction): at the socket layer,
during the DNS round trip, during the DNS lookup.
What we also see is that `t`'s value is ~5s when the `read` event
@ -562,6 +562,6 @@ Here's the answer I get:
## Conclusion
We have seen how we sending DNS queries over UDP, measure the
We have seen how to send DNS queries over UDP, measure the
results, and what happens on common error conditions.

8
internal/tutorial/measurex/chapter03/main.go
View File

@ -31,7 +31,7 @@ import (
)
func main() {
query := flag.String("query", "example.com", "domain to resolver")
query := flag.String("query", "example.com", "domain to resolve")
address := flag.String("address", "8.8.4.4:53", "DNS-over-UDP server address")
timeout := flag.Duration("timeout", 60*time.Second, "timeout to use")
flag.Parse()
@ -430,9 +430,9 @@ func main() {
// }
// ```
//
// We see that we do fail with a timeout (I have marked some of them
// We see that we fail with a timeout (I have marked some of them
// with comments inside the JSON). We see the timeout at three different
// level of abstractions (from lower to higher abstraction): at the socket layer,
// levels of abstractions (from lower to higher abstraction): at the socket layer,
// during the DNS round trip, during the DNS lookup.
//
// What we also see is that `t`'s value is ~5s when the `read` event
@ -563,7 +563,7 @@ func main() {
//
// ## Conclusion
//
// We have seen how we sending DNS queries over UDP, measure the
// We have seen how to send DNS queries over UDP, measure the
// results, and what happens on common error conditions.
//
// -=-=- StopHere -=-=-

8
internal/tutorial/measurex/chapter04/README.md
View File

@ -192,8 +192,8 @@ https://github.com/ooni/spec/tree/master/data-formats.
### Suggested follow-up experiments
Try to run experiments in the following scenarios, and
check the output JSON to familiarize with what changes in
different error conditions.
check the output JSON to familiarize yourself with what
changes in different error conditions.
1. measurement that causes timeout
@ -217,7 +217,7 @@ Here are the commands I used for each proposed exercise:
4. go run -race ./internal/tutorial/measurex/chapter04 -address 104.154.89.105:443 -sni expire.badssl.com
To emulate the two last scenario, if you're on Linux, a
To emulate the last two scenarios, if you're on Linux, a
possibility is building Jafar with this command:
```
@ -243,5 +243,5 @@ Likewise, you can obtain a timeout using the
## Conclusion
We have seen how to measure TLS handshakes. We have seen how
this flow produces different output on different error conditions.
this flow produces a different output on different error conditions.

8
internal/tutorial/measurex/chapter04/main.go
View File

@ -193,8 +193,8 @@ func main() {
// ### Suggested follow-up experiments
//
// Try to run experiments in the following scenarios, and
// check the output JSON to familiarize with what changes in
// different error conditions.
// check the output JSON to familiarize yourself with what
// changes in different error conditions.
//
// 1. measurement that causes timeout
//
@ -218,7 +218,7 @@ func main() {
//
// 4. go run -race ./internal/tutorial/measurex/chapter04 -address 104.154.89.105:443 -sni expire.badssl.com
//
// To emulate the two last scenario, if you're on Linux, a
// To emulate the last two scenarios, if you're on Linux, a
// possibility is building Jafar with this command:
//
// ```
@ -244,6 +244,6 @@ func main() {
// ## Conclusion
//
// We have seen how to measure TLS handshakes. We have seen how
// this flow produces different output on different error conditions.
// this flow produces a different output on different error conditions.
//
// -=-=- StopHere -=-=-

12
internal/tutorial/measurex/chapter05/README.md
View File

@ -10,7 +10,7 @@ For this reason, we will not see a connect event, but we
will only see a "QUIC handshake event".
Having said that, let us now move on and see the code of
the simple program that shows this functionality.
the simple program that uses this functionality.
(This file is auto-generated. Do not edit it directly! To apply
changes you need to modify `./internal/tutorial/measure/chapter05/main.go`.)
@ -63,7 +63,7 @@ The same remarks mentioned in the previous chapter regarding
the arguments for the TLS config also apply here. We need
to specify the SNI (`ServerName`), the ALPN (`NextProtos`),
and the CA pool we want to use. Here, again, we're using
the CA pool from cURL that we bundle with ooniprobe.
the CA pool from cURL that we bundle with OONI Probe.
As we did in the previous chapters, here's the usual three
lines of code for printing the resulting measurement.
@ -224,7 +224,7 @@ Produces this JSON:
],
// This section describes the QUIC handshake and it has
// basically the same fields of the TLS handshake.
// basically the same fields as the TLS handshake.
"quic_handshake": [
{
"cipher_suite": "TLS_CHACHA20_POLY1305_SHA256",
@ -260,9 +260,9 @@ Produces this JSON:
}
```
Here are some suggestions on other experiments to run:
Here are some suggestions for other experiments to run:
1. obtain a timeout by connecting on a port that is not
1. obtain a timeout by connecting to a port that is not
actually listening for QUIC;
2. obtain a certificate validation error by forcing
@ -271,7 +271,7 @@ a different SNI;
3. use a different ALPN (by changing the code), and see
how the error and the oddity are handled. Can we do
anything about this by changing `./internal/netxlite/errorx`
to better support for this specific error condition?
to better support this specific error condition?
## Conclusion

12
internal/tutorial/measurex/chapter05/main.go
View File

@ -11,7 +11,7 @@
// will only see a "QUIC handshake event".
//
// Having said that, let us now move on and see the code of
// the simple program that shows this functionality.
// the simple program that uses this functionality.
//
// (This file is auto-generated. Do not edit it directly! To apply
// changes you need to modify `./internal/tutorial/measure/chapter05/main.go`.)
@ -64,7 +64,7 @@ func main() {
// the arguments for the TLS config also apply here. We need
// to specify the SNI (`ServerName`), the ALPN (`NextProtos`),
// and the CA pool we want to use. Here, again, we're using
// the CA pool from cURL that we bundle with ooniprobe.
// the CA pool from cURL that we bundle with OONI Probe.
//
// As we did in the previous chapters, here's the usual three
// lines of code for printing the resulting measurement.
@ -225,7 +225,7 @@ func main() {
// ],
//
// // This section describes the QUIC handshake and it has
// // basically the same fields of the TLS handshake.
// // basically the same fields as the TLS handshake.
// "quic_handshake": [
// {
// "cipher_suite": "TLS_CHACHA20_POLY1305_SHA256",
@ -261,9 +261,9 @@ func main() {
// }
// ```
//
// Here are some suggestions on other experiments to run:
// Here are some suggestions for other experiments to run:
//
// 1. obtain a timeout by connecting on a port that is not
// 1. obtain a timeout by connecting to a port that is not
// actually listening for QUIC;
//
// 2. obtain a certificate validation error by forcing
@ -272,7 +272,7 @@ func main() {
// 3. use a different ALPN (by changing the code), and see
// how the error and the oddity are handled. Can we do
// anything about this by changing `./internal/netxlite/errorx`
// to better support for this specific error condition?
// to better support this specific error condition?
//
// ## Conclusion
//

10
internal/tutorial/measurex/chapter06/README.md
View File

@ -1,15 +1,15 @@
# Chapter VI: Getting a webpage from an HTTP/HTTPS/HTTP3 endpoint.
This chapter describes measuring getting a webpage from an
This chapter describes measuring the retrieval of a webpage from an
HTTPS endpoint. We have seen how to TCP connect, we have
seen how to TLS handshake, now it's time to see how we can
combine these operations with fetching a webpage from a
given TCP endpoint speaking HTTP and TLS. (As well as to
provide you with information on how to otherwise fetch
combine these operations with that of fetching a webpage from a
given TCP endpoint speaking HTTP and TLS. (As well as
providing you with information on how to otherwise fetch
from HTTP and HTTP/3 endpoints.)
The program we're going to write, `main.go`, will show a
The program we're going to write, `main.go`, will use a
high-level operation to perform this measurement in a
single API call. The code implementing this API call will
combine the operations we have seen in previous chapter

10
internal/tutorial/measurex/chapter06/main.go
View File

@ -2,15 +2,15 @@
//
// # Chapter VI: Getting a webpage from an HTTP/HTTPS/HTTP3 endpoint.
//
// This chapter describes measuring getting a webpage from an
// This chapter describes measuring the retrieval of a webpage from an
// HTTPS endpoint. We have seen how to TCP connect, we have
// seen how to TLS handshake, now it's time to see how we can
// combine these operations with fetching a webpage from a
// given TCP endpoint speaking HTTP and TLS. (As well as to
// provide you with information on how to otherwise fetch
// combine these operations with that of fetching a webpage from a
// given TCP endpoint speaking HTTP and TLS. (As well as
// providing you with information on how to otherwise fetch
// from HTTP and HTTP/3 endpoints.)
//
// The program we're going to write, `main.go`, will show a
// The program we're going to write, `main.go`, will use a
// high-level operation to perform this measurement in a
// single API call. The code implementing this API call will
// combine the operations we have seen in previous chapter

6
internal/tutorial/measurex/chapter08/README.md
View File

@ -58,7 +58,7 @@ func main() {
```
### Call LookupHTTPSSvc
Here we perform the `LookupHostUDP` we performed in the
Here we perform the `LookupHostUDP` we used in the
previous chapter and then we call `LookupHTTPSvcUDP`.
```Go
@ -67,7 +67,7 @@ previous chapter and then we call `LookupHTTPSvcUDP`.
```
The `LookupHTTPSSvcUDP` function has the same signature
of `LookupHostUDP` _but_ it behaves differently. Rather than
as `LookupHostUDP` _but_ it behaves differently. Rather than
querying for `A` and `AAAA`, it performs an `HTTPS` DNS
lookup. This query returns:
@ -80,7 +80,7 @@ lookup. This query returns:
### Build an []HTTPEndpoint and run serial measurements
Here we call `AllHTTPEndpointsForURL` like we did in the
previous chapter. However, note that we pass to it the
previous chapter. However, note that we pass it the
whole content of `m.DNS`, which now contains not only the
A/AAAA lookups results but also the HTTPS lookup results.

6
internal/tutorial/measurex/chapter08/main.go
View File

@ -59,7 +59,7 @@ func main() {
// ```
// ### Call LookupHTTPSSvc
//
// Here we perform the `LookupHostUDP` we performed in the
// Here we perform the `LookupHostUDP` we used in the
// previous chapter and then we call `LookupHTTPSvcUDP`.
//
// ```Go
@ -68,7 +68,7 @@ func main() {
// ```
//
// The `LookupHTTPSSvcUDP` function has the same signature
// of `LookupHostUDP` _but_ it behaves differently. Rather than
// as `LookupHostUDP` _but_ it behaves differently. Rather than
// querying for `A` and `AAAA`, it performs an `HTTPS` DNS
// lookup. This query returns:
//
@ -81,7 +81,7 @@ func main() {
// ### Build an []HTTPEndpoint and run serial measurements
//
// Here we call `AllHTTPEndpointsForURL` like we did in the
// previous chapter. However, note that we pass to it the
// previous chapter. However, note that we pass it the
// whole content of `m.DNS`, which now contains not only the
// A/AAAA lookups results but also the HTTPS lookup results.
//

6
internal/tutorial/measurex/chapter11/README.md
View File

@ -15,9 +15,9 @@ changes you need to modify `./internal/tutorial/measurex/chapter11/main.go`.)
## main.go
The beginning of the program is much simpler. We have removed
out custom measurement type. We are now going to use the
our custom measurement type. We are now going to use the
`URLMeasurement` type (`go doc ./internal/measurex.URLMeasurement`),
which as the same fields of `measurement` in chapter10 _plus_
which has the same fields of `measurement` in chapter10 _plus_
some extra fields that we'll examine in a later chapter.
```Go
@ -77,7 +77,7 @@ The arguments are:
The return value is either an `URLMeasurement`
or an error. The error happens, for example, if
the input URL scheme is not "http" or "https" (which
we handled by panicking in chapter11).
we handled by panicking in chapter07).
Now, rather than panicking inside `MeasureURL`, we
return the error to the caller and we `panic`

6
internal/tutorial/measurex/chapter11/main.go
View File

@ -16,9 +16,9 @@
// ## main.go
//
// The beginning of the program is much simpler. We have removed
// out custom measurement type. We are now going to use the
// our custom measurement type. We are now going to use the
// `URLMeasurement` type (`go doc ./internal/measurex.URLMeasurement`),
// which as the same fields of `measurement` in chapter10 _plus_
// which has the same fields of `measurement` in chapter10 _plus_
// some extra fields that we'll examine in a later chapter.
//
// ```Go
@ -78,7 +78,7 @@ func main() {
// The return value is either an `URLMeasurement`
// or an error. The error happens, for example, if
// the input URL scheme is not "http" or "https" (which
// we handled by panicking in chapter11).
// we handled by panicking in chapter07).
//
// Now, rather than panicking inside `MeasureURL`, we
// return the error to the caller and we `panic`

8
internal/tutorial/measurex/chapter14/README.md
View File

@ -67,7 +67,7 @@ func webConnectivity(ctx context.Context, URL string) (*measurement, error) {
```
We start by parsing the input URL. If we cannot parse it, of
course this is an hard error and we cannot continue.
course this is a hard error and we cannot continue.
```Go
parsedURL, err := url.Parse(URL)
@ -100,7 +100,7 @@ the input URL's domain using the system resolver.
```
This is code we have already seen in previous chapter.
This is code we have already seen in the previous chapters.
### 2. Building a list of endpoints
@ -149,7 +149,7 @@ now focus on the last point:
### 5. HTTP measurement
We need to manually build a `MeasurementDB`. This is a
"database" where networking code will store events.
"database" where the networking code will store events.
```Go
@ -190,7 +190,7 @@ the round trip. Reading a snapshot of the response
body is not implemented by this function but rather
is a property of the "tracing" HTTP transport we
created above (this type of transport is the one we
have been internally using in all the examples
have been using internally in all the examples
presented so far.)
```Go

8
internal/tutorial/measurex/chapter14/main.go
View File

@ -68,7 +68,7 @@ func webConnectivity(ctx context.Context, URL string) (*measurement, error) {
// ```
//
// We start by parsing the input URL. If we cannot parse it, of
// course this is an hard error and we cannot continue.
// course this is a hard error and we cannot continue.
//
// ```Go
parsedURL, err := url.Parse(URL)
@ -101,7 +101,7 @@ func webConnectivity(ctx context.Context, URL string) (*measurement, error) {
// ```
//
// This is code we have already seen in previous chapter.
// This is code we have already seen in the previous chapters.
//
//
// ### 2. Building a list of endpoints
@ -150,7 +150,7 @@ func webConnectivity(ctx context.Context, URL string) (*measurement, error) {
// ### 5. HTTP measurement
//
// We need to manually build a `MeasurementDB`. This is a
// "database" where networking code will store events.
// "database" where the networking code will store events.
//
// ```Go
@ -191,7 +191,7 @@ func webConnectivity(ctx context.Context, URL string) (*measurement, error) {
// body is not implemented by this function but rather
// is a property of the "tracing" HTTP transport we
// created above (this type of transport is the one we
// have been internally using in all the examples
// have been using internally in all the examples
// presented so far.)
//
// ```Go