From 79daae3604a09148abcfad8d1812656ed490edcf Mon Sep 17 00:00:00 2001 From: Abhishek Kumar Date: Fri, 16 Jan 2015 16:17:21 -0800 Subject: [PATCH 1/6] Create README.md --- README.md | 18 ++++++++++++++++++ 1 file changed, 18 insertions(+) create mode 100644 README.md diff --git a/README.md b/README.md new file mode 100644 index 00000000000..b4a37c0f9d5 --- /dev/null +++ b/README.md @@ -0,0 +1,18 @@ +gRPC - An RPC library and framework +=================================== + +Copyright 2015 Google Inc. + +Installation +------------ + +See grpc/INSTALL for installation instructions for various platforms. + +Overview +-------- + +Remote Procedure Calls (RPCs) provide a useful abstraction for building +distributed applications and services. The libraries in this repository +provide a concrete implementation of the gRPC protocol, layered over HTTP/2. +These libraries enable communication between clients and servers using any +combination of the supported languages. From 771928628f9d65150c4da2875e1bf2fc531c2775 Mon Sep 17 00:00:00 2001 From: Abhishek Kumar Date: Fri, 16 Jan 2015 16:28:50 -0800 Subject: [PATCH 2/6] Update README.md Added a section on protocol. --- README.md | 13 +++++++++++++ 1 file changed, 13 insertions(+) diff --git a/README.md b/README.md index b4a37c0f9d5..05414d8e21d 100644 --- a/README.md +++ b/README.md @@ -16,3 +16,16 @@ distributed applications and services. The libraries in this repository provide a concrete implementation of the gRPC protocol, layered over HTTP/2. These libraries enable communication between clients and servers using any combination of the supported languages. + +Developers using gRPC typically start with the description of an RPC service +(a collection of methods), and generate client and server side interfaces +which they use on the client-side and implement on the server side. + +Protocol +-------- + +The gRPC protocol specifies the abstract requirements for communication between +clients and servers. A concrete embedding over HTTP/2 completes the picture by +fleshing out the details of each of the required operations. + + From 0adce9db94793fc25603334268ce771e174fa673 Mon Sep 17 00:00:00 2001 From: Abhishek Kumar Date: Wed, 21 Jan 2015 11:32:18 -0800 Subject: [PATCH 3/6] Update README.md Added more details in the Interface and Protocol sections. --- README.md | 53 +++++++++++++++++++++++++++++++++++++++++++++++------ 1 file changed, 47 insertions(+), 6 deletions(-) diff --git a/README.md b/README.md index 05414d8e21d..1e5b61af95a 100644 --- a/README.md +++ b/README.md @@ -3,13 +3,12 @@ gRPC - An RPC library and framework Copyright 2015 Google Inc. -Installation ------------- +#Installation See grpc/INSTALL for installation instructions for various platforms. -Overview --------- +#Overview + Remote Procedure Calls (RPCs) provide a useful abstraction for building distributed applications and services. The libraries in this repository @@ -17,15 +16,57 @@ provide a concrete implementation of the gRPC protocol, layered over HTTP/2. These libraries enable communication between clients and servers using any combination of the supported languages. + +##Interface + + Developers using gRPC typically start with the description of an RPC service (a collection of methods), and generate client and server side interfaces which they use on the client-side and implement on the server side. -Protocol --------- +By default, gRPC uses [Protocol Buffers](github.com/google/protobuf) as the +Interface Definition Language (IDL) for describing both the service interface +and the structure of the payload messages. It is possible to use other +alternatives if desired. + +###Surface API +Starting from an interface definition in a .proto file, gRPC provides +Protocol Compiler plugins that generate Client- and Server-side APIs. +gRPC users typically call into these APIs on the Client side and implement +the corresponding API on the server side. + +#### Synchronous vs. Async +Synchronous RPC calls, that block till a response arrives from the server, are +the closest approximation to the abstraction of a procedure call that RPC +aspires to. + +On the other hand, networks are inherently asynchronous and in many scenarios, +it is desirable to have the ability to start RPCs without blocking the current +thread. + +The gRPC programming surface in most languages comes in both Synchronous and +async flavors. + + +## Streaming + +gRPC supports streaming semantics, where either the client or the server (or both) +send a stream of messages on a single RPC call. The most general case is +Bidirectional Streaming where a single gRPC call establishes a stream where both +the client and the server can send a stream of messages to each other. The streamed +messages are delivered in the order they were sent. + + + + + +#Protocol The gRPC protocol specifies the abstract requirements for communication between clients and servers. A concrete embedding over HTTP/2 completes the picture by fleshing out the details of each of the required operations. +## Abstract gRPC protocol +A gRPC RPC 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`. 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'). + From bb20de4c3f0a03d4206d3fb1434c67b0ea514398 Mon Sep 17 00:00:00 2001 From: Abhishek Kumar Date: Thu, 22 Jan 2015 10:13:34 -0800 Subject: [PATCH 4/6] Update README.md --- README.md | 9 +++++---- 1 file changed, 5 insertions(+), 4 deletions(-) diff --git a/README.md b/README.md index 1e5b61af95a..4ee4c573d6c 100644 --- a/README.md +++ b/README.md @@ -57,9 +57,6 @@ the client and the server can send a stream of messages to each other. The strea messages are delivered in the order they were sent. - - - #Protocol The gRPC protocol specifies the abstract requirements for communication between @@ -67,6 +64,10 @@ clients and servers. A concrete embedding over HTTP/2 completes the picture by fleshing out the details of each of the required operations. ## Abstract gRPC protocol -A gRPC RPC 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`. 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'). +A gRPC RPC 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`. 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`). + +## Implementation over HTTP/2 +The 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 HPAC 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). +**TODO(a11r): Add a section on flow control.** From 546e42fdd2ae111655baa9b146fe590812b0faad Mon Sep 17 00:00:00 2001 From: Abhishek Kumar Date: Thu, 22 Jan 2015 10:20:36 -0800 Subject: [PATCH 5/6] Update README.md Added a short blurb on flow control. --- README.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/README.md b/README.md index 4ee4c573d6c..9e8b8e77917 100644 --- a/README.md +++ b/README.md @@ -69,5 +69,5 @@ A gRPC RPC comprises of a bidirectional stream of messages, initiated by the cli ## Implementation over HTTP/2 The 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 HPAC 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). - -**TODO(a11r): Add a section on flow control.** +## Flow Control +gRPC inherits the flow control mchanims in HTTP/2 and uses them to enable fine-grained control of the amount of memory used for buffering in-flight messages. From 7453c3da4cd10ea57080601515eaa271a073bb64 Mon Sep 17 00:00:00 2001 From: Abhishek Kumar Date: Fri, 23 Jan 2015 10:04:53 -0800 Subject: [PATCH 6/6] Update README.md Addressed review comments. --- README.md | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/README.md b/README.md index 9e8b8e77917..fa39d3b3089 100644 --- a/README.md +++ b/README.md @@ -1,4 +1,4 @@ -gRPC - An RPC library and framework +[gRPC - An RPC library and framework](http://github.com/google/grpc) =================================== Copyright 2015 Google Inc. @@ -35,8 +35,8 @@ Protocol Compiler plugins that generate Client- and Server-side APIs. gRPC users typically call into these APIs on the Client side and implement the corresponding API on the server side. -#### Synchronous vs. Async -Synchronous RPC calls, that block till a response arrives from the server, are +#### Synchronous vs. asynchronous +Synchronous RPC calls, that block until a response arrives from the server, are the closest approximation to the abstraction of a procedure call that RPC aspires to. @@ -44,8 +44,8 @@ On the other hand, networks are inherently asynchronous and in many scenarios, it is desirable to have the ability to start RPCs without blocking the current thread. -The gRPC programming surface in most languages comes in both Synchronous and -async flavors. +The gRPC programming surface in most languages comes in both synchronous and +asynchronous flavors. ## Streaming