#prpc

                                     𝕎𝕙𝕒𝕥 has the world chosen ? 

                                             𝕎𝕙𝕖𝕣𝕖 will I go to ?

Fire in Highcastle, Johor. Dateline 2022-10-27, The Star: A fire broke out at a PETRONAS oil refinery here, which led to an explosion at 3.24pm on Thursday (Oct 27). In a statement, PETRONAS Refinery and Petrochemical Corporation Sdn Bhd (PRPC) said the fire broke out at one of the interconnecting pipes located in the Pengerang Integrated Complex (PIC) in Kota Tinggi, Johor. …

They came on a rainy evening to honor a man who’s given four decades of his life to public service.

I was one of the hundreds of Amarillo residents who flocked tonight to a brand new hotel downtown to honor Gary Pitner. I didn’t get too much face time with my friend, as he was pretty busy schmoozing with a lot of others in the reception room.

But I do want to write a few good words about this…

Maybe I am preaching to the proverbial choir, but I’ll preach this “sermon” anyway.

Amarillo City Council members’ decision to hire Jared Miller as our next city manager came after a discussion of issues that lacked one critical component: water management and conservation.

I don’t know, of course, what council members discussed in executive session with Miller and the four other finalists for…

gRPC is great, but is not available on Classic AppEngine at this time, so while waiting for it we wrote pRPC (provisional RPC) for Go. It is compatible with gRPC server/client code, but works on HTTP 1.x and Classic AppEngine. In addition it has gRPC-compatible discovery and a CLI tool.

IDL

Just like gRPC, pRPC uses Protocol Buffers to define API. I assume you know why protobufs are awesome because you care about gRPC.

This definition is taken from gRPC examples. pRPC proto definition is same as gRPC, but pRPC does not support streams.

Compile .proto

For Go code, we had to slightly alter (in a backward-compatible way) the code generated by protocol buffer compiler, so we wrote cproto tool.

Install cproto:

go get -u github.com/golang/protobuf/{proto,protoc-gen-go} go get -u github.com/luci/luci-go/grpc/cmd/cproto

cproto has minimalistic CLI:

//go:generate cproto

compiles all .proto files in the current directory to .go files

includes $GOPATH/src in proto import path, so you can (and should) import other .proto files with Go-style absolute paths, e.g. import "github.com/user/repo/proto/something.proto";

generates pb.discovery.go file that registers full service description for discoverability. You don't have to worry about it, it is just there and it is optional.

supports only Go

OK, now we have compiled our .proto files to Go code. Let's implement a service!

Service

A service implementation is fully compatible with gRPC:

pRPC uses gRPC codes

HTTP headers are accessible through metadata in the context.

In the code snippets I omit imports, but you can find them in the source code.

Server

Now let's host the service. Since AppEngine is our target user case, the example is for AppEngine. The init function registers HTTP routers in the default muxer.

This example registers pRPC HTTP handlers for helloworld service.

I've deployed prpc-helloworld.appspot.com, but you can run your own server locally:

goapp get -u github.com/nodirt/prpc-example/helloworld/server goapp serve github.com/nodirt/prpc-example/helloworld/server

Assuming your $GOPATH is correctly configured for goapp, this will run a pRPC server locally at port 8080.

CLI client

rpc is a CLI tool that can discover services and call them.

Install rpc:

go get -u github.com/luci/luci-go/grpc/cmd/rpc

I will use prpc-helloworld.appspot.com for future examples (and so can you), but you can use :8080 for your local server.

Discover services

List available services:

$ rpc show prpc-helloworld.appspot.com helloworld.Greeter discovery.Discovery

List service methods:

$ rpc show prpc-helloworld.appspot.com helloworld.Greeter // The greeting service definition. service Greeter { // Sends a greeting rpc SayHello(HelloRequest) returns (HelloReply) {}; }

Describe a service method:

$ rpc show prpc-helloworld.appspot.com helloworld.Greeter.SayHello // The greeting service definition. service Greeter { // Sends a greeting rpc SayHello(HelloRequest) returns (HelloReply) {}; } // The request message containing the user's name. message HelloRequest { string name = 1; } // The response message containing the greetings message HelloReply { string message = 1; }

Call services

rpc can make RPCs:

$ rpc call prpc-helloworld.appspot.com helloworld.Greeter.SayHello -name $USER message: "Hello nodir"

Go client

Now let's make RPCs ourselves. A pRPC client implements the same interface as gRPC client, but it is created using a different function:

This may print a gRPC error code to stderr or the greeting to stdout.

Try it yourself:

go get -u github.com/nodirt/prpc-example/helloworld/client/prpchello prpchello -server prpc-helloworld.appspot.com -name $USER

This should greet you.

gRPC compatibility

Server and client interfaces for servies are same for pRPC and gRPC.

The discovery is just a service that works with both gRPC and pRPC, but it relies on pb.discovery.go files generated by cproto.

The rpc tool currently works with pRPC only, but we will update it when we switch to gRPC. Patches are welcome too.

Authentication

Unlike gRPC, authentication in pRPC is based on HTTP because our main use case is OAuth.

Our repo implements GAE-based OAuth2. To enable it, all you need to do is to import github.com/luci/luci-go/appengine/gaeauth/server package and use our authentication framework, e.g. use CurrentIdentity function to read current user email.

Alternatively, you can set prpc.Server.CustomAuthenticator to true and do whatever you want in base function passed to Server.InstallHandlers.

RPC Explorer

With RPC Explorer you can discover services, methods, with documentation, and make requests. Has request autocompletion.

Demo: https://prpc-talk.appspot.com/rpcexplorer/

Protocol