This API documentation is for Ballerina 1.2.0. View API documentation for the latest release.

Module : grpc

Module Overview

This module provides support for the gRPC messaging protocol. 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 It 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.

syntax = "proto3";

service Helloworld {
     rpc hello(HelloRequest) returns (HelloResponse);
}

message HelloRequest {
  string name = 1;
}

message HelloResponse {
  string message = 1;
}

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 proto compiler.

For the guide on how to generate Ballerina code for Protocol Buffers definition, see how to guide. For examples on the usage of the operation, see the Proto to Ballerina Example.

gRPC Communication Patterns

The common communication pattern between 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-side streaming, client-side streaming, and bidirectional streaming.

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. Users can invoke in both blocking and non-blocking manner.

rpc hello (google.protobuf.StringValue)
      returns (google.protobuf.StringValue);
Creating the server

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

// The gRPC service is attached to the listener.
service HelloWorld on new grpc:Listener(9090)  {
   // A resource that accepts a string message.
   resource function hello(grpc:Caller caller, string name) {
       // Send the response to the client.
       grpc:Error? err = caller->send("Hi " + name + "! Greetings from gRPC service!");

       // After sending the response, call ‘complete()’ to indicate that the response was completely sent.
       grpc:Error? result = caller->complete();
   }
}
Creating the client

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

// Use ‘BlockingClient’ to execute the call in the blocking mode.
HelloWorldBlockingClient blockingClient = new("http://localhost:9090");

// Create gRPC headers.
grpc:Headers headers = new;
headers.setEntry("id", "newrequest1");

// Call the method in the service using a client stub.
[string, grpc:Headers]|grpc:Error responseFromServer = blockingClient->hello("Ballerina", headers);

For examples on the usage of the operation, see Unary Ballerina Example and Unary Non-Ballerina Example

Server streaming RPC

In server-side streaming RPC, the 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. Users can invoke in a non-blocking manner.

rpc lotsOfReplies (google.protobuf.StringValue)
      returns (stream google.protobuf.StringValue);
Creating the server

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

// The gRPC service is attached to the listener.
service HelloWorld on new grpc:Listener(9090) {
   // Set the Streaming Annotation to ‘true’. It specifies that the resource is capable of
   // sending multiple responses per request.
   @grpc:ResourceConfig { streaming: true }
   resource function lotsOfReplies(grpc:Caller caller, string name) {
       string[] greets = ["Hi", "Welcome"];
       // Send multiple responses to the client.
       foreach string greet in greets {
           grpc:Error? err = caller->send(greet + " " + name + "! Greetings from Ballerina service");
       }
       // Once the messages are sent to the server, call ‘complete()’ to indicate that the request was completely sent.
       grpc:Error? result = caller->complete();
   }
}
Creating the client

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

   // Client endpoint configurations.
    HelloWorldClient helloworldClient = new("http://localhost:9090");

    // Execute the service streaming call by registering a message listener.
    grpc:Error? result = helloworldClient->lotsOfReplies
("Ballerina", HelloWorldMessageListener);

// Define a listener service to receive the messages from the server.
service HelloWorldMessageListener = service {

   // This resource method is invoked when the service receives a message.
   resource function onMessage(string message) {
   }
   
   // This resource method is invoked if an error is returned.
   resource function onError(error err) {
   }

   // Invoke this resource when the server sends all the responses to the request.
    resource function onComplete() {
   }
}

For examples on the usage of the operation, see the Server Streaming Example.

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.

rpc lotsOfGreetings (stream google.protobuf.StringValue)
      returns (google.protobuf.StringValue);
Creating the server

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

// The gRPC service is attached to the listener.
@grpc:ServiceConfig {
    name: "HelloWorld",
    clientStreaming: true
}
service HelloWorld on new grpc:Listener(9090) {
//This `resource` is triggered when a new caller connection is initialized.
resource function onOpen(grpc:Caller caller) {
}

//This `resource` is triggered when the caller sends a request message to the service.
resource function onMessage(grpc:Caller caller, string name) {
}

//This `resource` is triggered when the server receives an error message from the caller.
resource function onError(grpc:Caller caller, error err) {
}

//This `resource` is triggered when the caller sends a notification to the server to indicate that it has finished sending messages.
resource function onComplete(grpc:Caller caller) {
    grpc:Error? err = caller->send("Ack");
}
}
Creating the client

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

   // Client endpoint configurations.
    HelloWorldClient helloworldClient = new("http://localhost:9090");

    // Execute the service streaming call by registering a message listener.
    grpc:StreamingClient|grpc:Error ep = helloworldClient->lotsOfGreetings(HelloWorldMessageListener);

// Send multiple messages to the server.
string[] greets = ["Hi", "Hey", "GM"];
foreach string greet in greets {
    grpc:Error? connErr = ep->send(greet + " " + "Ballerina");
}

