gRPC Concepts

An introduction to key gRPC concepts, with an overview of gRPC architectureand RPC life cycle.

Not familiar with gRPC? First readWhat is gRPC?. Forlanguage-specific details, see the Quick Start, tutorial, and referencedocumentation for your language of choice.

Overview

Service definition

Like many RPC systems, gRPC is based around the idea of defining a service,specifying the methods that can be called remotely with their parameters andreturn types. By default, gRPC usesprotocolbuffers as the InterfaceDefinition Language (IDL) for describing both the service interface and thestructure of the payload messages. It is possible to use other alternatives ifdesired.

service HelloService {
  rpc SayHello (HelloRequest) returns (HelloResponse);
}
message HelloRequest {
  string greeting = 1;
}
message HelloResponse {
  string reply = 1;
}

gRPC lets you define four kinds of service method:

• Unary RPCs where the client sends a single request to the server and gets asingle response back, just like a normal function call.

rpc SayHello(HelloRequest) returns (HelloResponse);

• Server streaming RPCs where the client sends a request to the server and getsa stream to read a sequence of messages back. The client reads from thereturned stream until there are no more messages. gRPC guarantees messageordering within an individual RPC call.

rpc LotsOfReplies(HelloRequest) returns (stream HelloResponse);

• Client streaming RPCs where the client writes a sequence of messages and sendsthem to the server, again using a provided stream. Once the client hasfinished writing the messages, it waits for the server to read them and returnits response. Again gRPC guarantees message ordering within an individual RPCcall.

rpc LotsOfGreetings(stream HelloRequest) returns (HelloResponse);

• Bidirectional streaming RPCs where both sides send a sequence of messagesusing a read-write stream. The two streams operate independently, so clientsand servers can read and write in whatever order they like: for example, theserver could wait to receive all the client messages before writing itsresponses, or it could alternately read a message then write a message, orsome other combination of reads and writes. The order of messages in eachstream is preserved.

rpc BidiHello(stream HelloRequest) returns (stream HelloResponse);

You’ll learn more about the different types of RPC in theRPC life cycle section below.

Using the API

Starting from a service definition in a .proto file, gRPC provides protocolbuffer compiler plugins that generate client- and server-side code. gRPC userstypically call these APIs on the client side and implement the corresponding APIon the server side.

• On the server side, the server implements the methods declared by the serviceand runs a gRPC server to handle client calls. The gRPC infrastructure decodesincoming requests, executes service methods, and encodes service responses.
• On the client side, the client has a local object known as stub (for somelanguages, the preferred term is client) that implements the same methods asthe service. The client can then just call those methods on the local object,wrapping the parameters for the call in the appropriate protocol buffermessage type - gRPC looks after sending the request(s) to the server andreturning the server’s protocol buffer response(s).

Synchronous vs. asynchronous

Synchronous RPC calls that block until a response arrives from the server arethe closest approximation to the abstraction of a procedure call that RPCaspires to. On the other hand, networks are inherently asynchronous and in manyscenarios it’s useful to be able to start RPCs without blocking the currentthread.

The gRPC programming API in most languages comes in both synchronous andasynchronous flavors. You can find out more in each language’s tutorial andreference documentation (complete reference docs are coming soon).

RPC life cycle

In this section, you’ll take a closer look at what happens when a gRPC clientcalls a gRPC server method. For complete implementation details, see thelanguage-specific pages.

Unary RPC

First consider the simplest type of RPC where the client sends a single requestand gets back a single response.

• Once the client calls a stub method, the server isnotified that the RPC has been invoked with the client’smetadatafor this call, the method name, and the specifieddeadline ifapplicable.
• The server can then either send back its own initial metadata (which must besent before any response) straight away, or wait for the client’s requestmessage. Which happens first, is application-specific.
• Once the server has the client’s request message, it does whatever work isnecessary to create and populate a response. The response is then returned(if successful) to the client together with status details (status code andoptional status message) and optional trailing metadata.
• If the response status is OK, then the client gets the response, whichcompletes the call on the client side.

Server streaming RPC

A server-streaming RPC is similar to a unary RPC, except that the server returnsa stream of messages in response to a client’s request. After sending all itsmessages, the server’s status details (status code and optional status message)and optional trailing metadata are sent to the client. This completes processingon the server side. The client completes once it has all the server’s messages.

Client streaming RPC

A client-streaming RPC is similar to a unary RPC, except that the client sends astream of messages to the server instead of a single message. The serverresponds with a single message (along with its status details and optionaltrailing metadata), typically but not necessarily after it has received all theclient’s messages.

Bidirectional streaming RPC

In a bidirectional streaming RPC, the call is initiated by the clientinvoking the method and the server receiving the client metadata, method name,and deadline. The server can choose to send back its initial metadata orwait for the client to start streaming messages.

Client- and server-side stream processing is application specific. Since the twostreams are independent, the client and server can read and write messages inany order. For example, a server can wait until it has received all of aclient’s messages before writing its messages, or the server and client can play“ping-pong” – the server gets a request, then sends back a response, then theclient sends another request based on the response, and so on.

Deadlines/Timeouts

gRPC allows clients to specify how long they are willing to wait for an RPC tocomplete before the RPC is terminated with a DEADLINE_EXCEEDED error. Onthe server side, the server can query to see if a particular RPC has timed out,or how much time is left to complete the RPC.

Specifying a deadline or timeout is language specific: some language APIs workin terms of timeouts (durations of time), and some language APIs work in termsof a deadline (a fixed point in time) and may or maynot have a default deadline.

RPC termination

In gRPC, both the client and server make independent and local determinations ofthe success of the call, and their conclusions may not match. This means that,for example, you could have an RPC that finishes successfully on the server side(“I have sent all my responses!") but fails on the client side (“The responsesarrived after my deadline!"). It’s also possible for a server to decide tocomplete before a client has sent all its requests.

Cancelling an RPC

Either the client or the server can cancel an RPC at any time. A cancellationterminates the RPC immediately so that no further work is done.

Warning

Changes made before a cancellation are not rolled back.

Metadata

Metadata is information about a particular RPC call (such asauthenticationdetails) in the form of a list of key-value pairs, where thekeys are strings and the values are typically strings, but can be binary data.Metadata is opaque to gRPC itself - it lets the client provide informationassociated with the call to the server and vice versa.

Access to metadata is language dependent.

Channels

A gRPC channel provides a connection to a gRPC server on a specified host andport. It is used when creating a client stub. Clients can specify channelarguments to modify gRPC’s default behaviour, such as switching messagecompression on or off. A channel has state, including connected and idle.

How gRPC deals with closing a channel is language dependent. Some languages alsopermit querying channel state.