feat: context-based tracing to record delayed DNS responses (#870)

See https://github.com/ooni/probe/issues/2221

Co-authored-by: decfox <decfox@github.com>
Co-authored-by: Simone Basso <bassosimone@gmail.com>

internal/model/mocks/trace.go

@@ -24,6 +24,9 @@ type Trace struct {
 	MockOnDNSRoundTripForLookupHost func(started time.Time, reso model.Resolver, query model.DNSQuery,
 		response model.DNSResponse, addrs []string, err error, finished time.Time)
 
+	MockOnDelayedDNSResponse func(started time.Time, txp model.DNSTransport, query model.DNSQuery,
+		response model.DNSResponse, addrs []string, err error, finished time.Time) error
+
 	MockOnConnectDone func(
 		started time.Time, network, domain, remoteAddr string, err error, finished time.Time)
 
@@ -57,6 +60,11 @@ func (t *Trace) OnDNSRoundTripForLookupHost(started time.Time, reso model.Resolv
 	t.MockOnDNSRoundTripForLookupHost(started, reso, query, response, addrs, err, finished)
 }
 
+func (t *Trace) OnDelayedDNSResponse(started time.Time, txp model.DNSTransport, query model.DNSQuery,
+	response model.DNSResponse, addrs []string, err error, finished time.Time) error {
+	return t.MockOnDelayedDNSResponse(started, txp, query, response, addrs, err, finished)
+}
+
 func (t *Trace) OnConnectDone(
 	started time.Time, network, domain, remoteAddr string, err error, finished time.Time) {
 	t.MockOnConnectDone(started, network, domain, remoteAddr, err, finished)

internal/model/mocks/trace_test.go

@@ -71,6 +71,30 @@ func TestTrace(t *testing.T) {
 		}
 	})
 
+	t.Run("OnDelayedDNSResponse", func(t *testing.T) {
+		var called bool
+		tx := &Trace{
+			MockOnDelayedDNSResponse: func(started time.Time, txp model.DNSTransport,
+				query model.DNSQuery, response model.DNSResponse,
+				addrs []string, err error, finished time.Time) error {
+				called = true
+				return nil
+			},
+		}
+		tx.OnDelayedDNSResponse(
+			time.Now(),
+			&DNSTransport{},
+			&DNSQuery{},
+			&DNSResponse{},
+			[]string{},
+			nil,
+			time.Now(),
+		)
+		if !called {
+			t.Fatal("not called")
+		}
+	})
+
 	t.Run("OnConnectDone", func(t *testing.T) {
 		var called bool
 		tx := &Trace{

internal/model/netx.go

@@ -340,6 +340,29 @@ type Trace interface {
 	OnDNSRoundTripForLookupHost(started time.Time, reso Resolver, query DNSQuery,
 		response DNSResponse, addrs []string, err error, finished time.Time)
 
+	// OnDelayedDNSResponse is used with a DNSOverUDPTransport and called
+	// when we get delayed, unexpected DNS responses.
+	//
+	// Arguments:
+	//
+	// - started is when we started reading the delayed response;
+	//
+	// - txp is the DNS transport used with the resolver;
+	//
+	// - query is the non-nil DNS query we use for the RoundTrip;
+	//
+	// - response is the non-nil valid DNS response, obtained after some delay;
+	//
+	// - addrs is the list of addresses obtained after decoding the delayed response,
+	// which is empty if the response did not contain any addresses, which we
+	// extract by calling the DecodeLookupHost method.
+	//
+	// - err is the result of DecodeLookupHost: either an error or nil;
+	//
+	// - finished is when we have read the delayed response.
+	OnDelayedDNSResponse(started time.Time, txp DNSTransport, query DNSQuery,
+		resp DNSResponse, addrs []string, err error, finsihed time.Time) error
+
 	// OnConnectDone is called when connect terminates.
 	//
 	// Arguments: