feat: support protobuf error details

v2/README.md

@@ -116,3 +116,46 @@ version, a herodot v1 version, or both. It runs `scripts/release.sh`, which:
 Every herodot/v2 release bumps the root module. A herodot v1 release requires
 the root module to require the latest herodot/v2 release. Run
 `scripts/release.sh` without `--push` for a local dry run.
+
+### Protobuf error details
+
+Attach standard or service-specific protobuf messages with `ProtoDetail`:
+
+```go
+err := serviceUnavailable.New(
+    herodot.ProtoDetail(&errdetails.RetryInfo{
+        RetryDelay: durationpb.New(time.Second),
+    }),
+)
+```
+
+`ProtoDetail` also works with `Annotate`. Messages are copied when attached;
+`Error.ProtoDetails()` returns deep copies. Except for `DebugInfo`, these
+details are public response data. Use `Cause` for internal diagnostics and
+`Violation` for invalid fields. Attached `DebugInfo` is rendered only when debug
+output is enabled, just like cause-derived debug information. `BadRequest` can
+also be attached directly. Only `ErrorInfo` and Herodot's `CodeInfo` are
+reserved because they define the error's identity and code; passing either or a
+nil message to `ProtoDetail` panics. Adding convenience APIs for other detail
+types does not reserve those types.
+
+`Violation(field, description)` is a convenience for attaching a `BadRequest`
+with one field violation. Full `BadRequest` messages are retained when decoding
+and forwarding, including reasons and localized messages. Read the complete
+merged `BadRequest` through `ProtoDetails()`. All `BadRequest` messages merge
+into one detail, including messages attached through `ProtoDetail` or decoded
+from either transport. Violations append in attachment order without
+deduplication, and protobuf unknown fields are preserved during merging.
+`ProtoDetails()` returns the merged `BadRequest` first, followed by other
+details in attachment order.
+
+The HTTP and gRPC renderers include additional details alongside `ErrorInfo`.
+HTTP uses protobuf JSON encoding, including `@type` and well-known types such as
+durations. A request ID supplied by the transport takes precedence over an
+attached `RequestInfo`.
+
+Decoders retain additional details whose protobuf types are registered in the
+process. Import the generated Go package for service-specific details. Unknown
+or malformed details are ignored. Decoded `DebugInfo` is retained but only
+rendered when debug output is enabled. Renderers omit details that cannot be
+encoded in their transport format.

v2/error.go

@@ -9,6 +9,9 @@ import (
 	"maps"
 	"slices"
 	"sort"
+
+	"google.golang.org/genproto/googleapis/rpc/errdetails"
+	"google.golang.org/protobuf/proto"
 )
 
 // Error is an occurrence of a Definition. It is immutable: its only field
@@ -20,16 +23,13 @@ type Error struct {
 }
 
 type errorData struct {
-	def        Definition
-	metadata   map[string]string
-	violations []FieldViolation
-	cause      error
+	def          Definition
+	metadata     map[string]string
+	cause        error
+	badRequest   *errdetails.BadRequest
+	protoDetails []proto.Message
 }
 
-// FieldViolation describes a request field error. It maps to
-// google.rpc.BadRequest.FieldViolation.
-type FieldViolation struct{ Field, Description string }
-
 var zeroData = &errorData{def: Internal}
 
 func (e Error) d() *errorData {
@@ -49,8 +49,19 @@ func (e Error) Error() string { return e.d().def.message }
 // none.
 func (e Error) Metadata() map[string]string { return maps.Clone(e.d().metadata) }
 
-// Violations returns a copy of the request field violations.
-func (e Error) Violations() []FieldViolation { return slices.Clone(e.d().violations) }
+// ProtoDetails returns deep copies of the additional protobuf details.
+// The merged BadRequest, if present, comes first, followed by other details in
+// attachment order.
+func (e Error) ProtoDetails() []proto.Message {
+	var details []proto.Message
+	if e.d().badRequest != nil {
+		details = append(details, proto.Clone(e.d().badRequest))
+	}
+	for _, d := range e.d().protoDetails {
+		details = append(details, proto.Clone(d))
+	}
+	return details
+}
 
 // Unwrap returns the cause.
 func (e Error) Unwrap() error { return e.d().cause }
@@ -84,8 +95,8 @@ func (e Error) Format(s fmt.State, verb rune) {
 			for _, k := range keys {
 				_, _ = fmt.Fprintf(s, "\nmetadata %s=%s", k, d.metadata[k])
 			}
-			for _, v := range d.violations {
-				_, _ = fmt.Fprintf(s, "\nviolation %s: %s", v.Field, v.Description)
+			for _, v := range d.badRequest.GetFieldViolations() {
+				_, _ = fmt.Fprintf(s, "\nviolation %s: %s", v.GetField(), v.GetDescription())
 			}
 			if d.cause != nil {
 				_, _ = fmt.Fprintf(s, "\ncause: %+v", d.cause)

v2/from.go

@@ -125,9 +125,11 @@ func merge(e Error, path []*annotation) Error {
 	}
 	src := e.d()
 	data := &errorData{
-		def:        src.def,
-		cause:      src.cause,
-		violations: slices.Clone(src.violations),
+		def:   src.def,
+		cause: src.cause,
+	}
+	for _, detail := range e.ProtoDetails() {
+		protoDetail{message: detail}.apply(data)
 	}
 	if len(src.metadata) > 0 {
 		data.metadata = make(map[string]string, len(src.metadata))

v2/grpcerr/grpcerr.go

@@ -25,8 +25,8 @@ import (
 const RequestIDKey = "x-request-id"
 
 // ToStatus returns the status for herodot.From(err): the canonical code,
-// ErrorInfo, CodeInfo for a refined code, RequestInfo and BadRequest, and
-// DebugInfo only if debug is true.
+// ErrorInfo, CodeInfo for a refined code, RequestInfo, BadRequest, additional
+// protobuf details, and DebugInfo only if debug is true.
 // It returns nil if err is nil.
 func ToStatus(ctx context.Context, err error, debug bool) *status.Status {
 	if err == nil {
@@ -53,12 +53,24 @@ func ToStatus(ctx context.Context, err error, debug bool) *status.Status {
 			details = append(details, &errdetails.RequestInfo{RequestId: validUTF8(ids[0])})
 		}
 	}
-	if vs := e.Violations(); len(vs) > 0 {
-		br := &errdetails.BadRequest{FieldViolations: make([]*errdetails.BadRequest_FieldViolation, len(vs))}
-		for i, v := range vs {
-			br.FieldViolations[i] = &errdetails.BadRequest_FieldViolation{Field: validUTF8(v.Field), Description: validUTF8(v.Description)}
+	for _, detail := range e.ProtoDetails() {
+		if detail.ProtoReflect().Descriptor().FullName() == "google.rpc.DebugInfo" && !debug {
+			continue
 		}
-		details = append(details, br)
+		if detail.ProtoReflect().Descriptor().FullName() == "google.rpc.RequestInfo" {
+			if md, ok := metadata.FromIncomingContext(ctx); ok && len(md.Get(RequestIDKey)) > 0 && md.Get(RequestIDKey)[0] != "" {
+				continue
+			}
+		}
+		if br, ok := detail.(*errdetails.BadRequest); ok {
+			for _, v := range br.FieldViolations {
+				if v != nil {
+					v.Field = validUTF8(v.Field)
+					v.Description = validUTF8(v.Description)
+				}
+			}
+		}
+		details = append(details, protoadapt.MessageV1Of(detail))
 	}
 	if debug {
 		if info, ok := e.DebugInfo(); ok {
@@ -69,13 +81,15 @@ func ToStatus(ctx context.Context, err error, debug bool) *status.Status {
 		}
 	}
 
-	base := status.New(codes.Code(def.Code().Canonical()), validUTF8(e.Error()))
-	s, wErr := base.WithDetails(details...)
-	if wErr != nil {
-		// Preserve the status even if a detail cannot be serialized.
-		return base
+	result := status.New(codes.Code(def.Code().Canonical()), validUTF8(e.Error()))
+	for _, detail := range details {
+		next, err := result.WithDetails(detail)
+		if err != nil {
+			continue
+		}
+		result = next
 	}
-	return s
+	return result
 }
 
 func validUTF8(s string) string { return strings.ToValidUTF8(s, "\uFFFD") }
@@ -121,9 +135,9 @@ func FromStatus(s *status.Status) (herodot.Error, bool) {
 	}
 
 	var (
-		info       *errdetails.ErrorInfo
-		code       = canonical
-		violations []herodot.Option
+		info    *errdetails.ErrorInfo
+		code    = canonical
+		details []herodot.Option
 	)
 	for _, d := range s.Details() {
 		switch d := d.(type) {
@@ -136,9 +150,9 @@ func FromStatus(s *status.Status) (herodot.Error, bool) {
 			if c := herodot.Code(d.GetCode()); c.Canonical() == canonical {
 				code = c
 			}
-		case *errdetails.BadRequest:
-			for _, v := range d.GetFieldViolations() {
-				violations = append(violations, herodot.Violation(v.GetField(), v.GetDescription()))
+		default:
+			if message, ok := d.(protoadapt.MessageV1); ok {
+				details = append(details, herodot.ProtoDetail(protoadapt.MessageV2Of(message)))
 			}
 		}
 	}
@@ -154,7 +168,7 @@ func FromStatus(s *status.Status) (herodot.Error, bool) {
 	for k, v := range info.GetMetadata() {
 		opts = append(opts, herodot.Metadata(k, v))
 	}
-	return def.New(append(opts, violations...)...), true
+	return def.New(append(opts, details...)...), true
 }
 
 // FromError decodes the status of an error returned by a gRPC call, also if

v2/grpcerr/grpcerr_test.go

@@ -80,7 +80,7 @@ func TestFromStatus(t *testing.T) {
 		assert.Equal(t, herodot.CodeExpired, received.Definition().Code(), "the refinement survives gRPC")
 		assert.Equal(t, "The flow has expired. Start a new flow.", received.Error(), "the received message is kept")
 		assert.Equal(t, map[string]string{"flowId": "1234"}, received.Metadata())
-		assert.Equal(t, []herodot.FieldViolation{{Field: "email", Description: "is required"}}, received.Violations())
+		assert.True(t, proto.Equal(&errdetails.BadRequest{FieldViolations: []*errdetails.BadRequest_FieldViolation{{Field: "email", Description: "is required"}}}, received.ProtoDetails()[0]))
 		assert.Equal(t, s.Err().Error(), received.Unwrap().Error())
 
 		forwarded := grpcerr.ToStatus(context.Background(), fmt.Errorf("forwarding: %w", received), false)

v2/herodot_test.go

@@ -10,6 +10,9 @@ import (
 	"strings"
 	"testing"
 
+	"google.golang.org/genproto/googleapis/rpc/errdetails"
+	"google.golang.org/protobuf/proto"
+
 	"github.com/stretchr/testify/assert"
 	"github.com/stretchr/testify/require"
 
@@ -67,21 +70,21 @@ func TestNew(t *testing.T) {
 	assert.Equal(t, identityNotFound, e.Definition())
 	assert.Equal(t, "The identity could not be found.", e.Error())
 	assert.Equal(t, map[string]string{"identityId": "1234"}, e.Metadata())
-	assert.Equal(t, []herodot.FieldViolation{{Field: "id", Description: "must exist"}}, e.Violations())
+	assert.True(t, proto.Equal(&errdetails.BadRequest{FieldViolations: []*errdetails.BadRequest_FieldViolation{{Field: "id", Description: "must exist"}}}, e.ProtoDetails()[0]))
 	assert.Same(t, cause, e.Unwrap())
 	assert.ErrorIs(t, e, cause)
 
 	t.Run("case=copies are immutable", func(t *testing.T) {
 		e.Metadata()["identityId"] = "changed"
-		e.Violations()[0].Field = "changed"
+		e.ProtoDetails()[0].(*errdetails.BadRequest).FieldViolations[0].Field = "changed"
 		assert.Equal(t, "1234", e.Metadata()["identityId"])
-		assert.Equal(t, "id", e.Violations()[0].Field)
+		assert.Equal(t, "id", e.ProtoDetails()[0].(*errdetails.BadRequest).FieldViolations[0].Field)
 	})
 
 	t.Run("case=no details", func(t *testing.T) {
 		e := flowExpired.New()
 		assert.Nil(t, e.Metadata())
-		assert.Nil(t, e.Violations())
+		assert.Nil(t, e.ProtoDetails())
 		assert.Nil(t, e.Unwrap())
 	})
 }
@@ -229,7 +232,7 @@ func TestFrom(t *testing.T) {
 		assert.Equal(t, flowExpired, got.Definition())
 		assert.Equal(t, e.Error(), got.Error())
 		assert.Equal(t, map[string]string{"flowId": "outer", "keep": "inner", "returnTo": "/x"}, got.Metadata())
-		assert.Equal(t, []herodot.FieldViolation{{"a", "1"}, {"b", "2"}, {"c", "3"}}, got.Violations())
+		assert.True(t, proto.Equal(&errdetails.BadRequest{FieldViolations: []*errdetails.BadRequest_FieldViolation{{Field: "a", Description: "1"}, {Field: "b", Description: "2"}, {Field: "c", Description: "3"}}}, got.ProtoDetails()[0]))
 		assert.Same(t, below, got.Unwrap())
 
 		assert.Equal(t, map[string]string{"flowId": "1", "keep": "inner"}, e.Metadata(), "the original is unchanged")

v2/httperr/decode.go

@@ -10,6 +10,9 @@ import (
 	"io"
 	"net/http"
 
+	"google.golang.org/protobuf/encoding/protojson"
+	"google.golang.org/protobuf/types/known/anypb"
+
 	"github.com/ory/herodot/v2"
 )
 
@@ -73,8 +76,8 @@ func decode(body []byte, httpStatus int) (herodot.Error, bool) {
 	}
 
 	var (
-		info       *ErrorInfo
-		violations []herodot.Option
+		info    *ErrorInfo
+		details []herodot.Option
 	)
 	for _, raw := range b.Error.Details {
 		var t struct {
@@ -89,11 +92,16 @@ func decode(body []byte, httpStatus int) (herodot.Error, bool) {
 			if info == nil && json.Unmarshal(raw, &d) == nil {
 				info = &d
 			}
-		case typePrefix + "BadRequest":
-			var d BadRequest
-			if json.Unmarshal(raw, &d) == nil {
-				for _, v := range d.FieldViolations {
-					violations = append(violations, herodot.Violation(v.Field, v.Description))
+		case "type.googleapis.com/ory.herodot.v1.CodeInfo":
+		default:
+			var packed anypb.Any
+			if protojson.Unmarshal(raw, &packed) == nil {
+				if message, err := packed.UnmarshalNew(); err == nil {
+					switch message.ProtoReflect().Descriptor().FullName() {
+					case "google.rpc.ErrorInfo", "ory.herodot.v1.CodeInfo":
+					default:
+						details = append(details, herodot.ProtoDetail(message))
+					}
 				}
 			}
 		}
@@ -110,7 +118,7 @@ func decode(body []byte, httpStatus int) (herodot.Error, bool) {
 	for k, v := range info.Metadata {
 		opts = append(opts, herodot.Metadata(k, v))
 	}
-	return def.New(append(opts, violations...)...), true
+	return def.New(append(opts, details...)...), true
 }
 
 // ResponseError is the cause of a decoded Error: the received response.

v2/httperr/decode_test.go

@@ -11,6 +11,9 @@ import (
 	"strings"
 	"testing"
 
+	"google.golang.org/genproto/googleapis/rpc/errdetails"
+	"google.golang.org/protobuf/proto"
+
 	"github.com/stretchr/testify/assert"
 	"github.com/stretchr/testify/require"
 
@@ -43,7 +46,7 @@ func TestDecode(t *testing.T) {
 		assert.Equal(t, herodot.CodeExpired, received.Definition().Code(), "the refinement survives HTTP")
 		assert.Equal(t, "The flow has expired. Start a new flow.", received.Error(), "the received message is kept")
 		assert.Equal(t, map[string]string{"flowId": "1234"}, received.Metadata())
-		assert.Equal(t, []herodot.FieldViolation{{Field: "email", Description: "is required"}}, received.Violations())
+		assert.True(t, proto.Equal(&errdetails.BadRequest{FieldViolations: []*errdetails.BadRequest_FieldViolation{{Field: "email", Description: "is required"}}}, received.ProtoDetails()[0]))
 
 		var re *httperr.ResponseError
 		require.ErrorAs(t, received, &re)