fix(httpgen): preserve structure of proto.Message errors returned from handlers

Previously, when a handler returned a custom proto error message (e.g.,
NotFoundError), it was wrapped in sebufhttp.Error{Message: err.Error()},
which converted the structured proto to a string and lost all its fields.

This fix:
- Adds proto.Message type check in genericHandler before wrapping errors
- Adds proto.Message type check in defaultErrorResponse as fallback
- Preserves full proto structure in error responses

Example:
Before: {"message":"{\"resourceType\":\"user\",\"resourceId\":\"123\"}"}
After:  {"resourceType":"user","resourceId":"123"}

Fixes #81

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

Author: 2 people

CLAUDE.md

@@ -259,6 +259,7 @@ service UserService {
 ### Error Handling
 - **Structured Error Responses**: All errors use protobuf messages for consistent API responses
 - **Automatic Go Error Interface**: Any protobuf message ending with "Error" automatically implements Go's error interface for `errors.As()` and `errors.Is()` support
+- **Proto Message Error Preservation**: Custom proto error messages returned from handlers are serialized directly, preserving their structure (not wrapped in a generic Error message)
 - **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
@@ -267,6 +268,31 @@ service UserService {
 - **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)
 
+**Custom Proto Error Example:**
+```protobuf
+// Define a custom error message
+message NotFoundError {
+  string resource_type = 1;
+  string resource_id = 2;
+}
+```
+
+```go
+// Return it from your handler - it will be serialized directly
+func (s *Server) GetUser(ctx context.Context, req *GetUserRequest) (*User, error) {
+    user, err := s.db.FindUser(req.Id)
+    if err != nil {
+        return nil, &NotFoundError{
+            ResourceType: "user",
+            ResourceId:   req.Id,
+        }
+    }
+    return user, nil
+}
+// Response: {"resourceType":"user","resourceId":"123"}
+// NOT: {"message":"{\"resourceType\":\"user\",\"resourceId\":\"123\"}"}
+```
+
 ## Type System
 
 The plugin handles comprehensive protobuf-to-Go type mapping in `getFieldType()` (generator.go:118):

internal/httpgen/error_handler_test.go

@@ -381,3 +381,87 @@ func TestErrorHandlerBackwardCompatibility(t *testing.T) {
 		}
 	})
 }
