From 957e3993664f7952270a84ac78234d6bcdb4fb5f Mon Sep 17 00:00:00 2001 From: Oleg Bespalov Date: Fri, 26 Jan 2024 09:31:40 +0100 Subject: [PATCH 1/3] Minor gRPC docs updates --- .../k6-net-grpc/client/client-invoke.md | 2 +- .../k6-net-grpc/stream/stream-write.md | 2 +- docs/sources/next/using-k6/protocols/grpc.md | 14 +++++++++----- 3 files changed, 11 insertions(+), 7 deletions(-) diff --git a/docs/sources/next/javascript-api/k6-net-grpc/client/client-invoke.md b/docs/sources/next/javascript-api/k6-net-grpc/client/client-invoke.md index c99ad5ae10..17f70c22e5 100644 --- a/docs/sources/next/javascript-api/k6-net-grpc/client/client-invoke.md +++ b/docs/sources/next/javascript-api/k6-net-grpc/client/client-invoke.md @@ -16,7 +16,7 @@ error will be thrown. | Parameter | Type | Description | | ----------------- | ------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | url | string | The gRPC method url to invoke, in the form `/package.Service/Method`, e.g. `/google.cloud.language.v1.LanguageService/AnalyzeSentiment`. The leading slash `/` is optional. | -| request | object | The canonical request object, as-per the [Protobuf JSON Mapping](https://developers.google.com/protocol-buffers/docs/proto3#json). | +| request | object | The canonical request object, as-per the [Protobuf JSON Mapping](https://grafana.com/docs/k6//using-k6/protocols/grpc/#protocol-buffers-json-mapping). | | params (optional) | object | [Params](https://grafana.com/docs/k6//javascript-api/k6-net-grpc/params) object containing additional request parameters. | ### Returns diff --git a/docs/sources/next/javascript-api/k6-net-grpc/stream/stream-write.md b/docs/sources/next/javascript-api/k6-net-grpc/stream/stream-write.md index aa2fe27a96..136733715a 100644 --- a/docs/sources/next/javascript-api/k6-net-grpc/stream/stream-write.md +++ b/docs/sources/next/javascript-api/k6-net-grpc/stream/stream-write.md @@ -6,7 +6,7 @@ weight: 40 # Stream.write() -Writes a message to the stream. +Writes a message to the stream. The message is a canonical request object, as-per the [Protobuf JSON Mapping](https://grafana.com/docs/k6//using-k6/protocols/grpc/#protocol-buffers-json-mapping). ### Example diff --git a/docs/sources/next/using-k6/protocols/grpc.md b/docs/sources/next/using-k6/protocols/grpc.md index e7ab18d968..018910c240 100644 --- a/docs/sources/next/using-k6/protocols/grpc.md +++ b/docs/sources/next/using-k6/protocols/grpc.md @@ -89,7 +89,7 @@ export default () => { In server streaming mode, the client sends a single request to the server, and the server replies with multiple responses. -The example below demonstrates client streaming. +The example below demonstrates server streaming. {{< code >}} @@ -256,11 +256,15 @@ stream.on('error', function (e) { {{< /code >}} -### Handle special cases in message Marshaling/Unmarshaling +### Protocol Buffers JSON Mapping + +It is worth mentioning how k6 handles requests/messages. First, it tries to marshal the request/message into a JSON. Then k6 uses the [protojson](https://pkg.go.dev/google.golang.org/protobuf/encoding/protojson) package for encoding/decoding to Protobuf message. + +The limitation of that is that the object that you passed as a request/message should be serializable, so unfortunately, structs like `Map` won't fit. -k6 uses the [protojson](https://pkg.go.dev/google.golang.org/protobuf/encoding/protojson) package for encoding and decoding of messages. +The benefit of using `protojson` is the canonical JSON encoding support. The [Protocol Buffers documentation](https://protobuf.dev/programming-guides/proto3/#json) describes this mapping. -Certain gRPC well-known types or wrappers have specific marshaling/unmarshaling rules. +#### Examples For instance, if you import `"google/protobuf/wrappers.proto"` and your proto-definitions look like this: @@ -301,7 +305,7 @@ if (respInt.message !== '6') { {{< /code >}} -Another special case could be usage of `oneof`. Let's say you have a proto-definition like this: +Another example could be usage of `oneof`. Let's say you have a proto-definition like this: ```proto syntax = "proto3"; From 860074b526d8cb79dc2fe76424ac439d725a8f96 Mon Sep 17 00:00:00 2001 From: Oleg Bespalov Date: Mon, 29 Jan 2024 14:12:27 +0100 Subject: [PATCH 2/3] Porting changes to v0.49 --- .../k6-net-grpc/client/client-invoke.md | 2 +- .../k6-net-grpc/stream/stream-write.md | 2 +- docs/sources/v0.49.x/using-k6/protocols/grpc.md | 14 +++++++++----- 3 files changed, 11 insertions(+), 7 deletions(-) diff --git a/docs/sources/v0.49.x/javascript-api/k6-net-grpc/client/client-invoke.md b/docs/sources/v0.49.x/javascript-api/k6-net-grpc/client/client-invoke.md index c99ad5ae10..17f70c22e5 100644 --- a/docs/sources/v0.49.x/javascript-api/k6-net-grpc/client/client-invoke.md +++ b/docs/sources/v0.49.x/javascript-api/k6-net-grpc/client/client-invoke.md @@ -16,7 +16,7 @@ error will be thrown. | Parameter | Type | Description | | ----------------- | ------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | url | string | The gRPC method url to invoke, in the form `/package.Service/Method`, e.g. `/google.cloud.language.v1.LanguageService/AnalyzeSentiment`. The leading slash `/` is optional. | -| request | object | The canonical request object, as-per the [Protobuf JSON Mapping](https://developers.google.com/protocol-buffers/docs/proto3#json). | +| request | object | The canonical request object, as-per the [Protobuf JSON Mapping](https://grafana.com/docs/k6//using-k6/protocols/grpc/#protocol-buffers-json-mapping). | | params (optional) | object | [Params](https://grafana.com/docs/k6//javascript-api/k6-net-grpc/params) object containing additional request parameters. | ### Returns diff --git a/docs/sources/v0.49.x/javascript-api/k6-net-grpc/stream/stream-write.md b/docs/sources/v0.49.x/javascript-api/k6-net-grpc/stream/stream-write.md index aa2fe27a96..136733715a 100644 --- a/docs/sources/v0.49.x/javascript-api/k6-net-grpc/stream/stream-write.md +++ b/docs/sources/v0.49.x/javascript-api/k6-net-grpc/stream/stream-write.md @@ -6,7 +6,7 @@ weight: 40 # Stream.write() -Writes a message to the stream. +Writes a message to the stream. The message is a canonical request object, as-per the [Protobuf JSON Mapping](https://grafana.com/docs/k6//using-k6/protocols/grpc/#protocol-buffers-json-mapping). ### Example diff --git a/docs/sources/v0.49.x/using-k6/protocols/grpc.md b/docs/sources/v0.49.x/using-k6/protocols/grpc.md index e7ab18d968..018910c240 100644 --- a/docs/sources/v0.49.x/using-k6/protocols/grpc.md +++ b/docs/sources/v0.49.x/using-k6/protocols/grpc.md @@ -89,7 +89,7 @@ export default () => { In server streaming mode, the client sends a single request to the server, and the server replies with multiple responses. -The example below demonstrates client streaming. +The example below demonstrates server streaming. {{< code >}} @@ -256,11 +256,15 @@ stream.on('error', function (e) { {{< /code >}} -### Handle special cases in message Marshaling/Unmarshaling +### Protocol Buffers JSON Mapping + +It is worth mentioning how k6 handles requests/messages. First, it tries to marshal the request/message into a JSON. Then k6 uses the [protojson](https://pkg.go.dev/google.golang.org/protobuf/encoding/protojson) package for encoding/decoding to Protobuf message. + +The limitation of that is that the object that you passed as a request/message should be serializable, so unfortunately, structs like `Map` won't fit. -k6 uses the [protojson](https://pkg.go.dev/google.golang.org/protobuf/encoding/protojson) package for encoding and decoding of messages. +The benefit of using `protojson` is the canonical JSON encoding support. The [Protocol Buffers documentation](https://protobuf.dev/programming-guides/proto3/#json) describes this mapping. -Certain gRPC well-known types or wrappers have specific marshaling/unmarshaling rules. +#### Examples For instance, if you import `"google/protobuf/wrappers.proto"` and your proto-definitions look like this: @@ -301,7 +305,7 @@ if (respInt.message !== '6') { {{< /code >}} -Another special case could be usage of `oneof`. Let's say you have a proto-definition like this: +Another example could be usage of `oneof`. Let's say you have a proto-definition like this: ```proto syntax = "proto3"; From 94ef7dffbca2ef12a9f6d39e52ce447791c3c6a0 Mon Sep 17 00:00:00 2001 From: Oleg Bespalov Date: Mon, 5 Feb 2024 10:50:57 +0100 Subject: [PATCH 3/3] Apply suggestions from code review Co-authored-by: Heitor Tashiro Sergent --- docs/sources/next/using-k6/protocols/grpc.md | 4 ++-- docs/sources/v0.49.x/using-k6/protocols/grpc.md | 4 ++-- 2 files changed, 4 insertions(+), 4 deletions(-) diff --git a/docs/sources/next/using-k6/protocols/grpc.md b/docs/sources/next/using-k6/protocols/grpc.md index 018910c240..84e23a23ec 100644 --- a/docs/sources/next/using-k6/protocols/grpc.md +++ b/docs/sources/next/using-k6/protocols/grpc.md @@ -258,9 +258,9 @@ stream.on('error', function (e) { ### Protocol Buffers JSON Mapping -It is worth mentioning how k6 handles requests/messages. First, it tries to marshal the request/message into a JSON. Then k6 uses the [protojson](https://pkg.go.dev/google.golang.org/protobuf/encoding/protojson) package for encoding/decoding to Protobuf message. +It's important to note how k6 handles requests and messages. First, it tries to marshal the request/message in JSON format. Then, k6 uses the [protojson](https://pkg.go.dev/google.golang.org/protobuf/encoding/protojson) package to encode or decode to a Protobuf message. -The limitation of that is that the object that you passed as a request/message should be serializable, so unfortunately, structs like `Map` won't fit. +A limitation during this process is that the object you pass as a request/message must be serializable. That means structs like `Map` don't work. The benefit of using `protojson` is the canonical JSON encoding support. The [Protocol Buffers documentation](https://protobuf.dev/programming-guides/proto3/#json) describes this mapping. diff --git a/docs/sources/v0.49.x/using-k6/protocols/grpc.md b/docs/sources/v0.49.x/using-k6/protocols/grpc.md index 018910c240..84e23a23ec 100644 --- a/docs/sources/v0.49.x/using-k6/protocols/grpc.md +++ b/docs/sources/v0.49.x/using-k6/protocols/grpc.md @@ -258,9 +258,9 @@ stream.on('error', function (e) { ### Protocol Buffers JSON Mapping -It is worth mentioning how k6 handles requests/messages. First, it tries to marshal the request/message into a JSON. Then k6 uses the [protojson](https://pkg.go.dev/google.golang.org/protobuf/encoding/protojson) package for encoding/decoding to Protobuf message. +It's important to note how k6 handles requests and messages. First, it tries to marshal the request/message in JSON format. Then, k6 uses the [protojson](https://pkg.go.dev/google.golang.org/protobuf/encoding/protojson) package to encode or decode to a Protobuf message. -The limitation of that is that the object that you passed as a request/message should be serializable, so unfortunately, structs like `Map` won't fit. +A limitation during this process is that the object you pass as a request/message must be serializable. That means structs like `Map` don't work. The benefit of using `protojson` is the canonical JSON encoding support. The [Protocol Buffers documentation](https://protobuf.dev/programming-guides/proto3/#json) describes this mapping.