Merge remote-tracking branch 'upstream/master' into service_config_lb_semantics

7 files changed, 122 insertions, 25 deletions

diff --git a/doc/PROTOCOL-HTTP2.md b/doc/PROTOCOL-HTTP2.md
index 2df1c74bee..68af1f2ca1 100644
--- a/doc/PROTOCOL-HTTP2.md
+++ b/doc/PROTOCOL-HTTP2.md
@@ -91,7 +91,7 @@ A **Compressed-Flag** value of 1 indicates that the binary octet sequence of **M
 
 For requests, **EOS** (end-of-stream) is indicated by the presence of the END_STREAM flag on the last received DATA frame. In scenarios where the **Request** stream needs to be closed but no data remains to be sent implementations MUST send an empty DATA frame with this flag set.
 
-###Responses
+### Responses
 
 * **Response** → (Response-Headers \*Length-Prefixed-Message Trailers) / Trailers-Only
 * **Response-Headers** → HTTP-Status [Message-Encoding] [Message-Accept-Encoding] Content-Type \*Custom-Metadata
@@ -128,7 +128,7 @@ implementation can decode valid portions while leaving broken %-encodings as-is
 or replacing them with a replacement character (e.g., '?' or the Unicode
 replacement character).
 
-####Example
+#### Example
 
 Sample unary-call showing HTTP2 framing sequence
 
@@ -162,7 +162,7 @@ HEADERS (flags = END_STREAM, END_HEADERS)
 grpc-status = 0 # OK
 trace-proto-bin = jher831yy13JHy3hc
 ```
-####User Agents
+#### User Agents
 
 While the protocol does not require a user-agent to function it is recommended that clients provide a structured user-agent string that provides a basic description of the calling library, version & platform to facilitate issue diagnosis in heterogeneous environments. The following structure is recommended to library developers
 ```
@@ -177,7 +177,7 @@ grpc-ruby-jruby/1.3.4
 grpc-java-android/0.9.1 (gingerbread/1.2.4; nexus5; tmobile)
 ```
 
-####Idempotency and Retries
+#### Idempotency and Retries
 
 Unless explicitly defined to be, gRPC Calls are not assumed to be idempotent.  Specifically:
 
@@ -186,15 +186,15 @@ Unless explicitly defined to be, gRPC Calls are not assumed to be idempotent.  S
 * Calls that are marked as idempotent may be sent multiple times.
 
 
-####HTTP2 Transport Mapping
+#### HTTP2 Transport Mapping
 
-#####Stream Identification
+##### Stream Identification
 All GRPC calls need to specify an internal ID. We will use HTTP2 stream-ids as call identifiers in this scheme. NOTE: These id’s are contextual to an open HTTP2 session and will not be unique within a given process that is handling more than one HTTP2 session nor can they be used as GUIDs.
 
-#####Data Frames
+##### Data Frames
 DATA frame boundaries have no relation to **Length-Prefixed-Message** boundaries and implementations should make no assumptions about their alignment.
 
-#####Errors
+##### Errors
 
 When an application or runtime error occurs during an RPC a **Status** and **Status-Message** are delivered in **Trailers**.
 
@@ -219,20 +219,20 @@ ENHANCE_YOUR_CALM|RESOURCE_EXHAUSTED ...with additional error detail provided by
 INADEQUATE_SECURITY| PERMISSION_DENIED … with additional detail indicating that permission was denied as protocol is not secure enough for call.
 
 
-#####Security
+##### Security
 
 The HTTP2 specification mandates the use of TLS 1.2 or higher when TLS is used with HTTP2. It also places some additional constraints on the allowed ciphers in deployments to avoid known-problems as well as requiring SNI support. It is also expected that HTTP2 will be used in conjunction with proprietary transport security mechanisms about which the specification can make no meaningful recommendations.
 
-#####Connection Management
-######GOAWAY Frame
+##### Connection Management
+###### GOAWAY Frame
 Sent by servers to clients to indicate that they will no longer accept any new streams on the associated connections. This frame includes the id of the last successfully accepted stream by the server. Clients should consider any stream initiated after the last successfully accepted stream as UNAVAILABLE and retry the call elsewhere. Clients are free to continue working with the already accepted streams until they complete or the connection is terminated.
 
 Servers should send GOAWAY before terminating a connection to reliably inform clients which work has been accepted by the server and is being executed.
 
-######PING Frame
+###### PING Frame
 Both clients and servers can send a PING frame that the peer must respond to by precisely echoing what they received. This is used to assert that the connection is still live as well as providing a means to estimate end-to-end latency. If a server initiated PING does not receive a response within the deadline expected by the runtime all outstanding calls on the server will be closed with a CANCELLED status. An expired client initiated PING will cause all calls to be closed with an UNAVAILABLE status. Note that the frequency of PINGs is highly dependent on the network environment, implementations are free to adjust PING frequency based on network and application requirements.
 
-######Connection failure
+###### Connection failure
 If a detectable connection failure occurs on the client all calls will be closed with an UNAVAILABLE status. For servers open calls will be closed with a CANCELLED status.
 
 
diff --git a/doc/PROTOCOL-WEB.md b/doc/PROTOCOL-WEB.md
index 5f01af3627..6bb280894a 100644
--- a/doc/PROTOCOL-WEB.md
+++ b/doc/PROTOCOL-WEB.md
@@ -83,7 +83,8 @@ in the body.
 
 User Agent
 
-* U-A: grpc-web-javascript
+* Do NOT use User-Agent header (which is to be set by browsers, by default)
+* Use X-User-Agent: grpc-web-javascript/0.1 (follow the same format as specified in [gRPC over HTTP2](http://www.grpc.io/docs/guides/wire.html))
 
 ---
 
diff --git a/doc/core/grpc-error.md b/doc/core/grpc-error.md
index 1fa2480231..c05d1dd909 100644
--- a/doc/core/grpc-error.md
+++ b/doc/core/grpc-error.md
@@ -56,7 +56,7 @@ For example, in the following code block, error1 and error2 are owned by the
 current function.
 
 ```C
