Example in Envoy control plane: github.com/envoyproxy/go-control-plane/envoy/type/http.pb.go. Protobuf outputs with some details about what generated it:
// Code generated by protoc-gen-go. DO NOT EDIT.
// versions:
// protoc-gen-go v1.22.0
// protoc v3.10.1
// source: envoy/type/http.proto
package envoy_typeUsing correct protobuf repositories ("google.golang.org/protobuf").
import (
_ "github.com/cncf/udpa/go/udpa/annotations"
proto "github.com/golang/protobuf/proto"
protoreflect "google.golang.org/protobuf/reflect/protoreflect"
protoimpl "google.golang.org/protobuf/runtime/protoimpl"
reflect "reflect"
)With some validation of Protobuf versions baked in:
const (
// Verify that this generated code is sufficiently up-to-date.
_ = protoimpl.EnforceVersion(20 - protoimpl.MinVersion)
// Verify that runtime/protoimpl is sufficiently up-to-date.
_ = protoimpl.EnforceVersion(protoimpl.MaxVersion - 20)
)This is supported using Google's Any type: https://github.com/protocolbuffers/protobuf/blob/master/src/google/protobuf/any.proto
Example of packing this up:
package google.profile;
message Person {
string first_name = 1;
string last_name = 2;
}foo := &pb.Person{...}
any, err := anypb.New(foo)
if err != nil {
...
}
...
foo := &pb.Person{}
if err := any.UnmarshalTo(foo); err != nil {
...
}Example JSON representation:
{
"@type": "type.googleapis.com/google.profile.Person",
"firstName": <string>,
"lastName": <string>
}@google-cloud/datastore ships with a /build/protos file including .{js,d.ts} files and a /build/protos/protos.json manifest. This is generated using Googles GAPIC Toolkit, specifically gapic-generator-typescript.
Googles GAPIC Toolkit exposes macros with Bazel for Protobuf compilation, and specifically gapic.node_library:
# synth.py: https://github.com/googleapis/nodejs-datastore/pull/695/files#diff-3620890cb174a7f98c0722895e37bb79L12-R12
v1_library = gapic.node_library('datastore', version, proto_path=f'google/datastore/{version}')Explainer in the repository: https://github.com/googleapis/gapic-generator#prerequisites-for-code-generation.
Easier is it to use the specific sub-generators that we need:
- https://github.com/googleapis/gapic-generator-go
- https://github.com/googleapis/gapic-generator-typescript
This repository contains common annotations to configure proto services:
For example rpc options with google.api.http and google.api.method_signature:
// Tests the specified permissions against the IAM access control policy
// for a [ServiceAccount][google.iam.admin.v1.ServiceAccount].
rpc TestIamPermissions(google.iam.v1.TestIamPermissionsRequest) returns (google.iam.v1.TestIamPermissionsResponse) {
option (google.api.http) = {
post: "/v1/{resource=projects/*/serviceAccounts/*}:testIamPermissions"
body: "*"
};
option (google.api.method_signature) = "resource,permissions";
}And [(google.api.field_behavior) = REQUIRED] for messages:
// Required. The account id that is used to generate the service account
// email address and a stable unique id. It is unique within a project,
// must be 6-30 characters long, and match the regular expression
// `[a-z]([-a-z0-9]*[a-z0-9])` to comply with RFC1035.
string account_id = 2 [(google.api.field_behavior) = REQUIRED];
// The [ServiceAccount][google.iam.admin.v1.ServiceAccount] resource to
// create. Currently, only the following values are user assignable:
// `display_name` and `description`.
ServiceAccount service_account = 3;