refactor(mlablocate): use interface, remove unused fields, add docs (#383)

This is a very light refactoring of the mlablocate package where we do
the following things:

1. use interfaces rather depending on other pkgs where possible

2. only keep the fields we really need in the result struct

3. write more comprehensive docs (including todo-next comments)

While there, use `neubot/dash` rather than `ndt7` for the tests.

internal/engine/internal/mlablocate/mlablocate.go

@@ -1,4 +1,7 @@
-// Package mlablocate contains a locate.measurementlab.net client.
+// Package mlablocate contains a locate.measurementlab.net client
+// implementing v1 of the locate API. This version of the API isn't
+// suitable for requesting servers for ndt7. You should use the
+// mlablocatev2 package for that.
 package mlablocate
 
 import (
@@ -9,21 +12,43 @@ import (
 	"net/http"
 	"net/url"
 
-	"github.com/ooni/probe-cli/v3/internal/engine/model"
 	"github.com/ooni/probe-cli/v3/internal/iox"
 )
 
-// Client is a locate.measurementlab.net client.
+// Logger is the logger expected by this package.
+type Logger interface {
+	// Debugf formats and emits a debug message.
+	Debugf(format string, v ...interface{})
+}
+
+// HTTPClient is anything that looks like an http.Client.
+type HTTPClient interface {
+	// Do behaves like http.Client.Do.
+	Do(req *http.Request) (*http.Response, error)
+}
+
+// Client is a locate.measurementlab.net client. Please use the
+// NewClient factory to construct a new instance of client, otherwise
+// you MUST fill all the fields marked as MANDATORY.
 type Client struct {
-	HTTPClient *http.Client
+	// HTTPClient is the MANDATORY http client to use.
-	Hostname   string
+	HTTPClient HTTPClient
-	Logger     model.Logger
+
-	Scheme     string
+	// Hostname is the MANDATORY hostname of the mlablocate API.
-	UserAgent  string
+	Hostname string
+
+	// Logger is the MANDATORY logger to use.
+	Logger Logger
+
+	// Scheme is the MANDATORY scheme to use (http or https).
+	Scheme string
+
+	// UserAgent is the MANDATORY user-agent to use.
+	UserAgent string
 }
 
 // NewClient creates a new locate.measurementlab.net client.
-func NewClient(httpClient *http.Client, logger model.Logger, userAgent string) *Client {
+func NewClient(httpClient HTTPClient, logger Logger, userAgent string) *Client {
 	return &Client{
 		HTTPClient: httpClient,
 		Hostname:   "locate.measurementlab.net",
@@ -35,15 +60,20 @@ func NewClient(httpClient *http.Client, logger model.Logger, userAgent string) *
 
 // Result is a result of a query to locate.measurementlab.net.
 type Result struct {
-	City    string   `json:"city"`
+	// FQDN is the mlab server's FQDN.
-	Country string   `json:"country"`
+	FQDN string `json:"fqdn"`
-	IP      []string `json:"ip"`
+
-	FQDN    string   `json:"fqdn"`
+	// Site is the ID of the site where the server is.
-	Site    string   `json:"site"`
+	Site string `json:"site"`
 }
 
-// Query performs a locate.measurementlab.net query.
+// Query performs a locate.measurementlab.net query. This function returns
+// either valid result, on success, or an error, on failure.
+// (Note thay you cannot use this API to query for ndt7 servers. You should
+// use the mlablocatev2 API to obtain such servers.)
 func (c *Client) Query(ctx context.Context, tool string) (Result, error) {
+	// TODO(bassosimone): this code should probably be
+	// refactored to use the httpx package.
 	URL := &url.URL{
 		Scheme: c.Scheme,
 		Host:   c.Hostname,

internal/engine/internal/mlablocate/mlablocate_test.go

@@ -17,7 +17,7 @@ func TestWithoutProxy(t *testing.T) {
 		log.Log,
 		"miniooni/0.1.0-dev",
 	)
-	result, err := client.Query(context.Background(), "ndt7")
+	result, err := client.Query(context.Background(), "neubot/dash")
 	if err != nil {
 		t.Fatal(err)
 	}