private/apigen: Add validations to improve usage

Add a few validations to panic with a nicer message or abort rather than
generating invalid code.

Also improve the panic message wrapping a standard error with errs2 at
the time that it's returned.

Change-Id: I1393933eb5f0bc3f86646bf4d0acfc64626efbe0

private/apigen/common.go

@@ -7,11 +7,17 @@ import (
 	"fmt"
 	"path"
 	"reflect"
+	"regexp"
 	"strings"
 
 	"storj.io/storj/private/api"
 )
 
+var (
+	groupNameRegExp   = regexp.MustCompile(`^([A-Z0-9]\w*)?$`)
+	groupPrefixRegExp = regexp.MustCompile(`^\w*$`)
+)
+
 // API represents specific API's configuration.
 type API struct {
 	// Version is the corresponding version of the API.
@@ -31,7 +37,27 @@ type API struct {
 }
 
 // Group adds new endpoints group to API.
+// name must be `^([A-Z0-9]\w*)?$“
+// prefix must be `^\w*$`.
 func (a *API) Group(name, prefix string) *EndpointGroup {
+	if !groupNameRegExp.MatchString(name) {
+		panic(
+			fmt.Sprintf(
+				"invalid name for API Endpoint Group. name must fulfill the regular expression `^([A-Z0-9]\\w*)?$``, got %q",
+				name,
+			),
+		)
+	}
+	if !groupPrefixRegExp.MatchString(prefix) {
+		panic(
+			fmt.Sprintf(
+				"invalid prefix for API Endpoint Group %q. prefix must fulfill the regular expression `^\\w*$`, got %q",
+				name,
+				prefix,
+			),
+		)
+	}
+
 	group := &EndpointGroup{
 		Name:   name,
 		Prefix: prefix,

private/apigen/endpoint.go

@@ -4,8 +4,10 @@
 package apigen
 
 import (
+	"fmt"
 	"net/http"
 	"reflect"
+	"strings"
 )
 
 // Endpoint represents endpoint's configuration.
@@ -56,6 +58,8 @@ type fullEndpoint struct {
 }
 
 // EndpointGroup represents endpoints group.
+// You should always create a group using API.Group because it validates the field values to
+// guarantee correct code generation.
 type EndpointGroup struct {
 	Name      string
 	Prefix    string
@@ -63,27 +67,43 @@ type EndpointGroup struct {
 }
 
 // Get adds new GET endpoint to endpoints group.
+// It panics if path doesn't begin with '/'.
 func (eg *EndpointGroup) Get(path string, endpoint *Endpoint) {
 	eg.addEndpoint(path, http.MethodGet, endpoint)
 }
 
 // Patch adds new PATCH endpoint to endpoints group.
+// It panics if path doesn't begin with '/'.
 func (eg *EndpointGroup) Patch(path string, endpoint *Endpoint) {
 	eg.addEndpoint(path, http.MethodPatch, endpoint)
 }
 
 // Post adds new POST endpoint to endpoints group.
+// It panics if path doesn't begin with '/'.
 func (eg *EndpointGroup) Post(path string, endpoint *Endpoint) {
 	eg.addEndpoint(path, http.MethodPost, endpoint)
 }
 
 // Delete adds new DELETE endpoint to endpoints group.
+// It panics if path doesn't begin with '/'.
 func (eg *EndpointGroup) Delete(path string, endpoint *Endpoint) {
 	eg.addEndpoint(path, http.MethodDelete, endpoint)
 }
 
 // addEndpoint adds new endpoint to endpoints list.
+// It panics if path doesn't begin with '/'.
 func (eg *EndpointGroup) addEndpoint(path, method string, endpoint *Endpoint) {
+	if !strings.HasPrefix(path, "/") {
+		panic(
+			fmt.Sprintf(
+				"invalid path for method %q of EndpointGroup %q. path must start with slash, got %q",
+				method,
+				eg.Name,
+				path,
+			),
+		)
+	}
+
 	ep := &fullEndpoint{*endpoint, path, method}
 	for i, e := range eg.endpoints {
 		if e.Path == path && e.Method == method {

private/apigen/gogen.go

@@ -26,7 +26,7 @@ const DateFormat = "2006-01-02T15:04:05.999Z"
 func (a *API) MustWriteGo(path string) {
 	generated, err := a.generateGo()
 	if err != nil {
-		panic(errs.Wrap(err))
+		panic(err)
 	}
 
 	err = os.WriteFile(path, generated, 0644)
@@ -298,7 +298,7 @@ func (a *API) generateGo() ([]byte, error) {
 
 	output, err := format.Source([]byte(result.String()))
 	if err != nil {
-		return nil, err
+		return nil, errs.Wrap(err)
 	}
 
 	return output, nil