ballerina/grpc package

Package overview

This package contains functions to support gRPC protocol based communication. gRPC is a framework developed by Google to support the RPC (Remote Procedure Call) protocol. The gRPC protocol is layered over HTTP/2. This protocol only supports client-initiated communication.

Protocol buffers

This is a mechanism to serialize the structured data introduced by Google and used by the gRPC framework. Specify the structured data that needs to be serialized in the .proto file. This package contains functions to automatically generate the .proto file based on the service definition of a gRPC service. A sample .proto file is shown below.

syntax = "proto3";
import "google/protobuf/wrappers.proto";
service ServerStreaming {
     rpc receiveMessage(google.protobuf.StringValue) returns (stream google.protobuf.StringValue);
}

gRPC allows client applications to directly call the server-side methods using the auto-generated client stubs. Protocol buffer compilers are used to generate the stubs for the specified language. In Ballerina, the client stubs are generated using the built-in proto compiler.

Endpoints

Endpoints specify how the client and server communicate. This package supports service endpoints and client endpoints. The service endpoint specifies how the client communicates with the server. The client endpoint is automatically generated by passing the .proto file of a service to a proto compiler.

The Ballerina tooling distribution provides a proto compiler to generate the Ballerina client endpoint. The client endpoint generated using the Ballerina proto compiler has two client endpoints. Use the endpoint to suit the use case.

RPC types

This package supports the following RPC client-to-service communication methods: unary, server streaming, client streaming, and bidirectional streaming. Listeners are used to support the asynchronous and streaming communication.

Unary

The server sends a response to each client request. Unary supports blocking and non-blocking communication.

Server streaming

The server sends multiple responses in an asynchronous manner for each client request.

Client streaming

The client sends multiple requests while the server sends a single response to these requests.

Bidirectional Streaming

The client and server send multiple requests and responses.

Samples

Unary communication

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

// Server endpoint configuration.
endpoint grpc:Listener ep {
   host:"localhost",
   port:9090
};

// The gRPC service that binds to the server endpoint.
service SamplegRPCService bind ep {
   // A resource that accepts a string message.
   receiveMessage (endpoint caller, string name) {
       // Print the received message.
       io:println("Received message from : " + name);
       // Send the response to the client.
       error? err = caller->send("Hi " + name + "! Greetings from gRPC service!");

       // After sending the response, call ‘complete()’ to indicate that the request was completely sent.
       _ = caller->complete();
   }
}

A proto file is automatically generated after this service is run. It is generated in the same folder as the service.

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

// Use ‘BlockingClient’ to execute the call in the blocking mode.
endpoint SamplegRPCServiceBlockingClient SamplegRPCServiceBlockingEp {
   host:"localhost",
   port:9090
};

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

// Call the method in the service using a client stub.
var responseFromServer = SamplegRPCServiceBlockingEp->receiveMessage("Ballerina", headers = headers);
match responseFromServer {
   // If a response is received, print the payload.
   (string, grpc:Headers) payload => {
       string result;
       grpc:Headers resHeaders;
       (result, resHeaders) = payload;
       io:println("Response received : " + result);
   }
   // If an error is returned, print the error message.
   error err => {
       io:println("Error while connecting grpc end-point : " + err.message);
   }
}

Server Streaming

The sample given below shows a server streaming service.

// Server endpoint configuration.
endpoint grpc:Listener ep {
   host:"localhost",
   port:9090
};

service ServerStreaming bind ep {
   // Set the Streaming Annotation to ‘true’. It specifies that the resource is capable of sending multiple responses per request.
   @grpc:ResourceConfig {streaming:true}
   receiveMessage(endpoint caller, string name) {
       string[] greets = ["Hi", "Welcome"];
       io:println("HelloWorld");
       // Send multiple responses to the client.
       foreach greet in greets {
           error? err = caller->send(greet + " " + name + "! Greetings from Ballerina service");
           // If an error is returned, print the error message. print response message otherwise.
           io:println(err.message but { () => "send reply: " + greet + " " + name });
       }
       // Once the messages are sent to the server, call ‘complete()’ to indicate that the request was completely sent.
       _ = caller->complete();
   }
}

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

// Keep track of the message that were completely received.
boolean isCompleted = false;
function main (string... args) {
   // Client endpoint configurations.
    endpoint ServerStreamingClient serverStreamingEp {
       host: "localhost",
       port: 9090
    };

    // Execute the service streaming call by registering a message listener.
    error? result = serverStreamingEp->receiveMessage("test", ServerStreamingMessageListener);
    match result {
         // If the service returns an error, print the error.
        error payloadError => {
            io:println("Error occured while sending event " + payloadError.message);
        }
        () => {
            io:println("Connected successfully to service");
        }
    }
   // Waits for the service to send the message.
   while (!isCompleted) {}
}

// Define a listener service to receive the messages from the server.
service<grpc:Service> ServerStreamingMessageListener {
   // This resource method is invoked when the service receives a message.
   onMessage (string message) {
       io:println("Response received from server: " + message);
   }
   
   // This resource method is invoked if an error is returned.
   onError (error err) {
       if (err != ()) {
           io:println("Error reported from server: " + err.message);
       }
   }

   // Invoke this resource when the server sends all the responses to the request.
   onComplete () {
       isCompleted = true;
       io:println("Server Complete Sending Responses.");
   }
}

Bidirectional Streaming

The sample 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 bind ep {
    // This resource method is invoked when there is a connection request from a client.
   onOpen(endpoint caller) {
       
   }
    // This resource method is invoked when the client sends a request.
   onMessage(endpoint caller, string message) {
   
   }
    // This resource method is invoked when the client returns an error while sending requests.
   onError(endpoint caller, error err) {
   
   }
    // This resource method is invoked when the client has finished sending requests.
   onComplete(endpoint caller) {
   
   }
}

The sample given below calls the above service.

endpoint grpc:Client ep;

// Call the relevant service.
var res = chatEp -> chat(ChatMessageListener);
match res {
   // If an error is returned while connecting to the service, print the error.
   error err => {
       io:print("error");
   }
   grpc:Client con => {
       ep = con;
   }
}

// Send multiple messages to the service.
error connErr = ep -> send(“Hello”);

// After sending the message, call ‘complete()’ to indicate that the request was completely sent. 
_ = ep -> complete();

Annotations

Name Attachement Points Data Type Description
ResourceConfig resource GrpcResourceConfig

Service resource configuration. Sets only for server streaming service.

ServiceConfig service GrpcServiceConfig

Service configuration. Sets only for client and bidirectional streaming service.

ServiceDescriptor service ServiceDescriptorData

Service descriptor data generated at compile time. This is for internal use.

Records Summary

Record Description
ClientEndpointConfig Represents client endpoint configuration.
GrpcResourceConfig Service resource configuration. Sets only for server streaming service.
GrpcServiceConfig Service configuration. Sets only for client and bidirectional streaming service.
KeyStore KeyStore record represents key store related options to be used for HTTP client/service invocation.
Protocols Protocols record represents SSL/TLS protocol related options to be used for HTTP client/service invocation.
SecureSocket SecureSocket struct represents SSL/TLS options to be used for gRPC client invocation.
ServiceDescriptorData Service descriptor data. This is for internal use.
ServiceEndpointConfiguration Represents the gRPC server endpoint configuration.
ServiceOcspStapling OcspStapling record represents options related to check whether a certificate is revoked or not.
ServiceSecureSocket SecureSocket struct represents SSL/TLS options to be used for gRPC service.
TrustStore TrustStore record represents trust store related options to be used for HTTP client/service invocation.
ValidateCert ValidateCert record represents options related to check whether a certificate is revoked or not.

Objects Summary

Object Description
CallerAction

Provides the gRPC actions for interacting with caller.

GrpcClient

Provides the gRPC actions for interacting with gRPC server.

Headers

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

Service
Stub

gRPC Service Stub for outbound gRPC requests. gRPC client code not directly calls these functions. Generated client endpoint actions uses these functions to interact with gRPC service.

Endpoints Summary

Endpoint Description
Client

The gRPC client endpoint provides the capability for initiating contact with a remote gRPC service. The API it provides includes functions to send request/error messages.

Listener

Represents service endpoint where one or more services can be registered. so that ballerina program can offer service through this endpoint.

Global Variables

Name Data Type Description
ABORTED int

Indicates the operation was aborted.

ALREADY_EXISTS int

Indicates the attempt to create an entity failed because one already exists.

CANCELED int

Indicates the operation was canceled (typically by the caller).

DATA_LOSS int

Indicates unrecoverable data loss or corruption.

DEADLINE_EXCEEDED int

Indicates operation expired before completion.

FAILED_PRECONDITION int

Indicates operation was rejected because the system is not in a state required for the operation's execution.

INTERNAL int

Indicates internal errors.

INVALID_ARGUMENT int

Indicates client specified an invalid argument.

NOT_FOUND int

Indicates some requested entity (e.g., file or directory) was not found.

OK int

Indicates operation is successful.

OUT_OF_RANGE int

Indicates specified value is out of range.

PERMISSION_DENIED int

Indicates the caller does not have permission to execute the specified operation.

RESOURCE_EXHAUSTED int

Indicates some resource has been exhausted.

UNAUTHENTICATED int

Indicates the request does not have valid authentication credentials for the operation.

UNAVAILABLE int

Indicates the service is currently unavailable.

UNIMPLEMENTED int

Indicates operation is not implemented or not supported/enabled in this service.

UNKNOWN int

Indicates unknown error.(e.g. Status value received is unknown)

public type ClientEndpointConfig

Represents client endpoint configuration.

Field Name Data Type Default Value Description
url string
  • The server url.
secureSocket grpc:0.0.0:SecureSocket?
  • The SSL configurations for the client endpoint.

public type GrpcResourceConfig

Service resource configuration. Sets only for server streaming service.

Field Name Data Type Default Value Description
streaming boolean
  • Server streaming flag. This flag sets to true to specify that the resource is capable of sending multiple responses per request.

public type GrpcServiceConfig

Service configuration. Sets only for client and bidirectional streaming service.

Field Name Data Type Default Value Description
name string
  • Resource name. This applies only for client streaming and bidirectional streaming where we can define only one resource. In order to generate proto file, service resource name need to pass as annotation parameter.
clientStreaming boolean
  • Client streaming flag. This applies only for client streaming and bidirectional streaming. Flag sets to true, if the service defines as client/bidirectional streaming.
serverStreaming boolean
  • Server streaming flag. This applies only for bidirectional streaming. Flag sets to true, if the service defines as bidirectional streaming.

public type KeyStore

KeyStore record represents key store related options to be used for HTTP client/service invocation.

Field Name Data Type Default Value Description
path string

File path to key store file

password string

Key store password

public type Protocols

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

Field Name Data Type Default Value Description
name string

SSL Protocol to be used. eg TLS1.2

versions string[]

SSL/TLS protocols to be enabled. eg TLSv1,TLSv1.1,TLSv1.2

public type SecureSocket

SecureSocket struct represents SSL/TLS options to be used for gRPC client invocation.

Field Name Data Type Default Value Description
trustStore grpc:0.0.0:TrustStore?
  • TrustStore related options.
keyStore grpc:0.0.0:KeyStore?
  • KeyStore related options.
protocol grpc:0.0.0:Protocols?
  • SSL/TLS protocol related options.
certValidation grpc:0.0.0:ValidateCert?
  • Certificate validation against CRL or OCSP related options.
ciphers string[]
  • List of ciphers to be used. eg: TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256, TLS_ECDHE_RSA_WITH_AES_128_CBC_SHA.
verifyHostname boolean true
  • Enable/disable host name verification.
shareSession boolean true
  • Enable/disable new ssl session creation.
ocspStapling boolean
  • Enable/disable ocsp stapling.

public type ServiceDescriptorData

Service descriptor data. This is for internal use.

Field Name Data Type Default Value Description
descriptor string
  • Service descriptor sets at compile time.

public type ServiceEndpointConfiguration

Represents the gRPC server endpoint configuration.

Field Name Data Type Default Value Description
host string
  • The server hostname.
port int
  • The server port.
secureSocket grpc:0.0.0:ServiceSecureSocket?
  • The SSL configurations for the client endpoint.

public type ServiceOcspStapling

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

Field Name Data Type Default Value Description
enable boolean

The status of OcspStapling

cacheSize int

Maximum size of the cache

cacheValidityPeriod int

Time duration of cache validity period

public type ServiceSecureSocket

SecureSocket struct represents SSL/TLS options to be used for gRPC service.

Field Name Data Type Default Value Description
trustStore grpc:0.0.0:TrustStore?
  • TrustStore related options.
keyStore grpc:0.0.0:KeyStore?
  • KeyStore related options.
protocol grpc:0.0.0:Protocols?
  • SSL/TLS protocol related options.
certValidation grpc:0.0.0:ValidateCert?
  • Certificate validation against CRL or OCSP related options.
ciphers string[]
  • List of ciphers to be used. eg: TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256, TLS_ECDHE_RSA_WITH_AES_128_CBC_SHA.
sslVerifyClient string
  • The type of client certificate verification.
shareSession boolean true
  • Enable/disable new ssl session creation.
ocspStapling grpc:0.0.0:ServiceOcspStapling?
  • Enable/disable ocsp stapling.

public type TrustStore

TrustStore record represents trust store related options to be used for HTTP client/service invocation.

Field Name Data Type Default Value Description
path string

File path to trust store file

password string

Trust store password

public type ValidateCert

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

Field Name Data Type Default Value Description
enable boolean

The status of validateCertEnabled

cacheSize int

Maximum size of the cache

cacheValidityPeriod int

Time duration of cache validity period

public type CallerAction object

Provides the gRPC actions for interacting with caller.

  • <CallerAction> send(any res, grpc:0.0.0:Headers? headers) returns (error)

    Sends outbound response to the caller.

    Parameter Name Data Type Default Value Description
    res any
    • The outbound response message.
    headers grpc:0.0.0:Headers? null
    • Optional headers parameter. Passes header value if needed. Default sets to nil.
    Return Type Description
    error
    • Returns an error if encounters an error while sending the response, returns nil otherwise.
  • <CallerAction> complete(grpc:0.0.0:Headers? headers) returns (error)

    Informs the caller, server finished sending messages.

    Parameter Name Data Type Default Value Description
    headers grpc:0.0.0:Headers? null
    • Optional headers parameter. Passes header value if needed. Default sets to nil.
    Return Type Description
    error
    • Returns an error if encounters an error while sending the response, returns nil otherwise.
  • <CallerAction> isCancelled() returns (boolean)

    Checks whether the connection is closed by the caller.

    Return Type Description
    boolean
    • Returns true, if caller already closed the connection. false otherwise.
  • <CallerAction> sendError(int statusCode, string message, grpc:0.0.0:Headers? headers) returns (error)

    Sends server error to the caller.

    Parameter Name Data Type Default Value Description
    statusCode int
    • Error status code.
    message string
    • Error message.
    headers grpc:0.0.0:Headers? null
    • Optional headers parameter. Passes header value if needed. Default sets to nil.
    Return Type Description
    error
    • Returns an error if encounters an error while sending the response, returns nil otherwise.

public type GrpcClient object

Provides the gRPC actions for interacting with gRPC server.

  • <GrpcClient> send(any res) returns (error)

    Sends request message to the server.

    Parameter Name Data Type Default Value Description
    res any
    • The inbound request message.
    Return Type Description
    error
    • Returns an error if encounters an error while sending the response, returns nil otherwise.
  • <GrpcClient> complete() returns (error)

    Informs the server, caller finished sending messages.

    Return Type Description
    error
    • Returns an error if encounters an error while sending the response, returns nil otherwise.
  • <GrpcClient> sendError(int statusCode, string message) returns (error)

    Sends error message to the server.

    Parameter Name Data Type Default Value Description
    statusCode int
    • Error status code.
    message string
    • Error message.
    Return Type Description
    error
    • Returns an error if encounters an error while sending the response, returns nil otherwise.

public type Headers object

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

  • <Headers> exists(string headerName) returns (boolean)

    Check whether the requested header exists.

    Parameter Name Data Type Default Value Description
    headerName string
    • The header name.
    Return Type Description
    boolean
    • Returns true if header exists, false otherwise.
  • <Headers> get(string headerName) returns (string)

    Returns the header value with the specified header name. If there are more than one header value for the specified header name, the first value is returned.

    Parameter Name Data Type Default Value Description
    headerName string
    • The header name.
    Return Type Description
    string
    • Returns first header value if exists, nil otherwise.
  • <Headers> getAll(string headerName) returns (string[])

    Gets all transport headers with the specified header name.

    Parameter Name Data Type Default Value Description
    headerName string
    • The header name.
    Return Type Description
    string[]
    • Returns header value array.
  • <Headers> setEntry(string headerName, string headerValue)

    Sets the value of a transport header.

    Parameter Name Data Type Default Value Description
    headerName string
    • The header name.
    headerValue string
    • The header value.
  • <Headers> addEntry(string headerName, string headerValue)

    Adds the specified key/value pair as an HTTP header to the request.

    Parameter Name Data Type Default Value Description
    headerName string
    • The header name.
    headerValue string
    • The header value.
  • <Headers> remove(string headerName)

    Removes a transport header from the request.

    Parameter Name Data Type Default Value Description
    headerName string
    • The header name.
  • <Headers> removeAll()

    Removes all transport headers from the message.

public type Service object

public type Stub object

gRPC Service Stub for outbound gRPC requests. gRPC client code not directly calls these functions. Generated client endpoint actions uses these functions to interact with gRPC service.

Field Name Data Type Default Value Description
client grpc:0.0.0:Client
  • <Stub> initStub(any clientEndpoint, string stubType, string descriptorKey, map descriptorMap)

    Calls when initializing client endpoint with service descriptor data extracted from proto file.

    Parameter Name Data Type Default Value Description
    clientEndpoint any
    • client endpoint struct.
    stubType string
    • Service Stub type. possible values: blocking, nonblocking.
    descriptorKey string
    • Proto descriptor key. Key of proto descriptor.
    descriptorMap map
    • Proto descriptor map. descriptor map with all dependent descriptors.
  • <Stub> blockingExecute(string methodID, any payload, grpc:0.0.0:Headers? headers) returns ((any,Headers) | error)

    Calls when executing blocking call with gRPC service.

    Parameter Name Data Type Default Value Description
    methodID string
    • Remote service method id.
    payload any
    • Request message. Message type varies with remote service method parameter.
    headers grpc:0.0.0:Headers? null
    • Optional headers parameter. Passes header value if needed. Default sets to nil.
    Return Type Description
    (any,Headers) | error
    • Returns response message and headers if executes successfully, error otherwise.
  • <Stub> nonBlockingExecute(string methodID, any payload, typedesc listenerService, grpc:0.0.0:Headers? headers) returns (error)

    Calls when executing non-blocking call with gRPC service.

    Parameter Name Data Type Default Value Description
    methodID string
    • Remote service method id.
    payload any
    • Request message. Message type varies with remote service method parameter..
    listenerService typedesc
    • Call back listener service. This service listens the response message from service.
    headers grpc:0.0.0:Headers? null
    • Optional headers parameter. Passes header value if needed. Default sets to nil.
    Return Type Description
    error
    • Returns an error if encounters an error while sending the request, returns nil otherwise.
  • <Stub> streamingExecute(string methodID, typedesc listenerService, grpc:0.0.0:Headers? headers) returns (Client | error)

    Calls when executing streaming call with gRPC service.

    Parameter Name Data Type Default Value Description
    methodID string
    • Remote service method id.
    listenerService typedesc
    • Call back listener service. This service listens the response message from service.
    headers grpc:0.0.0:Headers? null
    • Optional headers parameter. Passes header value if needed. Default sets to nil.
    Return Type Description
    Client | error
    • Returns client connection if executes successfully, error otherwise.

Endpoint Client

The gRPC client endpoint provides the capability for initiating contact with a remote gRPC service. The API it provides includes functions to send request/error messages.

  • <Client> send(any res) returns (error?)

    Sends request message to the server.

    Parameter Name Data Type Default Value Description
    res any
    Return Type Description
    error?
  • <Client> complete() returns (error?)

    Informs the server, caller finished sending messages.

    Return Type Description
    error?
  • <Client> sendError(int statusCode, string message) returns (error?)

    Sends error message to the server.

    Parameter Name Data Type Default Value Description
    statusCode int
    message string
    Return Type Description
    error?

Endpoint Listener

Represents service endpoint where one or more services can be registered. so that ballerina program can offer service through this endpoint.

Field Name Data Type Default Value Description
id int
  • Caller endpoint id.
  • <Listener> send(any res, grpc:0.0.0:Headers? headers) returns (error?)

    Sends outbound response to the caller.

    Parameter Name Data Type Default Value Description
    res any
    headers grpc:0.0.0:Headers?
    Return Type Description
    error?
  • <Listener> complete(grpc:0.0.0:Headers? headers) returns (error?)

    Informs the caller, server finished sending messages.

    Parameter Name Data Type Default Value Description
    headers grpc:0.0.0:Headers?
    Return Type Description
    error?
  • <Listener> isCancelled() returns (boolean)

    Checks whether the connection is closed by the caller.

    Return Type Description
    boolean
  • <Listener> sendError(int statusCode, string message, grpc:0.0.0:Headers? headers) returns (error?)

    Sends server error to the caller.

    Parameter Name Data Type Default Value Description
    statusCode int
    message string
    headers grpc:0.0.0:Headers?
    Return Type Description
    error?