From 32d347de632397852b50383c8eef4f105b995d1d Mon Sep 17 00:00:00 2001 From: Pepe Cano Date: Fri, 13 Nov 2020 17:41:40 +0100 Subject: [PATCH] gRPC API small doc improvements (#152) --- .../docs/02 javascript api/09 k6-net-grpc.md | 54 +++++++++++-------- .../09 k6-net-grpc/10-Client.md | 1 + ...0-Client-connect-connect-address-params.md | 2 +- .../20 Client/40-Client-close.md | 22 ++++++++ .../09 k6-net-grpc/30-Response.md | 31 ++++++++++- .../09 k6-net-grpc/40-Constants.md | 54 +++++++++++++++++++ 6 files changed, 141 insertions(+), 23 deletions(-) create mode 100644 src/data/markdown/docs/02 javascript api/09 k6-net-grpc/20 Client/40-Client-close.md create mode 100644 src/data/markdown/docs/02 javascript api/09 k6-net-grpc/40-Constants.md diff --git a/src/data/markdown/docs/02 javascript api/09 k6-net-grpc.md b/src/data/markdown/docs/02 javascript api/09 k6-net-grpc.md index 24680e9e4e..87b2a08619 100644 --- a/src/data/markdown/docs/02 javascript api/09 k6-net-grpc.md +++ b/src/data/markdown/docs/02 javascript api/09 k6-net-grpc.md @@ -13,30 +13,42 @@ The k6 gRPC API is currently considered in beta and is subject to change. Future | Class/Method | Description | |--------------|-------------| -| [Client](/javascript-api/k6-net-grpc/client) | gRPC client used for making RPC calls to a gRPC Server | +| [Client](/javascript-api/k6-net-grpc/client) | gRPC client used for making RPC calls to a gRPC Server. | | [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. | | [Client.connect(address [,params])](/javascript-api/k6-net-grpc/client/client-connect-address-params) | Connects to a given gRPC service. | | [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). | -| [Client.close()]() | Close the connection to the gRPC service. | +| [Client.close()](/javascript-api/k6-net-grpc/client/client-close) | Close the connection to the gRPC service. | | [Params](/javascript-api/k6-net-grpc/params) | RPC Request specific options. | | [Response](/javascript-api/k6-net-grpc/response) | Returned by RPC requests. | +| [Constants](/javascript-api/k6-net-grpc/constants) | Define constants to distinguish between [gRPC Response](/javascript-api/k6-net-grpc/response) statuses. | -| Constant | Description | -|----------|-------------| -| `StatusOK` | OK is returned on success. | -| `StatusCanceled` | Canceled indicates the operation was canceled (typically by the caller). | -| `StatusUnknown` | Unknown error. | -| `StatusInvalidArgument` | InvalidArgument indicates the client specified an invalid argument. | -| `StatusDeadlineExceeded` | DeadlineExceeded means operation expired before completion. | -| `StatusNotFound` | NotFound means some requested entity (e.g., file or directory) was not found. | -| `StatusAlreadyExists` | AlreadyExists means an attempt to create an entity failed because one already exists. | -| `StatusPermissionDenied` | PermissionDenied indicates the caller does not have permission to execute the specified operation. | -| `StatusResourceExhausted` | ResourceExhausted indicates some resource has been exhausted, perhaps a per-user quota, or perhaps the entire file system is out of space. | -| `StatusFailedPrecondition` | FailedPrecondition indicates operation was rejected because the system is not in a state required for the operation's execution. | -| `StatusAborted` | Aborted indicates the operation was aborted, typically due to a concurrency issue like sequencer check failures, transaction aborts, etc. | -| `StatusOutOfRange` | OutOfRange means operation was attempted past the valid range. E.g., seeking or reading past end of file. | -| `StatusUnimplemented` | Unimplemented indicates operation is not implemented or not supported/enabled in this service. | -| `StatusInternal` | Internal errors. Means some invariants expected by the underlying system have been broken. | -| `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. | -| `StatusDataLoss` | DataLoss indicates unrecoverable data loss or corruption. | -| `StatusUnauthenticated` | Unauthenticated indicates the request does not have valid authentication credentials for the operation. | +### Example + + + +```javascript +import grpc from 'k6/net/grpc'; + +const client = new grpc.Client(); +client.load(['definitions'], 'hello.proto'); + +export default () => { + client.connect('grpcb.in:9001', { + // plaintext: false + }); + + const data = { greeting: 'Bert' }; + const response = client.invoke('hello.HelloService/SayHello', data); + + check(response, { + 'status is OK': (r) => r && r.status === grpc.StatusOK, + }); + + console.log(JSON.stringify(response.message)); + + client.close(); + sleep(1); +}; +``` + + diff --git a/src/data/markdown/docs/02 javascript api/09 k6-net-grpc/10-Client.md b/src/data/markdown/docs/02 javascript api/09 k6-net-grpc/10-Client.md index 18c5c89f74..7bffa9ec9d 100644 --- a/src/data/markdown/docs/02 javascript api/09 k6-net-grpc/10-Client.md +++ b/src/data/markdown/docs/02 javascript api/09 k6-net-grpc/10-Client.md @@ -11,6 +11,7 @@ title: Client | [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. | | [Client.connect(address [,params])](/javascript-api/k6-net-grpc/client/client-connect-address-params) | Opens a connection to the given gRPC server. | | [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). | +| [Client.close()](/javascript-api/k6-net-grpc/client/client-close) | Close the connection to the gRPC service. | ### Examples diff --git a/src/data/markdown/docs/02 javascript api/09 k6-net-grpc/20 Client/20-Client-connect-connect-address-params.md b/src/data/markdown/docs/02 javascript api/09 k6-net-grpc/20 Client/20-Client-connect-connect-address-params.md index 10372f9dba..a6938a1902 100644 --- a/src/data/markdown/docs/02 javascript api/09 k6-net-grpc/20 Client/20-Client-connect-connect-address-params.md +++ b/src/data/markdown/docs/02 javascript api/09 k6-net-grpc/20 Client/20-Client-connect-connect-address-params.md @@ -4,7 +4,7 @@ title: "Client.connect(address [,params])" 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). -See [Client.close()]() to close the connection. +See [Client.close()](/javascript-api/k6-net-grpc/client/client-close) to close the connection. | Parameter | Type | Description | |-----------|------|-------------| diff --git a/src/data/markdown/docs/02 javascript api/09 k6-net-grpc/20 Client/40-Client-close.md b/src/data/markdown/docs/02 javascript api/09 k6-net-grpc/20 Client/40-Client-close.md new file mode 100644 index 0000000000..30763884f7 --- /dev/null +++ b/src/data/markdown/docs/02 javascript api/09 k6-net-grpc/20 Client/40-Client-close.md @@ -0,0 +1,22 @@ +--- +title: "Client.close()" +--- + +Close the connection to the gRPC service. Tear down all underlying connections. + +### Examples + +
+ +```javascript +import grpc from "k6/net/grpc"; + +const client = new grpc.Client(); +client.load(['definitions'], 'hello.proto'); + +export default () => { + client.connect("localhost:8080"); + client.close(); +} +``` +
diff --git a/src/data/markdown/docs/02 javascript api/09 k6-net-grpc/30-Response.md b/src/data/markdown/docs/02 javascript api/09 k6-net-grpc/30-Response.md index 99b5dea88f..e4e9f7f303 100644 --- a/src/data/markdown/docs/02 javascript api/09 k6-net-grpc/30-Response.md +++ b/src/data/markdown/docs/02 javascript api/09 k6-net-grpc/30-Response.md @@ -4,8 +4,37 @@ title: "Response" | Name | Type | Description | |------|------|-------------| -| `Response.status` | number | The response gRPC status code. Use the gRPC status constants to check equality. | +| `Response.status` | number | The response gRPC status code. Use the gRPC [status constants](/javascript-api/k6-net-grpc/constants) to check equality. | | `Response.message` | object | The successful protobuf message, serialized to JSON. Will be `null` if `status !== grpc.StatusOK`. | | `Response.headers` | object | Key-value pairs representing all the metadata headers returned by the gRPC server. | | `Response.trailers` | object | Key-value pairs representing all the metadata trailers returned by the gRPC server. | | `Response.error` | object | If `status !== grpc.StatusOK` then the error protobuf message, serialized to JSON; otherwise `null`. | + +### Example + + + +```javascript +import grpc from 'k6/net/grpc'; + +const client = new grpc.Client(); +client.load(['definitions'], 'hello.proto'); + +export default () => { + client.connect('grpcb.in:9001', { + // plaintext: false + }); + + const data = { greeting: 'Bert' }; + const response = client.invoke('hello.HelloService/SayHello', data); + + check(response, { + 'status is OK': (r) => r && r.status === grpc.StatusOK, + }); + + client.close(); + sleep(1); +}; +``` + + diff --git a/src/data/markdown/docs/02 javascript api/09 k6-net-grpc/40-Constants.md b/src/data/markdown/docs/02 javascript api/09 k6-net-grpc/40-Constants.md new file mode 100644 index 0000000000..8a3b3189d9 --- /dev/null +++ b/src/data/markdown/docs/02 javascript api/09 k6-net-grpc/40-Constants.md @@ -0,0 +1,54 @@ +--- +title: "Constants" +--- + +Define constants to distinguish between [gRPC Response](/javascript-api/k6-net-grpc/response) statuses. + +| Constant | Description | +|----------|-------------| +| `StatusOK` | OK is returned on success. | +| `StatusCanceled` | Canceled indicates the operation was canceled (typically by the caller). | +| `StatusUnknown` | Unknown error. | +| `StatusInvalidArgument` | InvalidArgument indicates the client specified an invalid argument. | +| `StatusDeadlineExceeded` | DeadlineExceeded means operation expired before completion. | +| `StatusNotFound` | NotFound means some requested entity (e.g., file or directory) was not found. | +| `StatusAlreadyExists` | AlreadyExists means an attempt to create an entity failed because one already exists. | +| `StatusPermissionDenied` | PermissionDenied indicates the caller does not have permission to execute the specified operation. | +| `StatusResourceExhausted` | ResourceExhausted indicates some resource has been exhausted, perhaps a per-user quota, or perhaps the entire file system is out of space. | +| `StatusFailedPrecondition` | FailedPrecondition indicates operation was rejected because the system is not in a state required for the operation's execution. | +| `StatusAborted` | Aborted indicates the operation was aborted, typically due to a concurrency issue like sequencer check failures, transaction aborts, etc. | +| `StatusOutOfRange` | OutOfRange means operation was attempted past the valid range. E.g., seeking or reading past end of file. | +| `StatusUnimplemented` | Unimplemented indicates operation is not implemented or not supported/enabled in this service. | +| `StatusInternal` | Internal errors. Means some invariants expected by the underlying system have been broken. | +| `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. | +| `StatusDataLoss` | DataLoss indicates unrecoverable data loss or corruption. | +| `StatusUnauthenticated` | Unauthenticated indicates the request does not have valid authentication credentials for the operation. | + +### Example + + + +```javascript +import grpc from 'k6/net/grpc'; + +const client = new grpc.Client(); +client.load(['definitions'], 'hello.proto'); + +export default () => { + client.connect('grpcb.in:9001', { + // plaintext: false + }); + + const data = { greeting: 'Bert' }; + const response = client.invoke('hello.HelloService/SayHello', data); + + check(response, { + 'status is OK': (r) => r && r.status === grpc.StatusOK, + }); + + client.close(); + sleep(1); +}; +``` + + \ No newline at end of file