tutorial/

directory
v3.15.1 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Jun 6, 2022 License: GPL-3.0

README

Tutorials: writing OONI nettests

This package contains a living tutorial explaining how to write OONI nettests. The code in here is based on existing nettests.

Because it's committed to the probe-cli repository and depends on real OONI code, it should always be up to date.

Index

  • Rewriting the torsf experiment: this tutorial explains to you how to write a simple experiment. After reading it, you will understand the interfaces between an experiment and the OONI core. What this tutorial does not teach you, though, is how to tell the OONI core about this experiment. To see how to do that, you should check how we do that in internal/engine/allexperiments.go.

  • Using the measurex package to write network experiments: this tutorial explains to you how to use the measurex library to write networking code that generates measurements using the OONI data format. You will learn how to perform DNS, TCP, TLS, QUIC, HTTP, HTTPS, and HTTP3 measurements.

  • Low-level networking using netxlite: this tutorial introduces you to the netxlite networking library. This is the underlying library used by measurex as well as by many other libraries inside OONI. You need to know about this library to contribute to measurex as well as to other parts of the OONI core that perform network operations.

Therefore, after reading these tutorials, you should have a better understanding of how an experiment interacts with the OONI core, as well as of which libraries you can use to write experiments.

Regenerating the tutorials

(cd ./internal/tutorial && go run ./generator)

Directories