// Once all the messages are sent, the server notifies the caller with a `complete` message.
grpc:Error? result = ep->complete();
...

// Define a listener service to receive the messages from the server.
service HelloWorldMessageListener = service {

   // This resource method is invoked when the service receives a message.
   resource function onMessage(string message) {
   }
   
   // This resource method is invoked if an error is returned.
   resource function onError(error err) {
   }

   // Invoke this resource when the server sends all the responses to the request.
    resource function onComplete() {
   }
}

For examples on the usage of the operation, see the Client Streaming Example.

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.

rpc chat (stream ChatMessage)
      returns (stream google.protobuf.StringValue);
Creating the server

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

// Set the ‘clientStreaming’ and ‘serverStreaming’ to true. It specifies that the service supports bidirectional streaming.
@grpc:ServiceConfig {
    name: "Chat",
    clientStreaming: true,
    serverStreaming: true
}
service Chat on new grpc:Listener(9090) {

    //This `resource` is triggered when a new caller connection is initialized.
    resource function onOpen(grpc:Caller caller) {
    }

    //This `resource` is triggered when the caller sends a request message to the `service`.
    resource function onMessage(grpc:Caller caller, ChatMessage chatMsg) {
            grpc:Error? err = caller->send(string `${chatMsg.name}: ${chatMsg.message}`);
    }

    //This `resource` is triggered when the server receives an error message from the caller.
    resource function onError(grpc:Caller caller, error err) {
    }

    //This `resource` is triggered when the caller sends a notification to the server to indicate that it has finished sending messages.
    resource function onComplete(grpc:Caller caller) {
    }
}
Creating the client

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.

   // Client endpoint configurations.
    ChatClient chatClient = new("http://localhost:9090");

    // Execute the service streaming call by registering a message listener.
    grpc:StreamingClient|grpc:Error ep = chatClient->chat(ChatMessageListener);

// Send multiple messages to the server.
string[] greets = ["Hi", "Hey", "GM"];
foreach string greet in greets {
    ChatMessage mes = {name: "Ballerina", message: greet};
    grpc:Error? connErr = ep->send(mes);
}

// Once all the messages are sent, the server notifies the caller with a `complete` message.
grpc:Error? result = ep->complete();
...

// Define a listener service to receive the messages from the server.
service ChatMessageListener = service {

   // This resource method is invoked when the service receives a message.
   resource function onMessage(string message) {
   }
   
   // This resource method is invoked if an error is returned.
   resource function onError(error err) {
   }

   // Invoke this resource when the server sends all the responses to the request.
    resource function onComplete() {
   }
}

For examples on the usage of the operation, see the Bidirectional Streaming Example.

Advanced Use cases

Using the TLS protocol

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

Configuring TLS in server side
// Server endpoint configuration with the SSL configurations.
listener grpc:Listener ep = new (9090, {
    host: "localhost",
    secureSocket: {
        keyStore: {
            path: config:getAsString("b7a.home") + "bre/security/ballerinaKeystore.p12",
            password: "ballerina"
        }
    }
});

service HelloWorld on ep {
    
}
Configuring TLS in client side
    // Client endpoint configuration with SSL configurations.
    HelloWorldBlockingClient helloWorldClient = new ("https://localhost:9090", {
            secureSocket: {
                trustStore: {
                    path: config:getAsString("b7a.home") + "/bre/security/ballerinaTruststore.p12",
                    password: "ballerina"
                }
            }
    });

For examples on the usage of the operation, see the Secured Unary Example.

Records

ClientConfiguration

Represents client endpoint configuration.

Detail

The details of a gRPC error.

GrpcResourceConfig

Service resource configuration.

GrpcServiceConfig

Service configuration.

ListenerConfiguration

Represents the gRPC server endpoint configuration.

ListenerOcspStapling

OcspStapling record represents options related to check whether a certificate is revoked or not.

ListenerSecureSocket

Configures the SSL/TLS options to be used for HTTP service.

Local

Presents a read-only view of the local address.

PoolConfiguration

Configurations for managing the gRPC client connection pool.

Protocols

Protocols record represents SSL/TLS protocol related options to be used for HTTP client/service invocation.

Remote

Presents a read-only view of the remote address.

RetryConfiguration

Represents grpc client retry functionality configurations.

SecureSocket

Provides the configurations for facilitating secure communication with a remote HTTP endpoint.

ServiceDescriptorData

Service descriptor data generated at the compile time.

ValidateCert

ValidateCert record represents options related to check whether a certificate is revoked or not.

Objects

AbstractClientEndpoint

Represents the abstract gRPC client endpoint.

Headers

Provides the actions to read/write header values in a gRPC request/response message.

Clients

Caller

Provides the gRPC remote functions for interacting with caller.

Client

The gRPC client endpoint provides the capability for initiating contact with a remote gRPC service.

