mirror of https://github.com/grpc/grpc.git
Craig Tiller
10 years ago
commit
a311bb6e47
308 changed files with 13744 additions and 1998 deletions
@ -0,0 +1,73 @@ |
||||
[gRPC - An RPC library and framework](http://github.com/google/grpc) |
||||
=================================== |
||||
|
||||
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. |
||||
|
||||
|
||||
##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. |
||||
|
||||
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. 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. |
||||
|
||||
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 |
||||
asynchronous 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`). |
||||
|
||||
## 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). |
||||
|
||||
## 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. |
||||
@ -0,0 +1,67 @@ |
||||
/*
|
||||
* |
||||
* Copyright 2014, Google Inc. |
||||
* All rights reserved. |
||||
* |
||||
* Redistribution and use in source and binary forms, with or without |
||||
* modification, are permitted provided that the following conditions are |
||||
* met: |
||||
* |
||||
* * Redistributions of source code must retain the above copyright |
||||
* notice, this list of conditions and the following disclaimer. |
||||
* * Redistributions in binary form must reproduce the above |
||||
* copyright notice, this list of conditions and the following disclaimer |
||||
* in the documentation and/or other materials provided with the |
||||
* distribution. |
||||
* * Neither the name of Google Inc. nor the names of its |
||||
* contributors may be used to endorse or promote products derived from |
||||
* this software without specific prior written permission. |
||||
* |
||||
* THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS |
||||
* "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT |
||||
* LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR |
||||
* A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT |
||||
* OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, |
||||
* SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT |
||||
* LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, |
||||
* DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY |
||||
* THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT |
||||
* (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE |
||||
* OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. |
||||
* |
||||
*/ |
||||
|
||||
#ifndef __GRPC_GRPC_HTTP_H__ |
||||
#define __GRPC_GRPC_HTTP_H__ |
||||
|
||||
#ifdef __cplusplus |
||||
extern "C" { |
||||
#endif |
||||
|
||||
/* HTTP GET support.
|
||||
|
||||
HTTP2 servers can publish statically generated text content served |
||||
via HTTP2 GET queries by publishing one or more grpc_http_server_page |
||||
elements via repeated GRPC_ARG_SERVE_OVER_HTTP elements in the servers |
||||
channel_args. |
||||
|
||||
This is not: |
||||
- a general purpose web server |
||||
- particularly fast |
||||
|
||||
It's useful for being able to serve up some static content (maybe some |
||||
javascript to be able to interact with your GRPC server?) */ |
||||
|
||||
typedef struct { |
||||
const char *path; |
||||
const char *content_type; |
||||
const char *content; |
||||
} grpc_http_server_page; |
||||
|
||||
#define GRPC_ARG_SERVE_OVER_HTTP "grpc.serve_over_http" |
||||
|
||||
#ifdef __cplusplus |
||||
} |
||||
#endif |
||||
|
||||
#endif /* __GRPC_GRPC_HTTP_H__ */ |
||||
Some files were not shown because too many files have changed in this diff Show More
Loading…
Reference in new issue