diff options
Diffstat (limited to 'doc/interop-test-descriptions.md')
-rw-r--r-- | doc/interop-test-descriptions.md | 320 |
1 files changed, 188 insertions, 132 deletions
diff --git a/doc/interop-test-descriptions.md b/doc/interop-test-descriptions.md index 7fd21c7022..a4f9abecfa 100644 --- a/doc/interop-test-descriptions.md +++ b/doc/interop-test-descriptions.md @@ -68,14 +68,12 @@ control (even if compression is enabled on the channel). Server features: * [UnaryCall][] -* [Compressable Payload][] Procedure: 1. Client calls UnaryCall with: ``` { - response_type: COMPRESSABLE response_size: 314159 payload:{ body: 271828 bytes of zeros @@ -85,56 +83,106 @@ Procedure: Client asserts: * call was successful -* response payload type is COMPRESSABLE * 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 -### large_compressed_unary - -This test verifies compressed unary calls succeed in sending messages. It -sends one unary request for every payload type, with and without requesting a -compressed response from the server. - -In all scenarios, whether compression was actually performed is determined by -the compression bit in the response's message flags. +### client_compressed_unary +This test verifies the client can compress unary messages by sending two unary +calls, for compressed and uncompressed payloads. It also sends an initial +probing request to verify whether the server supports the [CompressedRequest][] +feature by checking if the probing call fails with an `INVALID_ARGUMENT` status. Server features: * [UnaryCall][] -* [Compressable Payload][] -* [Uncompressable Payload][] +* [CompressedRequest][] Procedure: - 1. Client calls UnaryCall with: + 1. Client calls UnaryCall with the feature probe, an *uncompressed* message: + ``` + { + expect_compressed:{ + value: true + } + response_size: 314159 + payload:{ + body: 271828 bytes of zeros + } + } + ``` + + 1. Client calls UnaryCall with the *compressed* message: + + ``` + { + expect_compressed:{ + value: true + } + response_size: 314159 + payload:{ + body: 271828 bytes of zeros + } + } + ``` + + 1. Client calls UnaryCall with the *uncompressed* message: ``` { - request_compressed_response: bool - response_type: COMPRESSABLE + expect_compressed:{ + value: false + } response_size: 314159 payload:{ body: 271828 bytes of zeros } } ``` + Client asserts: - * call was successful - * response payload type is COMPRESSABLE - * if `request_compressed_response` is false, the response MUST NOT have the - compressed message flag set. - * if `request_compressed_response` is true, the response MUST have the - compressed message flag set. - * 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 + * First call failed with `INVALID_ARGUMENT` status. + * Subsequent calls were successful. + * Response payload body is 314159 bytes in size. + * Clients are free to assert that the response payload body contents are + zeros and comparing the entire response message against a golden response. - 2. Client calls UnaryCall with: +### server_compressed_unary + +This test verifies the server can compress unary messages. It sends two unary +requests, expecting the server's response to be compressed or not according to +the `response_compressed` boolean. + +Whether compression was actually performed is determined by the compression bit +in the response's message flags. *Note that some languages may not have access +to the message flags*. + + +Server features: +* [UnaryCall][] +* [CompressedResponse][] + +Procedure: + 1. Client calls UnaryCall with `SimpleRequest`: + + ``` + { + response_compressed:{ + value: true + } + response_size: 314159 + payload:{ + body: 271828 bytes of zeros + } + } + ``` + ``` { - request_compressed_response: bool - response_type: UNCOMPRESSABLE + response_compressed:{ + value: false + } response_size: 314159 payload:{ body: 271828 bytes of zeros @@ -143,11 +191,13 @@ Procedure: ``` Client asserts: * call was successful - * response payload type is UNCOMPRESSABLE - * the response MAY have the compressed message flag set. Some - implementations will choose to compress the payload even when the output - size if larger than the input. - * response payload body is 314159 bytes in size + * when `response_compressed` is true, the response MUST have the + compressed message flag set. + * when `response_compressed` is false, the response MUST NOT have + the compressed message flag set. + * response payload body is 314159 bytes in size in both cases. + * clients are free to assert that the response payload body contents are + zero and comparing the entire response message against a golden response ### client_streaming @@ -156,7 +206,6 @@ This test verifies that client-only streaming succeeds. Server features: * [StreamingInputCall][] -* [Compressable Payload][] Procedure: 1. Client calls StreamingInputCall @@ -206,25 +255,81 @@ Client asserts: * call was successful * response aggregated_payload_size is 74922 + +### client_compressed_streaming + +This test verifies the client can compress requests on per-message basis by +performing a two-request streaming call. It also sends an initial probing +request to verify whether the server supports the [CompressedRequest][] feature +by checking if the probing call fails with an `INVALID_ARGUMENT` status. + +Procedure: + 1. Client calls `StreamingInputCall` and sends the following feature-probing + *uncompressed* `StreamingInputCallRequest` message + + ``` + { + expect_compressed:{ + value: true + } + payload:{ + body: 27182 bytes of zeros + } + } + ``` + If the call fails with `INVALID_ARGUMENT`, the test fails. Otherwise, we + continue. + + 1. Client calls `StreamingInputCall` again, sending the *compressed* message + + ``` + { + expect_compressed:{ + value: true + } + payload:{ + body: 27182 bytes of zeros + } + } + ``` + + 1. And finally, the *uncompressed* message + ``` + { + expect_compressed:{ + value: false + } + payload:{ + body: 45904 bytes of zeros + } + } + ``` + + 1. Client half-closes + +Client asserts: +* First call fails with `INVALID_ARGUMENT`. +* Next calls succeeds. +* Response aggregated payload size is 73086. + + ### server_streaming This test verifies that server-only streaming succeeds. Server features: * [StreamingOutputCall][] -* [Compressable Payload][] Procedure: - 1. Client calls StreamingOutputCall with: + 1. Client calls StreamingOutputCall with `StreamingOutputCallRequest`: ``` { - response_type:COMPRESSABLE response_parameters:{ size: 31415 } response_parameters:{ - size: 59 + size: 9 } response_parameters:{ size: 2653 @@ -238,103 +343,64 @@ Procedure: Client asserts: * call was successful * exactly four responses -* response payloads are COMPRESSABLE * response payload bodies are sized (in order): 31415, 9, 2653, 58979 * clients are free to assert that the response payload body contents are zero and comparing the entire response messages against golden responses ### server_compressed_streaming -This test verifies that server-only compressed streaming succeeds. +This test verifies that the server can compress streaming messages and disable +compression on individual messages. Server features: * [StreamingOutputCall][] -* [Compressable Payload][] -* [Uncompressable Payload][] +* [CompressedResponse][] Procedure: - 1. Client calls StreamingOutputCall with: + 1. Client calls StreamingOutputCall with `StreamingOutputCallRequest`: ``` { - request_compressed_response: bool - response_type:COMPRESSABLE response_parameters:{ + compressed: { + value: true + } size: 31415 } response_parameters:{ - size: 59 - } - response_parameters:{ - size: 2653 - } - response_parameters:{ - size: 58979 + compressed: { + value: false + } + size: 92653 } } ``` Client asserts: * call was successful - * exactly four responses - * response payloads are COMPRESSABLE - * if `request_compressed_response` is false, the response's messages MUST + * exactly two responses + * when `response_compressed` is false, the response's messages MUST NOT have the compressed message flag set. - * if `request_compressed_response` is true, the response's messages MUST + * when `response_compressed` is true, the response's messages MUST have the compressed message flag set. - * response payload bodies are sized (in order): 31415, 59, 2653, 58979 + * response payload bodies are sized (in order): 31415, 92653 * clients are free to assert that the response payload body contents are zero and comparing the entire response messages against golden responses - 2. Client calls StreamingOutputCall with: - - ``` - { - request_compressed_response: bool - response_type:UNCOMPRESSABLE - response_parameters:{ - size: 31415 - } - response_parameters:{ - size: 59 - } - response_parameters:{ - size: 2653 - } - response_parameters:{ - size: 58979 - } - } - ``` - - Client asserts: - * call was successful - * exactly four responses - * response payloads are UNCOMPRESSABLE - * the response MAY have the compressed message flag set. Some - implementations will choose to compress the payload even when the output - size if larger than the input. - * response payload bodies are sized (in order): 31415, 59, 2653, 58979 - * clients are free to assert that the body of the responses are identical to - the golden uncompressable data at `test/cpp/interop/rnd.dat`. - - ### ping_pong This test verifies that full duplex bidi is supported. Server features: * [FullDuplexCall][] -* [Compressable Payload][] Procedure: 1. Client calls FullDuplexCall with: ``` { - response_type: COMPRESSABLE response_parameters:{ size: 31415 } @@ -348,9 +414,8 @@ Procedure: ``` { - response_type: COMPRESSABLE response_parameters:{ - size: 59 + size: 9 } payload:{ body: 8 bytes of zeros @@ -362,7 +427,6 @@ Procedure: ``` { - response_type: COMPRESSABLE response_parameters:{ size: 2653 } @@ -376,7 +440,6 @@ Procedure: ``` { - response_type: COMPRESSABLE response_parameters:{ size: 58979 } @@ -391,7 +454,6 @@ Procedure: Client asserts: * call was successful * exactly four responses -* response payloads are COMPRESSABLE * response payload bodies are sized (in order): 31415, 9, 2653, 58979 * clients are free to assert that the response payload body contents are zero and comparing the entire response messages against golden responses @@ -421,12 +483,12 @@ with desired oauth scope. The test uses `--default_service_account` with GCE service account email and `--oauth_scope` with the OAuth scope to use. For testing against -grpc-test.sandbox.googleapis.com, "https://www.googleapis.com/auth/xapi.zoo" should +grpc-test.sandbox.googleapis.com, "https://www.googleapis.com/auth/xapi.zoo" +should be passed in as `--oauth_scope`. Server features: * [UnaryCall][] -* [Compressable Payload][] * [Echo Authenticated Username][] * [Echo OAuth Scope][] @@ -436,7 +498,6 @@ Procedure: ``` { - response_type: COMPRESSABLE response_size: 314159 payload:{ body: 271828 bytes of zeros @@ -448,7 +509,8 @@ Procedure: Client asserts: * call was successful -* received SimpleResponse.username equals the value of `--default_service_account` flag +* received SimpleResponse.username equals the value of + `--default_service_account` flag * received SimpleResponse.oauth_scope is in `--oauth_scope` * response payload body is 314159 bytes in size * clients are free to assert that the response payload body contents are zero @@ -469,7 +531,6 @@ variable GOOGLE_APPLICATION_CREDENTIALS. Server features: * [UnaryCall][] -* [Compressable Payload][] * [Echo Authenticated Username][] * [Echo OAuth Scope][] @@ -479,7 +540,6 @@ Procedure: ``` { - response_type: COMPRESSABLE response_size: 314159 payload:{ body: 271828 bytes of zeros @@ -492,7 +552,8 @@ Client asserts: * call was successful * received SimpleResponse.username is not empty and is in the json key file used by the auth library. The client can optionally check the username matches the -email address in the key file or equals the value of `--default_service_account` flag. +email address in the key file or equals the value of `--default_service_account` +flag. * 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 @@ -518,18 +579,18 @@ variable GOOGLE_APPLICATION_CREDENTIALS, *OR* if GCE credentials is used to fetch the token, `--default_service_account` can be used to pass in GCE service account email. - uses the flag `--oauth_scope` for the oauth scope. For testing against -grpc-test.sandbox.googleapis.com, "https://www.googleapis.com/auth/xapi.zoo" should -be passed as the `--oauth_scope`. +grpc-test.sandbox.googleapis.com, "https://www.googleapis.com/auth/xapi.zoo" +should be passed as the `--oauth_scope`. Server features: * [UnaryCall][] -* [Compressable Payload][] * [Echo Authenticated Username][] * [Echo OAuth Scope][] Procedure: 1. Client uses the auth library to obtain an authorization token - 2. Client configures the channel to use AccessTokenCredentials with the access token obtained in step 1 + 2. Client configures the channel to use AccessTokenCredentials with the access + token obtained in step 1 3. Client calls UnaryCall with the following message ``` @@ -550,22 +611,21 @@ json key file or GCE default service account email. Similar to the other auth tests, this test is only for cloud-to-prod path. -This test verifies unary calls succeed in sending messages using a JWT or a service account -credentials set on the RPC. +This test verifies unary calls succeed in sending messages using a JWT or a +service account credentials set on the RPC. The test - uses the flag `--service_account_key_file` with the path to a json key file downloaded from https://console.developers.google.com. Alternately, if using a usable auth implementation, it may specify the file location in the environment variable GOOGLE_APPLICATION_CREDENTIALS -- optionally uses the flag `--oauth_scope` for the oauth scope if implementator +- optionally uses the flag `--oauth_scope` for the oauth scope if implementator wishes to use service account credential instead of JWT credential. For testing -against grpc-test.sandbox.googleapis.com, oauth scope +against grpc-test.sandbox.googleapis.com, oauth scope "https://www.googleapis.com/auth/xapi.zoo" should be used. Server features: * [UnaryCall][] -* [Compressable Payload][] * [Echo Authenticated Username][] * [Echo OAuth Scope][] @@ -596,7 +656,6 @@ by the server. Server features: * [UnaryCall][] * [FullDuplexCall][] -* [Compressable Payload][] * [Echo Metadata][] Procedure: @@ -611,7 +670,6 @@ Procedure: ``` { - response_type: COMPRESSABLE response_size: 314159 payload:{ body: 271828 bytes of zeros @@ -630,7 +688,6 @@ Procedure: ``` { - response_type: COMPRESSABLE response_size: 314159 payload:{ body: 271828 bytes of zeros @@ -736,14 +793,12 @@ from the server. Server features: * [FullDuplexCall][] -* [Compressable Payload][] Procedure: 1. Client starts FullDuplexCall with ``` { - response_type: COMPRESSABLE response_parameters:{ size: 31415 } @@ -887,6 +942,21 @@ payload body of size `SimpleRequest.response_size` bytes and type as appropriate for the `SimpleRequest.response_type`. If the server does not support the `response_type`, then it should fail the RPC with `INVALID_ARGUMENT`. +### CompressedResponse +[CompressedResponse]: #compressedresponse + +When the client sets `response_compressed` to true, the server's response is +sent back compressed. Note that `response_compressed` is present on both +`SimpleRequest` (unary) and `StreamingOutputCallRequest` (streaming). + +### CompressedRequest +[CompressedRequest]: #compressedrequest + +When the client sets `expect_compressed` to true, the server expects the client +request to be compressed. If it's not, it fails the RPC with `INVALID_ARGUMENT`. +Note that `response_compressed` is present on both `SimpleRequest` (unary) and +`StreamingOutputCallRequest` (streaming). + ### StreamingInputCall [StreamingInputCall]: #streaminginputcall @@ -913,20 +983,6 @@ payload body of size ResponseParameters.size bytes, as specified by its respective ResponseParameters. After receiving half close and sending all responses, it closes with OK. -### Compressable Payload -[Compressable Payload]: #compressable-payload - -When the client requests COMPRESSABLE payload, the response includes a payload -of the size requested containing all zeros and the payload type is -COMPRESSABLE. - -### Uncompressable Payload -[Uncompressable Payload]: #uncompressable-payload - -When the client requests UNCOMPRESSABLE payload, the response includes a payload -of the size requested containing uncompressable data and the payload type is -UNCOMPRESSABLE. - ### Echo Status [Echo Status]: #echo-status When the client sends a response_status in the request payload, the server closes |