From 302bc5efb15c01519faca9a1263eae4a7ccfa7ca Mon Sep 17 00:00:00 2001 From: Yordis Prieto Date: Wed, 6 May 2026 01:56:29 -0400 Subject: [PATCH] fix(error): align Go bindings with Error Specification ADR Signed-off-by: Yordis Prieto --- .../consistency/v1alpha1/consistency.pb.go | 2 +- gen/trogon/error/v1alpha1/options.pb.go | 46 +++++++----- gen/trogon/error/v1alpha1/visibility.pb.go | 70 +++++++++---------- 3 files changed, 61 insertions(+), 57 deletions(-) diff --git a/gen/trogon/consistency/v1alpha1/consistency.pb.go b/gen/trogon/consistency/v1alpha1/consistency.pb.go index fdc98e9..8396b61 100644 --- a/gen/trogon/consistency/v1alpha1/consistency.pb.go +++ b/gen/trogon/consistency/v1alpha1/consistency.pb.go @@ -109,7 +109,7 @@ type Consistency struct { // - Maximum: 5s (values above should be clamped and logged) // // If projection doesn't reach required version within timeout, query should return - // unavailable error with appropriate error metadata (e.g., projection_timeout). + // unavailable error with appropriate error metadata (e.g., projectionTimeout). TimeoutDuration *durationpb.Duration `protobuf:"bytes,3,opt,name=timeout_duration,json=timeoutDuration,proto3,oneof" json:"timeout_duration,omitempty"` // Delay between retry attempts. // diff --git a/gen/trogon/error/v1alpha1/options.pb.go b/gen/trogon/error/v1alpha1/options.pb.go index 81d6050..0c2ffb1 100644 --- a/gen/trogon/error/v1alpha1/options.pb.go +++ b/gen/trogon/error/v1alpha1/options.pb.go @@ -24,6 +24,11 @@ const ( ) // MessageOptions defines message-level options for error payload messages. +// +// These annotations describe the Google RPC rich error details a runtime +// should emit for this payload. They are not a transport envelope; runtimes +// adapt the template into google.rpc.Status, google.rpc.ErrorInfo, google.rpc.Help, +// or equivalent protocol-native details. type MessageOptions struct { state protoimpl.MessageState `protogen:"open.v1"` // template specifies the static error template for this message. @@ -72,11 +77,14 @@ func (x *MessageOptions) GetTemplate() *MessageOptions_Template { } // FieldOptions defines field-level options for error payload message fields. +// +// Runtimes copy payload fields into google.rpc.ErrorInfo.metadata unless a +// value policy supplies a default or fixed value. type FieldOptions struct { state protoimpl.MessageState `protogen:"open.v1"` // visibility controls who can see this metadata field at runtime. // - // When unset, defaults to INTERNAL for safety. + // UNSPECIFIED is invalid for emitted error details. Visibility Visibility `protobuf:"varint,1,opt,name=visibility,proto3,enum=trogon.error.v1alpha1.Visibility" json:"visibility,omitempty"` // Types that are valid to be assigned to ValuePolicy: // @@ -170,31 +178,32 @@ func (*FieldOptions_DefaultValue) isFieldOptions_ValuePolicy() {} func (*FieldOptions_Value) isFieldOptions_ValuePolicy() {} // Template defines the static error template for a message that can be -// adapted into a runtime error representation. +// adapted into a runtime Google RPC error representation. // // These fields are intentionally language-neutral so both Elixir and Go // runtimes can derive their native error template APIs from the same proto // annotation. type MessageOptions_Template struct { state protoimpl.MessageState `protogen:"open.v1"` - // domain identifies the logical owner of the error contract. + // domain maps to google.rpc.ErrorInfo.domain. // Example: "compute.googleapis.com" Domain string `protobuf:"bytes,1,opt,name=domain,proto3" json:"domain,omitempty"` - // reason identifies the stable machine-readable error reason. + // reason maps to google.rpc.ErrorInfo.reason. // Example: "RESOURCE_AVAILABILITY" Reason string `protobuf:"bytes,2,opt,name=reason,proto3" json:"reason,omitempty"` - // message is the default human-readable message template. + // message maps to google.rpc.Status.message. Message string `protobuf:"bytes,3,opt,name=message,proto3" json:"message,omitempty"` - // code is the canonical error code for the template. + // code maps to google.rpc.Status.code. Code Code `protobuf:"varint,4,opt,name=code,proto3,enum=trogon.error.v1alpha1.Code" json:"code,omitempty"` // visibility controls who can see this error at runtime. - // When unset, defaults to INTERNAL for safety. + // UNSPECIFIED is invalid for emitted error details. Visibility Visibility `protobuf:"varint,5,opt,name=visibility,proto3,enum=trogon.error.v1alpha1.Visibility" json:"visibility,omitempty"` - // help_links provides documentation or support links for this error. + // help_links maps to google.rpc.Help links. HelpLinks []*MessageOptions_HelpLink `protobuf:"bytes,6,rep,name=help_links,json=helpLinks,proto3" json:"help_links,omitempty"` // metadata declares fixed key/value pairs attached to every emission - // of this error. Unlike struct fields with FieldOptions.value, these - // entries have no wire representation on the payload message — they + // of this error. Runtimes copy these entries into + // google.rpc.ErrorInfo.metadata. Unlike struct fields with FieldOptions.value, + // these entries have no wire representation on the payload message — they // are part of the error contract itself. // // Keys must be unique within a template and must not collide with @@ -343,8 +352,8 @@ func (x *MessageOptions_HelpLink) GetDescription() string { // MetadataEntry declares a fixed metadata pair on a Template. type MessageOptions_MetadataEntry struct { state protoimpl.MessageState `protogen:"open.v1"` - // key is the metadata key. Lowercase snake_case, matching the - // convention used for FieldOptions-derived metadata keys. + // key is the metadata key. Use lowerCamelCase to match + // google.rpc.ErrorInfo.metadata guidance. Key string `protobuf:"bytes,1,opt,name=key,proto3" json:"key,omitempty"` // value is the literal value attached at every emission. Template // metadata is fixed by definition, so there is no `default_value` @@ -352,7 +361,7 @@ type MessageOptions_MetadataEntry struct { // a struct field can supply a runtime override. Value string `protobuf:"bytes,2,opt,name=value,proto3" json:"value,omitempty"` // visibility controls who can see this metadata at runtime. - // When unset, defaults to INTERNAL for safety. + // UNSPECIFIED is invalid for emitted error details. Visibility Visibility `protobuf:"varint,3,opt,name=visibility,proto3,enum=trogon.error.v1alpha1.Visibility" json:"visibility,omitempty"` unknownFields protoimpl.UnknownFields sizeCache protoimpl.SizeCache @@ -448,13 +457,12 @@ var ( // visibility: VISIBILITY_PUBLIC, // help_links: [{url: "https://docs.acme.com/compute", description: "Compute Docs"}], // metadata: [ - // {key: "component", value: "compute", visibility: VISIBILITY_PUBLIC}, - // {key: "team", value: "platform-compute", visibility: VISIBILITY_INTERNAL} + // {key: "component", value: "compute", visibility: VISIBILITY_PUBLIC} // ] // }; // - // string zone = 1; - // string vm_type = 2; + // string zone = 1 [(trogon.error.v1alpha1.field).visibility = VISIBILITY_PUBLIC]; + // string vm_type = 2 [(trogon.error.v1alpha1.field).visibility = VISIBILITY_PUBLIC]; // string service = 3 [(trogon.error.v1alpha1.field) = { // visibility: VISIBILITY_PUBLIC, // default_value: "compute-api" @@ -485,11 +493,11 @@ var ( // domain: "identity.acme.com", // reason: "USER_NOT_FOUND", // message: "The requested user was not found.", - // code: NOT_FOUND + // code: NOT_FOUND, + // visibility: VISIBILITY_PUBLIC // }; // // string user_id = 1 [(trogon.error.v1alpha1.field).visibility = VISIBILITY_PUBLIC]; - // string internal_trace = 2; // defaults to INTERNAL // } // // optional trogon.error.v1alpha1.FieldOptions field = 870013; diff --git a/gen/trogon/error/v1alpha1/visibility.pb.go b/gen/trogon/error/v1alpha1/visibility.pb.go index ff5e3cf..c260db0 100644 --- a/gen/trogon/error/v1alpha1/visibility.pb.go +++ b/gen/trogon/error/v1alpha1/visibility.pb.go @@ -24,38 +24,35 @@ const ( // Visibility controls who can see a given error metadata field. // -// This aligns with the three-tier model in the Trogon Error runtime -// (Trogon.Error.MetadataValue.visibility/0). +// Visibility is an exposure contract for shared descriptors. It is not a +// secrecy boundary for data encoded in proto annotations: anyone with the +// descriptor can read those keys and values. Internal-only metadata belongs in +// runtime enrichment, observability pipelines, or internal-only overlays. // -// Default (unspecified) is treated as INTERNAL for safety. +// Code generators should reject UNSPECIFIED for emitted error details. type Visibility int32 const ( Visibility_VISIBILITY_UNSPECIFIED Visibility = 0 - // INTERNAL fields are only visible to internal systems and developers. - // Use for stack traces, debug identifiers, internal correlation IDs. - Visibility_VISIBILITY_INTERNAL Visibility = 1 // PRIVATE fields are visible to authenticated users but not the general public. // Use for account-specific context that the caller owns. - Visibility_VISIBILITY_PRIVATE Visibility = 2 + Visibility_VISIBILITY_PRIVATE Visibility = 1 // PUBLIC fields are visible to all users including end consumers. // Use for identifiers the caller already knows or non-sensitive context. - Visibility_VISIBILITY_PUBLIC Visibility = 3 + Visibility_VISIBILITY_PUBLIC Visibility = 2 ) // Enum value maps for Visibility. var ( Visibility_name = map[int32]string{ 0: "VISIBILITY_UNSPECIFIED", - 1: "VISIBILITY_INTERNAL", - 2: "VISIBILITY_PRIVATE", - 3: "VISIBILITY_PUBLIC", + 1: "VISIBILITY_PRIVATE", + 2: "VISIBILITY_PUBLIC", } Visibility_value = map[string]int32{ "VISIBILITY_UNSPECIFIED": 0, - "VISIBILITY_INTERNAL": 1, - "VISIBILITY_PRIVATE": 2, - "VISIBILITY_PUBLIC": 3, + "VISIBILITY_PRIVATE": 1, + "VISIBILITY_PUBLIC": 2, } ) @@ -94,31 +91,30 @@ var file_trogon_error_v1alpha1_visibility_proto_rawDesc = string([]byte{ 0x74, 0x79, 0x2e, 0x70, 0x72, 0x6f, 0x74, 0x6f, 0x12, 0x15, 0x74, 0x72, 0x6f, 0x67, 0x6f, 0x6e, 0x2e, 0x65, 0x72, 0x72, 0x6f, 0x72, 0x2e, 0x76, 0x31, 0x61, 0x6c, 0x70, 0x68, 0x61, 0x31, 0x1a, 0x0e, 0x65, 0x6c, 0x69, 0x78, 0x69, 0x72, 0x70, 0x62, 0x2e, 0x70, 0x72, 0x6f, 0x74, 0x6f, 0x2a, - 0x70, 0x0a, 0x0a, 0x56, 0x69, 0x73, 0x69, 0x62, 0x69, 0x6c, 0x69, 0x74, 0x79, 0x12, 0x1a, 0x0a, + 0x57, 0x0a, 0x0a, 0x56, 0x69, 0x73, 0x69, 0x62, 0x69, 0x6c, 0x69, 0x74, 0x79, 0x12, 0x1a, 0x0a, 0x16, 0x56, 0x49, 0x53, 0x49, 0x42, 0x49, 0x4c, 0x49, 0x54, 0x59, 0x5f, 0x55, 0x4e, 0x53, 0x50, - 0x45, 0x43, 0x49, 0x46, 0x49, 0x45, 0x44, 0x10, 0x00, 0x12, 0x17, 0x0a, 0x13, 0x56, 0x49, 0x53, - 0x49, 0x42, 0x49, 0x4c, 0x49, 0x54, 0x59, 0x5f, 0x49, 0x4e, 0x54, 0x45, 0x52, 0x4e, 0x41, 0x4c, - 0x10, 0x01, 0x12, 0x16, 0x0a, 0x12, 0x56, 0x49, 0x53, 0x49, 0x42, 0x49, 0x4c, 0x49, 0x54, 0x59, - 0x5f, 0x50, 0x52, 0x49, 0x56, 0x41, 0x54, 0x45, 0x10, 0x02, 0x12, 0x15, 0x0a, 0x11, 0x56, 0x49, - 0x53, 0x49, 0x42, 0x49, 0x4c, 0x49, 0x54, 0x59, 0x5f, 0x50, 0x55, 0x42, 0x4c, 0x49, 0x43, 0x10, - 0x03, 0x42, 0x8f, 0x02, 0xba, 0x41, 0x1c, 0x0a, 0x1a, 0x54, 0x72, 0x6f, 0x67, 0x6f, 0x6e, 0x50, - 0x72, 0x6f, 0x74, 0x6f, 0x2e, 0x45, 0x72, 0x72, 0x6f, 0x72, 0x2e, 0x56, 0x31, 0x41, 0x6c, 0x70, - 0x68, 0x61, 0x31, 0x0a, 0x19, 0x63, 0x6f, 0x6d, 0x2e, 0x74, 0x72, 0x6f, 0x67, 0x6f, 0x6e, 0x2e, - 0x65, 0x72, 0x72, 0x6f, 0x72, 0x2e, 0x76, 0x31, 0x61, 0x6c, 0x70, 0x68, 0x61, 0x31, 0x42, 0x0f, - 0x56, 0x69, 0x73, 0x69, 0x62, 0x69, 0x6c, 0x69, 0x74, 0x79, 0x50, 0x72, 0x6f, 0x74, 0x6f, 0x50, - 0x01, 0x5a, 0x4a, 0x67, 0x69, 0x74, 0x68, 0x75, 0x62, 0x2e, 0x63, 0x6f, 0x6d, 0x2f, 0x54, 0x72, - 0x6f, 0x67, 0x6f, 0x6e, 0x53, 0x74, 0x61, 0x63, 0x6b, 0x2f, 0x74, 0x72, 0x6f, 0x67, 0x6f, 0x6e, - 0x70, 0x72, 0x6f, 0x74, 0x6f, 0x2f, 0x67, 0x65, 0x6e, 0x2f, 0x74, 0x72, 0x6f, 0x67, 0x6f, 0x6e, - 0x2f, 0x65, 0x72, 0x72, 0x6f, 0x72, 0x2f, 0x76, 0x31, 0x61, 0x6c, 0x70, 0x68, 0x61, 0x31, 0x3b, - 0x65, 0x72, 0x72, 0x6f, 0x72, 0x76, 0x31, 0x61, 0x6c, 0x70, 0x68, 0x61, 0x31, 0xa2, 0x02, 0x03, - 0x54, 0x45, 0x58, 0xaa, 0x02, 0x15, 0x54, 0x72, 0x6f, 0x67, 0x6f, 0x6e, 0x2e, 0x45, 0x72, 0x72, - 0x6f, 0x72, 0x2e, 0x56, 0x31, 0x61, 0x6c, 0x70, 0x68, 0x61, 0x31, 0xca, 0x02, 0x16, 0x54, 0x72, + 0x45, 0x43, 0x49, 0x46, 0x49, 0x45, 0x44, 0x10, 0x00, 0x12, 0x16, 0x0a, 0x12, 0x56, 0x49, 0x53, + 0x49, 0x42, 0x49, 0x4c, 0x49, 0x54, 0x59, 0x5f, 0x50, 0x52, 0x49, 0x56, 0x41, 0x54, 0x45, 0x10, + 0x01, 0x12, 0x15, 0x0a, 0x11, 0x56, 0x49, 0x53, 0x49, 0x42, 0x49, 0x4c, 0x49, 0x54, 0x59, 0x5f, + 0x50, 0x55, 0x42, 0x4c, 0x49, 0x43, 0x10, 0x02, 0x42, 0x8f, 0x02, 0xba, 0x41, 0x1c, 0x0a, 0x1a, + 0x54, 0x72, 0x6f, 0x67, 0x6f, 0x6e, 0x50, 0x72, 0x6f, 0x74, 0x6f, 0x2e, 0x45, 0x72, 0x72, 0x6f, + 0x72, 0x2e, 0x56, 0x31, 0x41, 0x6c, 0x70, 0x68, 0x61, 0x31, 0x0a, 0x19, 0x63, 0x6f, 0x6d, 0x2e, + 0x74, 0x72, 0x6f, 0x67, 0x6f, 0x6e, 0x2e, 0x65, 0x72, 0x72, 0x6f, 0x72, 0x2e, 0x76, 0x31, 0x61, + 0x6c, 0x70, 0x68, 0x61, 0x31, 0x42, 0x0f, 0x56, 0x69, 0x73, 0x69, 0x62, 0x69, 0x6c, 0x69, 0x74, + 0x79, 0x50, 0x72, 0x6f, 0x74, 0x6f, 0x50, 0x01, 0x5a, 0x4a, 0x67, 0x69, 0x74, 0x68, 0x75, 0x62, + 0x2e, 0x63, 0x6f, 0x6d, 0x2f, 0x54, 0x72, 0x6f, 0x67, 0x6f, 0x6e, 0x53, 0x74, 0x61, 0x63, 0x6b, + 0x2f, 0x74, 0x72, 0x6f, 0x67, 0x6f, 0x6e, 0x70, 0x72, 0x6f, 0x74, 0x6f, 0x2f, 0x67, 0x65, 0x6e, + 0x2f, 0x74, 0x72, 0x6f, 0x67, 0x6f, 0x6e, 0x2f, 0x65, 0x72, 0x72, 0x6f, 0x72, 0x2f, 0x76, 0x31, + 0x61, 0x6c, 0x70, 0x68, 0x61, 0x31, 0x3b, 0x65, 0x72, 0x72, 0x6f, 0x72, 0x76, 0x31, 0x61, 0x6c, + 0x70, 0x68, 0x61, 0x31, 0xa2, 0x02, 0x03, 0x54, 0x45, 0x58, 0xaa, 0x02, 0x15, 0x54, 0x72, 0x6f, + 0x67, 0x6f, 0x6e, 0x2e, 0x45, 0x72, 0x72, 0x6f, 0x72, 0x2e, 0x56, 0x31, 0x61, 0x6c, 0x70, 0x68, + 0x61, 0x31, 0xca, 0x02, 0x16, 0x54, 0x72, 0x6f, 0x67, 0x6f, 0x6e, 0x5c, 0x45, 0x72, 0x72, 0x6f, + 0x72, 0x5f, 0x5c, 0x56, 0x31, 0x61, 0x6c, 0x70, 0x68, 0x61, 0x31, 0xe2, 0x02, 0x22, 0x54, 0x72, 0x6f, 0x67, 0x6f, 0x6e, 0x5c, 0x45, 0x72, 0x72, 0x6f, 0x72, 0x5f, 0x5c, 0x56, 0x31, 0x61, 0x6c, - 0x70, 0x68, 0x61, 0x31, 0xe2, 0x02, 0x22, 0x54, 0x72, 0x6f, 0x67, 0x6f, 0x6e, 0x5c, 0x45, 0x72, - 0x72, 0x6f, 0x72, 0x5f, 0x5c, 0x56, 0x31, 0x61, 0x6c, 0x70, 0x68, 0x61, 0x31, 0x5c, 0x47, 0x50, - 0x42, 0x4d, 0x65, 0x74, 0x61, 0x64, 0x61, 0x74, 0x61, 0xea, 0x02, 0x17, 0x54, 0x72, 0x6f, 0x67, - 0x6f, 0x6e, 0x3a, 0x3a, 0x45, 0x72, 0x72, 0x6f, 0x72, 0x3a, 0x3a, 0x56, 0x31, 0x61, 0x6c, 0x70, - 0x68, 0x61, 0x31, 0x62, 0x06, 0x70, 0x72, 0x6f, 0x74, 0x6f, 0x33, + 0x70, 0x68, 0x61, 0x31, 0x5c, 0x47, 0x50, 0x42, 0x4d, 0x65, 0x74, 0x61, 0x64, 0x61, 0x74, 0x61, + 0xea, 0x02, 0x17, 0x54, 0x72, 0x6f, 0x67, 0x6f, 0x6e, 0x3a, 0x3a, 0x45, 0x72, 0x72, 0x6f, 0x72, + 0x3a, 0x3a, 0x56, 0x31, 0x61, 0x6c, 0x70, 0x68, 0x61, 0x31, 0x62, 0x06, 0x70, 0x72, 0x6f, 0x74, + 0x6f, 0x33, }) var (