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

internal/engine/netx/tracex/resolver.go

@@ -1,20 +1,43 @@
 package tracex
 
+//
+// DNS lookup and round trip
+//
+
 import (
 	"context"
+	"net"
 	"time"
 
 	"github.com/ooni/probe-cli/v3/internal/model"
 )
 
-// SaverResolver is a resolver that saves events
+// SaverResolver is a resolver that saves events.
 type SaverResolver struct {
-	model.Resolver
+	// Resolver is the underlying resolver.
+	Resolver model.Resolver
+
+	// Saver saves events.
 	Saver *Saver
 }
 
+// WrapResolver wraps a model.Resolver with a SaverResolver that will save
+// the DNS lookup results into this Saver.
+//
+// When this function is invoked on a nil Saver, it will directly return
+// the original Resolver without any wrapping.
+func (s *Saver) WrapResolver(r model.Resolver) model.Resolver {
+	if s == nil {
+		return r
+	}
+	return &SaverResolver{
+		Resolver: r,
+		Saver:    s,
+	}
+}
+
 // LookupHost implements Resolver.LookupHost
-func (r SaverResolver) LookupHost(ctx context.Context, hostname string) ([]string, error) {
+func (r *SaverResolver) LookupHost(ctx context.Context, hostname string) ([]string, error) {
 	start := time.Now()
 	r.Saver.Write(Event{
 		Address:  r.Resolver.Address(),
@@ -38,49 +61,105 @@ func (r SaverResolver) LookupHost(ctx context.Context, hostname string) ([]strin
 	return addrs, err
 }
 
-// SaverDNSTransport is a DNS transport that saves events
+func (r *SaverResolver) Network() string {
+	return r.Resolver.Network()
+}
+
+func (r *SaverResolver) Address() string {
+	return r.Resolver.Address()
+}
+
+func (r *SaverResolver) CloseIdleConnections() {
+	r.Resolver.CloseIdleConnections()
+}
+
+func (r *SaverResolver) LookupHTTPS(ctx context.Context, domain string) (*model.HTTPSSvc, error) {
+	// TODO(bassosimone): we should probably implement this method
+	return r.Resolver.LookupHTTPS(ctx, domain)
+}
+
+func (r *SaverResolver) LookupNS(ctx context.Context, domain string) ([]*net.NS, error) {
+	// TODO(bassosimone): we should probably implement this method
+	return r.Resolver.LookupNS(ctx, domain)
+}
+
+// SaverDNSTransport is a DNS transport that saves events.
 type SaverDNSTransport struct {
-	model.DNSTransport
+	// DNSTransport is the underlying DNS transport.
+	DNSTransport model.DNSTransport
+
+	// Saver saves events.
 	Saver *Saver
 }
 
+// WrapDNSTransport wraps a model.DNSTransport with a SaverDNSTransport that
+// will save the DNS round trip results into this Saver.
+//
+// When this function is invoked on a nil Saver, it will directly return
+// the original DNSTransport without any wrapping.
+func (s *Saver) WrapDNSTransport(txp model.DNSTransport) model.DNSTransport {
+	if s == nil {
+		return txp
+	}
+	return &SaverDNSTransport{
+		DNSTransport: txp,
+		Saver:        s,
+	}
+}
+
 // RoundTrip implements RoundTripper.RoundTrip
-func (txp SaverDNSTransport) RoundTrip(
+func (txp *SaverDNSTransport) RoundTrip(
 	ctx context.Context, query model.DNSQuery) (model.DNSResponse, error) {
 	start := time.Now()
 	txp.Saver.Write(Event{
-		Address:  txp.Address(),
-		DNSQuery: txp.maybeQueryBytes(query),
+		Address:  txp.DNSTransport.Address(),
+		DNSQuery: dnsMaybeQueryBytes(query),
 		Name:     "dns_round_trip_start",
-		Proto:    txp.Network(),
+		Proto:    txp.DNSTransport.Network(),
 		Time:     start,
 	})
 	response, err := txp.DNSTransport.RoundTrip(ctx, query)
 	stop := time.Now()
 	txp.Saver.Write(Event{
-		Address:  txp.Address(),
-		DNSQuery: txp.maybeQueryBytes(query),
-		DNSReply: txp.maybeResponseBytes(response),
+		Address:  txp.DNSTransport.Address(),
+		DNSQuery: dnsMaybeQueryBytes(query),
+		DNSReply: dnsMaybeResponseBytes(response),
 		Duration: stop.Sub(start),
 		Err:      err,
 		Name:     "dns_round_trip_done",
-		Proto:    txp.Network(),
+		Proto:    txp.DNSTransport.Network(),
 		Time:     stop,
 	})
 	return response, err
 }
 
-func (txp SaverDNSTransport) maybeQueryBytes(query model.DNSQuery) []byte {
+func (txp *SaverDNSTransport) Network() string {
+	return txp.DNSTransport.Network()
+}
+
+func (txp *SaverDNSTransport) Address() string {
+	return txp.DNSTransport.Address()
+}
+
+func (txp *SaverDNSTransport) CloseIdleConnections() {
+	txp.DNSTransport.CloseIdleConnections()
+}
+
+func (txp *SaverDNSTransport) RequiresPadding() bool {
+	return txp.DNSTransport.RequiresPadding()
+}
+
+func dnsMaybeQueryBytes(query model.DNSQuery) []byte {
 	data, _ := query.Bytes()
 	return data
 }
 
-func (txp SaverDNSTransport) maybeResponseBytes(response model.DNSResponse) []byte {
+func dnsMaybeResponseBytes(response model.DNSResponse) []byte {
 	if response == nil {
 		return nil
 	}
 	return response.Bytes()
 }
 
-var _ model.Resolver = SaverResolver{}
-var _ model.DNSTransport = SaverDNSTransport{}
+var _ model.Resolver = &SaverResolver{}
+var _ model.DNSTransport = &SaverDNSTransport{}