feat: add structured error responses for handler errors (#57)

* feat(errors): add Error proto message for structured handler errors

- Add Error message with string message field
- Provides structured error responses for handler failures
- Consistent with existing ValidationError pattern

* build(proto): regenerate Go code with new Error message

- Update errors.pb.go with Error type and methods
- Regenerate annotations.pb.go and headers.pb.go with latest protoc
- Generated code includes proper protobuf bindings for Error message

* feat(httpgen): replace plain string errors with structured Error responses

- Add generateWriteErrorResponseFunc to create error response helper
- Replace http.Error calls with structured sebufhttp.Error messages
- Apply consistent error handling for handler, marshal, and write errors
- Maintain HTTP 500 status code for internal server errors
- Serialize errors as JSON/protobuf based on request Content-Type

* chore(dev): update coverage reports and development settings

- Update coverage badge and reports after test execution
- Update local Claude settings for development workflow

* docs: update documentation for structured error handling

- Add comprehensive error handling section to http-generation.md
- Document Error proto message and handler error responses
- Update key features to include structured error responses
- Modernize CLAUDE.md examples to use structured error functions
- Add error hierarchy and response format examples
- Include JSON and protobuf serialization details

Reflects new Error message implementation and writeErrorResponse function.

* refactor(httpgen): eliminate code duplication in error response functions

- Extract common logic into shared writeProtoMessageResponse helper
- Replace duplicated marshaling logic in validation and handler error functions
- Fix golangci-lint duplication warnings (dupl)
- Maintain identical functionality while reducing code repetition
- Fix line length formatting issues

Author: SebastienMelki

.claude/settings.local.json

@@ -39,7 +39,8 @@
       "Bash(./generate_golden.sh:*)",
       "Bash(UPDATE_GOLDEN=1 go test -run TestExhaustiveGoldenFiles)",
       "Bash(git restore:*)",
-      "Bash(git checkout:*)"
+      "Bash(git checkout:*)",
+      "Bash(./scripts/run_tests.sh:*)"
     ],
     "deny": [],
     "ask": [],

CLAUDE.md

@@ -72,7 +72,7 @@ func BindingMiddleware[Req any](next http.Handler) http.Handler {
     // Automatic body validation happens here
     if msg, ok := any(toBind).(proto.Message); ok {
       if err := ValidateMessage(msg); err != nil {
-        http.Error(w, err.Error(), http.StatusBadRequest)
+        writeValidationError(w, r, err)
         return
       }
     }
@@ -86,17 +86,9 @@ func HeaderValidationMiddleware(requiredHeaders []HeaderConfig) func(http.Handle
   return func(next http.Handler) http.Handler {
     return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
       // Validate required headers
-      for _, header := range requiredHeaders {
-        value := r.Header.Get(header.Name)
-        if header.Required && value == "" {
-          http.Error(w, fmt.Sprintf("Missing required header: %s", header.Name), http.StatusBadRequest)
-          return
-        }
-        // Type and format validation
-        if err := validateHeaderValue(value, header.Type, header.Format); err != nil {
-          http.Error(w, err.Error(), http.StatusBadRequest)
-          return
-        }
+      if validationErr := validateHeaders(r, serviceHeaders, methodHeaders); validationErr != nil {
+        writeValidationErrorResponse(w, r, validationErr)
+        return
       }
       next.ServeHTTP(w, r)
     })
@@ -265,9 +257,12 @@ service UserService {
 ```
 
 ### Error Handling
-- **HTTP 400 responses**: Validation errors return Bad Request with error message for both body and header validation failures
-- **Detailed errors**: Full validation error details from protovalidate for body validation
-- **Header errors**: Clear messages indicating which header failed validation and why
+- **Structured Error Responses**: All errors use protobuf messages for consistent API responses
+- **Validation Errors (HTTP 400)**: ValidationError with field-level violations for body and header validation failures
+- **Handler Errors (HTTP 500)**: Error messages for service implementation failures with custom messages
+- **Content-Type Aware**: Error responses serialized as JSON or protobuf based on request Content-Type
+- **Detailed validation errors**: Full validation error details from protovalidate for body validation
+- **Header validation errors**: Clear messages indicating which header failed validation and why
 - **Fail-fast**: Validation stops request processing immediately on failure (headers validated before body)
 
 ## Type System