diff --git a/Makefile b/Makefile index 09c8874..9299240 100644 --- a/Makefile +++ b/Makefile @@ -12,15 +12,9 @@ GIT_REPO := gitea.libretechconsulting.com/rmcguire/go-server-with-otel all: proto test build docker -proto: check_protoc $(API_DIR) - protoc --proto_path=proto --proto_path=proto/google \ - --go_out=$(API_DIR) --go_opt=paths=source_relative \ - --go-grpc_out=$(API_DIR) --go-grpc_opt=paths=source_relative \ - --grpc-gateway_out=$(API_DIR) --grpc-gateway_opt=paths=source_relative \ - --openapiv2_out=$(SCHEMA_DIR) \ - --openapiv2_opt allow_merge=true \ - --openapiv2_opt merge_file_name=$(CMD_NAME) \ - $(foreach dir, $(PROTO_DIRS), $(wildcard $(dir)/*.proto)) +proto: check_buf + buf dep update + buf generate test: go test -v ./... @@ -56,13 +50,9 @@ install: clean: rm -rf bin/${CMD_NAME} -check_protoc: - @if ! command -v protoc-gen-go > /dev/null; then \ - echo "Error: protoc-gen-go not found in PATH"; \ - exit 1; \ - fi - @if ! command -v protoc-gen-go-grpc > /dev/null; then \ - echo "Error: protoc-gen-go-grpc not found in PATH"; \ +check_buf: + @if ! command -v buf > /dev/null; then \ + echo "Error: buf not found in PATH"; \ exit 1; \ fi diff --git a/api/demo/app/v1alpha1/app.pb.go b/api/demo/app/v1alpha1/app.pb.go index 7148251..872b096 100644 --- a/api/demo/app/v1alpha1/app.pb.go +++ b/api/demo/app/v1alpha1/app.pb.go @@ -1,7 +1,7 @@ // Code generated by protoc-gen-go. DO NOT EDIT. // versions: // protoc-gen-go v1.36.6 -// protoc v5.29.3 +// protoc (unknown) // source: demo/app/v1alpha1/app.proto package demo @@ -153,7 +153,8 @@ const file_demo_app_v1alpha1_app_proto_rawDesc = "" + "\x06source\x18\x03 \x01(\tR\x06source\x12\x1a\n" + "\blanguage\x18\x04 \x01(\tR\blanguage2z\n" + "\x0eDemoAppService\x12h\n" + - "\aGetDemo\x12!.demo.app.v1alpha1.GetDemoRequest\x1a\".demo.app.v1alpha1.GetDemoResponse\"\x16\x82\xd3\xe4\x93\x02\x10\x12\x0e/v1alpha1/demoBNZLgitea.libretechconsulting.com/rmcguire/go-server-with-otel/api/v1alpha1/demob\x06proto3" + "\aGetDemo\x12!.demo.app.v1alpha1.GetDemoRequest\x1a\".demo.app.v1alpha1.GetDemoResponse\"\x16\x82\xd3\xe4\x93\x02\x10\x12\x0e/v1alpha1/demoB\xd5\x01\n" + + "\x15com.demo.app.v1alpha1B\bAppProtoP\x01ZLgitea.libretechconsulting.com/rmcguire/go-server-with-otel/api/v1alpha1/demo\xa2\x02\x03DAX\xaa\x02\x11Demo.App.V1alpha1\xca\x02\x11Demo\\App\\V1alpha1\xe2\x02\x1dDemo\\App\\V1alpha1\\GPBMetadata\xea\x02\x13Demo::App::V1alpha1b\x06proto3" var ( file_demo_app_v1alpha1_app_proto_rawDescOnce sync.Once diff --git a/api/demo/app/v1alpha1/app.pb.gw.go b/api/demo/app/v1alpha1/app.pb.gw.go index 7e042b8..8ac26a0 100644 --- a/api/demo/app/v1alpha1/app.pb.gw.go +++ b/api/demo/app/v1alpha1/app.pb.gw.go @@ -42,7 +42,9 @@ func request_DemoAppService_GetDemo_0(ctx context.Context, marshaler runtime.Mar protoReq GetDemoRequest metadata runtime.ServerMetadata ) - io.Copy(io.Discard, req.Body) + if req.Body != nil { + _, _ = io.Copy(io.Discard, req.Body) + } if err := req.ParseForm(); err != nil { return nil, metadata, status.Errorf(codes.InvalidArgument, "%v", err) } diff --git a/api/demo/app/v1alpha1/app.pb.validate.go b/api/demo/app/v1alpha1/app.pb.validate.go new file mode 100644 index 0000000..3a36825 --- /dev/null +++ b/api/demo/app/v1alpha1/app.pb.validate.go @@ -0,0 +1,275 @@ +// Code generated by protoc-gen-validate. DO NOT EDIT. +// source: demo/app/v1alpha1/app.proto + +package demo + +import ( + "bytes" + "errors" + "fmt" + "net" + "net/mail" + "net/url" + "regexp" + "sort" + "strings" + "time" + "unicode/utf8" + + "google.golang.org/protobuf/types/known/anypb" +) + +// ensure the imports are used +var ( + _ = bytes.MinRead + _ = errors.New("") + _ = fmt.Print + _ = utf8.UTFMax + _ = (*regexp.Regexp)(nil) + _ = (*strings.Reader)(nil) + _ = net.IPv4len + _ = time.Duration(0) + _ = (*url.URL)(nil) + _ = (*mail.Address)(nil) + _ = anypb.Any{} + _ = sort.Sort +) + +// Validate checks the field values on GetDemoRequest with the rules defined in +// the proto definition for this message. If any rules are violated, the first +// error encountered is returned, or nil if there are no violations. +func (m *GetDemoRequest) Validate() error { + return m.validate(false) +} + +// ValidateAll checks the field values on GetDemoRequest with the rules defined +// in the proto definition for this message. If any rules are violated, the +// result is a list of violation errors wrapped in GetDemoRequestMultiError, +// or nil if none found. +func (m *GetDemoRequest) ValidateAll() error { + return m.validate(true) +} + +func (m *GetDemoRequest) validate(all bool) error { + if m == nil { + return nil + } + + var errors []error + + if m.Language != nil { + // no validation rules for Language + } + + if len(errors) > 0 { + return GetDemoRequestMultiError(errors) + } + + return nil +} + +// GetDemoRequestMultiError is an error wrapping multiple validation errors +// returned by GetDemoRequest.ValidateAll() if the designated constraints +// aren't met. +type GetDemoRequestMultiError []error + +// Error returns a concatenation of all the error messages it wraps. +func (m GetDemoRequestMultiError) Error() string { + msgs := make([]string, 0, len(m)) + for _, err := range m { + msgs = append(msgs, err.Error()) + } + return strings.Join(msgs, "; ") +} + +// AllErrors returns a list of validation violation errors. +func (m GetDemoRequestMultiError) AllErrors() []error { return m } + +// GetDemoRequestValidationError is the validation error returned by +// GetDemoRequest.Validate if the designated constraints aren't met. +type GetDemoRequestValidationError struct { + field string + reason string + cause error + key bool +} + +// Field function returns field value. +func (e GetDemoRequestValidationError) Field() string { return e.field } + +// Reason function returns reason value. +func (e GetDemoRequestValidationError) Reason() string { return e.reason } + +// Cause function returns cause value. +func (e GetDemoRequestValidationError) Cause() error { return e.cause } + +// Key function returns key value. +func (e GetDemoRequestValidationError) Key() bool { return e.key } + +// ErrorName returns error name. +func (e GetDemoRequestValidationError) ErrorName() string { return "GetDemoRequestValidationError" } + +// Error satisfies the builtin error interface +func (e GetDemoRequestValidationError) Error() string { + cause := "" + if e.cause != nil { + cause = fmt.Sprintf(" | caused by: %v", e.cause) + } + + key := "" + if e.key { + key = "key for " + } + + return fmt.Sprintf( + "invalid %sGetDemoRequest.%s: %s%s", + key, + e.field, + e.reason, + cause) +} + +var _ error = GetDemoRequestValidationError{} + +var _ interface { + Field() string + Reason() string + Key() bool + Cause() error + ErrorName() string +} = GetDemoRequestValidationError{} + +// Validate checks the field values on GetDemoResponse with the rules defined +// in the proto definition for this message. If any rules are violated, the +// first error encountered is returned, or nil if there are no violations. +func (m *GetDemoResponse) Validate() error { + return m.validate(false) +} + +// ValidateAll checks the field values on GetDemoResponse with the rules +// defined in the proto definition for this message. If any rules are +// violated, the result is a list of violation errors wrapped in +// GetDemoResponseMultiError, or nil if none found. +func (m *GetDemoResponse) ValidateAll() error { + return m.validate(true) +} + +func (m *GetDemoResponse) validate(all bool) error { + if m == nil { + return nil + } + + var errors []error + + if all { + switch v := interface{}(m.GetTimestamp()).(type) { + case interface{ ValidateAll() error }: + if err := v.ValidateAll(); err != nil { + errors = append(errors, GetDemoResponseValidationError{ + field: "Timestamp", + reason: "embedded message failed validation", + cause: err, + }) + } + case interface{ Validate() error }: + if err := v.Validate(); err != nil { + errors = append(errors, GetDemoResponseValidationError{ + field: "Timestamp", + reason: "embedded message failed validation", + cause: err, + }) + } + } + } else if v, ok := interface{}(m.GetTimestamp()).(interface{ Validate() error }); ok { + if err := v.Validate(); err != nil { + return GetDemoResponseValidationError{ + field: "Timestamp", + reason: "embedded message failed validation", + cause: err, + } + } + } + + // no validation rules for Fact + + // no validation rules for Source + + // no validation rules for Language + + if len(errors) > 0 { + return GetDemoResponseMultiError(errors) + } + + return nil +} + +// GetDemoResponseMultiError is an error wrapping multiple validation errors +// returned by GetDemoResponse.ValidateAll() if the designated constraints +// aren't met. +type GetDemoResponseMultiError []error + +// Error returns a concatenation of all the error messages it wraps. +func (m GetDemoResponseMultiError) Error() string { + msgs := make([]string, 0, len(m)) + for _, err := range m { + msgs = append(msgs, err.Error()) + } + return strings.Join(msgs, "; ") +} + +// AllErrors returns a list of validation violation errors. +func (m GetDemoResponseMultiError) AllErrors() []error { return m } + +// GetDemoResponseValidationError is the validation error returned by +// GetDemoResponse.Validate if the designated constraints aren't met. +type GetDemoResponseValidationError struct { + field string + reason string + cause error + key bool +} + +// Field function returns field value. +func (e GetDemoResponseValidationError) Field() string { return e.field } + +// Reason function returns reason value. +func (e GetDemoResponseValidationError) Reason() string { return e.reason } + +// Cause function returns cause value. +func (e GetDemoResponseValidationError) Cause() error { return e.cause } + +// Key function returns key value. +func (e GetDemoResponseValidationError) Key() bool { return e.key } + +// ErrorName returns error name. +func (e GetDemoResponseValidationError) ErrorName() string { return "GetDemoResponseValidationError" } + +// Error satisfies the builtin error interface +func (e GetDemoResponseValidationError) Error() string { + cause := "" + if e.cause != nil { + cause = fmt.Sprintf(" | caused by: %v", e.cause) + } + + key := "" + if e.key { + key = "key for " + } + + return fmt.Sprintf( + "invalid %sGetDemoResponse.%s: %s%s", + key, + e.field, + e.reason, + cause) +} + +var _ error = GetDemoResponseValidationError{} + +var _ interface { + Field() string + Reason() string + Key() bool + Cause() error + ErrorName() string +} = GetDemoResponseValidationError{} diff --git a/api/demo/app/v1alpha1/app_grpc.pb.go b/api/demo/app/v1alpha1/app_grpc.pb.go index 46d49c3..c1f3287 100644 --- a/api/demo/app/v1alpha1/app_grpc.pb.go +++ b/api/demo/app/v1alpha1/app_grpc.pb.go @@ -1,7 +1,7 @@ // Code generated by protoc-gen-go-grpc. DO NOT EDIT. // versions: // - protoc-gen-go-grpc v1.5.1 -// - protoc v5.29.3 +// - protoc (unknown) // source: demo/app/v1alpha1/app.proto package demo @@ -48,14 +48,13 @@ func (c *demoAppServiceClient) GetDemo(ctx context.Context, in *GetDemoRequest, } // DemoAppServiceServer is the server API for DemoAppService service. -// All implementations must embed UnimplementedDemoAppServiceServer +// All implementations should embed UnimplementedDemoAppServiceServer // for forward compatibility. type DemoAppServiceServer interface { GetDemo(context.Context, *GetDemoRequest) (*GetDemoResponse, error) - mustEmbedUnimplementedDemoAppServiceServer() } -// UnimplementedDemoAppServiceServer must be embedded to have +// UnimplementedDemoAppServiceServer should be embedded to have // forward compatible implementations. // // NOTE: this should be embedded by value instead of pointer to avoid a nil @@ -65,8 +64,7 @@ type UnimplementedDemoAppServiceServer struct{} func (UnimplementedDemoAppServiceServer) GetDemo(context.Context, *GetDemoRequest) (*GetDemoResponse, error) { return nil, status.Errorf(codes.Unimplemented, "method GetDemo not implemented") } -func (UnimplementedDemoAppServiceServer) mustEmbedUnimplementedDemoAppServiceServer() {} -func (UnimplementedDemoAppServiceServer) testEmbeddedByValue() {} +func (UnimplementedDemoAppServiceServer) testEmbeddedByValue() {} // UnsafeDemoAppServiceServer may be embedded to opt out of forward compatibility for this service. // Use of this interface is not recommended, as added methods to DemoAppServiceServer will diff --git a/buf.gen.yaml b/buf.gen.yaml new file mode 100644 index 0000000..6ec8cf2 --- /dev/null +++ b/buf.gen.yaml @@ -0,0 +1,32 @@ +version: v2 +managed: + enabled: true + disable: + - file_option: go_package + module: buf.build/bufbuild/protovalidate +plugins: + - remote: buf.build/protocolbuffers/go + out: api + opt: + - paths=source_relative + - remote: buf.build/grpc/go + out: api + opt: + - paths=source_relative + - require_unimplemented_servers=false + - remote: buf.build/bufbuild/validate-go + out: api + opt: + - paths=source_relative + - remote: buf.build/grpc-ecosystem/gateway + out: api + opt: + - paths=source_relative + - generate_unbound_methods=true + - remote: buf.build/grpc-ecosystem/openapiv2 + out: contrib/ + opt: + - merge_file_name=go-server-with-otel + - allow_merge=true +inputs: + - directory: proto diff --git a/buf.lock b/buf.lock new file mode 100644 index 0000000..22c5f3b --- /dev/null +++ b/buf.lock @@ -0,0 +1,12 @@ +# Generated by buf. DO NOT EDIT. +version: v2 +deps: + - name: buf.build/bufbuild/protovalidate + commit: 6c6e0d3c608e4549802254a2eee81bc8 + digest: b5:a7ca081f38656fc0f5aaa685cc111d3342876723851b47ca6b80cbb810cbb2380f8c444115c495ada58fa1f85eff44e68dc54a445761c195acdb5e8d9af675b6 + - name: buf.build/googleapis/googleapis + commit: 61b203b9a9164be9a834f58c37be6f62 + digest: b5:7811a98b35bd2e4ae5c3ac73c8b3d9ae429f3a790da15de188dc98fc2b77d6bb10e45711f14903af9553fa9821dff256054f2e4b7795789265bc476bec2f088c + - name: buf.build/grpc-ecosystem/grpc-gateway + commit: 4c5ba75caaf84e928b7137ae5c18c26a + digest: b5:c113e62fb3b29289af785866cae062b55ec8ae19ab3f08f3004098928fbca657730a06810b2012951294326b95669547194fa84476b9e9b688d4f8bf77a0691d diff --git a/buf.yaml b/buf.yaml new file mode 100644 index 0000000..db67900 --- /dev/null +++ b/buf.yaml @@ -0,0 +1,14 @@ +# For details on buf.yaml configuration, visit https://buf.build/docs/configuration/v2/buf-yaml +version: v2 +modules: + - path: proto +deps: + - buf.build/bufbuild/protovalidate + - buf.build/googleapis/googleapis + - buf.build/grpc-ecosystem/grpc-gateway +lint: + use: + - STANDARD +breaking: + use: + - FILE diff --git a/proto/google/README.md b/proto/google/README.md deleted file mode 100644 index 3d5a283..0000000 --- a/proto/google/README.md +++ /dev/null @@ -1,22 +0,0 @@ -# Google API Proto - -These are required for grpc-gateway. Ideally these are either -added to a git submodule, retrieved from a Makefile, downloaded by -buf, or retrieved by a CI job. - -**These are not guaranteed to be up to date** - -## Repo and Files - -These come from the following repo, and are required for -grpc gateway [per their documentation]() - -* Repo: [googleapis git repo](https://github.com/googleapis/googleapis) -* Docs: [grpc-gateay docs](https://github.com/grpc-ecosystem/grpc-gateway?tab=readme-ov-file#2-with-custom-annotations) - -### Files - -- [annotations.proto](https://raw.githubusercontent.com/googleapis/googleapis/refs/heads/master/google/api/annotations.proto) -- [field_behavior.proto](https://github.com/googleapis/googleapis/raw/refs/heads/master/google/api/field_behavior.proto) -- [http.proto](https://github.com/googleapis/googleapis/raw/refs/heads/master/google/api/http.proto) -- [httpbody.proto](https://github.com/googleapis/googleapis/raw/refs/heads/master/google/api/httpbody.proto) diff --git a/proto/google/api/annotations.proto b/proto/google/api/annotations.proto deleted file mode 100644 index 417edd8..0000000 --- a/proto/google/api/annotations.proto +++ /dev/null @@ -1,31 +0,0 @@ -// Copyright 2025 Google LLC -// -// Licensed under the Apache License, Version 2.0 (the "License"); -// you may not use this file except in compliance with the License. -// You may obtain a copy of the License at -// -// http://www.apache.org/licenses/LICENSE-2.0 -// -// Unless required by applicable law or agreed to in writing, software -// distributed under the License is distributed on an "AS IS" BASIS, -// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -// See the License for the specific language governing permissions and -// limitations under the License. - -syntax = "proto3"; - -package google.api; - -import "google/api/http.proto"; -import "google/protobuf/descriptor.proto"; - -option go_package = "google.golang.org/genproto/googleapis/api/annotations;annotations"; -option java_multiple_files = true; -option java_outer_classname = "AnnotationsProto"; -option java_package = "com.google.api"; -option objc_class_prefix = "GAPI"; - -extend google.protobuf.MethodOptions { - // See `HttpRule`. - HttpRule http = 72295728; -} diff --git a/proto/google/api/field_behavior.proto b/proto/google/api/field_behavior.proto deleted file mode 100644 index 1fdaaed..0000000 --- a/proto/google/api/field_behavior.proto +++ /dev/null @@ -1,104 +0,0 @@ -// Copyright 2025 Google LLC -// -// Licensed under the Apache License, Version 2.0 (the "License"); -// you may not use this file except in compliance with the License. -// You may obtain a copy of the License at -// -// http://www.apache.org/licenses/LICENSE-2.0 -// -// Unless required by applicable law or agreed to in writing, software -// distributed under the License is distributed on an "AS IS" BASIS, -// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -// See the License for the specific language governing permissions and -// limitations under the License. - -syntax = "proto3"; - -package google.api; - -import "google/protobuf/descriptor.proto"; - -option go_package = "google.golang.org/genproto/googleapis/api/annotations;annotations"; -option java_multiple_files = true; -option java_outer_classname = "FieldBehaviorProto"; -option java_package = "com.google.api"; -option objc_class_prefix = "GAPI"; - -extend google.protobuf.FieldOptions { - // A designation of a specific field behavior (required, output only, etc.) - // in protobuf messages. - // - // Examples: - // - // string name = 1 [(google.api.field_behavior) = REQUIRED]; - // State state = 1 [(google.api.field_behavior) = OUTPUT_ONLY]; - // google.protobuf.Duration ttl = 1 - // [(google.api.field_behavior) = INPUT_ONLY]; - // google.protobuf.Timestamp expire_time = 1 - // [(google.api.field_behavior) = OUTPUT_ONLY, - // (google.api.field_behavior) = IMMUTABLE]; - repeated google.api.FieldBehavior field_behavior = 1052 [packed = false]; -} - -// An indicator of the behavior of a given field (for example, that a field -// is required in requests, or given as output but ignored as input). -// This **does not** change the behavior in protocol buffers itself; it only -// denotes the behavior and may affect how API tooling handles the field. -// -// Note: This enum **may** receive new values in the future. -enum FieldBehavior { - // Conventional default for enums. Do not use this. - FIELD_BEHAVIOR_UNSPECIFIED = 0; - - // Specifically denotes a field as optional. - // While all fields in protocol buffers are optional, this may be specified - // for emphasis if appropriate. - OPTIONAL = 1; - - // Denotes a field as required. - // This indicates that the field **must** be provided as part of the request, - // and failure to do so will cause an error (usually `INVALID_ARGUMENT`). - REQUIRED = 2; - - // Denotes a field as output only. - // This indicates that the field is provided in responses, but including the - // field in a request does nothing (the server *must* ignore it and - // *must not* throw an error as a result of the field's presence). - OUTPUT_ONLY = 3; - - // Denotes a field as input only. - // This indicates that the field is provided in requests, and the - // corresponding field is not included in output. - INPUT_ONLY = 4; - - // Denotes a field as immutable. - // This indicates that the field may be set once in a request to create a - // resource, but may not be changed thereafter. - IMMUTABLE = 5; - - // Denotes that a (repeated) field is an unordered list. - // This indicates that the service may provide the elements of the list - // in any arbitrary order, rather than the order the user originally - // provided. Additionally, the list's order may or may not be stable. - UNORDERED_LIST = 6; - - // Denotes that this field returns a non-empty default value if not set. - // This indicates that if the user provides the empty value in a request, - // a non-empty value will be returned. The user will not be aware of what - // non-empty value to expect. - NON_EMPTY_DEFAULT = 7; - - // Denotes that the field in a resource (a message annotated with - // google.api.resource) is used in the resource name to uniquely identify the - // resource. For AIP-compliant APIs, this should only be applied to the - // `name` field on the resource. - // - // This behavior should not be applied to references to other resources within - // the message. - // - // The identifier field of resources often have different field behavior - // depending on the request it is embedded in (e.g. for Create methods name - // is optional and unused, while for Update methods it is required). Instead - // of method-specific annotations, only `IDENTIFIER` is required. - IDENTIFIER = 8; -} diff --git a/proto/google/api/http.proto b/proto/google/api/http.proto deleted file mode 100644 index 57621b5..0000000 --- a/proto/google/api/http.proto +++ /dev/null @@ -1,370 +0,0 @@ -// Copyright 2025 Google LLC -// -// Licensed under the Apache License, Version 2.0 (the "License"); -// you may not use this file except in compliance with the License. -// You may obtain a copy of the License at -// -// http://www.apache.org/licenses/LICENSE-2.0 -// -// Unless required by applicable law or agreed to in writing, software -// distributed under the License is distributed on an "AS IS" BASIS, -// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -// See the License for the specific language governing permissions and -// limitations under the License. - -syntax = "proto3"; - -package google.api; - -option go_package = "google.golang.org/genproto/googleapis/api/annotations;annotations"; -option java_multiple_files = true; -option java_outer_classname = "HttpProto"; -option java_package = "com.google.api"; -option objc_class_prefix = "GAPI"; - -// Defines the HTTP configuration for an API service. It contains a list of -// [HttpRule][google.api.HttpRule], each specifying the mapping of an RPC method -// to one or more HTTP REST API methods. -message Http { - // A list of HTTP configuration rules that apply to individual API methods. - // - // **NOTE:** All service configuration rules follow "last one wins" order. - repeated HttpRule rules = 1; - - // When set to true, URL path parameters will be fully URI-decoded except in - // cases of single segment matches in reserved expansion, where "%2F" will be - // left encoded. - // - // The default behavior is to not decode RFC 6570 reserved characters in multi - // segment matches. - bool fully_decode_reserved_expansion = 2; -} - -// gRPC Transcoding -// -// gRPC Transcoding is a feature for mapping between a gRPC method and one or -// more HTTP REST endpoints. It allows developers to build a single API service -// that supports both gRPC APIs and REST APIs. Many systems, including [Google -// APIs](https://github.com/googleapis/googleapis), -// [Cloud Endpoints](https://cloud.google.com/endpoints), [gRPC -// Gateway](https://github.com/grpc-ecosystem/grpc-gateway), -// and [Envoy](https://github.com/envoyproxy/envoy) proxy support this feature -// and use it for large scale production services. -// -// `HttpRule` defines the schema of the gRPC/REST mapping. The mapping specifies -// how different portions of the gRPC request message are mapped to the URL -// path, URL query parameters, and HTTP request body. It also controls how the -// gRPC response message is mapped to the HTTP response body. `HttpRule` is -// typically specified as an `google.api.http` annotation on the gRPC method. -// -// Each mapping specifies a URL path template and an HTTP method. The path -// template may refer to one or more fields in the gRPC request message, as long -// as each field is a non-repeated field with a primitive (non-message) type. -// The path template controls how fields of the request message are mapped to -// the URL path. -// -// Example: -// -// service Messaging { -// rpc GetMessage(GetMessageRequest) returns (Message) { -// option (google.api.http) = { -// get: "/v1/{name=messages/*}" -// }; -// } -// } -// message GetMessageRequest { -// string name = 1; // Mapped to URL path. -// } -// message Message { -// string text = 1; // The resource content. -// } -// -// This enables an HTTP REST to gRPC mapping as below: -// -// - HTTP: `GET /v1/messages/123456` -// - gRPC: `GetMessage(name: "messages/123456")` -// -// Any fields in the request message which are not bound by the path template -// automatically become HTTP query parameters if there is no HTTP request body. -// For example: -// -// service Messaging { -// rpc GetMessage(GetMessageRequest) returns (Message) { -// option (google.api.http) = { -// get:"/v1/messages/{message_id}" -// }; -// } -// } -// message GetMessageRequest { -// message SubMessage { -// string subfield = 1; -// } -// string message_id = 1; // Mapped to URL path. -// int64 revision = 2; // Mapped to URL query parameter `revision`. -// SubMessage sub = 3; // Mapped to URL query parameter `sub.subfield`. -// } -// -// This enables a HTTP JSON to RPC mapping as below: -// -// - HTTP: `GET /v1/messages/123456?revision=2&sub.subfield=foo` -// - gRPC: `GetMessage(message_id: "123456" revision: 2 sub: -// SubMessage(subfield: "foo"))` -// -// Note that fields which are mapped to URL query parameters must have a -// primitive type or a repeated primitive type or a non-repeated message type. -// In the case of a repeated type, the parameter can be repeated in the URL -// as `...?param=A¶m=B`. In the case of a message type, each field of the -// message is mapped to a separate parameter, such as -// `...?foo.a=A&foo.b=B&foo.c=C`. -// -// For HTTP methods that allow a request body, the `body` field -// specifies the mapping. Consider a REST update method on the -// message resource collection: -// -// service Messaging { -// rpc UpdateMessage(UpdateMessageRequest) returns (Message) { -// option (google.api.http) = { -// patch: "/v1/messages/{message_id}" -// body: "message" -// }; -// } -// } -// message UpdateMessageRequest { -// string message_id = 1; // mapped to the URL -// Message message = 2; // mapped to the body -// } -// -// The following HTTP JSON to RPC mapping is enabled, where the -// representation of the JSON in the request body is determined by -// protos JSON encoding: -// -// - HTTP: `PATCH /v1/messages/123456 { "text": "Hi!" }` -// - gRPC: `UpdateMessage(message_id: "123456" message { text: "Hi!" })` -// -// The special name `*` can be used in the body mapping to define that -// every field not bound by the path template should be mapped to the -// request body. This enables the following alternative definition of -// the update method: -// -// service Messaging { -// rpc UpdateMessage(Message) returns (Message) { -// option (google.api.http) = { -// patch: "/v1/messages/{message_id}" -// body: "*" -// }; -// } -// } -// message Message { -// string message_id = 1; -// string text = 2; -// } -// -// -// The following HTTP JSON to RPC mapping is enabled: -// -// - HTTP: `PATCH /v1/messages/123456 { "text": "Hi!" }` -// - gRPC: `UpdateMessage(message_id: "123456" text: "Hi!")` -// -// Note that when using `*` in the body mapping, it is not possible to -// have HTTP parameters, as all fields not bound by the path end in -// the body. This makes this option more rarely used in practice when -// defining REST APIs. The common usage of `*` is in custom methods -// which don't use the URL at all for transferring data. -// -// It is possible to define multiple HTTP methods for one RPC by using -// the `additional_bindings` option. Example: -// -// service Messaging { -// rpc GetMessage(GetMessageRequest) returns (Message) { -// option (google.api.http) = { -// get: "/v1/messages/{message_id}" -// additional_bindings { -// get: "/v1/users/{user_id}/messages/{message_id}" -// } -// }; -// } -// } -// message GetMessageRequest { -// string message_id = 1; -// string user_id = 2; -// } -// -// This enables the following two alternative HTTP JSON to RPC mappings: -// -// - HTTP: `GET /v1/messages/123456` -// - gRPC: `GetMessage(message_id: "123456")` -// -// - HTTP: `GET /v1/users/me/messages/123456` -// - gRPC: `GetMessage(user_id: "me" message_id: "123456")` -// -// Rules for HTTP mapping -// -// 1. Leaf request fields (recursive expansion nested messages in the request -// message) are classified into three categories: -// - Fields referred by the path template. They are passed via the URL path. -// - Fields referred by the [HttpRule.body][google.api.HttpRule.body]. They -// are passed via the HTTP -// request body. -// - All other fields are passed via the URL query parameters, and the -// parameter name is the field path in the request message. A repeated -// field can be represented as multiple query parameters under the same -// name. -// 2. If [HttpRule.body][google.api.HttpRule.body] is "*", there is no URL -// query parameter, all fields -// are passed via URL path and HTTP request body. -// 3. If [HttpRule.body][google.api.HttpRule.body] is omitted, there is no HTTP -// request body, all -// fields are passed via URL path and URL query parameters. -// -// Path template syntax -// -// Template = "/" Segments [ Verb ] ; -// Segments = Segment { "/" Segment } ; -// Segment = "*" | "**" | LITERAL | Variable ; -// Variable = "{" FieldPath [ "=" Segments ] "}" ; -// FieldPath = IDENT { "." IDENT } ; -// Verb = ":" LITERAL ; -// -// The syntax `*` matches a single URL path segment. The syntax `**` matches -// zero or more URL path segments, which must be the last part of the URL path -// except the `Verb`. -// -// The syntax `Variable` matches part of the URL path as specified by its -// template. A variable template must not contain other variables. If a variable -// matches a single path segment, its template may be omitted, e.g. `{var}` -// is equivalent to `{var=*}`. -// -// The syntax `LITERAL` matches literal text in the URL path. If the `LITERAL` -// contains any reserved character, such characters should be percent-encoded -// before the matching. -// -// If a variable contains exactly one path segment, such as `"{var}"` or -// `"{var=*}"`, when such a variable is expanded into a URL path on the client -// side, all characters except `[-_.~0-9a-zA-Z]` are percent-encoded. The -// server side does the reverse decoding. Such variables show up in the -// [Discovery -// Document](https://developers.google.com/discovery/v1/reference/apis) as -// `{var}`. -// -// If a variable contains multiple path segments, such as `"{var=foo/*}"` -// or `"{var=**}"`, when such a variable is expanded into a URL path on the -// client side, all characters except `[-_.~/0-9a-zA-Z]` are percent-encoded. -// The server side does the reverse decoding, except "%2F" and "%2f" are left -// unchanged. Such variables show up in the -// [Discovery -// Document](https://developers.google.com/discovery/v1/reference/apis) as -// `{+var}`. -// -// Using gRPC API Service Configuration -// -// gRPC API Service Configuration (service config) is a configuration language -// for configuring a gRPC service to become a user-facing product. The -// service config is simply the YAML representation of the `google.api.Service` -// proto message. -// -// As an alternative to annotating your proto file, you can configure gRPC -// transcoding in your service config YAML files. You do this by specifying a -// `HttpRule` that maps the gRPC method to a REST endpoint, achieving the same -// effect as the proto annotation. This can be particularly useful if you -// have a proto that is reused in multiple services. Note that any transcoding -// specified in the service config will override any matching transcoding -// configuration in the proto. -// -// The following example selects a gRPC method and applies an `HttpRule` to it: -// -// http: -// rules: -// - selector: example.v1.Messaging.GetMessage -// get: /v1/messages/{message_id}/{sub.subfield} -// -// Special notes -// -// When gRPC Transcoding is used to map a gRPC to JSON REST endpoints, the -// proto to JSON conversion must follow the [proto3 -// specification](https://developers.google.com/protocol-buffers/docs/proto3#json). -// -// While the single segment variable follows the semantics of -// [RFC 6570](https://tools.ietf.org/html/rfc6570) Section 3.2.2 Simple String -// Expansion, the multi segment variable **does not** follow RFC 6570 Section -// 3.2.3 Reserved Expansion. The reason is that the Reserved Expansion -// does not expand special characters like `?` and `#`, which would lead -// to invalid URLs. As the result, gRPC Transcoding uses a custom encoding -// for multi segment variables. -// -// The path variables **must not** refer to any repeated or mapped field, -// because client libraries are not capable of handling such variable expansion. -// -// The path variables **must not** capture the leading "/" character. The reason -// is that the most common use case "{var}" does not capture the leading "/" -// character. For consistency, all path variables must share the same behavior. -// -// Repeated message fields must not be mapped to URL query parameters, because -// no client library can support such complicated mapping. -// -// If an API needs to use a JSON array for request or response body, it can map -// the request or response body to a repeated field. However, some gRPC -// Transcoding implementations may not support this feature. -message HttpRule { - // Selects a method to which this rule applies. - // - // Refer to [selector][google.api.DocumentationRule.selector] for syntax - // details. - string selector = 1; - - // Determines the URL pattern is matched by this rules. This pattern can be - // used with any of the {get|put|post|delete|patch} methods. A custom method - // can be defined using the 'custom' field. - oneof pattern { - // Maps to HTTP GET. Used for listing and getting information about - // resources. - string get = 2; - - // Maps to HTTP PUT. Used for replacing a resource. - string put = 3; - - // Maps to HTTP POST. Used for creating a resource or performing an action. - string post = 4; - - // Maps to HTTP DELETE. Used for deleting a resource. - string delete = 5; - - // Maps to HTTP PATCH. Used for updating a resource. - string patch = 6; - - // The custom pattern is used for specifying an HTTP method that is not - // included in the `pattern` field, such as HEAD, or "*" to leave the - // HTTP method unspecified for this rule. The wild-card rule is useful - // for services that provide content to Web (HTML) clients. - CustomHttpPattern custom = 8; - } - - // The name of the request field whose value is mapped to the HTTP request - // body, or `*` for mapping all request fields not captured by the path - // pattern to the HTTP body, or omitted for not having any HTTP request body. - // - // NOTE: the referred field must be present at the top-level of the request - // message type. - string body = 7; - - // Optional. The name of the response field whose value is mapped to the HTTP - // response body. When omitted, the entire response message will be used - // as the HTTP response body. - // - // NOTE: The referred field must be present at the top-level of the response - // message type. - string response_body = 12; - - // Additional HTTP bindings for the selector. Nested bindings must - // not contain an `additional_bindings` field themselves (that is, - // the nesting may only be one level deep). - repeated HttpRule additional_bindings = 11; -} - -// A custom pattern is used for defining custom HTTP verb. -message CustomHttpPattern { - // The name of this custom HTTP verb. - string kind = 1; - - // The path matched by this custom verb. - string path = 2; -} diff --git a/proto/google/api/httpbody.proto b/proto/google/api/httpbody.proto deleted file mode 100644 index e3e17c8..0000000 --- a/proto/google/api/httpbody.proto +++ /dev/null @@ -1,80 +0,0 @@ -// Copyright 2025 Google LLC -// -// Licensed under the Apache License, Version 2.0 (the "License"); -// you may not use this file except in compliance with the License. -// You may obtain a copy of the License at -// -// http://www.apache.org/licenses/LICENSE-2.0 -// -// Unless required by applicable law or agreed to in writing, software -// distributed under the License is distributed on an "AS IS" BASIS, -// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -// See the License for the specific language governing permissions and -// limitations under the License. - -syntax = "proto3"; - -package google.api; - -import "google/protobuf/any.proto"; - -option go_package = "google.golang.org/genproto/googleapis/api/httpbody;httpbody"; -option java_multiple_files = true; -option java_outer_classname = "HttpBodyProto"; -option java_package = "com.google.api"; -option objc_class_prefix = "GAPI"; - -// Message that represents an arbitrary HTTP body. It should only be used for -// payload formats that can't be represented as JSON, such as raw binary or -// an HTML page. -// -// -// This message can be used both in streaming and non-streaming API methods in -// the request as well as the response. -// -// It can be used as a top-level request field, which is convenient if one -// wants to extract parameters from either the URL or HTTP template into the -// request fields and also want access to the raw HTTP body. -// -// Example: -// -// message GetResourceRequest { -// // A unique request id. -// string request_id = 1; -// -// // The raw HTTP body is bound to this field. -// google.api.HttpBody http_body = 2; -// -// } -// -// service ResourceService { -// rpc GetResource(GetResourceRequest) -// returns (google.api.HttpBody); -// rpc UpdateResource(google.api.HttpBody) -// returns (google.protobuf.Empty); -// -// } -// -// Example with streaming methods: -// -// service CaldavService { -// rpc GetCalendar(stream google.api.HttpBody) -// returns (stream google.api.HttpBody); -// rpc UpdateCalendar(stream google.api.HttpBody) -// returns (stream google.api.HttpBody); -// -// } -// -// Use of this type only changes how the request and response bodies are -// handled, all other features will continue to work unchanged. -message HttpBody { - // The HTTP Content-Type header value specifying the content type of the body. - string content_type = 1; - - // The HTTP request/response body as raw binary. - bytes data = 2; - - // Application specific response metadata. Must be set in the first response - // for streaming APIs. - repeated google.protobuf.Any extensions = 3; -}