grpc-transcode

Description

The grpc-transcode Plugin converts between HTTP and gRPC requests.

APISIX takes in an HTTP request, transcodes it and forwards it to a gRPC service, gets the response and returns it back to the client in HTTP format.

Attributes

NameTypeRequiredDefaultDescription
proto_idstring/integerTrueid of the the proto content.
servicestringTrueName of the gRPC service.
methodstringTrueMethod name of the gRPC service.
deadlinenumberFalse0Deadline for the gRPC service in ms.
pb_optionarray[string(pb_option_def)]Falseprotobuf options.
show_status_in_bodybooleanFalsefalseWhether to display the parsed grpc-status-details-bin in the response body
status_detail_typestringFalseThe message type corresponding to the details part of grpc-status-details-bin, if not specified, this part will not be decoded

Options for pb_option

TypeValid values
enum as resultenum_as_name, enum_as_value
int64 as resultint64_as_number, int64_as_string, int64_as_hexstring
default valuesauto_default_values, no_default_values, use_default_values, use_default_metatable
hooksenable_hooks, disable_hooks

Enabling the Plugin

Before enabling the Plugin, you have to add the content of your .proto or .pb files to APISIX.

You can use the /admin/protos/id endpoint and add the contents of the file to the content field:

  1. curl http://127.0.0.1:9180/apisix/admin/protos/1 -H 'X-API-KEY: edd1c9f034335f136f87ad84b625c8f1' -X PUT -d '
  2. {
  3.     "content" : "syntax = \"proto3\";
  4.     package helloworld;
  5.     service Greeter {
  6.         rpc SayHello (HelloRequest) returns (HelloReply) {}
  7.     }
  8.     message HelloRequest {
  9.         string name = 1;
  10.     }
  11.     message HelloReply {
  12.         string message = 1;
  13.     }"
  14. }'

If your proto file contains imports, or if you want to combine multiple proto files, you can generate a .pb file and use it in APISIX.

For example, if we have a file called proto/helloworld.proto which imports another proto file:

  1. syntax = "proto3";
  3. package helloworld;
  4. import "proto/import.proto";
  5. ...

We first generate a .pb file from the proto files:

  1. protoc --include_imports --descriptor_set_out=proto.pb proto/helloworld.proto

The output binary file, proto.pb will contain both helloworld.proto and import.proto.

We can now use the content of proto.pb in the content field of the API request.

As the content of the proto is binary, we encode it in base64 using this Python script:

upload_pb.py

  1. #!/usr/bin/env python
  2. # coding: utf-8
  4. import base64
  5. import sys
  7. # sudo pip install requests
  8. import requests
  10. if len(sys.argv) <= 1:
  11.     print("bad argument")
  12.     sys.exit(1)
  13. with open(sys.argv[1], 'rb') as f:
  14.     content = base64.b64encode(f.read())
  15. id = sys.argv[2]
  16. api_key = "edd1c9f034335f136f87ad84b625c8f1" # use a different API key
  18. reqParam = {
  19.     "content": content,
  20. }
  21. resp = requests.put("http://127.0.0.1:9180/apisix/admin/protos/" + id, json=reqParam, headers={
  22.     "X-API-KEY": api_key,
  23. })
  24. print(resp.status_code)
  25. print(resp.text)

This script will take in a .pb file and the id to create, encodes the content of the proto to base64, and calls the Admin API with this encoded content.

To run the script:

  1. chmod +x ./upload_pb.py
  1. ./upload_pb.py proto.pb 1

Response:

  1. # 200
  2. # {"node":{"value":{"create_time":1643879753,"update_time":1643883085,"content":"CmgKEnByb3RvL2ltcG9ydC5wcm90bxIDcGtnIhoKBFVzZXISEgoEbmFtZRgBIAEoCVIEbmFtZSIeCghSZXNwb25zZRISCgRib2R5GAEgASgJUgRib2R5QglaBy4vcHJvdG9iBnByb3RvMwq9AQoPcHJvdG8vc3JjLnByb3RvEgpoZWxsb3dvcmxkGhJwcm90by9pbXBvcnQucHJvdG8iPAoHUmVxdWVzdBIdCgR1c2VyGAEgASgLMgkucGtnLlVzZXJSBHVzZXISEgoEYm9keRgCIAEoCVIEYm9keTI5CgpUZXN0SW1wb3J0EisKA1J1bhITLmhlbGxvd29ybGQuUmVxdWVzdBoNLnBrZy5SZXNwb25zZSIAQglaBy4vcHJvdG9iBnByb3RvMw=="},"key":"\/apisix\/proto\/1"}}

