rmcguire/go-server-with-otel
Template
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

move to buf

Browse Source
This commit is contained in:
Ryan McGuire
2025-07-20 11:13:38 -04:00
parent d875bbb2f7
commit 55497b9d2a
13 changed files with 349 additions and 632 deletions
Download Patch File Download Diff File Expand all files Collapse all files

22
Makefile
View File

@ -12,15 +12,9 @@ GIT_REPO := gitea.libretechconsulting.com/rmcguire/go-server-with-otel
all: proto test build docker all: proto test build docker
proto: check_protoc $(API_DIR) proto: check_buf
protoc --proto_path=proto --proto_path=proto/google \ buf dep update
--go_out=$(API_DIR) --go_opt=paths=source_relative \ buf generate
--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))
test: test:
go test -v ./... go test -v ./...
@ -56,13 +50,9 @@ install:
clean: clean:
rm -rf bin/${CMD_NAME} rm -rf bin/${CMD_NAME}
check_protoc: check_buf:
@if ! command -v protoc-gen-go > /dev/null; then \ @if ! command -v buf > /dev/null; then \
echo "Error: protoc-gen-go not found in PATH"; \ echo "Error: buf 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"; \
exit 1; \ exit 1; \
fi fi

5
api/demo/app/v1alpha1/app.pb.go
View File

@ -1,7 +1,7 @@
// Code generated by protoc-gen-go. DO NOT EDIT. // Code generated by protoc-gen-go. DO NOT EDIT.
// versions: // versions:
// protoc-gen-go v1.36.6 // protoc-gen-go v1.36.6
// protoc v5.29.3 // protoc (unknown)
// source: demo/app/v1alpha1/app.proto // source: demo/app/v1alpha1/app.proto
package demo package demo
@ -153,7 +153,8 @@ const file_demo_app_v1alpha1_app_proto_rawDesc = "" +
"\x06source\x18\x03 \x01(\tR\x06source\x12\x1a\n" + "\x06source\x18\x03 \x01(\tR\x06source\x12\x1a\n" +
"\blanguage\x18\x04 \x01(\tR\blanguage2z\n" + "\blanguage\x18\x04 \x01(\tR\blanguage2z\n" +
"\x0eDemoAppService\x12h\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 ( var (
file_demo_app_v1alpha1_app_proto_rawDescOnce sync.Once file_demo_app_v1alpha1_app_proto_rawDescOnce sync.Once

4
api/demo/app/v1alpha1/app.pb.gw.go
View File

@ -42,7 +42,9 @@ func request_DemoAppService_GetDemo_0(ctx context.Context, marshaler runtime.Mar
protoReq GetDemoRequest protoReq GetDemoRequest
metadata runtime.ServerMetadata 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 { if err := req.ParseForm(); err != nil {
return nil, metadata, status.Errorf(codes.InvalidArgument, "%v", err) return nil, metadata, status.Errorf(codes.InvalidArgument, "%v", err)
} }

275
api/demo/app/v1alpha1/app.pb.validate.go Normal file
View File

@ -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{}

8
api/demo/app/v1alpha1/app_grpc.pb.go
View File

@ -1,7 +1,7 @@
// Code generated by protoc-gen-go-grpc. DO NOT EDIT. // Code generated by protoc-gen-go-grpc. DO NOT EDIT.
// versions: // versions:
// - protoc-gen-go-grpc v1.5.1 // - protoc-gen-go-grpc v1.5.1
// - protoc v5.29.3 // - protoc (unknown)
// source: demo/app/v1alpha1/app.proto // source: demo/app/v1alpha1/app.proto
package demo package demo
@ -48,14 +48,13 @@ func (c *demoAppServiceClient) GetDemo(ctx context.Context, in *GetDemoRequest,
} }
// DemoAppServiceServer is the server API for DemoAppService service. // DemoAppServiceServer is the server API for DemoAppService service.
// All implementations must embed UnimplementedDemoAppServiceServer // All implementations should embed UnimplementedDemoAppServiceServer
// for forward compatibility. // for forward compatibility.
type DemoAppServiceServer interface { type DemoAppServiceServer interface {
GetDemo(context.Context, *GetDemoRequest) (*GetDemoResponse, error) GetDemo(context.Context, *GetDemoRequest) (*GetDemoResponse, error)
mustEmbedUnimplementedDemoAppServiceServer()
} }
// UnimplementedDemoAppServiceServer must be embedded to have // UnimplementedDemoAppServiceServer should be embedded to have
// forward compatible implementations. // forward compatible implementations.
// //
// NOTE: this should be embedded by value instead of pointer to avoid a nil // NOTE: this should be embedded by value instead of pointer to avoid a nil
@ -65,7 +64,6 @@ type UnimplementedDemoAppServiceServer struct{}
func (UnimplementedDemoAppServiceServer) GetDemo(context.Context, *GetDemoRequest) (*GetDemoResponse, error) { func (UnimplementedDemoAppServiceServer) GetDemo(context.Context, *GetDemoRequest) (*GetDemoResponse, error) {
return nil, status.Errorf(codes.Unimplemented, "method GetDemo not implemented") 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. // UnsafeDemoAppServiceServer may be embedded to opt out of forward compatibility for this service.

32
buf.gen.yaml Normal file
View File

@ -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

12
buf.lock Normal file
View File

@ -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

14
buf.yaml Normal file
View File

@ -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

22
proto/google/README.md
View File

@ -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)

31
proto/google/api/annotations.proto
View File

@ -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;
}

104
proto/google/api/field_behavior.proto
View File

@ -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;
}

370
proto/google/api/http.proto
View File

@ -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&param=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;
}

80
proto/google/api/httpbody.proto
View File

@ -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;
}