mirror of https://github.com/grpc/grpc.git
Yuchen Zeng
8 years ago
commit
bd363544fd
1158 changed files with 33902 additions and 16599 deletions
@ -0,0 +1,151 @@ |
|||||||
|
# Overview |
||||||
|
|
||||||
|
gRPC-Web provides a JS client library that supports the same API |
||||||
|
as gRPC-Node to access a gRPC service. Due to browser limitation, |
||||||
|
the Web client library implements a different protocol than the |
||||||
|
[native gRPC protocol](http://www.grpc.io/docs/guides/wire.html). |
||||||
|
This protocol is designed to make it easy for a proxy to translate |
||||||
|
between the protocols as this is the most likely deployment model. |
||||||
|
|
||||||
|
This document lists the differences between the two protocols. |
||||||
|
To help tracking future revisions, this document describes a delta |
||||||
|
with the protocol details specified in the |
||||||
|
[native gRPC protocol](http://www.grpc.io/docs/guides/wire.html). |
||||||
|
|
||||||
|
# Design goals |
||||||
|
|
||||||
|
For the gRPC-Web protocol, we have decided on the following design goals: |
||||||
|
|
||||||
|
* adopt the same framing as “application/grpc” whenever possible |
||||||
|
* decouple from HTTP/2 framing which is not, and will never, be directly |
||||||
|
exposed by browsers |
||||||
|
* support text streams (e.g. base64) in order to provide cross-browser |
||||||
|
support (e.g. IE-10) |
||||||
|
|
||||||
|
While the new protocol will be published/reviewed publicly, we also |
||||||
|
intend to keep the protocol as an internal detail to gRPC-Web. |
||||||
|
More specifically, we expect the protocol to |
||||||
|
|
||||||
|
* evolve over time, mainly to optimize for browser clients or support |
||||||
|
web-specific features such as CORS, XSRF |
||||||
|
* become optional (in 1-2 years) when browsers are able to speak the native |
||||||
|
gRPC protocol via the new [whatwg fetch/streams API](https://github.com/whatwg/fetch) |
||||||
|
|
||||||
|
# Protocol differences vs [gRPC over HTTP2](http://www.grpc.io/docs/guides/wire.html) |
||||||
|
|
||||||
|
Content-Type |
||||||
|
|
||||||
|
1. application/grpc-web |
||||||
|
* e.g. application/grpc-web+[proto, json, thrift] |
||||||
|
2. application/grpc-web-text |
||||||
|
* text-encoded streams of “application/grpc-web” |
||||||
|
|
||||||
|
--- |
||||||
|
|
||||||
|
HTTP wire protocols |
||||||
|
|
||||||
|
1. support any HTTP/*, with no dependency on HTTP/2 specific framing |
||||||
|
2. use lower-case header/trailer names |
||||||
|
3. use EOF (end of body) to close the stream |
||||||
|
|
||||||
|
--- |
||||||
|
|
||||||
|
HTTP/2 related behavior (specified in [gRPC over HTTP2](http://www.grpc.io/docs/guides/wire.html)) |
||||||
|
|
||||||
|
1. stream-id is not supported or used |
||||||
|
2. go-away is not supported or used |
||||||
|
|
||||||
|
--- |
||||||
|
|
||||||
|
Message framing (vs. [http2-transport-mapping](http://www.grpc.io/docs/guides/wire.html#http2-transport-mapping)) |
||||||
|
|
||||||
|
1. Response status encoded as part of the response body |
||||||
|
* Key-value pairs formatted as HTTP/1.1 headers block (without the empty |
||||||
|
newline \r\n to terminate the block) |
||||||
|
2. 8th (MSB) bit of the 1st gRPC frame byte |
||||||
|
* 0: data |
||||||
|
* 1: trailers |
||||||
|
3. Trailers must be the last message of the response, as enforced |
||||||
|
by the implementation |
||||||
|
4. Trailers-only responses: no change to the gRPC protocol spec. |
||||||
|
Trailers will be sent together with response headers, with no message |
||||||
|
in the body. |
||||||
|
|
||||||
|
--- |
||||||
|
|
||||||
|
User Agent |
||||||
|
|
||||||
|
* grpc-web-javascript/0.1 |
||||||
|
|
||||||
|
--- |
||||||
|
|
||||||
|
Text-encoded (response) streams |
||||||
|
|
||||||
|
1. The client library should indicate to the server via the "Accept" header that |
||||||
|
the response stream needs to be text encoded e.g. when XHR is used or due |
||||||
|
to security policies with XHR |
||||||
|
* Accept: application/grpc-web-text |
||||||
|
2. The default text encoding is base64 |
||||||
|
* Text encoding may be specified with Content-Type or Accept headers as |
||||||
|
* application/grpc-web-text-base64 |
||||||
|
* Note that “Content-Transfer-Encoding: base64” should not be used. |
||||||
|
Due to in-stream base64 padding when delimiting messages, the entire |
||||||
|
response body is not necessarily a valid base64-encoded entity |
||||||
|
* While the server runtime will always base64-encode and flush gRPC messages |
||||||
|
atomically the client library should not assume base64 padding always |
||||||
|
happens at the boundary of message frames. |
||||||
|
3. For binary trailers, when the content-type is set to |
||||||
|
application/grpc-web-text, the extra base64 encoding specified |
||||||
|
in [gRPC over HTTP2](http://www.grpc.io/docs/guides/wire.html) |
||||||
|
for binary custom metadata is skipped. |
||||||
|
|
||||||
|
# Other features |
||||||
|
|
||||||
|
Compression |
||||||
|
|
||||||
|
* Full-body compression is supported and expected for all unary |
||||||
|
requests/responses. The compression/decompression will be done |
||||||
|
by browsers, using standard Content-Encoding headers |
||||||
|
* “grpc-encoding” header is not used |
||||||
|
* SDCH, Brotli will be supported |
||||||
|
* Message-level compression for streamed requests/responses is not supported |
||||||
|
because manual compression/decompression is prohibitively expensive using JS |
||||||
|
* Per-message compression may be feasible in future with wasm |
||||||
|
|
||||||
|
--- |
||||||
|
|
||||||
|
Retries, caching |
||||||
|
|
||||||
|
* Will spec out the support after their respective gRPC spec extensions |
||||||
|
are finalized |
||||||
|
* Safe retries: PUT |
||||||
|
* Caching: header encoded request and/or a web specific spec |
||||||
|
|
||||||
|
--- |
||||||
|
|
||||||
|
Security |
||||||
|
|
||||||
|
* XSRF, XSS etc to be specified |
||||||
|
|
||||||
|
--- |
||||||
|
|
||||||
|
CORS preflight |
||||||
|
|
||||||
|
* The client library may support header overwrites to avoid preflight |
||||||
|
* https://github.com/whatwg/fetch/issues/210 |
||||||
|
* CSP support to be specified |
||||||
|
|
||||||
|
--- |
||||||
|
|
||||||
|
Keep-alive |
||||||
|
|
||||||
|
* HTTP/2 PING is not supported or used |
||||||
|
* Will not support send-beacon (GET) |
||||||
|
|
||||||
|
--- |
||||||
|
|
||||||
|
Bidi-streaming, with flow-control |
||||||
|
|
||||||
|
* Pending on [whatwg fetch/streams](https://github.com/whatwg/fetch) to be |
||||||
|
finalized and implemented in modern browsers |
||||||
|
* gRPC-Web client will support the native gRPC protocol with modern browsers |
||||||
@ -1,111 +0,0 @@ |
|||||||
/*
|
|
||||||
* |
|
||||||
* Copyright 2015, 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 GRPCXX_IMPL_CODEGEN_SYNC_NO_CXX11_H |
|
||||||
#define GRPCXX_IMPL_CODEGEN_SYNC_NO_CXX11_H |
|
||||||
|
|
||||||
#include <grpc++/impl/codegen/core_codegen_interface.h> |
|
||||||
|
|
||||||
namespace grpc { |
|
||||||
|
|
||||||
extern CoreCodegenInterface *g_core_codegen_interface; |
|
||||||
|
|
||||||
template <class mutex> |
|
||||||
class lock_guard; |
|
||||||
class condition_variable; |
|
||||||
|
|
||||||
class mutex { |
|
||||||
public: |
|
||||||
mutex() { g_core_codegen_interface->gpr_mu_init(&mu_); } |
|
||||||
~mutex() { g_core_codegen_interface->gpr_mu_destroy(&mu_); } |
|
||||||
|
|
||||||
private: |
|
||||||
::gpr_mu mu_; |
|
||||||
template <class mutex> |
|
||||||
friend class lock_guard; |
|
||||||
friend class condition_variable; |
|
||||||
}; |
|
||||||
|
|
||||||
template <class mutex> |
|
||||||
class lock_guard { |
|
||||||
public: |
|
||||||
lock_guard(mutex &mu) : mu_(mu), locked(true) { |
|
||||||
g_core_codegen_interface->gpr_mu_lock(&mu.mu_); |
|
||||||
} |
|
||||||
~lock_guard() { unlock_internal(); } |
|
||||||
|
|
||||||
protected: |
|
||||||
void lock_internal() { |
|
||||||
if (!locked) g_core_codegen_interface->gpr_mu_lock(&mu_.mu_); |
|
||||||
locked = true; |
|
||||||
} |
|
||||||
void unlock_internal() { |
|
||||||
if (locked) g_core_codegen_interface->gpr_mu_unlock(&mu_.mu_); |
|
||||||
locked = false; |
|
||||||
} |
|
||||||
|
|
||||||
private: |
|
||||||
mutex &mu_; |
|
||||||
bool locked; |
|
||||||
friend class condition_variable; |
|
||||||
}; |
|
||||||
|
|
||||||
template <class mutex> |
|
||||||
class unique_lock : public lock_guard<mutex> { |
|
||||||
public: |
|
||||||
unique_lock(mutex &mu) : lock_guard<mutex>(mu) {} |
|
||||||
void lock() { this->lock_internal(); } |
|
||||||
void unlock() { this->unlock_internal(); } |
|
||||||
}; |
|
||||||
|
|
||||||
class condition_variable { |
|
||||||
public: |
|
||||||
condition_variable() { g_core_codegen_interface->gpr_cv_init(&cv_); } |
|
||||||
~condition_variable() { g_core_codegen_interface->gpr_cv_destroy(&cv_); } |
|
||||||
void wait(lock_guard<mutex> &mu) { |
|
||||||
mu.locked = false; |
|
||||||
g_core_codegen_interface->gpr_cv_wait( |
|
||||||
&cv_, &mu.mu_.mu_, |
|
||||||
g_core_codegen_interface->gpr_inf_future(GPR_CLOCK_REALTIME)); |
|
||||||
mu.locked = true; |
|
||||||
} |
|
||||||
void notify_one() { g_core_codegen_interface->gpr_cv_signal(&cv_); } |
|
||||||
void notify_all() { g_core_codegen_interface->gpr_cv_broadcast(&cv_); } |
|
||||||
|
|
||||||
private: |
|
||||||
gpr_cv cv_; |
|
||||||
}; |
|
||||||
|
|
||||||
} // namespace grpc
|
|
||||||
|
|
||||||
#endif // GRPCXX_IMPL_CODEGEN_SYNC_NO_CXX11_H
|
|
||||||
@ -1,39 +0,0 @@ |
|||||||
/*
|
|
||||||
* |
|
||||||
* Copyright 2015, 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 GRPCXX_IMPL_SYNC_H |
|
||||||
#define GRPCXX_IMPL_SYNC_H |
|
||||||
|
|
||||||
#include <grpc++/impl/codegen/sync.h> |
|
||||||
|
|
||||||
#endif // GRPCXX_IMPL_SYNC_H
|
|
||||||
@ -1,117 +0,0 @@ |
|||||||
/*
|
|
||||||
* |
|
||||||
* Copyright 2015, 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 GRPCXX_IMPL_THD_NO_CXX11_H |
|
||||||
#define GRPCXX_IMPL_THD_NO_CXX11_H |
|
||||||
|
|
||||||
#include <grpc/support/thd.h> |
|
||||||
|
|
||||||
namespace grpc { |
|
||||||
|
|
||||||
class thread { |
|
||||||
public: |
|
||||||
template <class T> |
|
||||||
thread(void (T::*fptr)(), T *obj) { |
|
||||||
func_ = new thread_function<T>(fptr, obj); |
|
||||||
joined_ = false; |
|
||||||
start(); |
|
||||||
} |
|
||||||
template <class T, class U> |
|
||||||
thread(void (T::*fptr)(U arg), T *obj, U arg) { |
|
||||||
func_ = new thread_function_arg<T, U>(fptr, obj, arg); |
|
||||||
joined_ = false; |
|
||||||
start(); |
|
||||||
} |
|
||||||
~thread() { |
|
||||||
if (!joined_) std::terminate(); |
|
||||||
delete func_; |
|
||||||
} |
|
||||||
thread(thread &&other) |
|
||||||
: func_(other.func_), thd_(other.thd_), joined_(other.joined_) { |
|
||||||
other.joined_ = true; |
|
||||||
other.func_ = NULL; |
|
||||||
} |
|
||||||
void join() { |
|
||||||
gpr_thd_join(thd_); |
|
||||||
joined_ = true; |
|
||||||
} |
|
||||||
|
|
||||||
private: |
|
||||||
void start() { |
|
||||||
gpr_thd_options options = gpr_thd_options_default(); |
|
||||||
gpr_thd_options_set_joinable(&options); |
|
||||||
gpr_thd_new(&thd_, thread_func, (void *)func_, &options); |
|
||||||
} |
|
||||||
static void thread_func(void *arg) { |
|
||||||
thread_function_base *func = (thread_function_base *)arg; |
|
||||||
func->call(); |
|
||||||
} |
|
||||||
class thread_function_base { |
|
||||||
public: |
|
||||||
virtual ~thread_function_base() {} |
|
||||||
virtual void call() = 0; |
|
||||||
}; |
|
||||||
template <class T> |
|
||||||
class thread_function : public thread_function_base { |
|
||||||
public: |
|
||||||
thread_function(void (T::*fptr)(), T *obj) : fptr_(fptr), obj_(obj) {} |
|
||||||
virtual void call() { (obj_->*fptr_)(); } |
|
||||||
|
|
||||||
private: |
|
||||||
void (T::*fptr_)(); |
|
||||||
T *obj_; |
|
||||||
}; |
|
||||||
template <class T, class U> |
|
||||||
class thread_function_arg : public thread_function_base { |
|
||||||
public: |
|
||||||
thread_function_arg(void (T::*fptr)(U arg), T *obj, U arg) |
|
||||||
: fptr_(fptr), obj_(obj), arg_(arg) {} |
|
||||||
virtual void call() { (obj_->*fptr_)(arg_); } |
|
||||||
|
|
||||||
private: |
|
||||||
void (T::*fptr_)(U arg); |
|
||||||
T *obj_; |
|
||||||
U arg_; |
|
||||||
}; |
|
||||||
thread_function_base *func_; |
|
||||||
gpr_thd_id thd_; |
|
||||||
bool joined_; |
|
||||||
|
|
||||||
// Disallow copy and assign.
|
|
||||||
thread(const thread &); |
|
||||||
void operator=(const thread &); |
|
||||||
}; |
|
||||||
|
|
||||||
} // namespace grpc
|
|
||||||
|
|
||||||
#endif // GRPCXX_IMPL_THD_NO_CXX11_H
|
|
||||||
Some files were not shown because too many files have changed in this diff Show More
Loading…
Reference in new issue