ballerina/grpc

Overview

This module provides APIs for connecting and interacting with gRPC endpoints.

gRPC is an inter-process communication technology that allows you to connect, invoke, and operate distributed, heterogeneous applications as easily as making a local function call. The gRPC protocol is layered over HTTP/2 and uses Protocol Buffers for marshaling/unmarshaling messages. This makes gRPC highly efficient on wire and a simple service definition framework.

When you develop a gRPC application, the first thing you do is define a service definition using Protocol Buffers.

Protocol buffers

This is a mechanism to serialize the structured data introduced by Google and used by the gRPC framework. Defining the service using Protocol Buffers includes defining remote methods in the service and defining message types that are sent across the network. A sample service definition is shown below.

gRPC allows client applications to directly call the server-side methods using the auto-generated stubs. Protocol Buffer compiler is used to generate the stubs for the specified language. In Ballerina, the stubs are generated using the built-in 'Protocol Buffers to Ballerina' tool.

For information on how to generate Ballerina code for Protocol Buffers definition, see Write a gRPC service with Ballerina.

gRPC communication patterns

The common communication pattern between a client and server is simple request-response style communication. However, with gRPC, you can leverage different inter-process communication patterns other than the simple request-response pattern. This module supports four fundamental communication patterns used in gRPC-based applications: simple RPC(unary RPC), server streaming RPC, client streaming RPC, and bidirectional streaming RPC.

Simple RPC (Unary RPC)

In this pattern, the client invokes a remote function of a server and sends a single request to the server. The server sends a single response in return to the client along with status details.

Implement the gRPC server

The code snippet given below contains a service that sends a response to each request.

Implement the gRPC client

The code snippet given below calls the above service in a synchronized manner using an auto-generated Ballerina stub.

Server streaming RPC

In server-side streaming RPC, the server sends back a sequence of responses after getting the client's request message. After sending all the server responses, the server marks the end of the stream by sending the server status details. You can invoke this in a non-blocking manner.

Implement the gRPC server

The code snippet given below contains a service that sends a sequence of responses to each request.

Implement the gRPC server

The code snippet given below calls the above service using the auto-generated Ballerina client stub and reads multiple server responses using a stream. Here, the message stream is ended with a () value.

Client streaming RPC

In client streaming RPC, the client sends multiple messages to the server instead of a single request. The server sends back a single response to the client.

Implement the gRPC server

The code snippet given below contains a service that receives a sequence of requests from the client and sends a single response in return.

Implement the gRPC server

The code snippet given below calls the above service using the auto-generated Ballerina client stub and sends multiple request messages from the server.

Bidirectional streaming RPC

In bidirectional streaming RPC, the client is sending a request to the server as a stream of messages. The server also responds with a stream of messages.

Implement the gRPC server

The code snippet given below includes a service that handles bidirectional streaming.

Implement the gRPC server

The code snippet given below calls the above service using the auto-generated Ballerina client stub and sends multiple request messages to the server and receives multiple responses from the server.

Advanced use cases

Use the TLS protocol

The Ballerina gRPC module allows the use of TLS in communication. This setting expects a secure socket to be set in the connection configuration as shown below.

Configure TLS in server side

Configure TLS in client side

Use headers

The Ballerina gRPC module allows to send/receive headers with the request and response using the context record type. The context record type consists of two fields called headers and content. E.g: For the string message, a type generated context record type will be as follows.

Use headers at the client side

Use headers at the server side

Use deadlines

Deadlines allow gRPC clients to specify how long they are willing to wait for an RPC to complete before the RPC is terminated with the DEADLINE_EXCEEDED error. In Ballerina, a deadline value is set directly to the headers and it is sent via the request headers.

Set a deadline in the request headers

Check the deadlines