Feature/boilerplate

go.mod

@@ -67,6 +67,7 @@ require (
 	github.com/golang/protobuf v1.5.3-0.20210916003710-5d5e8c018a13 // indirect
 	github.com/grafov/m3u8 v0.11.1 // indirect
 	github.com/hashicorp/golang-lru v0.5.4 // indirect
+	github.com/inconshreveable/mousetrap v1.0.0 // indirect
 	github.com/juju/ratelimit v1.0.2 // indirect
 	github.com/kballard/go-shellquote v0.0.0-20180428030007-95032a82bc51 // indirect
 	github.com/klauspost/cpuid/v2 v2.1.0 // indirect
@@ -103,6 +104,8 @@ require (
 	github.com/refraction-networking/utls v1.0.0 // indirect
 	github.com/sergeyfrolov/bsbuffer v0.0.0-20180903213811-94e85abb8507 // indirect
 	github.com/sirupsen/logrus v1.9.0 // indirect
+	github.com/spf13/cobra v1.5.0
+	github.com/spf13/pflag v1.0.5 // indirect
 	github.com/syndtr/gocapability v0.0.0-20200815063812-42c35b437635 // indirect
 	github.com/templexxx/cpu v0.0.9 // indirect
 	github.com/templexxx/xorsimd v0.4.1 // indirect

go.sum

@@ -155,6 +155,7 @@ github.com/coreos/pkg v0.0.0-20160727233714-3ac0863d7acf/go.mod h1:E3G3o1h8I7cfc
 github.com/cpuguy83/go-md2man v1.0.10/go.mod h1:SmD6nW6nTyfqj6ABTjUi3V3JVMnlJmwcJI5acqYI6dE=
 github.com/cpuguy83/go-md2man/v2 v2.0.0-20190314233015-f79a8a8ca69d/go.mod h1:maD7wRr/U5Z6m/iR4s+kqSMx2CaBsrgA7czyZG/E6dU=
 github.com/cpuguy83/go-md2man/v2 v2.0.0/go.mod h1:maD7wRr/U5Z6m/iR4s+kqSMx2CaBsrgA7czyZG/E6dU=
+github.com/cpuguy83/go-md2man/v2 v2.0.2/go.mod h1:tgQtvFlXSQOSOSIRvRPT7W67SCa46tRHOmNcaadrF8o=
 github.com/creack/pty v1.1.7/go.mod h1:lj5s0c3V2DBrqTV7llrYr5NG6My20zk30Fl46Y7DoTY=
 github.com/creack/pty v1.1.17 h1:QeVUsEDNrLBW4tMgZHvxy18sKtr6VI492kBhUfhDJNI=
 github.com/creack/pty v1.1.17/go.mod h1:MOBLtS5ELjhRRrroQr9kyvTxUAFNvYEK993ew/Vr4O4=
@@ -395,6 +396,7 @@ github.com/iancoleman/strcase v0.2.0/go.mod h1:iwCmte+B7n89clKwxIoIXy/HfoL7AsD47
 github.com/ianlancetaylor/demangle v0.0.0-20181102032728-5e5cf60278f6/go.mod h1:aSSvb/t6k1mPoxDqO4vJh6VOCGPwU4O0C2/Eqndh1Sc=
 github.com/ianlancetaylor/demangle v0.0.0-20200824232613-28f6c0f3b639/go.mod h1:aSSvb/t6k1mPoxDqO4vJh6VOCGPwU4O0C2/Eqndh1Sc=
 github.com/imdario/mergo v0.3.11/go.mod h1:jmQim1M+e3UYxmgPu/WyfjB3N3VflVyUjjjwH0dnCYA=
+github.com/inconshreveable/mousetrap v1.0.0 h1:Z8tu5sraLXCXIcARxBp/8cbvlwVa7Z1NHg9XEKhtSvM=
 github.com/inconshreveable/mousetrap v1.0.0/go.mod h1:PxqpIevigyE2G7u3NXJIT2ANytuPF1OarO4DADm73n8=
 github.com/influxdata/influxdb1-client v0.0.0-20191209144304-8bf82d3c094d/go.mod h1:qj24IKcXYK6Iy9ceXlo3Tc+vtHo9lIhSX5JddghvEPo=
 github.com/ipfs/go-detect-race v0.0.1 h1:qX/xay2W3E4Q1U7d9lNs1sU9nvguX0a7319XbyQ6cOk=
@@ -760,6 +762,7 @@ github.com/rubenv/sql-migrate v1.1.2 h1:9M6oj4e//owVVHYrFISmY9LBRw6gzkCNmD9MV36t
 github.com/rubenv/sql-migrate v1.1.2/go.mod h1:/7TZymwxN8VWumcIxw1jjHEcR1djpdkMHQPT4FWdnbQ=
 github.com/russross/blackfriday v1.5.2/go.mod h1:JO/DiYxRf+HjHt06OyowR9PTA263kcR/rfWxYHBV53g=
 github.com/russross/blackfriday/v2 v2.0.1/go.mod h1:+Rmxgy9KzJVeS9/2gXHxylqXiyQDYRxCVz55jmeOWTM=
+github.com/russross/blackfriday/v2 v2.1.0/go.mod h1:+Rmxgy9KzJVeS9/2gXHxylqXiyQDYRxCVz55jmeOWTM=
 github.com/ryanuber/columnize v0.0.0-20160712163229-9b3edd62028f/go.mod h1:sm1tb6uqfes/u+d4ooFouqFdy9/2g9QGwK3SQygK0Ts=
 github.com/ryanuber/go-glob v0.0.0-20170128012129-256dc444b735 h1:7YvPJVmEeFHR1Tj9sZEYsmarJEQfMVYpd/Vyy/A8dqE=
 github.com/samuel/go-zookeeper v0.0.0-20190923202752-2cc03de413da/go.mod h1:gi+0XIa01GRL2eRQVjQkKGqKF3SF9vZR/HnPullcV2E=
@@ -821,10 +824,13 @@ github.com/spf13/cast v1.3.1/go.mod h1:Qx5cxh0v+4UWYiBimWS+eyWzqEqokIECu5etghLkU
 github.com/spf13/cobra v0.0.3/go.mod h1:1l0Ry5zgKvJasoi3XT1TypsSe7PqH0Sj9dhYf7v3XqQ=
 github.com/spf13/cobra v0.0.5/go.mod h1:3K3wKZymM7VvHMDS9+Akkh4K60UwM26emMESw8tLCHU=
 github.com/spf13/cobra v1.2.1/go.mod h1:ExllRjgxM/piMAM+3tAZvg8fsklGAf3tPfi+i8t68Nk=
+github.com/spf13/cobra v1.5.0 h1:X+jTBEBqF0bHN+9cSMgmfuvv2VHJ9ezmFNf9Y/XstYU=
+github.com/spf13/cobra v1.5.0/go.mod h1:dWXEIy2H428czQCjInthrTRUg7yKbok+2Qi/yBIJoUM=
 github.com/spf13/jwalterweatherman v1.0.0/go.mod h1:cQK4TGJAtQXfYWX+Ddv3mKDzgVb68N+wFjFa4jdeBTo=
 github.com/spf13/jwalterweatherman v1.1.0/go.mod h1:aNWZUN0dPAAO/Ljvb5BEdw96iTZ0EXowPYD95IqWIGo=
 github.com/spf13/pflag v1.0.1/go.mod h1:DYY7MBk1bdzusC3SYhjObp+wFpr4gzcvqqNjLnInEg4=
 github.com/spf13/pflag v1.0.3/go.mod h1:DYY7MBk1bdzusC3SYhjObp+wFpr4gzcvqqNjLnInEg4=
+github.com/spf13/pflag v1.0.5 h1:iy+VFUOCP1a+8yFto/drg2CJ5u0yRoB7fZw3DKv/JXA=
 github.com/spf13/pflag v1.0.5/go.mod h1:McXfInJRrz4CZXVZOBLb0bTZqETkiAhM9Iw0y3An2Bg=
 github.com/spf13/viper v1.3.2/go.mod h1:ZiWeW+zYFKm7srdB9IoDzzZXaJaI5eL9QjNiN/DMA2s=
 github.com/spf13/viper v1.8.1/go.mod h1:o0Pch8wJ9BVSWGQMbra6iw0oQ5oktSIBaujf1rJH9Ns=

internal/cmd/boilerplate/experiment.go

@@ -0,0 +1,218 @@
+package main
+
+//
+// Code to generate a new experiment.
+//
+
+import (
+	_ "embed"
+	"path/filepath"
+	"strings"
+	"text/template"
+
+	"github.com/AlecAivazis/survey/v2"
+	"github.com/ooni/probe-cli/v3/internal/runtimex"
+	"github.com/spf13/cobra"
+)
+
+// Implements interactively generating a new experiment.
+type NewExperimentCommand struct{}
+
+// Information about the experiment to create.
+type ExperimentInfo struct {
+	// Experiment name
+	Name string
+
+	// Experiment version
+	Version string
+
+	// Experiment spec URL
+	SpecURL string
+
+	// Experiment input policy
+	InputPolicy string
+
+	// Whether this experiment is interruptible.
+	Interruptible bool
+}
+
+// Package returns the package name.
+func (info *ExperimentInfo) Package() string {
+	return strings.ReplaceAll(strings.ToLower(info.Name), "_", "")
+}
+
+// Called by the CLI parser
+func (c *NewExperimentCommand) Run(*cobra.Command, []string) {
+	printf("\n")
+	printf("Welcome! This command will help you to automatically generate code\n")
+	printf("implementing a new OONI network experiment!\n")
+	print("\n")
+
+	info := getExperimentInfo()
+
+	printf("\n")
+	printf("Thank you! Now I'm going to generate boilerplate code for the new experiment!\n")
+	printf("\n")
+
+	makeExperimentDirectory(info)
+	generateDocGo(info)
+	generateMeasurerGo(info)
+	generateModelsGo(info)
+	generateRegistryEntryGo(info)
+	if info.InputPolicy != "InputNone" {
+		generateInputParserGo(info)
+	}
+
+	pkg := filepath.Join("internal", "experiment", info.Package(), "/...")
+	gofmt(pkg)
+
+	printf("\n")
+	printf("🏁 All done!\n")
+	printf("\n")
+}
+
+// Obtains the experiment info
+func getExperimentInfo() *ExperimentInfo {
+	return &ExperimentInfo{
+		Name:          getExperimentName(),
+		Version:       getExperimentVersion(),
+		SpecURL:       getExperimentSpecURL(),
+		InputPolicy:   getExperimentInputPolicy(),
+		Interruptible: getExperimentInterruptible(),
+	}
+}
+
+// Obtains the experiment name
+func getExperimentName() string {
+	prompt := &survey.Input{
+		Message: "Experiment's name:",
+	}
+	var experiment string
+	err := survey.AskOne(prompt, &experiment)
+	runtimex.PanicOnError(err, "survey.AskOne failed")
+	return experiment
+}
+
+// Obtains the experiment version
+func getExperimentVersion() string {
+	prompt := &survey.Input{
+		Message: "Experiment's version:",
+	}
+	var version string
+	err := survey.AskOne(prompt, &version)
+	runtimex.PanicOnError(err, "survey.AskOne failed")
+	return version
+}
+
+// Obtains the experiment spec URL
+func getExperimentSpecURL() string {
+	prompt := &survey.Input{
+		Message: "Experiment's spec URL:",
+	}
+	var specURL string
+	err := survey.AskOne(prompt, &specURL)
+	runtimex.PanicOnError(err, "survey.AskOne failed")
+	return specURL
+}
+
+// Obtains the experiment input policy.
+func getExperimentInputPolicy() string {
+	var inputPolicy string
+	prompt := &survey.Select{
+		Message: "Choose an experiment input policy:",
+		Options: []string{
+			"InputOrQueryBackend",
+			"InputOrStaticDefault",
+			"InputStrictlyRequired",
+			"InputNone",
+		},
+	}
+	err := survey.AskOne(prompt, &inputPolicy)
+	runtimex.PanicOnError(err, "survey.AskOne failed")
+	return inputPolicy
+}
+
+// Returns whether we can interrupt experiments midway.
+func getExperimentInterruptible() bool {
+	var interruptible bool
+	prompt := &survey.Confirm{
+		Message: "Should the engine be able to abruptly interrupt a measurement?",
+	}
+	err := survey.AskOne(prompt, &interruptible)
+	runtimex.PanicOnError(err, "survey.AskOne failed")
+	return interruptible
+}
+
+// Creates a directory for the new experiment.
+func makeExperimentDirectory(info *ExperimentInfo) {
+	fulldir := filepath.Join("internal", "experiment", info.Package())
+	mkdirP(fulldir)
+}
+
+//go:embed "experiment/doc.go.txt"
+var experimentDocGoTemplate string
+
+// Generates the doc.go file
+func generateDocGo(info *ExperimentInfo) {
+	fullpath := filepath.Join("internal", "experiment", info.Package(), "doc.go")
+	tmpl := template.Must(template.New("doc.go").Parse(experimentDocGoTemplate))
+	writeTemplate(fullpath, tmpl, info)
+}
+
+//go:embed "experiment/measurer.go.txt"
+var experimentMeasurerGoTemplate string
+
+// Generates the measurer.go file
+func generateMeasurerGo(info *ExperimentInfo) {
+	fullpath := filepath.Join("internal", "experiment", info.Package(), "measurer.go")
+	tmpl := template.Must(template.New("measurer.go").Parse(experimentMeasurerGoTemplate))
+	writeTemplate(fullpath, tmpl, info)
+}
+
+//go:embed "experiment/config.go.txt"
+var experimentConfigGoTemplate string
+
+//go:embed "experiment/summary.go.txt"
+var experimentSummaryGoTemplate string
+
+//go:embed "experiment/testkeys.go.txt"
+var experimentTestkeysGoTemplate string
+
+// Generates the model.go file
+func generateModelsGo(info *ExperimentInfo) {
+	{
+		fullpath := filepath.Join("internal", "experiment", info.Package(), "config.go")
+		tmpl := template.Must(template.New("config.go").Parse(experimentConfigGoTemplate))
+		writeTemplate(fullpath, tmpl, info)
+	}
+	{
+		fullpath := filepath.Join("internal", "experiment", info.Package(), "summary.go")
+		tmpl := template.Must(template.New("model.go").Parse(experimentSummaryGoTemplate))
+		writeTemplate(fullpath, tmpl, info)
+	}
+	{
+		fullpath := filepath.Join("internal", "experiment", info.Package(), "testkeys.go")
+		tmpl := template.Must(template.New("model.go").Parse(experimentTestkeysGoTemplate))
+		writeTemplate(fullpath, tmpl, info)
+	}
+}
+
+//go:embed "experiment/registry.go.txt"
+var experimentRegistryEntryGoTemplate string
+
+// Generates the experiment's entry inside ./internal/registry
+func generateRegistryEntryGo(info *ExperimentInfo) {
+	fullpath := filepath.Join("internal", "registry", info.Package()+".go")
+	tmpl := template.Must(template.New("registryentry.go").Parse(experimentRegistryEntryGoTemplate))
+	writeTemplate(fullpath, tmpl, info)
+}
+
+//go:embed "experiment/inputparser.go.txt"
+var experimentInputParserGoTemplate string
+
+// Generates the experiment's entry inside ./internal/registry
+func generateInputParserGo(info *ExperimentInfo) {
+	fullpath := filepath.Join("internal", "experiment", info.Package(), "inputparser.go")
+	tmpl := template.Must(template.New("inputparser.go").Parse(experimentInputParserGoTemplate))
+	writeTemplate(fullpath, tmpl, info)
+}

internal/cmd/boilerplate/experiment/config.go.txt

@@ -0,0 +1,12 @@
+package {{ .Package }}
+
+//
+// Config
+//
+
+// Config contains {{ .Package }} experiment configuration.
+type Config struct {
+	// TODO: add fields here if you need any config
+}
+
+// TODO: implement convenience accessors you may need for Config

internal/cmd/boilerplate/experiment/doc.go.txt

@@ -0,0 +1,4 @@
+// Package {{ .Package }} implements the {{ .Name }} experiment.
+//
+// Spec: {{ .SpecURL }}.
+package {{ .Package }}

internal/cmd/boilerplate/experiment/inputparser.go.txt

@@ -0,0 +1,63 @@
+package {{ .Package }}
+
+//
+// Input parsing
+//
+
+import (
+	"errors"
+	"net"
+	"net/url"
+
+	"github.com/ooni/probe-cli/v3/internal/runtimex"
+)
+
+// InputParser helps to print the experiment's input.
+type InputParser struct {
+	// List of accepted URL schemes.
+	AcceptedSchemes []string
+
+	// Whether to allow endpoints in input.
+	AllowEndpoints bool
+
+	// The default scheme to use if AllowEndpoints == true.
+	DefaultScheme string
+}
+
+// Parse parses the experiment input and returns the resulting URL.
+func (ip *InputParser) Parse(input string) (*url.URL, error) {
+	// put this check at top-level such that we always see the crash if needed
+	runtimex.PanicIfTrue(
+		ip.AllowEndpoints && ip.DefaultScheme == "",
+		"invalid configuration for InputParser.AllowEndpoints == true",
+	)
+	URL, err := url.Parse(input)
+	if err != nil {
+		return ip.maybeAllowEndpoints(URL, err)
+	}
+	for _, scheme := range ip.AcceptedSchemes {
+		if URL.Scheme == scheme {
+			// TODO: here you may want to perform additional parsing
+			return URL, nil
+		}
+	}
+	return nil, errors.New("cannot parse input")
+}
+
+// Conditionally allows endpoints when ip.AllowEndpoints is true.
+func (ip *InputParser) maybeAllowEndpoints(URL *url.URL, err error) (*url.URL, error) {
+	runtimex.PanicIfNil(err, "expected to be called with a non-nil error")
+	if ip.AllowEndpoints && URL.Scheme != "" && URL.Opaque != "" && URL.User == nil &&
+		URL.Host == "" && URL.Path == "" && URL.RawPath == "" &&
+		URL.RawQuery == "" && URL.Fragment == "" && URL.RawFragment == "" {
+		// See https://go.dev/play/p/Rk5pS_zGY5U
+		//
+		// Note that we know that `ip.DefaultScheme != ""` from the above runtime check.
+		out := &url.URL{
+			Scheme: ip.DefaultScheme,
+			Host:   net.JoinHostPort(URL.Scheme, URL.Opaque),
+		}
+		return out, nil
+	}
+	return nil, err
+}