1Negative HTTP/2 Interop Test Case Descriptions
2=======================================
3
4Client and server use
5[test.proto](../src/proto/grpc/testing/test.proto).
6
7Server
8------
9The code for the custom http2 server can be found
10[here](https://github.com/grpc/grpc/tree/master/test/http2_test).
11It is responsible for handling requests and sending responses, and also for
12fulfilling the behavior of each particular test case.
13
14Server should accept these arguments:
15* --port=PORT
16  * The port the server will run on. For example, "8080"
17* --test_case=TESTCASE
18  * The name of the test case to execute. For example, "goaway"
19
20Client
21------
22
23Clients implement test cases that test certain functionality. Each client is
24provided the test case it is expected to run as a command-line parameter. Names
25should be lowercase and without spaces.
26
27Clients should accept these arguments:
28* --server_host=HOSTNAME
29    * The server host to connect to. For example, "localhost" or "127.0.0.1"
30* --server_port=PORT
31    * The server port to connect to. For example, "8080"
32* --test_case=TESTCASE
33    * The name of the test case to execute. For example, "goaway"
34
35Note
36-----
37
38Note that the server and client must be invoked with the same test case or else
39the test will be meaningless. For convenience, we provide a shell script wrapper
40that invokes both server and client at the same time, with the same test_case.
41This is the preferred way to run these tests.
42
43## Test Cases
44
45### goaway
46
47This test verifies that the client correctly responds to a goaway sent by the
48server. The client should handle the goaway by switching to a new stream without
49the user application having to do a thing.
50
51Client Procedure:
52 1. Client sends two UnaryCall requests (and sleeps for 1 second in-between).
53 TODO: resolve [9300](https://github.com/grpc/grpc/issues/9300) and remove the 1 second sleep
54
55    ```
56    {
57      response_size: 314159
58      payload:{
59        body: 271828 bytes of zeros
60      }
61    }
62    ```
63
64Client asserts:
65* Both calls are successful.
66* Response payload body is 314159 bytes in size.
67
68Server Procedure:
69  1. Server sends a GOAWAY after receiving the first UnaryCall.
70
71Server asserts:
72* Two different connections were used from the client.
73
74### rst_after_header
75
76This test verifies that the client fails correctly when the server sends a
77RST_STREAM immediately after sending headers to the client.
78
79Procedure:
80 1. Client sends UnaryCall with:
81
82    ```
83    {
84      response_size: 314159
85      payload:{
86        body: 271828 bytes of zeros
87      }
88    }
89    ```
90
91Client asserts:
92* Call was not successful.
93
94Server Procedure:
95  1. Server sends a RST_STREAM with error code 0 after sending headers to the client.
96
97*At the moment the error code and message returned are not standardized throughout all
98languages. Those checks will be added once all client languages behave the same way. [#9142](https://github.com/grpc/grpc/issues/9142) is in flight.*
99
100### rst_during_data
101
102This test verifies that the client fails "correctly" when the server sends a
103RST_STREAM halfway through sending data to the client.
104
105Procedure:
106 1. Client sends UnaryCall with:
107
108    ```
109    {
110      response_size: 314159
111      payload:{
112        body: 271828 bytes of zeros
113      }
114    }
115    ```
116
117Client asserts:
118* Call was not successful.
119
120Server Procedure:
121  1. Server sends a RST_STREAM with error code 0 after sending half of
122     the requested data to the client.
123
124### rst_after_data
125
126This test verifies that the client fails "correctly" when the server sends a
127RST_STREAM after sending all of the data to the client.
128
129Procedure:
130 1. Client sends UnaryCall with:
131
132    ```
133    {
134      response_size: 314159
135      payload:{
136        body: 271828 bytes of zeros
137      }
138    }
139    ```
140
141Client asserts:
142* Call was not successful.
143
144Server Procedure:
145  1. Server sends a RST_STREAM with error code 0 after sending all of the
146  data to the client.
147
148*Certain client languages allow the data to be accessed even though a RST_STREAM
149was encountered. Once all client languages behave this way, checks will be added on
150the incoming data.*
151
152### ping
153
154This test verifies that the client correctly acknowledges all pings it gets from the
155server.
156
157Procedure:
158 1. Client sends UnaryCall with:
159
160    ```
161    {
162      response_size: 314159
163      payload:{
164        body: 271828 bytes of zeros
165      }
166    }
167    ```
168
169Client asserts:
170* call was successful.
171* response payload body is 314159 bytes in size.
172
173Server Procedure:
174  1. Server tracks the number of outstanding pings (i.e. +1 when it sends a ping, and -1
175  when it receives an ack from the client).
176  2. Server sends pings before and after sending headers, also before and after sending data.
177
178Server Asserts:
179* Number of outstanding pings is 0 when the connection is lost.
180
181### max_streams
182
183This test verifies that the client observes the MAX_CONCURRENT_STREAMS limit set by the server.
184
185Client Procedure:
186  1. Client sends initial UnaryCall to allow the server to update its MAX_CONCURRENT_STREAMS settings.
187  2. Client concurrently sends 10 UnaryCalls.
188
189Client Asserts:
190* All UnaryCalls were successful, and had the correct type and payload size.
191
192Server Procedure:
193  1. Sets MAX_CONCURRENT_STREAMS to one after the connection is made.
194
195*The assertion that the MAX_CONCURRENT_STREAMS limit is upheld occurs in the http2 library we used.*
196
197### data_frame_padding
198
199This test verifies that the client can correctly receive padded http2 data
200frames. It also stresses the client's flow control (there is a high chance
201that the sender will deadlock if the client's flow control logic doesn't
202correctly account for padding).
203
204Client Procedure:
205(Note this is the same procedure as in the "large_unary" gRPC interop tests.
206Clients should use their "large_unary" gRPC interop test implementations.)
207Procedure:
208 1. Client calls UnaryCall with:
209
210    ```
211    {
212      response_size: 314159
213      payload:{
214        body: 271828 bytes of zeros
215      }
216    }
217    ```
218
219Client asserts:
220* call was successful
221* response payload body is 314159 bytes in size
222* clients are free to assert that the response payload body contents are zero
223  and comparing the entire response message against a golden response
224
225Server Procedure:
226  1. Reply to the client's request with a `SimpleResponse`, with a payload
227  body length of `SimpleRequest.response_size`. But send it across specific
228  http2 data frames as follows:
229    * Each http2 data frame contains a 5 byte payload and 255 bytes of padding.
230
231  * Note the 5 byte payload and 255 byte padding are partly arbitrary,
232  and other numbers are also ok. With 255 bytes of padding for each 5 bytes of
233  payload containing actual gRPC message, the 300KB response size will
234  multiply into around 15 megabytes of flow control debt, which should stress
235  flow control accounting.
236
237### no_df_padding_sanity_test
238
239This test verifies that the client can correctly receive a series of small
240data frames. Note that this test is intentionally a slight variation of
241"data_frame_padding", with the only difference being that this test doesn't use data
242frame padding when the response is sent. This test is primarily meant to
243prove correctness of the http2 server implementation and highlight failures
244of the "data_frame_padding" test.
245
246Client Procedure:
247(Note this is the same procedure as in the "large_unary" gRPC interop tests.
248Clients should use their "large_unary" gRPC interop test implementations.)
249Procedure:
250 1. Client calls UnaryCall with:
251
252    ```
253    {
254      response_size: 314159
255      payload:{
256        body: 271828 bytes of zeros
257      }
258    }
259    ```
260
261Client asserts:
262* call was successful
263* response payload body is 314159 bytes in size
264* clients are free to assert that the response payload body contents are zero
265  and comparing the entire response message against a golden response
266
267Server Procedure:
268  1. Reply to the client's request with a `SimpleResponse`, with a payload
269  body length of `SimpleRequest.response_size`. But send it across series of
270  http2 data frames that contain 5 bytes of "payload" and zero bytes of
271  "padding" (the padding flags on the data frames should not be set).
272