ooni-probe-cli/internal/tracex/doc.go

// Package tracex performs measurements using tracing. To use tracing means
// that we'll wrap netx data types (e.g., a Dialer) with equivalent data types
// saving events into a Saver data struture. Then we will use the data types
// normally (e.g., call the Dialer's DialContet method and then use the
// resulting connection). When done, we will extract the trace containing
// all the events that occurred from the saver and process it to determine
// what happened during the measurement itself.
package tracex
refactor(tracex): start applying recent code conventions (#773) The code that is now into the tracex package was written a long time ago, so let's start to make it more in line with the coding style of packages that were written more recently. I didn't apply all the changes I'd like to apply in a single diff and for now I am committing just this diff. Broadly, what we need to do is: 1. improve documentation 2. ~always use pointer receivers (object receives have the issue that they are not mutable by accident meaning that you can mutate them but their state do not change after the call returns, which is potentially a source of bugs in case you later refactor to use a pointer receiver, so always use pointer receivers) 3. ~always avoid embedding (let's say we want to avoid embedding for types we define and it's instead fine to embed types that are defined in the stdlib: if later we add a new method, we will not see a broken build and we'll probably forget to add the new method to all wrappers -- conversely, if we're wrapping rather than embedding, we'll see a broken build and act accordingly) 4. prefer unit tests and group tests by type being tested rather than using a flat structure for tests There's a coverage slippage that I'll compensate in a follow-up diff where I'll focus on unit testing. Reference issue: https://github.com/ooni/probe/issues/2121 2022-06-01 07:44:54 +02:00			`// Package tracex performs measurements using tracing. To use tracing means`
			`// that we'll wrap netx data types (e.g., a Dialer) with equivalent data types`
			`// saving events into a Saver data struture. Then we will use the data types`
			`// normally (e.g., call the Dialer's DialContet method and then use the`
			`// resulting connection). When done, we will extract the trace containing`
			`// all the events that occurred from the saver and process it to determine`
			`// what happened during the measurement itself.`
refactor(netx): merge archival, trace, and the savers (#772) This diff creates a new package under netx called tracex that contains everything we need to perform measurements using events tracing and postprocessing (which is the technique with which we implement most network experiments). The general idea here is to (1) create a unique package out of all of these packages; (2) clean up the code a bit (improve tests, docs, apply more recent code patterns); (3) move the resulting code as a toplevel package inside of internal. Once this is done, netx can be further refactored to avoid subpackages and we can search for more code to salvage/refactor. See https://github.com/ooni/probe/issues/2121 2022-05-31 21:53:01 +02:00			`package tracex`