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/quic.go

@@ -1,5 +1,9 @@
 package tracex
 
+//
+// QUIC
+//
+
 import (
 	"context"
 	"crypto/tls"
@@ -11,14 +15,32 @@ import (
 	"github.com/ooni/probe-cli/v3/internal/netxlite"
 )
 
-// QUICHandshakeSaver saves events occurring during the handshake
+// QUICHandshakeSaver saves events occurring during the QUIC handshake.
 type QUICHandshakeSaver struct {
+	// QUICDialer is the wrapped dialer
+	QUICDialer model.QUICDialer
+
+	// Saver saves events
 	Saver *Saver
-	model.QUICDialer
 }
 
-// DialContext implements ContextDialer.DialContext
-func (h QUICHandshakeSaver) DialContext(ctx context.Context, network string,
+// WrapQUICDialer wraps a model.QUICDialer with a QUICHandshakeSaver that will
+// save the QUIC handshake results into this Saver.
+//
+// When this function is invoked on a nil Saver, it will directly return
+// the original QUICDialer without any wrapping.
+func (s *Saver) WrapQUICDialer(qd model.QUICDialer) model.QUICDialer {
+	if s == nil {
+		return qd
+	}
+	return &QUICHandshakeSaver{
+		QUICDialer: qd,
+		Saver:      s,
+	}
+}
+
+// DialContext implements QUICDialer.DialContext
+func (h *QUICHandshakeSaver) DialContext(ctx context.Context, network string,
 	host string, tlsCfg *tls.Config, cfg *quic.Config) (quic.EarlyConnection, error) {
 	start := time.Now()
 	// TODO(bassosimone): in the future we probably want to also save
@@ -35,6 +57,7 @@ func (h QUICHandshakeSaver) DialContext(ctx context.Context, network string,
 	sess, err := h.QUICDialer.DialContext(ctx, network, host, tlsCfg, cfg)
 	stop := time.Now()
 	if err != nil {
+		// TODO(bassosimone): here we should save the peer certs
 		h.Saver.Write(Event{
 			Duration:      stop.Sub(start),
 			Err:           err,
@@ -54,7 +77,7 @@ func (h QUICHandshakeSaver) DialContext(ctx context.Context, network string,
 		TLSCipherSuite:     netxlite.TLSCipherSuiteString(state.CipherSuite),
 		TLSNegotiatedProto: state.NegotiatedProtocol,
 		TLSNextProtos:      tlsCfg.NextProtos,
-		TLSPeerCerts:       PeerCerts(state, err),
+		TLSPeerCerts:       tlsPeerCerts(state, err),
 		TLSServerName:      tlsCfg.ServerName,
 		TLSVersion:         netxlite.TLSVersionString(state.Version),
 		Time:               stop,
@@ -62,6 +85,10 @@ func (h QUICHandshakeSaver) DialContext(ctx context.Context, network string,
 	return sess, nil
 }
 
+func (h *QUICHandshakeSaver) CloseIdleConnections() {
+	h.QUICDialer.CloseIdleConnections()
+}
+
 // quicConnectionState returns the ConnectionState of a QUIC Session.
 func quicConnectionState(sess quic.EarlyConnection) tls.ConnectionState {
 	return sess.ConnectionState().TLS.ConnectionState
@@ -70,32 +97,50 @@ func quicConnectionState(sess quic.EarlyConnection) tls.ConnectionState {
 // QUICListenerSaver is a QUICListener that also implements saving events.
 type QUICListenerSaver struct {
 	// QUICListener is the underlying QUICListener.
-	model.QUICListener
+	QUICListener model.QUICListener
 
 	// Saver is the underlying Saver.
 	Saver *Saver
 }
 
+// WrapQUICListener wraps a model.QUICDialer with a QUICListenerSaver that will
+// save the QUIC I/O packet conn events into this Saver.
+//
+// When this function is invoked on a nil Saver, it will directly return
+// the original QUICListener without any wrapping.
+func (s *Saver) WrapQUICListener(ql model.QUICListener) model.QUICListener {
+	if s == nil {
+		return ql
+	}
+	return &QUICListenerSaver{
+		QUICListener: ql,
+		Saver:        s,
+	}
+}
+
 // Listen implements QUICListener.Listen.
 func (qls *QUICListenerSaver) Listen(addr *net.UDPAddr) (model.UDPLikeConn, error) {
 	pconn, err := qls.QUICListener.Listen(addr)
 	if err != nil {
 		return nil, err
 	}
-	return &saverUDPConn{
+	pconn = &udpLikeConnSaver{
 		UDPLikeConn: pconn,
 		saver:       qls.Saver,
-	}, nil
+	}
+	return pconn, nil
 }
 
-type saverUDPConn struct {
+// udpLikeConnSaver saves I/O events
+type udpLikeConnSaver struct {
+	// UDPLikeConn is the wrapped underlying conn
 	model.UDPLikeConn
+
+	// Saver saves events
 	saver *Saver
 }
 
-var _ model.UDPLikeConn = &saverUDPConn{}
-
-func (c *saverUDPConn) WriteTo(p []byte, addr net.Addr) (int, error) {
+func (c *udpLikeConnSaver) WriteTo(p []byte, addr net.Addr) (int, error) {
 	start := time.Now()
 	count, err := c.UDPLikeConn.WriteTo(p, addr)
 	stop := time.Now()
@@ -111,7 +156,7 @@ func (c *saverUDPConn) WriteTo(p []byte, addr net.Addr) (int, error) {
 	return count, err
 }
 
-func (c *saverUDPConn) ReadFrom(b []byte) (int, net.Addr, error) {
+func (c *udpLikeConnSaver) ReadFrom(b []byte) (int, net.Addr, error) {
 	start := time.Now()
 	n, addr, err := c.UDPLikeConn.ReadFrom(b)
 	stop := time.Now()
@@ -131,9 +176,13 @@ func (c *saverUDPConn) ReadFrom(b []byte) (int, net.Addr, error) {
 	return n, addr, err
 }
 
-func (c *saverUDPConn) safeAddrString(addr net.Addr) (out string) {
+func (c *udpLikeConnSaver) safeAddrString(addr net.Addr) (out string) {
 	if addr != nil {
 		out = addr.String()
 	}
 	return
 }
+
+var _ model.QUICDialer = &QUICHandshakeSaver{}
+var _ model.QUICListener = &QUICListenerSaver{}
+var _ model.UDPLikeConn = &udpLikeConnSaver{}