From e751e1c62f1484044ec8df6084fee6d51dfae87a Mon Sep 17 00:00:00 2001 From: Oleg Bespalov Date: Mon, 23 Sep 2024 12:58:48 +0200 Subject: [PATCH] Document gRPC message metadata --- .../k6-net-grpc/stream/_index.md | 2 + .../k6-net-grpc/stream/event-handler.md | 49 +++++++++++++++++++ .../k6-net-grpc/stream/message-metadata.md | 48 ++++++++++++++++++ .../k6-net-grpc/stream/stream-on.md | 8 +-- .../next/shared/javascript-api/k6-net-grpc.md | 2 + 5 files changed, 105 insertions(+), 4 deletions(-) create mode 100644 docs/sources/next/javascript-api/k6-net-grpc/stream/event-handler.md create mode 100644 docs/sources/next/javascript-api/k6-net-grpc/stream/message-metadata.md diff --git a/docs/sources/next/javascript-api/k6-net-grpc/stream/_index.md b/docs/sources/next/javascript-api/k6-net-grpc/stream/_index.md index b66f4b43ed..dc692f71cf 100644 --- a/docs/sources/next/javascript-api/k6-net-grpc/stream/_index.md +++ b/docs/sources/next/javascript-api/k6-net-grpc/stream/_index.md @@ -16,6 +16,8 @@ Using a gRPC client creates a stream. The client should be connected to the serv | [Stream.write(message)](https://grafana.com/docs/k6//javascript-api/k6-net-grpc/stream/stream-write) | Writes a message to the stream. | | [Stream.on(event, handler)](https://grafana.com/docs/k6//javascript-api/k6-net-grpc/stream/stream-on) | Sets up handler functions for various events on the gRPC stream. | | [Stream.end()](https://grafana.com/docs/k6//javascript-api/k6-net-grpc/stream/stream-end) | Signals to the server that the client has finished sending. | +| [EventHandler](https://grafana.com/docs/k6//javascript-api/k6-net-grpc/stream/event-handler) | The handler function for various events on the gRPC stream. | +| [Metadata](https://grafana.com/docs/k6//javascript-api/k6-net-grpc/stream/message-metadata) | The metadata of a gRPC stream's message. | ### Examples diff --git a/docs/sources/next/javascript-api/k6-net-grpc/stream/event-handler.md b/docs/sources/next/javascript-api/k6-net-grpc/stream/event-handler.md new file mode 100644 index 0000000000..bd5da9fe45 --- /dev/null +++ b/docs/sources/next/javascript-api/k6-net-grpc/stream/event-handler.md @@ -0,0 +1,49 @@ +--- +title: 'Event Handler' +description: 'The handler function for various events on the gRPC stream.' +weight: 50 +--- + +# Event Handler + +The function to call for various events on the gRPC stream. It is set up using the [`stream.on()`](https://grafana.com/docs/k6//javascript-api/k6-net-grpc/stream/stream-on) method. + +| Name | Type | Description | +| ---------- | ------------------------------------------------------------------------------------------------------------ | ----------------------------------------------------------------------------------------------------- | +| `data` | object or [`Error`](https://grafana.com/docs/k6//javascript-api/k6-net-grpc/stream/stream-error) | It's either object with the data from server (a message) or an error object, in case of `error` event | +| `metadata` | [`Metadata`](https://grafana.com/docs/k6//javascript-api/k6-net-grpc/stream/message-metadata) | The object that represents the gRPC stream's message metadata. | + +### Example + +
+ +```javascript +import { Client, Stream } from 'k6/net/grpc'; +import { sleep } from 'k6'; + +const client = new Client(); +client.load([], '../../grpc_server/route_guide.proto'); + +export default () => { + if (__ITER == 0) { + client.connect('127.0.0.1:10000', { plaintext: true }); + } + + const stream = new Stream(client, 'main.RouteGuide/RecordRoute'); + + // sets up a handler for the data (server sends data) event + stream.on('data', (stats, metadata) => { + console.log('It took', stats.elapsedTime, 'seconds'); + console.log('This message has been received:', metadata.ts); + }); + + stream.on('end', function () { + // The server has finished sending + client.close(); + }); + + sleep(1); +}; +``` + +
diff --git a/docs/sources/next/javascript-api/k6-net-grpc/stream/message-metadata.md b/docs/sources/next/javascript-api/k6-net-grpc/stream/message-metadata.md new file mode 100644 index 0000000000..0f89bbbd7d --- /dev/null +++ b/docs/sources/next/javascript-api/k6-net-grpc/stream/message-metadata.md @@ -0,0 +1,48 @@ +--- +title: 'Metadata' +description: "The metadata of a gRPC stream's message." +weight: 60 +--- + +# Metadata + +The `Metadata` is an object that represents the gRPC stream's message. + +| Name | Type | Description | +| ------------- | ------ | -------------------------------------------------------------------------------------------- | +| `Metadata.ts` | number | Contains the timestamp of the original event. For example, when a message has been received. | + +### Example + +
+ +```javascript +import { Client, Stream } from 'k6/net/grpc'; +import { sleep } from 'k6'; + +const client = new Client(); +client.load([], '../../grpc_server/route_guide.proto'); + +export default () => { + if (__ITER == 0) { + client.connect('127.0.0.1:10000', { plaintext: true }); + } + + const stream = new Stream(client, 'main.RouteGuide/RecordRoute'); + + // sets up a handler for the data (server sends data) event + stream.on('data', (stats, metadata) => { + console.log('It took', stats.elapsedTime, 'seconds'); + console.log('This message has been received:', metadata.ts); + }); + + stream.on('end', function () { + // The server has finished sending + client.close(); + }); + + sleep(1); +}; +``` + +
diff --git a/docs/sources/next/javascript-api/k6-net-grpc/stream/stream-on.md b/docs/sources/next/javascript-api/k6-net-grpc/stream/stream-on.md index 01b4429714..e732d40167 100644 --- a/docs/sources/next/javascript-api/k6-net-grpc/stream/stream-on.md +++ b/docs/sources/next/javascript-api/k6-net-grpc/stream/stream-on.md @@ -10,10 +10,10 @@ aliases: Set up handler functions for various events on the gRPC stream. -| Parameter | Type | Description | -| --------- | -------- | -------------------------------------------- | -| event | string | The event name to define a handler for. | -| handler | function | The function to call when the event happens. | +| Parameter | Type | Description | +| --------- | ---------------------------------------------------------------------------------------------------------- | -------------------------------------------- | +| event | string | The event name to define a handler for. | +| handler | [`EventHandler`](https://grafana.com/docs/k6//javascript-api/k6-net-grpc/stream/event-handler) | The function to call when the event happens. | Possible events: diff --git a/docs/sources/next/shared/javascript-api/k6-net-grpc.md b/docs/sources/next/shared/javascript-api/k6-net-grpc.md index e75f818aec..15d3b782a8 100644 --- a/docs/sources/next/shared/javascript-api/k6-net-grpc.md +++ b/docs/sources/next/shared/javascript-api/k6-net-grpc.md @@ -19,3 +19,5 @@ The [`k6/net/grpc` module](https://grafana.com/docs/k6//javascript-a | [Stream.on(event, handler)](https://grafana.com/docs/k6//javascript-api/k6-net-grpc/stream/stream-on) | Adds a new listener to one of the possible stream events. | | [Stream.write(message)](https://grafana.com/docs/k6//javascript-api/k6-net-grpc/stream/stream-write) | Writes a message to the stream. | | [Stream.end()](https://grafana.com/docs/k6//javascript-api/k6-net-grpc/stream/stream-end) | Signals to the server that the client has finished sending. | +| [EventHandler](https://grafana.com/docs/k6//javascript-api/k6-net-grpc/stream/event-handler) | The function to call for various events on the gRPC stream. | +| [Metadata](https://grafana.com/docs/k6//javascript-api/k6-net-grpc/stream/message-metadata) | The metadata of a gRPC stream’s message. |