+
+// TestProtoMessageErrorPreservation tests that proto.Message errors are preserved without wrapping.
+func TestProtoMessageErrorPreservation(t *testing.T) {
+	files := generateTestFiles(t, "http_verbs_comprehensive.proto")
+
+	t.Run("genericHandler checks for proto.Message errors", func(t *testing.T) {
+		// The genericHandler should check if the error is already a proto.Message
+		if !strings.Contains(files.binding, "if protoErr, ok := err.(proto.Message); ok {") {
+			t.Error("genericHandler should check if error is a proto.Message")
+		}
+	})
+
+	t.Run("genericHandler passes proto.Message errors directly to writeErrorWithHandler", func(t *testing.T) {
+		// When error is a proto.Message, it should be passed directly without wrapping
+		if !strings.Contains(files.binding, "writeErrorWithHandler(w, r, protoErr, errorHandler)") {
+			t.Error("genericHandler should pass proto.Message errors directly to writeErrorWithHandler")
+		}
+	})
+
+	t.Run("genericHandler has comment explaining proto.Message check", func(t *testing.T) {
+		if !strings.Contains(files.binding, "Check if error is already a proto.Message") {
+			t.Error("genericHandler should have comment explaining proto.Message check")
+		}
+	})
+
+	t.Run("defaultErrorResponse checks for proto.Message errors", func(t *testing.T) {
+		// defaultErrorResponse should also check for proto.Message errors as fallback
+		if !strings.Contains(files.binding, "if protoErr, ok := err.(proto.Message); ok {") {
+			t.Error("defaultErrorResponse should check if error is a proto.Message")
+		}
+	})
+
+	t.Run("defaultErrorResponse returns proto.Message errors directly", func(t *testing.T) {
+		// The function should return the proto.Message directly without wrapping
+		if !strings.Contains(files.binding, "return protoErr") {
+			t.Error("defaultErrorResponse should return proto.Message errors directly")
+		}
+	})
+
+	t.Run("proto.Message check comes before sebufhttp.Error wrapping", func(t *testing.T) {
+		// In genericHandler, the proto.Message check should come before the sebufhttp.Error wrapping
+		binding := files.binding
+		protoMsgCheckPos := strings.Index(binding, "if protoErr, ok := err.(proto.Message)")
+		sebufErrorPos := strings.Index(binding, "errorMsg := &sebufhttp.Error{")
+
+		if protoMsgCheckPos == -1 || sebufErrorPos == -1 {
+			t.Error("Both proto.Message check and sebufhttp.Error creation should exist")
+			return
+		}
+
+		if protoMsgCheckPos > sebufErrorPos {
+			t.Error("proto.Message check should come before sebufhttp.Error wrapping in genericHandler")
+		}
+	})
+
+	t.Run("defaultErrorResponse proto.Message check comes after known error types", func(t *testing.T) {
+		// In defaultErrorResponse, proto.Message check should be after ValidationError and Error checks
+		binding := files.binding
+
+		// Find the defaultErrorResponse function
+		funcStart := strings.Index(binding, "func defaultErrorResponse(err error) proto.Message {")
+		if funcStart == -1 {
+			t.Error("defaultErrorResponse function not found")
+			return
+		}
+
+		funcBody := binding[funcStart:]
+
+		// Check order: ValidationError -> Error -> proto.Message -> fallback
+		valErrPos := strings.Index(funcBody, "var valErr *sebufhttp.ValidationError")
+		handlerErrPos := strings.Index(funcBody, "var handlerErr *sebufhttp.Error")
+		protoMsgPos := strings.Index(funcBody, "if protoErr, ok := err.(proto.Message)")
+		fallbackPos := strings.Index(funcBody, "return &sebufhttp.Error{Message: err.Error()}")
+
+		if valErrPos == -1 || handlerErrPos == -1 || protoMsgPos == -1 || fallbackPos == -1 {
+			t.Error("defaultErrorResponse should have all four error handling cases")
+			return
+		}
+
+		if !(valErrPos < handlerErrPos && handlerErrPos < protoMsgPos && protoMsgPos < fallbackPos) {
+			t.Error("defaultErrorResponse should check errors in order: ValidationError, Error, proto.Message, fallback")
+		}
+	})
+}

internal/httpgen/generator.go

@@ -565,6 +565,11 @@ func (g *Generator) generateBindingFile(file *protogen.File) error {
 	gf.P()
 	gf.P("response, err := serve(r.Context(), request)")
 	gf.P("if err != nil {")
+	gf.P("// Check if error is already a proto.Message (e.g., custom proto error types)")
+	gf.P("if protoErr, ok := err.(proto.Message); ok {")
+	gf.P("writeErrorWithHandler(w, r, protoErr, errorHandler)")
+	gf.P("return")
+	gf.P("}")
 	gf.P("errorMsg := &sebufhttp.Error{")
 	gf.P("Message: err.Error(),")
 	gf.P("}")
@@ -961,6 +966,10 @@ func (g *Generator) generateDefaultErrorResponseFunc(gf *protogen.GeneratedFile)
 	gf.P("if errors.As(err, &handlerErr) {")
 	gf.P("return handlerErr")
 	gf.P("}")
+	gf.P("// Check if error is already a proto.Message (e.g., custom proto error types)")
+	gf.P("if protoErr, ok := err.(proto.Message); ok {")
+	gf.P("return protoErr")
+	gf.P("}")
 	gf.P("return &sebufhttp.Error{Message: err.Error()}")
 	gf.P("}")
 	gf.P()