StreamingClient

Provides the gRPC streaming client actions for interacting with the gRPC server.

Listeners

Listener

Represents server listener where one or more services can be registered.

Functions

prepareError

Prepare the error as a gRPC-specific Error.

Constants

OK

The gRPC error status code: 0 OK.

CANCELED

The gRPC error status code: 1 Canceled.

UNKNOWN

The gRPC error status code: 2 Unknown.

INVALID_ARGUMENT

The gRPC error status code: 3 Invalid Argument.

DEADLINE_EXCEEDED

The gRPC error status code: 4 Deadline Exceeded.

NOT_FOUND

The gRPC error status code: 5 Not Found.

ALREADY_EXISTS

The gRPC error status code: 6 Already Exists.

PERMISSION_DENIED

The gRPC error status code: 7 Permission Denied.

RESOURCE_EXHAUSTED

The gRPC error status code: 8 Resource Exhausted.

FAILED_PRECONDITION

The gRPC error status code: 9 Failed Precondition.

ABORTED

The gRPC error status code: 10 Aborted.

OUT_OF_RANGE

The gRPC error status code: 11 Out of Range.

UNIMPLEMENTED

The gRPC error status code: 12 Unimplemented.

INTERNAL

The gRPC error status code: 13 Internal.

UNAVAILABLE

The gRPC error status code: 14 Unavailable.

DATA_LOSS

The gRPC error status code: 15 Data Loss.

UNAUTHENTICATED

The gRPC error status code: 16 Unauthenticated.

COMPRESSION_AUTO

When service behaves as a HTTP gateway inbound request/response accept-encoding option is set as the outbound request/response accept-encoding/content-encoding option.

COMPRESSION_ALWAYS

Always set accept-encoding/content-encoding in outbound request/response.

COMPRESSION_NEVER

Never set accept-encoding/content-encoding header in outbound request/response.

CANCELLED_ERROR

Represents the reason of the cancelled error.

UNKNOWN_ERROR

Represents the reason of the unknown error.

INVALID_ARGUMENT_ERROR

Represents the reason of the invalid argument error.

DEADLINE_EXCEEDED_ERROR

Represents the reason of the deadline exceeded error.

NOT_FOUND_ERROR

Represents the reason of the not found error.

ALREADY_EXISTS_ERROR

Represents the reason of the already exists error.

PERMISSION_DENIED_ERROR

Represents the reason of the permission denied error.

UNAUTHENTICATED_ERROR

Represents the reason of the unauthenticated error.

RESOURCE_EXHAUSTED_ERROR

Represents the reason of the resource exhausted error.

FAILED_PRECONDITION_ERROR

Represents the reason of the failed precondition error.

ABORTED_ERROR

Represents the reason of the aborted error.

OUT_OF_RANGE_ERROR

Represents the reason of the out of range error.

UNIMPLEMENTED_ERROR

Represents the reason of the unimplemented error.

INTERNAL_ERROR

Represents the reason of the internal error.

UNAVAILABLE_ERROR

Represents the reason of the unavailable error.

DATA_LOSS_ERROR

Represents the reason of the data loss error.

ALL_RETRY_ATTEMPTS_FAILED

Represents the reason of all the retry attempts failed scenario.

Annotations

ResourceConfig

Service resource configuration annotation.

ServiceConfig

Service configuration annotation.

ServiceDescriptor

Service descriptor annotation.

Types

Compression

Options to compress using gzip or deflate.

Error

Represents gRPC related errors.

ErrorType

Represents gRPC related error types.

ResiliencyError

Represents all the resiliency-related errors.

ResiliencyErrorType

Represents the reason of all the resiliency-related error.

Errors

AbortedError

Represents error occur when operation is aborted.

AleadyExistsError

Represents error occur when attempt to create an entity which already exists.

AllRetryAttemptsFailed

Represents error scenario where the maximum retry attempts are done and still received an error.

CancelledError

Represents the operation canceled(typically by the caller) error.

DataLossError

Represents unrecoverable data loss or corruption erros.

DeadlineExceededError

Represents operation expired before completion error.

FailedPreconditionError

Represents error occur when operation is rejected because the system is not in a state required for the operation's execution.

InternalError

Represents internal error.

InvalidArgumentError

Represents client specified an invalid argument error.

NotFoundError

Represents requested entity (e.

OutOfRangeError

Represents error occur when specified value is out of range.

PermissionDeniedError

Represents error occur when the caller does not have permission to execute the specified operation.

ResourceExhaustedError

Represents error occur when the resource is exhausted.

UnKnownError

Represents unknown error.

UnauthenticatedError

Represents error occur when the request does not have valid authentication credentials for the operation.

UnavailableError

Represents error occur when the service is currently unavailable.

UnimplementedError

Represents error occur when operation is not implemented or not supported/enabled in this service.