feat: introduce richer input

Most of the existing code is designed to move around lists of
`model.OOAPIURLInfo` and measuring such URLs.

This design originally suited Web Connectivity but it's not good
enough for richer input because it does not contain options.

With this diff, we move into the direction of richer input by
replacing `model.OOAPIURLInfo` lists with lists of:

```Go
// internal/model/experiment.go

type ExperimentTarget struct {
	Category() string
	Country() string
	Input() string
}
```

where `*model.OOAPIURLInfo` implements `model.ExperimentTarget`
in a trivial way and where, additionally:

1. the `InputLoader` is modified to load `ExperimentTarget`;

2. the `Experiment` is modify to measure an `ExperimentTarget`.

In addition to applying these changes, this diff also adapts the
whole tree to use `ExperimentTarget` in all places and adds a
trivial constructor to obtain `OOAPIURLInfo` when the category
code and the country code are unknown.

With this diff merged, implementing richer input for real is a
matter of implementing the following changes:

1. the `*registry.Factory` has a new func field, defined by
each experiment, that loads a list of `ExperimentTarget`;

2. we have a library for input loading containing the same code
that we currently use for the input loader;

3. the `InputLoader` is gone and instead we use the factory (or its
`*engine.experimentBuilder` wrapper for input loading;

4. we modify the `ExperimentArgs` passed to the `ExperimentMeasurer`
to contain an additional field that is the `ExperimentTarget` we
want to measure;

5. each experiment that needs richer input type-casts from the
`ExperimentTarget` interface to the concrete type that the experiment
richer input should have and accesses any option.

Part of #1612.

This implementation strategy emerged while discussing this matter
with @ainghazal, thank you so much for that!

cmd/ooniprobe/internal/nettests/dash.go

@@ -1,5 +1,7 @@
 package nettests
 
+import "github.com/ooni/probe-cli/v3/internal/model"
+
 // Dash test implementation
 type Dash struct {
 }
@@ -10,5 +12,5 @@ func (d Dash) Run(ctl *Controller) error {
 	if err != nil {
 		return err
 	}
-	return ctl.Run(builder, []string{""})
+	return ctl.Run(builder, []model.ExperimentTarget{model.NewOOAPIURLInfoWithDefaultCategoryAndCountry("")})
 }

cmd/ooniprobe/internal/nettests/dnscheck.go

@@ -10,7 +10,7 @@ import (
 // DNSCheck nettest implementation.
 type DNSCheck struct{}
 
-func (n DNSCheck) lookupURLs(ctl *Controller) ([]string, error) {
+func (n DNSCheck) lookupURLs(ctl *Controller) ([]model.ExperimentTarget, error) {
 	inputloader := &engine.InputLoader{
 		CheckInConfig: &model.OOAPICheckInConfig{
 			// not needed because we have default static input in the engine

cmd/ooniprobe/internal/nettests/echcheck.go

@@ -1,5 +1,7 @@
 package nettests
 
+import "github.com/ooni/probe-cli/v3/internal/model"
+
 // ECHCheck nettest implementation.
 type ECHCheck struct{}
 
@@ -11,5 +13,5 @@ func (n ECHCheck) Run(ctl *Controller) error {
 	}
 	// providing an input containing an empty string causes the experiment
 	// to recognize the empty string and use the default URL
-	return ctl.Run(builder, []string{""})
+	return ctl.Run(builder, []model.ExperimentTarget{model.NewOOAPIURLInfoWithDefaultCategoryAndCountry("")})
 }

cmd/ooniprobe/internal/nettests/facebook_messenger.go

@@ -1,5 +1,7 @@
 package nettests
 
+import "github.com/ooni/probe-cli/v3/internal/model"
+
 // FacebookMessenger test implementation
 type FacebookMessenger struct {
 }
@@ -12,5 +14,5 @@ func (h FacebookMessenger) Run(ctl *Controller) error {
 	if err != nil {
 		return err
 	}
-	return ctl.Run(builder, []string{""})
+	return ctl.Run(builder, []model.ExperimentTarget{model.NewOOAPIURLInfoWithDefaultCategoryAndCountry("")})
 }

cmd/ooniprobe/internal/nettests/http_header_field_manipulation.go

@@ -1,5 +1,7 @@
 package nettests
 
+import "github.com/ooni/probe-cli/v3/internal/model"
+
 // HTTPHeaderFieldManipulation test implementation
 type HTTPHeaderFieldManipulation struct {
 }
@@ -12,5 +14,5 @@ func (h HTTPHeaderFieldManipulation) Run(ctl *Controller) error {
 	if err != nil {
 		return err
 	}
-	return ctl.Run(builder, []string{""})
+	return ctl.Run(builder, []model.ExperimentTarget{model.NewOOAPIURLInfoWithDefaultCategoryAndCountry("")})
 }

cmd/ooniprobe/internal/nettests/http_invalid_request_line.go

@@ -1,5 +1,7 @@
 package nettests
 
+import "github.com/ooni/probe-cli/v3/internal/model"
+
 // HTTPInvalidRequestLine test implementation
 type HTTPInvalidRequestLine struct {
 }
@@ -12,5 +14,5 @@ func (h HTTPInvalidRequestLine) Run(ctl *Controller) error {
 	if err != nil {
 		return err
 	}
-	return ctl.Run(builder, []string{""})
+	return ctl.Run(builder, []model.ExperimentTarget{model.NewOOAPIURLInfoWithDefaultCategoryAndCountry("")})
 }

cmd/ooniprobe/internal/nettests/ndt.go

@@ -1,5 +1,7 @@
 package nettests
 
+import "github.com/ooni/probe-cli/v3/internal/model"
+
 // NDT test implementation. We use v7 of NDT since 2020-03-12.
 type NDT struct {
 }
@@ -11,5 +13,5 @@ func (n NDT) Run(ctl *Controller) error {
 	if err != nil {
 		return err
 	}
-	return ctl.Run(builder, []string{""})
+	return ctl.Run(builder, []model.ExperimentTarget{model.NewOOAPIURLInfoWithDefaultCategoryAndCountry("")})
 }

cmd/ooniprobe/internal/nettests/nettests.go

@@ -88,24 +88,22 @@ type Controller struct {
 // - on success, a list of strings containing URLs to test;
 //
 // - on failure, an error.
-func (c *Controller) BuildAndSetInputIdxMap(testlist []model.OOAPIURLInfo) ([]string, error) {
-	var urls []string
+func (c *Controller) BuildAndSetInputIdxMap(testlist []model.ExperimentTarget) ([]model.ExperimentTarget, error) {
 	urlIDMap := make(map[int64]int64)
 	for idx, url := range testlist {
 		log.Debugf("Going over URL %d", idx)
 		urlID, err := c.Probe.DB().CreateOrUpdateURL(
-			url.URL, url.CategoryCode, url.CountryCode,
+			url.Input(), url.Category(), url.Country(),
 		)
 		if err != nil {
 			log.Error("failed to add to the URL table")
 			return nil, err
 		}
-		log.Debugf("Mapped URL %s to idx %d and urlID %d", url.URL, idx, urlID)
+		log.Debugf("Mapped URL %s to idx %d and urlID %d", url.Input(), idx, urlID)
 		urlIDMap[int64(idx)] = urlID
-		urls = append(urls, url.URL)
 	}
 	c.inputIdxMap = urlIDMap
-	return urls, nil
+	return testlist, nil
 }
 
 // SetNettestIndex is used to set the current nettest index and total nettest
@@ -120,7 +118,7 @@ func (c *Controller) SetNettestIndex(i, n int) {
 //
 // This function will continue to run in most cases but will
 // immediately halt if something's wrong with the file system.
-func (c *Controller) Run(builder model.ExperimentBuilder, inputs []string) error {
+func (c *Controller) Run(builder model.ExperimentBuilder, inputs []model.ExperimentTarget) error {
 	db := c.Probe.DB()
 	// This will configure the controller as handler for the callbacks
 	// called by ooni/probe-engine/experiment.Experiment.
@@ -193,7 +191,7 @@ func (c *Controller) Run(builder model.ExperimentBuilder, inputs []string) error
 		}
 		c.msmts[idx64] = msmt
 
-		if input != "" {
+		if input.Input() != "" {
 			c.OnProgress(0, fmt.Sprintf("processing input: %s", input))
 		}
 		measurement, err := exp.MeasureWithContext(context.Background(), input)

cmd/ooniprobe/internal/nettests/psiphon.go

@@ -1,5 +1,7 @@
 package nettests
 
+import "github.com/ooni/probe-cli/v3/internal/model"
+
 // Psiphon test implementation
 type Psiphon struct {
 }
@@ -12,5 +14,5 @@ func (h Psiphon) Run(ctl *Controller) error {
 	if err != nil {
 		return err
 	}
-	return ctl.Run(builder, []string{""})
+	return ctl.Run(builder, []model.ExperimentTarget{model.NewOOAPIURLInfoWithDefaultCategoryAndCountry("")})
 }

cmd/ooniprobe/internal/nettests/riseupvpn.go

@@ -1,5 +1,7 @@
 package nettests
 
+import "github.com/ooni/probe-cli/v3/internal/model"
+
 // RiseupVPN test implementation
 type RiseupVPN struct {
 }
@@ -12,6 +14,5 @@ func (h RiseupVPN) Run(ctl *Controller) error {
 	if err != nil {
 		return err
 	}
-
-	return ctl.Run(builder, []string{""})
+	return ctl.Run(builder, []model.ExperimentTarget{model.NewOOAPIURLInfoWithDefaultCategoryAndCountry("")})
 }

cmd/ooniprobe/internal/nettests/signal.go

@@ -1,5 +1,7 @@
 package nettests
 
+import "github.com/ooni/probe-cli/v3/internal/model"
+
 // Signal nettest implementation.
 type Signal struct{}
 
@@ -11,5 +13,5 @@ func (h Signal) Run(ctl *Controller) error {
 	if err != nil {
 		return err
 	}
-	return ctl.Run(builder, []string{""})
+	return ctl.Run(builder, []model.ExperimentTarget{model.NewOOAPIURLInfoWithDefaultCategoryAndCountry("")})
 }

cmd/ooniprobe/internal/nettests/stunreachability.go

@@ -10,7 +10,7 @@ import (
 // STUNReachability nettest implementation.
 type STUNReachability struct{}
 
-func (n STUNReachability) lookupURLs(ctl *Controller) ([]string, error) {
+func (n STUNReachability) lookupURLs(ctl *Controller) ([]model.ExperimentTarget, error) {
 	inputloader := &engine.InputLoader{
 		CheckInConfig: &model.OOAPICheckInConfig{
 			// not needed because we have default static input in the engine

cmd/ooniprobe/internal/nettests/telegram.go

@@ -1,5 +1,7 @@
 package nettests
 
+import "github.com/ooni/probe-cli/v3/internal/model"
+
 // Telegram test implementation
 type Telegram struct {
 }
@@ -12,5 +14,5 @@ func (h Telegram) Run(ctl *Controller) error {
 	if err != nil {
 		return err
 	}
-	return ctl.Run(builder, []string{""})
+	return ctl.Run(builder, []model.ExperimentTarget{model.NewOOAPIURLInfoWithDefaultCategoryAndCountry("")})
 }

cmd/ooniprobe/internal/nettests/tor.go

@@ -1,5 +1,7 @@
 package nettests
 
+import "github.com/ooni/probe-cli/v3/internal/model"
+
 // Tor test implementation
 type Tor struct {
 }
@@ -12,5 +14,5 @@ func (h Tor) Run(ctl *Controller) error {
 	if err != nil {
 		return err
 	}
-	return ctl.Run(builder, []string{""})
+	return ctl.Run(builder, []model.ExperimentTarget{model.NewOOAPIURLInfoWithDefaultCategoryAndCountry("")})
 }

cmd/ooniprobe/internal/nettests/torsf.go

@@ -1,5 +1,7 @@
 package nettests
 
+import "github.com/ooni/probe-cli/v3/internal/model"
+
 // TorSf test implementation
 type TorSf struct {
 }
@@ -10,7 +12,7 @@ func (h TorSf) Run(ctl *Controller) error {
 	if err != nil {
 		return err
 	}
-	return ctl.Run(builder, []string{""})
+	return ctl.Run(builder, []model.ExperimentTarget{model.NewOOAPIURLInfoWithDefaultCategoryAndCountry("")})
 }
 
 func (h TorSf) onlyBackground() {}

cmd/ooniprobe/internal/nettests/vanillator.go

@@ -1,5 +1,7 @@
 package nettests
 
+import "github.com/ooni/probe-cli/v3/internal/model"
+
 // VanillaTor test implementation
 type VanillaTor struct {
 }
@@ -10,7 +12,7 @@ func (h VanillaTor) Run(ctl *Controller) error {
 	if err != nil {
 		return err
 	}
-	return ctl.Run(builder, []string{""})
+	return ctl.Run(builder, []model.ExperimentTarget{model.NewOOAPIURLInfoWithDefaultCategoryAndCountry("")})
 }
 
 func (h VanillaTor) onlyBackground() {}

cmd/ooniprobe/internal/nettests/web_connectivity.go

@@ -8,7 +8,7 @@ import (
 	"github.com/ooni/probe-cli/v3/internal/model"
 )
 
-func (n WebConnectivity) lookupURLs(ctl *Controller, categories []string) ([]string, error) {
+func (n WebConnectivity) lookupURLs(ctl *Controller, categories []string) ([]model.ExperimentTarget, error) {
 	inputloader := &engine.InputLoader{
 		CheckInConfig: &model.OOAPICheckInConfig{
 			// Setting Charging and OnWiFi to true causes the CheckIn

cmd/ooniprobe/internal/nettests/whatsapp.go

@@ -1,5 +1,7 @@
 package nettests
 
+import "github.com/ooni/probe-cli/v3/internal/model"
+
 // WhatsApp test implementation
 type WhatsApp struct {
 }
@@ -12,5 +14,5 @@ func (h WhatsApp) Run(ctl *Controller) error {
 	if err != nil {
 		return err
 	}
-	return ctl.Run(builder, []string{""})
+	return ctl.Run(builder, []model.ExperimentTarget{model.NewOOAPIURLInfoWithDefaultCategoryAndCountry("")})
 }

internal/engine/experiment.go

@@ -58,6 +58,8 @@ type experiment struct {
 	testVersion   string
 }
 
+var _ model.Experiment = &experiment{}
+
 // newExperiment creates a new [*experiment] given a [model.ExperimentMeasurer].
 func newExperiment(sess *Session, measurer model.ExperimentMeasurer) *experiment {
 	return &experiment{
@@ -180,7 +182,8 @@ func (e *experiment) OpenReportContext(ctx context.Context) error {
 }
 
 // MeasureWithContext implements [model.Experiment].
-func (e *experiment) MeasureWithContext(ctx context.Context, input string) (*model.Measurement, error) {
+func (e *experiment) MeasureWithContext(
+	ctx context.Context, target model.ExperimentTarget) (*model.Measurement, error) {
 	// Here we ensure that we have already looked up the probe location
 	// information such that we correctly populate the measurement and also
 	// VERY IMPORTANTLY to scrub the IP address from the measurement.
@@ -204,7 +207,7 @@ func (e *experiment) MeasureWithContext(ctx context.Context, input string) (*mod
 	// by adding the test keys etc. Please, note that, as of 2024-06-05, we're using
 	// the measurement Input to provide input to an experiment. We'll probably
 	// change this, when we'll have finished implementing richer input.
-	measurement := e.newMeasurement(input)
+	measurement := e.newMeasurement(target.Input())
 
 	// Record when we started the experiment, to compute the runtime.
 	start := time.Now()

internal/engine/experiment_integration_test.go

@@ -177,7 +177,8 @@ func TestSetCallbacks(t *testing.T) {
 	}
 	register := &registerCallbacksCalled{}
 	builder.SetCallbacks(register)
-	if _, err := builder.NewExperiment().MeasureWithContext(context.Background(), ""); err != nil {
+	target := model.NewOOAPIURLInfoWithDefaultCategoryAndCountry("")
+	if _, err := builder.NewExperiment().MeasureWithContext(context.Background(), target); err != nil {
 		t.Fatal(err)
 	}
 	if register.onProgressCalled == false {
@@ -221,7 +222,8 @@ func TestMeasurementFailure(t *testing.T) {
 	if err := builder.SetOptionAny("ReturnError", true); err != nil {
 		t.Fatal(err)
 	}
-	measurement, err := builder.NewExperiment().MeasureWithContext(context.Background(), "")
+	target := model.NewOOAPIURLInfoWithDefaultCategoryAndCountry("")
+	measurement, err := builder.NewExperiment().MeasureWithContext(context.Background(), target)
 	if err == nil {
 		t.Fatal("expected an error here")
 	}
@@ -255,7 +257,8 @@ func runexperimentflow(t *testing.T, experiment model.Experiment, input string)
 	if experiment.ReportID() == "" {
 		t.Fatal("reportID should not be empty here")
 	}
-	measurement, err := experiment.MeasureWithContext(ctx, input)
+	target := model.NewOOAPIURLInfoWithDefaultCategoryAndCountry(input)
+	measurement, err := experiment.MeasureWithContext(ctx, target)
 	if err != nil {
 		t.Fatal(err)
 	}
@@ -413,7 +416,8 @@ func TestMeasureLookupLocationFailure(t *testing.T) {
 	exp := newExperiment(sess, new(antaniMeasurer))
 	ctx, cancel := context.WithCancel(context.Background())
 	cancel() // so we fail immediately
-	if _, err := exp.MeasureWithContext(ctx, "xx"); err == nil {
+	target := model.NewOOAPIURLInfoWithDefaultCategoryAndCountry("xx")
+	if _, err := exp.MeasureWithContext(ctx, target); err == nil {
 		t.Fatal("expected an error here")
 	}
 }