The README_NEW doc that's been added to the repo over the weekend is basically directing users away from the existing README/Overview and straight into language-specific docs. There is also a C++ Hello World that we don't particularly need (or rather, we need a C++ Route Guide tutorial a lot more).

I think there's also some misunderstanding about the role of the existing README - it is not a "Hello World Java tutorial" that other language developers can ignore or will find useless, it's "Hello World" for all gRPC users to introduce them to gRPC concepts eg service definition, stub, server, that happens to use Java as an illustration because I had to pick something rather than just hand-waving vaguely about stubs (plus there'll be a Go client in it as well once I finish my next PR), and it's not even really a tutorial. I have already deliberately removed a lot of the Java-specific explanation from the text and explicitly mentioned that it is not just for Java users and that other language users can see the same service implemented in the relevant subfolders in the repo if they want to play around with it. I will also add more detail about going to the language-specific repos to find out how to build the relevant plugin.

We don't need a separate "Hello World for C++ Tutorial" or any other language, we're going to have (once people have implemented RouteGuide) separate much more detailed language tutorials for each lang that are much more realistic and include all RPC types. The user route through these minimal docs regardless of what their favourite language is should be Overview -> Language Specific Route Guide Tutorial (if there's anything else to direct them to depends on what we get done over the next few days). Apart from anything else, having multiple Hello World tutorials as well as Route Guide tutorials is going to be even more of a maintenance nightmare and gives everyone a lot more work to do.

Example currently just shows running a (possibly not up to date) protoc command from the command line, should probably be changed to use gradle build from grpc-java repo (though still show explicit protoc command).

hi :

I've gone through the cpp tutorial, and I didn't find any other further docs. So what I want to know are:
1、 Is grpc easy to deploy a distributed server cluster?
2、 If 1 is yes then does the cluster support Load Balancing ?
3、 Dose it support HA by doing a config?

BTW:
Is there a maillist or mail group about grpc? I didn't find.

Thank you very much~

Unsure if you guys wanted this bug here or elsewhere, but there are some changes from proto2->3 that should probably be communicated on d.g.c. Stuff like removal of 'required', addition of maps, etc.

I want to implement a Java nano client at the same time as a Java server. So I've set up a multi-project gradle repo with the subprojects 'client', 'server' and 'shared':

• the 'client' subproject contains a Java nano client
• the 'server' subproject contains a Java server
• the 'shared' subproject just contains my .proto file.

I've created a test class in my 'server' subproject called TestServer. This instantiates and starts an instance of the server, and also starts an instance of a client. It then uses the client to test the API and assert the responses are as expected.

Initially I created an ApiClient class in the 'server' subproject, and used that in my TestServer as the client. This worked. Because it was using the non-nano generated code, I used the builders to build protobuf datatypes, just like the server was doing.

But, when I created a gradle testCompile dependency between my client and server subprojects, so the 'server' depended on the 'client', things stopped working. The problem is that the nano code doesn't use builders for creating the protobuf datatypes, but instead uses accessors, i.e.:

// Creating a User in the nano client:
User user = new User();
user.username = "the username";

// Creating a User in the server:
User user = User.newBuilder().setUsername("the username").build();
// the accessor style used by java nano is not permitted on the server because the 
// constructors and fields are private.

The package name of the generated code is the same for both the client and the server, but has different implementations. So when I include my nano client in tests on in my 'server' subproject, the class loader can load the client, but when it instantiates a 'User' object in the nano client it loads the one from the 'server' subproject which uses the builder pattern. If I change the package name of the client generated code, I get NotImplemented exceptions raised by the server, presumably because the types don't match.

It'd be really useful to be able to develop both in parallel, and to use the nano client to test the server. The way to fix this seems to be for the non-nano objects to have public constructors and accessors as well as supporting builders.

Alternatively is there any way I can force my client jar to only load classes from within that jar itself, and not to load them from the 'server' subproject instead when it's being used from within the 'server' subproject?

In the Ruby helloworld example, both the client and server fail with the error

/usr/local/google/home/mlumish/grpc/src/ruby/lib/grpc/generic/bidi_call.rb:38:in `<class:BidiCall>': uninitialized constant GRPC::Core::CallOps (NameError)

I get the following output from make:

protoc -I ../../protos --cpp_out=. --grpc_out=. --plugin=protoc-gen-grpc=`which grpc_cpp_plugin` ../../protos/helloworld.proto
g++ -std=c++11 -I/usr/local/include -pthread  -c -o helloworld.pb.o helloworld.pb.cc
g++ -std=c++11 -I/usr/local/include -pthread  -c -o greeter_client.o greeter_client.cc
greeter_client.cc: In function ‘int main(int, char**)’:
greeter_client.cc:84:46: error: ‘InsecureCredentials’ is not a member of ‘grpc’
       grpc::CreateChannel("localhost:50051", grpc::InsecureCredentials(),
                                              ^
make: *** [greeter_client.o] Error 1
rm helloworld.pb.cc

I get substantially similar output when I try to build the cpp/route_guide

Running through the Ruby Hello World, when execute

gem install bundler && bundle install

I get:

You don't have write permissions for the /usr/local/rvm/gems/ruby-2.1.1 directory.

No amount of sudo-ing seems to help. Environment problem, or README problem?

https://github.com/grpc/grpc-common/blob/master/go/README.md suggests that go get -u github.com/grpc/grpc-common/go/greeter_client should compile cleanly. It does not.

Steps to repeat:

$ cat Dockerfile.grpc-go
FROM golang:1.4
RUN echo GOPATH=${GOPATH}
RUN echo PATH=${PATH}
RUN go get -u github.com/grpc/grpc-common/go/greeter_client
$ docker build -f Dockerfile.grpc-go .
Sending build context to Docker daemon 3.584 kB
Sending build context to Docker daemon 
Step 0 : FROM golang:1.4
 ---> aac88aa7c9ab
Step 1 : RUN echo GOPATH=${GOPATH}
 ---> Running in fe237133de48
GOPATH=/go
 ---> 9c6e22e0ca43
Removing intermediate container fe237133de48
Step 2 : RUN echo PATH=${PATH}
 ---> Running in 7d5ef3333231
PATH=/go/bin:/usr/src/go/bin:/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin
 ---> 93e47ee870b3
Removing intermediate container 7d5ef3333231
Step 3 : RUN go get -u github.com/grpc/grpc-common/go/greeter_client
 ---> Running in f305fb25f4df
# github.com/grpc/grpc-common/go/helloworld
src/github.com/grpc/grpc-common/go/helloworld/helloworld.pb.go:105: cannot use _Greeter_SayHello_Handler (type func(interface {}, context.Context, []byte) (proto.Message, error)) as type grpc.methodHandler in field value

Results: The package fails to compile with the following error:

# github.com/grpc/grpc-common/go/helloworld
src/github.com/grpc/grpc-common/go/helloworld/helloworld.pb.go:105: cannot use _Greeter_SayHello_Handler (type func(interface {}, context.Context, []byte) (proto.Message, error)) as type grpc.methodHandler in field value

Expected: The package should build.

It would be nice if there was an explicit and required way in the grpc streams to distinguish them from others (for instance normal web traffic). This way a single port could serve a web page and the services via grpc. Options that come to mind are:

• Either add a header to all grpc stream (grpc-stream or grpc-version or something like that)
• Use a special method (like grpc) in the :method header

Cheers 🍻

I'm looking at this example
https://github.com/grpc/grpc-common/blob/master/cpp/helloworld/greeter_client.cc#L83

And it uses the CreateChannelDeprecated function. Is there a newer, non-deprecated function that could be used? It might be more appropriate for an example that will likely get copy and pasted lots of times.

Thanks!

Documentation for Windows / Visual Studio is non-existent. There are vsprojects files, which is nice. The file do compile things, which is good. However, nowhere is there help on how to fix problems and what to expect. Please address the following hiccups :

Comping gRPC

• compiling fails on missing openssl includes
• solution : run build_openssl_x86.bat in a command-line with visual studio.
  then compiling grpc works

Generating protoc

Now, I am trying to generate some C++ code.

• Protoc would not compile because of some ruby problems in the ruby generator
  • solution 1 : deactivating ruby support fixed it.
  • solution 2 : point to the binary release

Running protoc

• According to helloworld tutorial, this works :

  protoc -I ../../protos/ --cpp_out=. --grpc_out=. --plugin=protoc-gen-grpc=grpc_cpp_plugin ../../protos/helloworld.proto

• This fails on the missing grpc_cpp_plugin plugin.

  • Solution : I looked in many places, makefiles and so on but could not find how to create this plugin. Please help...

@LisaFC

Hi Lisa,

It would be highly appreciated if you can help take a look at grpc/grpc-common/go/gotutorial.go. Thanks!

Using auth with gRPC - examples in available languages.

~/grpc-common/cpp/helloworld ⮀ ⭠ master ⮀ make helloworld.grpc.pb.cc helloworld.pb.cc
protoc -I ../../protos --grpc_out=. --plugin=protoc-gen-grpc=which grpc_cpp_plugin ../../protos/helloworld.proto
protoc -I ../../protos --cpp_out=. ../../protos/helloworld.proto
~/grpc-common/cpp/helloworld ⮀ ⭠ master ⮀ make
g++ -std=c++11 -I/usr/local/include -pthread -c -o helloworld.grpc.pb.o helloworld.grpc.pb.cc
g++ -std=c++11 -I/usr/local/include -pthread -c -o helloworld.pb.o helloworld.pb.cc
g++ -std=c++11 -I/usr/local/include -pthread -c -o greeter_client.o greeter_client.cc
g++ helloworld.grpc.pb.o helloworld.pb.o greeter_client.o -L/usr/local/lib -lgrpc++_unsecure -lgrpc -lgpr -lprotobuf -lpthread -ldl -o greeter_client
g++ -std=c++11 -I/usr/local/include -pthread -c -o greeter_server.o greeter_server.cc
g++ helloworld.pb.o greeter_server.o -L/usr/local/lib -lgrpc++_unsecure -lgrpc -lgpr -lprotobuf -lpthread -ldl -o greeter_server
Undefined symbols for architecture x86_64:
"helloworld::Greeter::Service::service()", referenced from:
vtable for GreeterServiceImpl in greeter_server.o
"helloworld::Greeter::Service::~Service()", referenced from:
GreeterServiceImpl::~GreeterServiceImpl() in greeter_server.o
"typeinfo for helloworld::Greeter::Service", referenced from:
typeinfo for GreeterServiceImpl in greeter_server.o
"vtable for helloworld::Greeter::Service", referenced from:
helloworld::Greeter::Service::Service() in greeter_server.o
NOTE: a missing vtable usually means the first non-inline virtual member function has no definition.
ld: symbol(s) not found for architecture x86_64
clang: error: linker command failed with exit code 1 (use -v to see invocation)
make: *** [greeter_server] Error 1

I'm just following this tutorial https://github.com/grpc/grpc-common/tree/master/cpp

This link, in the "Read More!" section, leads to a 404 for me.

Should be realtively straightforward for HAProxy. Largely following the recipe here

https://www.igvita.com/2012/10/31/simple-spdy-and-npn-negotiation-with-haproxy/

but adjusting for HTTP2 and ALPN.

Currently nghttp2 does not support multiple http2 backends but if it did we should have a recipe for that.

I'm trying to run the python hello world examples on a fresh ubuntu 14.04 install, but running into an issue with the client not being able to send RPCs to the server. Here's the log:

~/grpc-common/python/helloworld$ python greeter_server.py &
[1] 26449
~/grpc-common/python/helloworld$ netstat -a | grep 50051
tcp6 0 0 [::]:50051 [::]:* LISTEN
~/grpc-common/python/helloworld$ python greeter_client.py
ERROR:root:RPC write not accepted! Event: (Event(kind=<Kind.WRITE_ACCEPTED: <object object at 0xb75304c8>>, tag=UUID('33a32e3c-c9ea-4594-9294-27b56d424110'), write_accepted=False, complete_accepted=None, service_acceptance=None, bytes=None, status=None),)
Traceback (most recent call last):
File "greeter_client.py", line 44, in
run()
File "greeter_client.py", line 39, in run
response = stub.SayHello(helloworld_pb2.HelloRequest(name='you'), _TIMEOUT_SECONDS)
File "/usr/local/lib/python2.7/dist-packages/grpc/early_adopter/_reexport.py", line 158, in call
self._underlying, request, timeout)
File "/usr/local/lib/python2.7/dist-packages/grpc/early_adopter/_reexport.py", line 113, in _call_reexporting_errors
raise _reexport_error(e)
grpc.early_adopter.exceptions.ExpirationError
D0318 10:04:52.261256665 26463 iomgr.c:107] Waiting for 1 iomgr objects to be destroyed
D0318 10:05:02.262263114 26463 iomgr.c:121] Failed to free 1 iomgr objects before shutdown deadline: memory leaks are likely

I've gone through the Java tutorial, but I'm not clear on how to structure my code for a new project. Say I want to create a new mobile project, I'd want to create 4 new git repos (I guess) for the common code, Java server, Android client & iOS client.

It'd be useful to document how to organise code in this situtation in Intellij so that each repo only referenced the necessary code/dependencies. I want to avoid the Android jar/iOS code containing loads of unnecessary dependencies for the server, etc. and for the common code, client and server versions to be managed through maven/gradle.

After build grpc-common/cpp/helloworld, I use curl to send request like this:

 curl -v -X POST -d '{"name":"world"}'  http://127.0.0.1:50051/SayHello -H "Content-Type:application/grpc+json"

in greeter_client side it prints out:

* About to connect() to 127.0.0.1 port 50051 (#0)
*   Trying 127.0.0.1...
* Connected to 127.0.0.1 (127.0.0.1) port 50051 (#0)
> POST /SayHello HTTP/1.1
> User-Agent: curl/7.29.0
> Host: 127.0.0.1:50051
> Accept: */*
> Content-Type:application/grpc+json
> Content-Length: 16
> 
* upload completely sent off: 16 out of 16 bytes

in greeter_server side it prints out:

E0315 18:34:43.347566027   14660 chttp2_transport.c:1570] Connect string mismatch: expected 'R' (82) got 'O' (79) at byte 1

I have not got "Hello world" message.

Could some body help me find what is wrong?

RPC configuration options and what they do

There doesn't seem to be any documentation anywhere on how to run protoc for Android. The javatutorial doesn't use nano proto, so the protoc command documented there doesn't work. We need to add some documentation that provides a command similar to the comment in grpc/grpc-java@dcff315

/usr/bin/ld: warning: libgpr.so.0, needed by /usr/local/lib/libgrpc.so, not found (try using -rpath or -rpath-link)
After previous line errors with missing references for gpr_split_host_port, gpr_timespec_to_micros, etc.

I'm just following this tutorial https://github.com/grpc/grpc-common/tree/master/cpp

Markdown syntax highlighting has support for Protocol Buffers. This file has a list of every supported language. You can get this by putting protobuf in the code fence.

Custom link anchors (<a name="something"></a>) are not always necessary. All headers already have these, with the full text of the header slugified to make the anchor name. To get the anchor link for a specific header on a live Markdown file on GitHub, hovering over the header will display a link icon (:link:) that links to that header.

GitHub has a live Markdown editor on the website. To get to it, visit the file directly, then click the edit link (pencil icon) in the upper right corner. This allows you to preview the edit before submitting it.

For a good reference, the Mastering Markdown guide has pretty much all of the important information. This page is also helpful for more technical syntax information.

The spec currently has content-type as optional for requests, but that means there isn't a way to know that client is a grpc client.

There's one in python/helloworld, one for python/route_guide in code review, and there should be one at python.

I was under the impression that all fields in proto3 are optional, and the keyword is ~meaningless. Can it just be removed from the example helloworld.proto entirely?

Not sure if you're interested in mentioning this in the docs, but protobuf v3.0.0-alpha-2 is now in Homebrew, a popular OS X package manager. It makes it a lot easier to install from source.
brew update && brew install --devel protobuf

Update the auth document with a python snippet, similar to the C++, Ruby and Node snippets.

There does not appear to be a document that describes the proto3 syntax (only a transition document describing what's changed since proto2). Such a document would be very helpful for those new to gRPC.

Only just spotted this - is there a reason for this that I missed somewhere? I'm currently updating the protocol buffers docs and warning people off using gRPC with proto2 unless they absolutely have to because of compatibility issues with proto3.

In the Android example, I see:

            HelloRequest message = new HelloRequest();
            message.name = mMessage;

I gather that this means it uses the "javanano" implementation of protocol buffers, which uses public fields and mutable messages.

However, when I try to generate my service definitions for the javanano runtime, I get an error:

$ protoc --version
libprotoc 3.0.0
$ protoc --javanano_out=../app/core/gen my.proto
--javanano_out: my.proto: my.proto: Java NANO_RUNTIME does not support services"

So how is this supposed to work? Some documentation on how the example files in the grpc-common repository were generated (without Gradle, not everyone uses Gradle) would be really helpful.

1. Why use HTTP/2 transport rather than raw TCP?
2. Why does application-layer need its own flow control? Doesn't TCP flow control itself take care of all these problems?

https://github.com/grpc/grpc-common/blob/master/README.md has a section labeled TODO: Diagram?

Is there a plan to include a diagram? Or should we just retitle that section?

In the Node.js sample, replace the INSTALL (and build) of the grpc binaries with an apt get grpc as soon as the package is available.

gRPC Java no longer has the Maven build. To build it you must use Gradle. This can be done by installing gradle or by using the gradlew or gradlew.bat (based on your OS) in the repo. Gradle will install into the Maven local repo just like Maven does, so this does not impact other projects using Maven.

We should have a Hello World sample in C/C++, Java, Go, Python, Ruby, Node.js.

This repository contains many references to Stubby. See:
https://github.com/grpc/grpc-common/search?utf8=%E2%9C%93&q=stubby

@tbetbetbe @LisaFC Should these be removed / replaced?

bundle install failed on me ... maybe I did something wrong?
The machine is ubuntu with grpc c installed and protobuf 3.0.0 installed too, if that matters.

$ bundle install
Fetching gem metadata from https://rubygems.org/.........
Fetching version metadata from https://rubygems.org/..
Resolving dependencies...
Installing addressable 2.3.7
Installing extlib 0.9.16
Installing multipart-post 2.0.0
Installing faraday 0.9.1

Gem::Installer::ExtensionBuildError: ERROR: Failed to build gem native extension.

    /usr/bin/ruby1.9.1 extconf.rb 

/usr/lib/ruby/1.9.1/rubygems/custom_require.rb:36:in require': cannot load such file -- mkmf (LoadError) from /usr/lib/ruby/1.9.1/rubygems/custom_require.rb:36:inrequire'
from extconf.rb:3:in `

Gem files will remain installed in /tmp/bundler20150224-13709-1qy30yv/google-protobuf-3.0.0.alpha.1.1/gems/google-protobuf-3.0.0.alpha.1.1 for inspection.
Results logged to /tmp/bundler20150224-13709-1qy30yv/google-protobuf-3.0.0.alpha.1.1/gems/google-protobuf-3.0.0.alpha.1.1/ext/google/protobuf_c/gem_make.out
An error occurred while installing google-protobuf (3.0.0.alpha.1.1), and
Bundler cannot continue.
Make sure that gem install google-protobuf -v '3.0.0.alpha.1.1' succeeds
before bundling.

In the PREREQUISITES section, it's not clear if you only need to run the curl command if you do not have Ruby 2.1 or not.

If it is true that, if you have Ruby 2.1, you do not need to run that command, the first sentence should be "This requires Ruby 2.1, as the gRPC API surface uses keyword args. If you do have Ruby 2.1, go to the Install section"

Also: the command is strange. Is it two lines or one? Looks like two separate commands (because there is a $ prompt on the second).

More detailed information on gRPC concepts such as architecture, RPC types/life cycle,

As for the Android sample https://github.com/grpc/grpc-common/tree/master/java/android,
building an app by gradle is a de-facto standard for Android apps rather than copying the libraries manually.

Is there any reason you don't use gradle for that sample?

Relevant discussion on mailing list: https://groups.google.com/d/topic/grpc-io/5Ic8MKgltwY/discussion

https://github.com/grpc/grpc-common/tree/master/python/helloworld#the-server

should be referenced before

https://github.com/grpc/grpc-common/tree/master/python/helloworld#the-client

programmer should take care of running server first and then client. But if we just follow this doc blindly end up running client without server and hence client errors out.

Hence it would be better to change the order.