grpc/grpc-proto

gRPC-defined protobufs for peripheral services such as health checking, load balancing, etc.

gRPC – An RPC library and framework

gRPC is a modern, open source, high-performance remote procedure call (RPC) framework that can run anywhere. gRPC enables client and server applications to communicate transparently, and simplifies the building of connected systems.

Homepage:	grpc.io
Mailing List:	[email protected]

To start using gRPC

To maximize usability, gRPC supports the standard method for adding dependencies to a user's chosen language (if there is one). In most languages, the gRPC runtime comes as a package available in a user's language package manager.

For instructions on how to use the language-specific gRPC runtime for a project, please refer to these documents

• C++: follow the instructions under the src/cpp directory
• C#/.NET: NuGet packages Grpc.Net.Client, Grpc.AspNetCore.Server
• Dart: pub package grpc
• Go: go get google.golang.org/grpc
• Java: Use JARs from Maven Central Repository
• Kotlin: Use JARs from Maven Central Repository
• Node: npm install @grpc/grpc-js
• Objective-C: Add gRPC-ProtoRPC dependency to podspec
• PHP: pecl install grpc
• Python: pip install grpcio
• Ruby: gem install grpc
• WebJS: follow the grpc-web instructions

Per-language quickstart guides and tutorials can be found in the documentation section on the grpc.io website. Code examples are available in the examples directory.

Precompiled bleeding-edge package builds of gRPC master branch's HEAD are uploaded daily to packages.grpc.io.

To start developing gRPC

Contributions are welcome!

Please read How to contribute which will guide you through the entire workflow of how to build the source code, how to run the tests, and how to contribute changes to the gRPC codebase. The "How to contribute" document also contains info on how the contribution process works and contains best practices for creating contributions.

Troubleshooting

Sometimes things go wrong. Please check out the Troubleshooting guide if you are experiencing issues with gRPC.

Performance

See the Performance dashboard for performance numbers of master branch daily builds.

Concepts

See gRPC Concepts

About This Repository

This repository contains source code for gRPC libraries implemented in multiple languages written on top of a shared C++ core library src/core.

Libraries in different languages may be in various states of development. We are seeking contributions for all of these libraries:

Language	Source
Shared C++ [core library]	src/core
C++	src/cpp
Ruby	src/ruby
Python	src/python
PHP	src/php
C# (core library based)	src/csharp
Objective-C	src/objective-c

Language	Source repo
Java	grpc-java
Kotlin	grpc-kotlin
Go	grpc-go
NodeJS	grpc-node
WebJS	grpc-web
Dart	grpc-dart
.NET (pure C# impl.)	grpc-dotnet
Swift	grpc-swift

grpc-proto's Issues

Add idempotency_level to health check schema

What do you think of adding idempotency_level options to the health check schema? The most appropriate level seems to be NO_SIDE_EFFECTS.

Even though gRPC always uses HTTP POST, these annotations would be useful:

• They document the expected behavior of servers.
• They allow client-side interceptors to adopt more aggressive retry policies.
• They allow gRPC-aware middleboxes to cache responses (though setting a TTL may be tricky).
• They allow other RPC protocols to serve the Check RPC using HTTP GETs.

Happy to open a PR if there's any interest!

Unable to compile s2a_context.proto

Similar to #150, there is a syntax error in grpc/gcp/s2a/s2a_context.proto (missing semicolon):

grpc/gcp/s2a/s2a_context.proto:36:3: Expected ";".

error building for QNX: major and minor field names

I am trying to build grpc-proto for QNX (v7.0.0) and i get the following error in this part of the code

https://github.com/grpc/grpc-proto/blob/master/grpc/gcp/transport_security_common.proto#L36

[2023-07-25T20:16:07.905Z] [ 27%] Building CXX object CMakeFiles/grpc_binarylog_proto.dir/grpc/binlog/v1/binarylog.pb.cc.o
[2023-07-25T20:16:08.469Z] In file included from /opt/qnx700/target/qnx7/usr/include/sched.h:29:0,
[2023-07-25T20:16:08.469Z]                  from /opt/qnx700/target/qnx7/usr/include/pthread.h:45,
[2023-07-25T20:16:08.469Z]                  from /opt/qnx700/target/qnx7/usr/include/c++/v1/__mutex_base:17,
[2023-07-25T20:16:08.469Z]                  from /opt/qnx700/target/qnx7/usr/include/c++/v1/mutex:176,
[2023-07-25T20:16:08.469Z]                  from /opt/qnx700/target/qnx7/usr/include/c++/v1/__locale:18,
[2023-07-25T20:16:08.469Z]                  from /opt/qnx700/target/qnx7/usr/include/c++/v1/ios:216,
[2023-07-25T20:16:08.469Z]                  from /opt/qnx700/target/qnx7/usr/include/c++/v1/iostream:38,
[2023-07-25T20:16:08.469Z]                  from /var/jenkins/workspace/........../include/google/protobuf/stubs/common.h:39,
[2023-07-25T20:16:08.469Z]                  from /var/jenkins/workspace/........../include/google/protobuf/io/coded_stream.h:131,
[2023-07-25T20:16:08.469Z]                  from /var/jenkins/workspace/........../build/Release/grpc/gcp/altscontext.pb.h:23,
[2023-07-25T20:16:08.469Z]                  from /var/jenkins/workspace/........../build/Release/grpc/gcp/altscontext.pb.cc:4:
[2023-07-25T20:16:08.469Z] /var/jenkins/workspace/........../build/Release/grpc/gcp/transport_security_common.pb.h:219:12: error: expected unqualified-id before 'int'
[2023-07-25T20:16:08.469Z]    uint32_t major() const;
[2023-07-25T20:16:08.469Z]             ^
[2023-07-25T20:16:08.469Z] /var/jenkins/workspace/........../build/Release/grpc/gcp/transport_security_common.pb.h:219:12: error: expected ')' before 'int'
[2023-07-25T20:16:08.469Z] /var/jenkins/workspace/........../build/Release/grpc/gcp/transport_security_common.pb.h:219:12: error: expected ')' before 'int'
[2023-07-25T20:16:08.469Z] /var/jenkins/workspace/........../build/Release/grpc/gcp/transport_security_common.pb.h:228:12: error: expected unqualified-id before 'int'
[2023-07-25T20:16:08.469Z]    uint32_t minor() const;
[2023-07-25T20:16:08.469Z]             ^
[2023-07-25T20:16:08.469Z] /var/jenkins/workspace/........../build/Release/grpc/gcp/transport_security_common.pb.h:228:12: error: expected ')' before 'int'
[2023-07-25T20:16:08.469Z] /var/jenkins/workspace/........../build/Release/grpc/gcp/transport_security_common.pb.h:228:12: error: expected ')' before 'int'
[2023-07-25T20:16:08.469Z] /var/jenkins/workspace/........../build/Release/grpc/gcp/transport_security_common.pb.h:447:46: error: expected unqualified-id before '(' token
[2023-07-25T20:16:08.469Z]  inline uint32_t RpcProtocolVersions_Version::major() const {
[2023-07-25T20:16:08.469Z]                                               ^
[2023-07-25T20:16:08.469Z] /var/jenkins/workspace/........../build/Release/grpc/gcp/transport_security_common.pb.h:467:46: error: expected unqualified-id before '(' token
[2023-07-25T20:16:08.469Z]  inline uint32_t RpcProtocolVersions_Version::minor() const {
[2023-07-25T20:16:08.469Z]                                               ^
[2023-07-25T20:16:08.469Z] CMakeFiles/grpc_alts_handshaker_proto.dir/build.make:99: recipe for target 'CMakeFiles/grpc_alts_handshaker_proto.dir/grpc/gcp/altscontext.pb.cc.o' failed
[2023-07-25T20:16:08.469Z] make[2]: *** [CMakeFiles/grpc_alts_handshaker_proto.dir/grpc/gcp/altscontext.pb.cc.o] Error 1
[2023-07-25T20:16:08.469Z] CMakeFiles/Makefile2:324: recipe for target 'CMakeFiles/grpc_alts_handshaker_proto.dir/all' failed

i suspected about the words major and minor could be already defined elsewhere in QNX and apparently they are.
Just for testing this theory, i changed these fields names to major_version and minor_version. and the compilation worked.

but this change is far from good one since this field is referenced dozens of times in grpc, which depends on grpc-proto. Any other app that uses this proto would also need a patch ... a never ending patch ...

the words major and minor might be defined in something equivalent to libc in qnx since the dont appear in source code, thus, should have been removed by the linker.

my best guess so far (as a workaround) is to try to remove this existing major and minor definitions. but i dont know how to do that. any thoughts ?

for the future, consider renaming these two fields. would that be an option ?

Unable to compile s2a.proto

The newly added s2a proto files from #149 fail to compile with protoc 26.1 with the following error message:

grpc/gcp/s2a/s2a.proto:306:3: "s2a.proto.Identity" is resolved to "grpc.gcp.s2a.proto.Identity", which is not defined. The innermost scope is searched first in name resolution. Consider using a leading '.'(i.e., ".s2a.proto.Identity") to start from the outermost scope.

I believe the fix is:

--- a/grpc/gcp/s2a/s2a.proto
+++ b/grpc/gcp/s2a/s2a.proto
@@ -303,7 +303,7 @@ message SessionReq {
   // identity is not populated, S2A will try to deduce the managed identity to
   // use from the SNI extension. If that also fails, S2A uses the default
   // identity (if one exists).
-  s2a.proto.Identity local_identity = 1;
+  Identity local_identity = 1;
 
   // The authentication mechanisms that the application wishes to use to
   // authenticate to S2A, ordered by preference. S2A will always use the first

weighted_target json name

All load balancer names are configured to have JSON names that have underscores. The one exception is weighted_target. It looks like it would be inferred to be weightedTarget. Is this intentional?

grpc-proto/grpc/service_config/service_config.proto

Line 356 in ec88602

WeightedTargetLoadBalancingPolicyConfig weighted_target = 10;

Added here

@markdroth

Set up a Bazel CI

As came up in #49, there was a lot of iteration in separate PRs because the repository doesn't have a CI system to double-check the Bazel targets build.

Could be hosted on Travis-CI or Kokoro pretty easy.

A second health GRPC endpoint to differentiate Kubernetes liveness/readiness checks (e.g.)

NOTE: I have a change I can submit for review, given branch access.

TL;DR: This PR proposes a second GRPC health endpoint for use with GRPC transcoders running within Kubernetes. Kubernetes supports both liveness and readiness endpoints, but for HTTP->GRPC transcoding use cases, two separate GRPCs need to be registered to differentiate their functionality. (Kubernetes probe definitions)

For grpc-gateway and Envoy for example, the transcoding is 1:1 from HTTP endpoint to GRPC, and transcoding can't multiplex two HTTP endpoints to a single GRPC endpoint.

One alternative is to create a stub HTTP service within an otherwise pure GRPC service, however the business logic of liveness vs readiness would have to be duplicated in the HTTP logic layer, rather than within the parallel GRPC layer.

The proposed change essentially duplicates the Health GRPC and wraps it around the new "Readiness" name. This was chosen because of the simplicity and small change footprint.

An alternative approach could be to add two additional endpoints, one for Liveness and one for Readiness, each perhaps with their own (duplicate) Request and Response structures. There's a certain naming cleanliness here, but it seems overly complex.

Feedback welcome!

Quick summary of liveness vs readiness use cases:

• A liveness check should be used to verify the application/service itself
  is up and serving GRPC.
  IMPORTANT: Kubernetes will restart containers that fail a liveness check.
• A readiness check should be used to verify that the application/service
  has completed loading any prerequisite data, and that the service's
  upstream dependencies (e.g., MySQL, Kafka) are available and working.
  IMPORTANT: Kubernetes will remove the container from the service load
  balancers, but will not restart the container.

In other words, liveness represents permanent failure, while readiness
represents a transient failure, and the application-side implementation of
these checks should differ accordingly.