Path Synopsis
experiment
torsf/chapter01
-=-=- StartHere -=-=- # Chapter I: main.go using the real torsf implementation In this chapter we will write together a `main.go` file that uses the real `torsf` implementation to run the experiment.
-=-=- StartHere -=-=- # Chapter I: main.go using the real torsf implementation In this chapter we will write together a `main.go` file that uses the real `torsf` implementation to run the experiment.
torsf/chapter02
-=-=- StartHere -=-=- ## The torsf.go file This file will contain the implementation of the `NewExperimentMeasurer` function.
-=-=- StartHere -=-=- ## The torsf.go file This file will contain the implementation of the `NewExperimentMeasurer` function.
Command generator generates or re-generates the tutorial chapters.
Command generator generates or re-generates the tutorial chapters.
measurex
chapter01
-=-=- StartHere -=-=- # Chapter I: using the system resolver In this chapter we explain how to measure DNS resolutions performed using the system resolver.
-=-=- StartHere -=-=- # Chapter I: using the system resolver In this chapter we explain how to measure DNS resolutions performed using the system resolver.
chapter02
-=-=- StartHere -=-=- # Chapter II: establishing TCP connections In this chapter we explain how to measure establishing TCP connections.
-=-=- StartHere -=-=- # Chapter II: establishing TCP connections In this chapter we explain how to measure establishing TCP connections.
chapter03
-=-=- StartHere -=-=- # Chapter III: using a custom DNS-over-UDP resolver In this chapter we learn how to measure sending DNS queries to a DNS server speaking the DNS-over-UDP protocol.
-=-=- StartHere -=-=- # Chapter III: using a custom DNS-over-UDP resolver In this chapter we learn how to measure sending DNS queries to a DNS server speaking the DNS-over-UDP protocol.
chapter04
-=-=- StartHere -=-=- # Chapter IV: TLS handshaking This chapter describes measuring TLS handshakes.
-=-=- StartHere -=-=- # Chapter IV: TLS handshaking This chapter describes measuring TLS handshakes.
chapter05
-=-=- StartHere -=-=- # Chapter V: QUIC handshaking This chapter describes measuring QUIC handshakes.
-=-=- StartHere -=-=- # Chapter V: QUIC handshaking This chapter describes measuring QUIC handshakes.
chapter06
-=-=- StartHere -=-=- # Chapter VI: Getting a webpage from an HTTP/HTTPS/HTTP3 endpoint.
-=-=- StartHere -=-=- # Chapter VI: Getting a webpage from an HTTP/HTTPS/HTTP3 endpoint.
chapter07
-=-=- StartHere -=-=- # Chapter VII: Measuring all the HTTPEndpoints for a domain We are now going to combine DNS resolutions with getting HTTPEndpoints.
-=-=- StartHere -=-=- # Chapter VII: Measuring all the HTTPEndpoints for a domain We are now going to combine DNS resolutions with getting HTTPEndpoints.
chapter08
-=-=- StartHere -=-=- # Chapter VII: HTTPSSvc DNS queries The program we see here is _really_ similar to the one we discussed in the previous chapter.
-=-=- StartHere -=-=- # Chapter VII: HTTPSSvc DNS queries The program we see here is _really_ similar to the one we discussed in the previous chapter.
chapter09
-=-=- StartHere -=-=- # Chapter IX: Parallel HTTPEndpoint measurements The program we see here is _really_ similar to the one we discussed in the previous chapter.
-=-=- StartHere -=-=- # Chapter IX: Parallel HTTPEndpoint measurements The program we see here is _really_ similar to the one we discussed in the previous chapter.
chapter10
-=-=- StartHere -=-=- # Chapter IX: Parallel DNS lookups The program we see here is _really_ similar to the one we discussed in the previous chapter.
-=-=- StartHere -=-=- # Chapter IX: Parallel DNS lookups The program we see here is _really_ similar to the one we discussed in the previous chapter.
chapter11
-=-=- StartHere -=-=- # Chapter XI: Measuring a URL This program shows how to measure an HTTP/HTTPS URL.
-=-=- StartHere -=-=- # Chapter XI: Measuring a URL This program shows how to measure an HTTP/HTTPS URL.
chapter12
-=-=- StartHere -=-=- # Chapter XII: Following redirections.
-=-=- StartHere -=-=- # Chapter XII: Following redirections.
chapter13
-=-=- StartHere -=-=- # Chapter XIII: Rewriting Web Connectivity This chapter contains an exercise.
-=-=- StartHere -=-=- # Chapter XIII: Rewriting Web Connectivity This chapter contains an exercise.
chapter14
-=-=- StartHere -=-=- # Chapter XIV: A possible rewrite of Web Connectivity In this chapter we try to solve the exercise laid out in the previous chapter, using `measurex` primitives.
-=-=- StartHere -=-=- # Chapter XIV: A possible rewrite of Web Connectivity In this chapter we try to solve the exercise laid out in the previous chapter, using `measurex` primitives.
netxlite
chapter01
-=-=- StartHere -=-=- # Chapter I: establishing TCP connections In this chapter we will write together a `main.go` file that uses netxlite to establish a new TCP connection.
-=-=- StartHere -=-=- # Chapter I: establishing TCP connections In this chapter we will write together a `main.go` file that uses netxlite to establish a new TCP connection.
chapter02
-=-=- StartHere -=-=- # Chapter I: TLS handshakes In this chapter we will write together a `main.go` file that uses netxlite to establish a new TCP connection and then performs a TLS handshake using the established connection.
-=-=- StartHere -=-=- # Chapter I: TLS handshakes In this chapter we will write together a `main.go` file that uses netxlite to establish a new TCP connection and then performs a TLS handshake using the established connection.
chapter03
-=-=- StartHere -=-=- # Chapter I: TLS parroting In this chapter we will write together a `main.go` file that uses netxlite to establish a new TCP connection and then performs a TLS handshake using the established connection.
-=-=- StartHere -=-=- # Chapter I: TLS parroting In this chapter we will write together a `main.go` file that uses netxlite to establish a new TCP connection and then performs a TLS handshake using the established connection.
chapter04
-=-=- StartHere -=-=- # Chapter I: Using QUIC In this chapter we will write together a `main.go` file that uses netxlite to establish a new QUIC connection with an UDP endpoint.
-=-=- StartHere -=-=- # Chapter I: Using QUIC In this chapter we will write together a `main.go` file that uses netxlite to establish a new QUIC connection with an UDP endpoint.
chapter05
-=-=- StartHere -=-=- # Chapter I: Using the "system" DNS resolver In this chapter we will write together a `main.go` file that uses the "system" DNS resolver to lookup domain names.
-=-=- StartHere -=-=- # Chapter I: Using the "system" DNS resolver In this chapter we will write together a `main.go` file that uses the "system" DNS resolver to lookup domain names.
chapter06
-=-=- StartHere -=-=- # Chapter I: Using a custom UDP resolver In this chapter we will write together a `main.go` file that uses a custom UDP DNS resolver to lookup domain names.
-=-=- StartHere -=-=- # Chapter I: Using a custom UDP resolver In this chapter we will write together a `main.go` file that uses a custom UDP DNS resolver to lookup domain names.
chapter07
-=-=- StartHere -=-=- # Chapter I: HTTP GET with TLS conn In this chapter we will write together a `main.go` file that uses netxlite to establish a TLS connection to a remote endpoint and then fetches a webpage from it using GET.
-=-=- StartHere -=-=- # Chapter I: HTTP GET with TLS conn In this chapter we will write together a `main.go` file that uses netxlite to establish a TLS connection to a remote endpoint and then fetches a webpage from it using GET.
chapter08
-=-=- StartHere -=-=- # Chapter I: HTTP GET with QUIC conn In this chapter we will write together a `main.go` file that uses netxlite to establish a QUIC connection to a remote endpoint and then fetches a webpage from it using GET.
-=-=- StartHere -=-=- # Chapter I: HTTP GET with QUIC conn In this chapter we will write together a `main.go` file that uses netxlite to establish a QUIC connection to a remote endpoint and then fetches a webpage from it using GET.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL