feat: expanding problem details

Author: rluders

examples/chi/main.go

@@ -52,6 +52,9 @@ func main() {
 	r.Use(middleware.Logger)
 	r.Use(middleware.Recoverer)
 
+	// Define the ProblemBaseURL - doesn't create the handlers
+	httpsuite.SetProblemBaseURL("http://localhost:8080")
+
 	// Define the endpoint POST
 	r.Post("/submit/{id}", func(w http.ResponseWriter, r *http.Request) {
 		// Using the function for parameter extraction to the ParseRequest

examples/gorillamux/main.go

@@ -42,6 +42,9 @@ func main() {
 	// Creating the router with Gorilla Mux
 	r := mux.NewRouter()
 
+	// Define the ProblemBaseURL - doesn't create the handlers
+	httpsuite.SetProblemBaseURL("http://localhost:8080")
+
 	r.HandleFunc("/submit/{id}", func(w http.ResponseWriter, r *http.Request) {
 		// Using the function for parameter extraction to the ParseRequest
 		req, err := httpsuite.ParseRequest[*SampleRequest](w, r, GorillaMuxParamExtractor, "id")

examples/stdmux/main.go

@@ -46,6 +46,9 @@ func main() {
 	// Creating the router using the Go standard mux
 	mux := http.NewServeMux()
 
+	// Define the ProblemBaseURL - doesn't create the handlers
+	httpsuite.SetProblemBaseURL("http://localhost:8080")
+
 	// Define the endpoint POST
 	mux.HandleFunc("/submit/", func(w http.ResponseWriter, r *http.Request) {
 		// Using the function for parameter extraction to the ParseRequest

problem_details.go

@@ -0,0 +1,123 @@
+package httpsuite
+
+const BlankUrl = "about:blank"
+
+var problemBaseURL = BlankUrl
+var errorTypePaths = map[string]string{
+	"validation_error":  "/errors/validation-error",
+	"not_found_error":   "/errors/not-found",
+	"server_error":      "/errors/server-error",
+	"bad_request_error": "/errors/bad-request",
+}
+
+// ProblemDetails conforms to RFC 9457, providing a standard format for describing errors in HTTP APIs.
+type ProblemDetails struct {
+	Type       string                 `json:"type"`                 // A URI reference identifying the problem type.
+	Title      string                 `json:"title"`                // A short, human-readable summary of the problem.
+	Status     int                    `json:"status"`               // The HTTP status code.
+	Detail     string                 `json:"detail,omitempty"`     // Detailed explanation of the problem.
+	Instance   string                 `json:"instance,omitempty"`   // A URI reference identifying the specific instance of the problem.
+	Extensions map[string]interface{} `json:"extensions,omitempty"` // Custom fields for additional details.
+}
+
+// NewProblemDetails creates a ProblemDetails instance with standard fields.
+func NewProblemDetails(status int, problemType, title, detail string) *ProblemDetails {
+	if problemType == "" {
+		problemType = BlankUrl
+	}
+	return &ProblemDetails{
+		Type:   problemType,
+		Title:  title,
+		Status: status,
+		Detail: detail,
+	}
+}
+
+// SetProblemBaseURL configures the base URL used in the "type" field for ProblemDetails.
+//
+// This function allows applications using httpsuite to provide a custom domain and structure
+// for error documentation URLs. By setting this base URL, the library can generate meaningful
+// and discoverable problem types.
+//
+// Parameters:
+// - baseURL: The base URL where error documentation is hosted (e.g., "https://api.mycompany.com").
+//
+// Example usage:
+//
+//	httpsuite.SetProblemBaseURL("https://api.mycompany.com")
+//
+// Once configured, generated ProblemDetails will include a "type" such as:
+//
+//	"https://api.mycompany.com/errors/validation-error"
+//
+// If the base URL is not set, the default value for the "type" field will be "about:blank".
+func SetProblemBaseURL(baseURL string) {
+	problemBaseURL = baseURL
+}
+
+// SetProblemErrorTypePath sets or updates the path for a specific error type.
+//
+// This allows applications to define custom paths for error documentation.
+//
+// Parameters:
+// - errorType: The unique key identifying the error type (e.g., "validation_error").
+// - path: The path under the base URL where the error documentation is located.
+//
+// Example usage:
+//
+//	httpsuite.SetProblemErrorTypePath("validation_error", "/errors/validation-error")
+//
+// After setting this path, the generated problem type for "validation_error" will be:
+//
+//	"https://api.mycompany.com/errors/validation-error"
+func SetProblemErrorTypePath(errorType, path string) {
+	errorTypePaths[errorType] = path
+}
+
+// SetProblemErrorTypePaths sets or updates multiple paths for different error types.
+//
+// This allows applications to define multiple custom paths at once.
+//
+// Parameters:
+// - paths: A map of error types to paths (e.g., {"validation_error": "/errors/validation-error"}).
+//
+// Example usage:
+//
+//	paths := map[string]string{
+//	    "validation_error":  "/errors/validation-error",
+//	    "not_found_error":   "/errors/not-found",
+//	}
+//	httpsuite.SetProblemErrorTypePaths(paths)
+//
+// This method overwrites any existing paths with the same keys.
+func SetProblemErrorTypePaths(paths map[string]string) {
+	for errorType, path := range paths {
+		errorTypePaths[errorType] = path
+	}
+}
+
+// GetProblemTypeURL get the full problem type URL based on the error type.
+//
+// If the error type is not found in the predefined paths, it returns a default unknown error path.
+//
+// Parameters:
+// - errorType: The unique key identifying the error type (e.g., "validation_error").
+//
+// Example usage:
+//
+//	problemTypeURL := GetProblemTypeURL("validation_error")
+func GetProblemTypeURL(errorType string) string {
+	if path, exists := errorTypePaths[errorType]; exists {
+		return getProblemBaseURL() + path
+	}
+
+	return BlankUrl
+}
+
+// getProblemBaseURL just return the baseURL if it isn't "about:blank"
+func getProblemBaseURL() string {
+	if problemBaseURL == BlankUrl {
+		return ""
+	}
+	return problemBaseURL
+}

problem_details_test.go

@@ -0,0 +1,156 @@
+package httpsuite
+
+import (
+	"testing"
+
+	"github.com/stretchr/testify/assert"
+)
+
+func Test_SetProblemBaseURL(t *testing.T) {
+	tests := []struct {
+		name     string
+		input    string
+		expected string
+	}{
+		{
+			name:     "Set valid base URL",
+			input:    "https://api.example.com",
+			expected: "https://api.example.com",
+		},
+		{
+			name:     "Set base URL to blank",
+			input:    BlankUrl,
+			expected: BlankUrl,
+		},
+	}
+
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			SetProblemBaseURL(tt.input)
+			assert.Equal(t, tt.expected, problemBaseURL)
+		})
+	}
+}
+
+func Test_SetProblemErrorTypePath(t *testing.T) {
+	tests := []struct {
+		name     string
+		errorKey string
+		path     string
+		expected string
+	}{
+		{
+			name:     "Set custom error path",
+			errorKey: "custom_error",
+			path:     "/errors/custom-error",
+			expected: "/errors/custom-error",
+		},
+		{
+			name:     "Override existing path",
+			errorKey: "validation_error",
+			path:     "/errors/new-validation-error",
+			expected: "/errors/new-validation-error",
+		},
+	}
+
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			SetProblemErrorTypePath(tt.errorKey, tt.path)
+			assert.Equal(t, tt.expected, errorTypePaths[tt.errorKey])
+		})
+	}
+}
+
+func Test_GetProblemTypeURL(t *testing.T) {
+	// Setup initial state
+	SetProblemBaseURL("https://api.example.com")
+	SetProblemErrorTypePath("validation_error", "/errors/validation-error")
+
+	tests := []struct {
+		name        string
+		errorType   string
+		expectedURL string
+	}{
+		{
+			name:        "Valid error type",
+			errorType:   "validation_error",
+			expectedURL: "https://api.example.com/errors/validation-error",
+		},
+		{
+			name:        "Unknown error type",
+			errorType:   "unknown_error",
+			expectedURL: BlankUrl,
+		},
+	}
+
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			result := GetProblemTypeURL(tt.errorType)
+			assert.Equal(t, tt.expectedURL, result)
+		})
+	}
+}
+
+func Test_getProblemBaseURL(t *testing.T) {
+	tests := []struct {
+		name           string
+		baseURL        string
+		expectedResult string
+	}{
+		{
+			name:           "Base URL is set",
+			baseURL:        "https://api.example.com",
+			expectedResult: "https://api.example.com",
+		},
+		{
+			name:           "Base URL is about:blank",
+			baseURL:        BlankUrl,
+			expectedResult: "",
+		},
+	}
+
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			problemBaseURL = tt.baseURL
+			assert.Equal(t, tt.expectedResult, getProblemBaseURL())
+		})
+	}
+}
+
+func Test_NewProblemDetails(t *testing.T) {
+	tests := []struct {
+		name         string
+		status       int
+		problemType  string
+		title        string
+		detail       string
+		expectedType string
+	}{
+		{
+			name:         "All fields provided",
+			status:       400,
+			problemType:  "https://api.example.com/errors/validation-error",
+			title:        "Validation Error",
+			detail:       "Invalid input",
+			expectedType: "https://api.example.com/errors/validation-error",
+		},
+		{
+			name:         "Empty problem type",
+			status:       404,
+			problemType:  "",
+			title:        "Not Found",
+			detail:       "The requested resource was not found",
+			expectedType: BlankUrl,
+		},
+	}
+
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			details := NewProblemDetails(tt.status, tt.problemType, tt.title, tt.detail)
+			assert.Equal(t, tt.status, details.Status)
+			assert.Equal(t, tt.title, details.Title)
+			assert.Equal(t, tt.detail, details.Detail)
+			assert.Equal(t, tt.expectedType, details.Type)
+		})
+	}
+}

request.go

@@ -64,7 +64,12 @@ func ParseRequest[T RequestParamSetter](w http.ResponseWriter, r *http.Request,
 	// Decode JSON body if present
 	if r.Body != http.NoBody {
 		if err := json.NewDecoder(r.Body).Decode(&request); err != nil {
-			problem := NewProblemDetails(http.StatusBadRequest, "Invalid Request", err.Error())
+			problem := NewProblemDetails(
+				http.StatusBadRequest,
+				GetProblemTypeURL("bad_request_error"),
+				"Invalid Request",
+				err.Error(),
+			)
 			SendResponse[any](w, http.StatusBadRequest, nil, problem, nil)
 			return empty, err
 		}
@@ -79,12 +84,23 @@ func ParseRequest[T RequestParamSetter](w http.ResponseWriter, r *http.Request,
 	for _, key := range pathParams {
 		value := paramExtractor(r, key)
 		if value == "" {
-			problem := NewProblemDetails(http.StatusBadRequest, "Missing Parameter", "Parameter "+key+" not found in request")
+			problem := NewProblemDetails(
+				http.StatusBadRequest,
+				GetProblemTypeURL("bad_request_error"),
+				"Missing Parameter",
+				"Parameter "+key+" not found in request",
+			)
 			SendResponse[any](w, http.StatusBadRequest, nil, problem, nil)
 			return empty, errors.New("missing parameter: " + key)
 		}
+
 		if err := request.SetParam(key, value); err != nil {
-			problem := NewProblemDetails(http.StatusInternalServerError, "Parameter Error", "Failed to set field "+key)
+			problem := NewProblemDetails(
+				http.StatusInternalServerError,
+				GetProblemTypeURL("sever_error"),
+				"Parameter Error",
+				"Failed to set field "+key,
+			)
 			problem.Extensions = map[string]interface{}{"error": err.Error()}
 			SendResponse[any](w, http.StatusInternalServerError, nil, problem, nil)
 			return empty, err

request_test.go

@@ -82,7 +82,7 @@ func Test_ParseRequest(t *testing.T) {
 			},
 			want:       nil,
 			wantErr:    assert.Error,
-			wantDetail: NewProblemDetails(http.StatusBadRequest, "Validation Error", "One or more fields failed validation."),
+			wantDetail: NewProblemDetails(http.StatusBadRequest, "about:blank", "Validation Error", "One or more fields failed validation."),
 		},
 		{
 			name: "Invalid JSON Body",
@@ -97,7 +97,7 @@ func Test_ParseRequest(t *testing.T) {
 			},
 			want:       nil,
 			wantErr:    assert.Error,
-			wantDetail: NewProblemDetails(http.StatusBadRequest, "Invalid Request", "invalid character 'i' looking for beginning of object key string"),
+			wantDetail: NewProblemDetails(http.StatusBadRequest, "about:blank", "Invalid Request", "invalid character 'i' looking for beginning of object key string"),
 		},
 	}