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