1*cc02d7e2SAndroid Build Coastguard Worker# gRPC Concepts Overview 2*cc02d7e2SAndroid Build Coastguard Worker 3*cc02d7e2SAndroid Build Coastguard WorkerRemote Procedure Calls (RPCs) provide a useful abstraction for building 4*cc02d7e2SAndroid Build Coastguard Workerdistributed applications and services. The libraries in this repository 5*cc02d7e2SAndroid Build Coastguard Workerprovide a concrete implementation of the gRPC protocol, layered over HTTP/2. 6*cc02d7e2SAndroid Build Coastguard WorkerThese libraries enable communication between clients and servers using any 7*cc02d7e2SAndroid Build Coastguard Workercombination of the supported languages. 8*cc02d7e2SAndroid Build Coastguard Worker 9*cc02d7e2SAndroid Build Coastguard Worker 10*cc02d7e2SAndroid Build Coastguard Worker## Interface 11*cc02d7e2SAndroid Build Coastguard Worker 12*cc02d7e2SAndroid Build Coastguard WorkerDevelopers using gRPC start with a language agnostic description of an RPC service (a collection 13*cc02d7e2SAndroid Build Coastguard Workerof methods). From this description, gRPC will generate client and server side interfaces 14*cc02d7e2SAndroid Build Coastguard Workerin any of the supported languages. The server implements 15*cc02d7e2SAndroid Build Coastguard Workerthe service interface, which can be remotely invoked by the client interface. 16*cc02d7e2SAndroid Build Coastguard Worker 17*cc02d7e2SAndroid Build Coastguard WorkerBy default, gRPC uses [Protocol Buffers](https://github.com/protocolbuffers/protobuf) as the 18*cc02d7e2SAndroid Build Coastguard WorkerInterface Definition Language (IDL) for describing both the service interface 19*cc02d7e2SAndroid Build Coastguard Workerand the structure of the payload messages. It is possible to use other 20*cc02d7e2SAndroid Build Coastguard Workeralternatives if desired. 21*cc02d7e2SAndroid Build Coastguard Worker 22*cc02d7e2SAndroid Build Coastguard Worker### Invoking & handling remote calls 23*cc02d7e2SAndroid Build Coastguard WorkerStarting from an interface definition in a .proto file, gRPC provides 24*cc02d7e2SAndroid Build Coastguard WorkerProtocol Compiler plugins that generate Client- and Server-side APIs. 25*cc02d7e2SAndroid Build Coastguard WorkergRPC users call into these APIs on the Client side and implement 26*cc02d7e2SAndroid Build Coastguard Workerthe corresponding API on the server side. 27*cc02d7e2SAndroid Build Coastguard Worker 28*cc02d7e2SAndroid Build Coastguard Worker#### Synchronous vs. asynchronous 29*cc02d7e2SAndroid Build Coastguard WorkerSynchronous RPC calls, that block until a response arrives from the server, are 30*cc02d7e2SAndroid Build Coastguard Workerthe closest approximation to the abstraction of a procedure call that RPC 31*cc02d7e2SAndroid Build Coastguard Workeraspires to. 32*cc02d7e2SAndroid Build Coastguard Worker 33*cc02d7e2SAndroid Build Coastguard WorkerOn the other hand, networks are inherently asynchronous and in many scenarios, 34*cc02d7e2SAndroid Build Coastguard Workerit is desirable to have the ability to start RPCs without blocking the current 35*cc02d7e2SAndroid Build Coastguard Workerthread. 36*cc02d7e2SAndroid Build Coastguard Worker 37*cc02d7e2SAndroid Build Coastguard WorkerThe gRPC programming surface in most languages comes in both synchronous and 38*cc02d7e2SAndroid Build Coastguard Workerasynchronous flavors. 39*cc02d7e2SAndroid Build Coastguard Worker 40*cc02d7e2SAndroid Build Coastguard Worker 41*cc02d7e2SAndroid Build Coastguard Worker## Streaming 42*cc02d7e2SAndroid Build Coastguard Worker 43*cc02d7e2SAndroid Build Coastguard WorkergRPC supports streaming semantics, where either the client or the server (or both) 44*cc02d7e2SAndroid Build Coastguard Workersend a stream of messages on a single RPC call. The most general case is 45*cc02d7e2SAndroid Build Coastguard WorkerBidirectional Streaming where a single gRPC call establishes a stream in which both 46*cc02d7e2SAndroid Build Coastguard Workerthe client and the server can send a stream of messages to each other. The streamed 47*cc02d7e2SAndroid Build Coastguard Workermessages are delivered in the order they were sent. 48*cc02d7e2SAndroid Build Coastguard Worker 49*cc02d7e2SAndroid Build Coastguard Worker 50*cc02d7e2SAndroid Build Coastguard Worker# Protocol 51*cc02d7e2SAndroid Build Coastguard Worker 52*cc02d7e2SAndroid Build Coastguard WorkerThe [gRPC protocol](doc/PROTOCOL-HTTP2.md) specifies the abstract requirements for communication between 53*cc02d7e2SAndroid Build Coastguard Workerclients and servers. A concrete embedding over HTTP/2 completes the picture by 54*cc02d7e2SAndroid Build Coastguard Workerfleshing out the details of each of the required operations. 55*cc02d7e2SAndroid Build Coastguard Worker 56*cc02d7e2SAndroid Build Coastguard Worker## Abstract gRPC protocol 57*cc02d7e2SAndroid Build Coastguard WorkerA gRPC call comprises of a bidirectional stream of messages, initiated by the client. In the client-to-server direction, this stream begins with a mandatory `Call Header`, followed by optional `Initial-Metadata`, followed by zero or more `Payload Messages`. A client signals end of its message stream by means of an underlying lower level protocol. The server-to-client direction contains an optional `Initial-Metadata`, followed by zero or more `Payload Messages` terminated with a mandatory `Status` and optional `Status-Metadata` (a.k.a.,`Trailing-Metadata`). 58*cc02d7e2SAndroid Build Coastguard Worker 59*cc02d7e2SAndroid Build Coastguard Worker## Implementation over HTTP/2 60*cc02d7e2SAndroid Build Coastguard WorkerThe abstract protocol defined above is implemented over [HTTP/2](https://http2.github.io/). gRPC bidirectional streams are mapped to HTTP/2 streams. The contents of `Call Header` and `Initial Metadata` are sent as HTTP/2 headers and subject to HPACK compression. `Payload Messages` are serialized into a byte stream of length prefixed gRPC frames which are then fragmented into HTTP/2 frames at the sender and reassembled at the receiver. `Status` and `Trailing-Metadata` are sent as HTTP/2 trailing headers (a.k.a., trailers). A client signals end of its message stream by setting `END_STREAM` flag on the last DATA frame. 61*cc02d7e2SAndroid Build Coastguard WorkerFor a detailed description see [doc/PROTOCOL-HTTP2.md](doc/PROTOCOL-HTTP2.md). 62*cc02d7e2SAndroid Build Coastguard Worker 63*cc02d7e2SAndroid Build Coastguard Worker## Flow Control 64*cc02d7e2SAndroid Build Coastguard WorkergRPC uses the flow control mechanism in HTTP/2. This enables fine-grained control of memory used for buffering in-flight messages. 65