-grpc_error* error1 = GRPC_ERROR_CREATE("Some error occured");
+grpc_error* error1 = GRPC_ERROR_CREATE_FROM_STATIC_STRING("Some error occured");
 grpc_error* error2 = some_operation_that_might_fail(...);
 ```
 
@@ -87,7 +87,7 @@ callbacks with `grpc_closure_run` and `grpc_closure_sched`. These functions are
 not callbacks, so they will take ownership of the error passed to them.
 
 ```C
-grpc_error* error = GRPC_ERROR_CREATE("Some error occured");
+grpc_error* error = GRPC_ERROR_CREATE_FROM_STATIC_STRING("Some error occured");
 grpc_closure_run(exec_ctx, cb, error);
 // current function no longer has ownership of the error
 ```
@@ -96,7 +96,7 @@ If you schedule or run a closure, but still need ownership of the error, then
 you must explicitly take a reference.
 
 ```C
-grpc_error* error = GRPC_ERROR_CREATE("Some error occured");
+grpc_error* error = GRPC_ERROR_CREATE_FROM_STATIC_STRING("Some error occured");
 grpc_closure_run(exec_ctx, cb, GRPC_ERROR_REF(error));
 // do some other things with the error
 GRPC_ERROR_UNREF(error);
@@ -128,7 +128,7 @@ void on_some_action(grpc_exec_ctx *exec_ctx, void *arg, grpc_error *error) {
 Take the following example:
 
 ```C
-grpc_error* error = GRPC_ERROR_CREATE("Some error occured");
+grpc_error* error = GRPC_ERROR_CREATE_FROM_STATIC_STRING("Some error occured");
 // do some things
 some_function(error);
 // can't use error anymore! might be gone.
@@ -142,7 +142,7 @@ if would have to take on a reference to it. This is a common pattern seen.
 
 ```C
 void func() {
-  grpc_error* error = GRPC_ERROR_CREATE("Some error occured");
+  grpc_error* error = GRPC_ERROR_CREATE_FROM_STATIC_STRING("Some error");
   some_function(GRPC_ERROR_REF(error));
   // do things
   some_other_function(GRPC_ERROR_REF(error));
diff --git a/doc/environment_variables.md b/doc/environment_variables.md
index a380673233..47efb3a1d8 100644
--- a/doc/environment_variables.md
+++ b/doc/environment_variables.md
@@ -55,6 +55,7 @@ some configuration as environment variables that can be set.
   - queue_timeout
   - server_channel - lightweight trace of significant server channel events
   - secure_endpoint - traces bytes flowing through encrypted channels
+  - timer - timers (alarms) in the grpc internals
   - transport_security - traces metadata about secure channel establishment
   - tcp - traces bytes in and out of a channel
 
@@ -69,3 +70,11 @@ some configuration as environment variables that can be set.
   - DEBUG - log all gRPC messages
   - INFO - log INFO and ERROR message
   - ERROR - log only errors
+
+* GRPC_DNS_RESOLVER
+  Declares which DNS resolver to use. The default is ares if gRPC is built with
+  c-ares support. Otherwise, the value of this environment variable is ignored.
+  Available DNS resolver include:
+  - native (default)- a DNS resolver based around getaddrinfo(), creates a new thread to
+    perform name resolution
+  - ares - a DNS resolver based around the c-ares library
diff --git a/doc/negative-http2-interop-test-descriptions.md b/doc/http2-interop-test-descriptions.md
index b64fe6a024..435a8de709 100644
--- a/doc/negative-http2-interop-test-descriptions.md
+++ b/doc/http2-interop-test-descriptions.md
@@ -193,3 +193,79 @@ Server Procedure:
   1. Sets MAX_CONCURRENT_STREAMS to one after the connection is made.
 
 *The assertion that the MAX_CONCURRENT_STREAMS limit is upheld occurs in the http2 library we used.*
+
+### data_frame_padding
+
+This test verifies that the client can correctly receive padded http2 data
+frames. It also stresses the client's flow control (there is a high chance
+that the sender will deadlock if the client's flow control logic doesn't
+correctly account for padding).
+
+Client Procedure:
+(Note this is the same procedure as in the "large_unary" gRPC interop tests.
+Clients should use their "large_unary" gRPC interop test implementations.)
+Procedure:
+ 1. Client calls UnaryCall with:
+
+    ```
+    {
+      response_size: 314159
+      payload:{
+        body: 271828 bytes of zeros
+      }
+    }
+    ```
+
+Client asserts:
+* call was successful
+* response payload body is 314159 bytes in size
+* clients are free to assert that the response payload body contents are zero
+  and comparing the entire response message against a golden response
+
+Server Procedure:
+  1. Reply to the client's request with a `SimpleResponse`, with a payload
+  body length of `SimpleRequest.response_size`. But send it across specific
+  http2 data frames as follows:
+    * Each http2 data frame contains a 5 byte payload and 255 bytes of padding.
+
+  * Note the 5 byte payload and 255 byte padding are partly arbitrary,
+  and other numbers are also ok. With 255 bytes of padding for each 5 bytes of
+  payload containing actual gRPC message, the 300KB response size will
+  multiply into around 15 megabytes of flow control debt, which should stress
+  flow control accounting.
+
+### no_df_padding_sanity_test
+
+This test verifies that the client can correctly receive a series of small
+data frames. Note that this test is intentionally a slight variation of
+"data_frame_padding", with the only difference being that this test doesn't use data
+frame padding when the response is sent. This test is primarily meant to
+prove correctness of the http2 server implementation and highlight failures
+of the "data_frame_padding" test.
+
+Client Procedure:
+(Note this is the same procedure as in the "large_unary" gRPC interop tests.
+Clients should use their "large_unary" gRPC interop test implementations.)
+Procedure:
+ 1. Client calls UnaryCall with:
+
+    ```
+    {
+      response_size: 314159
+      payload:{
+        body: 271828 bytes of zeros
+      }
+    }
+    ```
+
+Client asserts:
+* call was successful
+* response payload body is 314159 bytes in size
+* clients are free to assert that the response payload body contents are zero
+  and comparing the entire response message against a golden response
+
+Server Procedure:
+  1. Reply to the client's request with a `SimpleResponse`, with a payload
+  body length of `SimpleRequest.response_size`. But send it across series of
+  http2 data frames that contain 5 bytes of "payload" and zero bytes of
+  "padding" (the padding flags on the data frames should not be set).
diff --git a/doc/interop-test-descriptions.md b/doc/interop-test-descriptions.md
index da3b976744..66a034d630 100644
--- a/doc/interop-test-descriptions.md
+++ b/doc/interop-test-descriptions.md
@@ -27,7 +27,7 @@ Clients should accept these arguments:
     * Whether to use a plaintext or encrypted connection
 * --use_test_ca=BOOLEAN
     * Whether to replace platform root CAs with
-      [ca.pem](https://github.com/grpc/grpc/blob/master/src/core/lib/tsi/test_creds/ca.pem)
+      [ca.pem](https://github.com/grpc/grpc/blob/master/src/core/tsi/test_creds/ca.pem)
       as the CA root
 * --default_service_account=ACCOUNT_EMAIL
     * Email of the GCE default service account.
@@ -969,7 +969,7 @@ Servers should accept these arguments:
     * Whether to use a plaintext or encrypted connection
 
 Servers must support TLS with ALPN. They should use
-[server1.pem](https://github.com/grpc/grpc/blob/master/src/core/lib/tsi/test_creds/server1.pem)
+[server1.pem](https://github.com/grpc/grpc/blob/master/src/core/tsi/test_creds/server1.pem)
 for their certificate.
 
 ### EmptyCall
diff --git a/doc/statuscodes.md b/doc/statuscodes.md
index 1cd72df30a..f2df9e00de 100644
--- a/doc/statuscodes.md
+++ b/doc/statuscodes.md
@@ -1,9 +1,20 @@
 # Status codes and their use in gRPC
 
-gRPC uses a set of well defined status codes as part of the RPC API. All RPCs started at a client return  a `status` object composed of an integer `code` and a string `message`. The server-side can choose the status it returns for a given RPC.
+gRPC uses a set of well defined status codes as part of the RPC API. All
+RPCs started at a client return  a `status` object composed of an integer
+`code` and a string `message`. The server-side can choose the status it
+returns for a given RPC.
 
-The gRPC client and server-side implementations may also generate and return `status` on their own when errors happen.  
-Only a subset of the pre-defined status codes are generated by the gRPC libraries. The following table lists these codes and summarizes the situations in which they are generated, either by the client or the server-side library implementation.
+The gRPC client and server-side implementations may also generate and
+return `status` on their own when errors happen.  Only a subset of
+the pre-defined status codes are generated by the gRPC libraries.  This
+allows applications to be sure that any other code it sees was actually
+returned by the application (although it is also possible for the
+server-side to return one of the codes generated by the gRPC libraries).
+
+The following table lists the codes that may be returned by the gRPC
+libraries (on either the client-side or server-side) and summarizes the
+situations in which they are generated.
 
 | Case        | Code           | Generated at Client or Server  |
 | ------------- |:-------------| :-----:|
@@ -26,7 +37,7 @@ Only a subset of the pre-defined status codes are generated by the gRPC librarie
 | Response cardinality violation (method requires exactly one response but server sent some other number of responses) | UNIMPLEMENTED | Client|
 | Error parsing response proto	| INTERNAL | Client|
 | Error parsing request proto	| INTERNAL | Server|
-
+| Sent or received message was larger than configured limit | RESOURCE_EXHAUSTED | Both |
 
 The following status codes are never generated by the library:
 - INVALID_ARGUMENT