Now, we can enable the grpc-transcode Plugin to a specific Route:

  1. curl http://127.0.0.1:9180/apisix/admin/routes/111 -H 'X-API-KEY: edd1c9f034335f136f87ad84b625c8f1' -X PUT -d '
  2. {
  3.     "methods": ["GET"],
  4.     "uri": "/grpctest",
  5.     "plugins": {
  6.         "grpc-transcode": {
  7.             "proto_id": "1",
  8.             "service": "helloworld.Greeter",
  9.             "method": "SayHello"
  10.         }
  11.     },
  12.     "upstream": {
  13.         "scheme": "grpc",
  14.         "type": "roundrobin",
  15.         "nodes": {
  16.             "127.0.0.1:50051": 1
  17.         }
  18.     }
  19. }'
grpc-transcode - 图1note

The Upstream service used here should be a gRPC service. Note that the scheme is set to grpc.

You can use the grpc_server_example for testing.

Example usage

Once you configured the Plugin as mentioned above, you can make a request to APISIX to get a response back from the gRPC service (through APISIX):

  1. curl -i http://127.0.0.1:9080/grpctest?name=world

Response:

  1. HTTP/1.1 200 OK
  2. Date: Fri, 16 Aug 2019 11:55:36 GMT
  3. Content-Type: application/json
  4. Transfer-Encoding: chunked
  5. Connection: keep-alive
  6. Server: APISIX web server
  7. Proxy-Connection: keep-alive
  9. {"message":"Hello world"}

You can also configure the pb_option as shown below:

  1. curl http://127.0.0.1:9180/apisix/admin/routes/23 -H 'X-API-KEY: edd1c9f034335f136f87ad84b625c8f1' -X PUT -d '
  2. {
  3.     "methods": ["GET"],
  4.     "uri": "/zeebe/WorkflowInstanceCreate",
  5.     "plugins": {
  6.         "grpc-transcode": {
  7.             "proto_id": "1",
  8.             "service": "gateway_protocol.Gateway",
  9.             "method": "CreateWorkflowInstance",
  10.             "pb_option":["int64_as_string"]
  11.         }
  12.     },
  13.     "upstream": {
  14.         "scheme": "grpc",
  15.         "type": "roundrobin",
  16.         "nodes": {
  17.             "127.0.0.1:26500": 1
  18.         }
  19.     }
  20. }'

Now if you check the configured Route:

  1. curl -i "http://127.0.0.1:9080/zeebe/WorkflowInstanceCreate?bpmnProcessId=order-process&version=1&variables=\{\"orderId\":\"7\",\"ordervalue\":99\}"
  1. HTTP/1.1 200 OK
  2. Date: Wed, 13 Nov 2019 03:38:27 GMT
  3. Content-Type: application/json
  4. Transfer-Encoding: chunked
  5. Connection: keep-alive
  6. grpc-encoding: identity
  7. grpc-accept-encoding: gzip
  8. Server: APISIX web server
  9. Trailer: grpc-status
  10. Trailer: grpc-message
  12. {"workflowKey":"#2251799813685260","workflowInstanceKey":"#2251799813688013","bpmnProcessId":"order-process","version":1}

Show grpc-status-details-bin in response body

If the gRPC service returns an error, there may be a grpc-status-details-bin field in the response header describing the error, which you can decode and display in the response body.

Upload the proto file：

  1. curl http://127.0.0.1:9080/apisix/admin/proto/1 \
  2. -H 'X-API-KEY: edd1c9f034335f136f87ad84b625c8f1' -X PUT -d '
  3. {
  4.     "content" : "syntax = \"proto3\";
  5.     package helloworld;
  6.     service Greeter {
  7.         rpc GetErrResp (HelloRequest) returns (HelloReply) {}
  8.     }
  9.     message HelloRequest {
  10.         string name = 1;
  11.         repeated string items = 2;
  12.     }
  13.     message HelloReply {
  14.         string message = 1;
  15.         repeated string items = 2;
  16.     }"
  17. }'

Enable the grpc-transcode plugin，and set the option show_status_in_body to true：

  1. curl http://127.0.0.1:9080/apisix/admin/routes/1 \
  2. -H 'X-API-KEY: edd1c9f034335f136f87ad84b625c8f1' -X PUT -d '
  3. {
  4.     "methods": ["GET"],
  5.     "uri": "/grpctest",
  6.     "plugins": {
  7.         "grpc-transcode": {
  8.          "proto_id": "1",
  9.          "service": "helloworld.Greeter",
  10.          "method": "GetErrResp",
  11.          "show_status_in_body": true
  12.         }
  13.     },
  14.     "upstream": {
  15.         "scheme": "grpc",
  16.         "type": "roundrobin",
  17.         "nodes": {
  18.             "127.0.0.1:50051": 1
  19.         }
  20.     }
  21. }'

