Skip to content

Commit 32d347d

Browse files
author
Pepe Cano
authored
gRPC API small doc improvements (#152)
1 parent a1d0d61 commit 32d347d

File tree

6 files changed

+141
-23
lines changed

6 files changed

+141
-23
lines changed

‎src/data/markdown/docs/02 javascript api/09 k6-net-grpc.md‎

Lines changed: 33 additions & 21 deletions
Original file line numberDiff line numberDiff line change
@@ -13,30 +13,42 @@ The k6 gRPC API is currently considered in beta and is subject to change. Future
1313

1414
| Class/Method | Description |
1515
|--------------|-------------|
16-
| [Client](/javascript-api/k6-net-grpc/client) | gRPC client used for making RPC calls to a gRPC Server |
16+
| [Client](/javascript-api/k6-net-grpc/client) | gRPC client used for making RPC calls to a gRPC Server. |
1717
| [Client.load(importPaths, ...protoFiles)](/javascript-api/k6-net-grpc/client/client-load-importpaths----protofiles) | Loads and parses the given protocol buffer definitions to be made available for RPC requests. |
1818
| [Client.connect(address [,params])](/javascript-api/k6-net-grpc/client/client-connect-address-params) | Connects to a given gRPC service. |
1919
| [Client.invoke(url, request [,params])](/javascript-api/k6-net-grpc/client/client-invoke-url-request-params) | Makes an unary RPC for the given service/method and returns a [Response](/javascript-api/k6-net-grpc/response). |
20-
| [Client.close()]() | Close the connection to the gRPC service. |
20+
| [Client.close()](/javascript-api/k6-net-grpc/client/client-close) | Close the connection to the gRPC service. |
2121
| [Params](/javascript-api/k6-net-grpc/params) | RPC Request specific options. |
2222
| [Response](/javascript-api/k6-net-grpc/response) | Returned by RPC requests. |
23+
| [Constants](/javascript-api/k6-net-grpc/constants) | Define constants to distinguish between [gRPC Response](/javascript-api/k6-net-grpc/response) statuses. |
2324

24-
| Constant | Description |
25-
|----------|-------------|
26-
| `StatusOK` | OK is returned on success. |
27-
| `StatusCanceled` | Canceled indicates the operation was canceled (typically by the caller). |
28-
| `StatusUnknown` | Unknown error. |
29-
| `StatusInvalidArgument` | InvalidArgument indicates the client specified an invalid argument. |
30-
| `StatusDeadlineExceeded` | DeadlineExceeded means operation expired before completion. |
31-
| `StatusNotFound` | NotFound means some requested entity (e.g., file or directory) was not found. |
32-
| `StatusAlreadyExists` | AlreadyExists means an attempt to create an entity failed because one already exists. |
33-
| `StatusPermissionDenied` | PermissionDenied indicates the caller does not have permission to execute the specified operation. |
34-
| `StatusResourceExhausted` | ResourceExhausted indicates some resource has been exhausted, perhaps a per-user quota, or perhaps the entire file system is out of space. |
35-
| `StatusFailedPrecondition` | FailedPrecondition indicates operation was rejected because the system is not in a state required for the operation's execution. |
36-
| `StatusAborted` | Aborted indicates the operation was aborted, typically due to a concurrency issue like sequencer check failures, transaction aborts, etc. |
37-
| `StatusOutOfRange` | OutOfRange means operation was attempted past the valid range. E.g., seeking or reading past end of file. |
38-
| `StatusUnimplemented` | Unimplemented indicates operation is not implemented or not supported/enabled in this service. |
39-
| `StatusInternal` | Internal errors. Means some invariants expected by the underlying system have been broken. |
40-
| `StatusUnavailable` | Unavailable indicates the service is currently unavailable. This is a most likely a transient condition and may be corrected by retrying with a backoff. Note that it is not always safe to retry non-idempotent operations. |
41-
| `StatusDataLoss` | DataLoss indicates unrecoverable data loss or corruption. |
42-
| `StatusUnauthenticated` | Unauthenticated indicates the request does not have valid authentication credentials for the operation. |
25+
### Example
26+
27+
<CodeGroup labels={["grpc-test.js"]}>
28+
29+
```javascript
30+
import grpc from 'k6/net/grpc';
31+
32+
const client = new grpc.Client();
33+
client.load(['definitions'], 'hello.proto');
34+
35+
export default () => {
36+
client.connect('grpcb.in:9001', {
37+
// plaintext: false
38+
});
39+
40+
const data = { greeting: 'Bert' };
41+
const response = client.invoke('hello.HelloService/SayHello', data);
42+
43+
check(response, {
44+
'status is OK': (r) => r && r.status === grpc.StatusOK,
45+
});
46+
47+
console.log(JSON.stringify(response.message));
48+
49+
client.close();
50+
sleep(1);
51+
};
52+
```
53+
54+
</CodeGroup>

‎src/data/markdown/docs/02 javascript api/09 k6-net-grpc/10-Client.md‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -11,6 +11,7 @@ title: Client
1111
| [Client.load(importPaths, ...protoFiles)](/javascript-api/k6-net-grpc/client/client-load-importpaths----protofiles) | Loads and parses the given protocol buffer definitions to be made available for RPC requests. |
1212
| [Client.connect(address [,params])](/javascript-api/k6-net-grpc/client/client-connect-address-params) | Opens a connection to the given gRPC server. |
1313
| [Client.invoke(url, request [,params])](/javascript-api/k6-net-grpc/client/client-invoke-url-request-params) | Makes an unary RPC for the given service/method and returns a [Response](/javascript-api/k6-net-grpc/response). |
14+
| [Client.close()](/javascript-api/k6-net-grpc/client/client-close) | Close the connection to the gRPC service. |
1415

1516

1617
### Examples

‎src/data/markdown/docs/02 javascript api/09 k6-net-grpc/20 Client/20-Client-connect-connect-address-params.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -4,7 +4,7 @@ title: "Client.connect(address [,params])"
44

55
Opens a connection to a gRPC server; will block until a connection is made or a connection error is thrown. Cannot be called during the [`init` phase](/using-k6/test-life-cycle).
66

7-
See [Client.close()]() to close the connection.
7+
See [Client.close()](/javascript-api/k6-net-grpc/client/client-close) to close the connection.
88

99
| Parameter | Type | Description |
1010
|-----------|------|-------------|

‎src/data/markdown/docs/02 javascript api/09 k6-net-grpc/20 Client/40-Client-close.md‎

Lines changed: 22 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,22 @@
1+
---
2+
title: "Client.close()"
3+
---
4+
5+
Close the connection to the gRPC service. Tear down all underlying connections.
6+
7+
### Examples
8+
9+
<div class="code-group" data-props='{"labels": ["Simple example"], "lineNumbers": [true]}'>
10+
11+
```javascript
12+
import grpc from "k6/net/grpc";
13+
14+
const client = new grpc.Client();
15+
client.load(['definitions'], 'hello.proto');
16+
17+
export default () => {
18+
client.connect("localhost:8080");
19+
client.close();
20+
}
21+
```
22+
</div>

‎src/data/markdown/docs/02 javascript api/09 k6-net-grpc/30-Response.md‎

Lines changed: 30 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -4,8 +4,37 @@ title: "Response"
44

55
| Name | Type | Description |
66
|------|------|-------------|
7-
| `Response.status` | number | The response gRPC status code. Use the gRPC status constants to check equality. |
7+
| `Response.status` | number | The response gRPC status code. Use the gRPC [status constants](/javascript-api/k6-net-grpc/constants) to check equality. |
88
| `Response.message` | object | The successful protobuf message, serialized to JSON. Will be `null` if `status !== grpc.StatusOK`. |
99
| `Response.headers` | object | Key-value pairs representing all the metadata headers returned by the gRPC server. |
1010
| `Response.trailers` | object | Key-value pairs representing all the metadata trailers returned by the gRPC server. |
1111
| `Response.error` | object | If `status !== grpc.StatusOK` then the error protobuf message, serialized to JSON; otherwise `null`. |
12+
13+
### Example
14+
15+
<CodeGroup labels={["grpc-test.js"]}>
16+
17+
```javascript
18+
import grpc from 'k6/net/grpc';
19+
20+
const client = new grpc.Client();
21+
client.load(['definitions'], 'hello.proto');
22+
23+
export default () => {
24+
client.connect('grpcb.in:9001', {
25+
// plaintext: false
26+
});
27+
28+
const data = { greeting: 'Bert' };
29+
const response = client.invoke('hello.HelloService/SayHello', data);
30+
31+
check(response, {
32+
'status is OK': (r) => r && r.status === grpc.StatusOK,
33+
});
34+
35+
client.close();
36+
sleep(1);
37+
};
38+
```
39+
40+
</CodeGroup>

‎src/data/markdown/docs/02 javascript api/09 k6-net-grpc/40-Constants.md‎

Lines changed: 54 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,54 @@
1+
---
2+
title: "Constants"
3+
---
4+
5+
Define constants to distinguish between [gRPC Response](/javascript-api/k6-net-grpc/response) statuses.
6+
7+
| Constant | Description |
8+
|----------|-------------|
9+
| `StatusOK` | OK is returned on success. |
10+
| `StatusCanceled` | Canceled indicates the operation was canceled (typically by the caller). |
11+
| `StatusUnknown` | Unknown error. |
12+
| `StatusInvalidArgument` | InvalidArgument indicates the client specified an invalid argument. |
13+
| `StatusDeadlineExceeded` | DeadlineExceeded means operation expired before completion. |
14+
| `StatusNotFound` | NotFound means some requested entity (e.g., file or directory) was not found. |
15+
| `StatusAlreadyExists` | AlreadyExists means an attempt to create an entity failed because one already exists. |
16+
| `StatusPermissionDenied` | PermissionDenied indicates the caller does not have permission to execute the specified operation. |
17+
| `StatusResourceExhausted` | ResourceExhausted indicates some resource has been exhausted, perhaps a per-user quota, or perhaps the entire file system is out of space. |
18+
| `StatusFailedPrecondition` | FailedPrecondition indicates operation was rejected because the system is not in a state required for the operation's execution. |
19+
| `StatusAborted` | Aborted indicates the operation was aborted, typically due to a concurrency issue like sequencer check failures, transaction aborts, etc. |
20+
| `StatusOutOfRange` | OutOfRange means operation was attempted past the valid range. E.g., seeking or reading past end of file. |
21+
| `StatusUnimplemented` | Unimplemented indicates operation is not implemented or not supported/enabled in this service. |
22+
| `StatusInternal` | Internal errors. Means some invariants expected by the underlying system have been broken. |
23+
| `StatusUnavailable` | Unavailable indicates the service is currently unavailable. This is a most likely a transient condition and may be corrected by retrying with a backoff. Note that it is not always safe to retry non-idempotent operations. |
24+
| `StatusDataLoss` | DataLoss indicates unrecoverable data loss or corruption. |
25+
| `StatusUnauthenticated` | Unauthenticated indicates the request does not have valid authentication credentials for the operation. |
26+
27+
### Example
28+
29+
<CodeGroup labels={["grpc-test.js"]}>
30+
31+
```javascript
32+
import grpc from 'k6/net/grpc';
33+
34+
const client = new grpc.Client();
35+
client.load(['definitions'], 'hello.proto');
36+
37+
export default () => {
38+
client.connect('grpcb.in:9001', {
39+
// plaintext: false
40+
});
41+
42+
const data = { greeting: 'Bert' };
43+
const response = client.invoke('hello.HelloService/SayHello', data);
44+
45+
check(response, {
46+
'status is OK': (r) => r && r.status === grpc.StatusOK,
47+
});
48+
49+
client.close();
50+
sleep(1);
51+
};
52+
```
53+
54+
</CodeGroup>

0 commit comments

Comments
 (0)