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..84e23a23ec 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'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. + +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. -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"; 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..84e23a23ec 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'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. + +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. -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";