Access the route configured above：

  1. curl -i http://127.0.0.1:9080/grpctest?name=world

Response:

  1. HTTP/1.1 503 Service Temporarily Unavailable
  2. Date: Wed, 10 Aug 2022 08:59:46 GMT
  3. Content-Type: application/json
  4. Transfer-Encoding: chunked
  5. Connection: keep-alive
  6. grpc-status: 14
  7. grpc-message: Out of service
  8. grpc-status-details-bin: CA4SDk91dCBvZiBzZXJ2aWNlGlcKKnR5cGUuZ29vZ2xlYXBpcy5jb20vaGVsbG93b3JsZC5FcnJvckRldGFpbBIpCAESHFRoZSBzZXJ2ZXIgaXMgb3V0IG9mIHNlcnZpY2UaB3NlcnZpY2U
  9. Server: APISIX web server
  11. {"error":{"details":[{"type_url":"type.googleapis.com\/helloworld.ErrorDetail","value":"\b\u0001\u0012\u001cThe server is out of service\u001a\u0007service"}],"message":"Out of service","code":14}}

Note that there is an undecoded field in the return body. If you need to decode the field, you need to add the message type of the field in the uploaded proto file.

  1. curl http://127.0.0.1:9080/apisix/admin/proto/1 \
  2. -H 'X-API-KEY: edd1c9f034335f136f87ad84b625c8f1' -X PUT -d '
  3. {
  4.     "content" : "syntax = \"proto3\";
  5.     package helloworld;
  6.     service Greeter {
  7.         rpc GetErrResp (HelloRequest) returns (HelloReply) {}
  8.     }
  9.     message HelloRequest {
  10.         string name = 1;
  11.         repeated string items = 2;
  12.     }
  13.     message HelloReply {
  14.         string message = 1;
  15.         repeated string items = 2;
  16.     }
  17.     message ErrorDetail {
  18.         int64 code = 1;
  19.         string message = 2;
  20.         string type = 3;
  21.     }"
  22. }'

Also configure the option status_detail_type to helloworld.ErrorDetail.

  1. curl http://127.0.0.1:9080/apisix/admin/routes/1 \
  2. -H 'X-API-KEY: edd1c9f034335f136f87ad84b625c8f1' -X PUT -d '
  3. {
  4.     "methods": ["GET"],
  5.     "uri": "/grpctest",
  6.     "plugins": {
  7.         "grpc-transcode": {
  8.          "proto_id": "1",
  9.          "service": "helloworld.Greeter",
  10.          "method": "GetErrResp",
  11.          "show_status_in_body": true,
  12.          "status_detail_type": "helloworld.ErrorDetail"
  13.         }
  14.     },
  15.     "upstream": {
  16.         "scheme": "grpc",
  17.         "type": "roundrobin",
  18.         "nodes": {
  19.             "127.0.0.1:50051": 1
  20.         }
  21.     }
  22. }'

The fully decoded result is returned.

  1. HTTP/1.1 503 Service Temporarily Unavailable
  2. Date: Wed, 10 Aug 2022 09:02:46 GMT
  3. Content-Type: application/json
  4. Transfer-Encoding: chunked
  5. Connection: keep-alive
  6. grpc-status: 14
  7. grpc-message: Out of service
  8. grpc-status-details-bin: CA4SDk91dCBvZiBzZXJ2aWNlGlcKKnR5cGUuZ29vZ2xlYXBpcy5jb20vaGVsbG93b3JsZC5FcnJvckRldGFpbBIpCAESHFRoZSBzZXJ2ZXIgaXMgb3V0IG9mIHNlcnZpY2UaB3NlcnZpY2U
  9. Server: APISIX web server
  11. {"error":{"details":[{"type":"service","message":"The server is out of service","code":1}],"message":"Out of service","code":14}}

Disable Plugin

To disable the grpc-transcode Plugin, you can delete the corresponding JSON configuration from the Plugin configuration. APISIX will automatically reload and you do not have to restart for this to take effect.

  1. curl http://127.0.0.1:9180/apisix/admin/routes/111 -H 'X-API-KEY: edd1c9f034335f136f87ad84b625c8f1' -X PUT -d '
  2. {
  3.     "uri": "/grpctest",
  4.     "plugins": {},
  5.     "upstream": {
  6.         "scheme": "grpc",
  7.         "type": "roundrobin",
  8.         "nodes": {
  9.             "127.0.0.1:50051": 1
  10.         }
  11.     }
  12. }'