ballerina/grpc package

Primitives Summary

Type Description

Type Definitions

Type Values Description
Chunking NEVER | AUTO | ALWAYS
Compression NEVER | AUTO | ALWAYS
TransferEncoding CHUNKING

Annotations

Name Attachement Points Data Type Description
ResourceConfig resource GrpcResourceConfig
gRPC service resource configuration annotation.
ServiceConfig service GrpcServiceConfig
gRPC service configuration annotation.
ServiceDescriptor service ServiceDescriptorData
gRPC service internal annotation which is to attach service descriptor generated at compile time.

Objects Summary

Object Description
ClientEndpointConfig
Represents the gRPC client endpoint configuration.
GrpcResourceConfig
gRPC service resource configuration.
GrpcServiceConfig
gRPC service configuration.
KeyStore
KeyStore record represents key store related options to be used for HTTP client/service invocation.
PayloadError
Represent all http payload related.
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
gRPC service descriptor data.
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.

Endpoints Summary

Endpoint Description

Functions Summary

Return Type Function and Description

Global Variables

Name Data Type Description
CHUNKING_ALWAYS Chunking
CHUNKING_AUTO Chunking
CHUNKING_NEVER Chunking
COMPRESSION_ALWAYS Compression
COMPRESSION_AUTO Compression
COMPRESSION_NEVER Compression
TRANSFERENCODE_CHUNKING TransferEncoding

public object ClientEndpointConfig

Represents the gRPC client endpoint configuration.

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

public object GrpcResourceConfig

gRPC service resource configuration.

Field Name Data Type Default Value Description
streaming boolean
  • gRPC server streaming flag. This flag sets to true when service resource is considered as server streaming.

public object GrpcServiceConfig

gRPC service configuration.

Field Name Data Type Default Value Description
name string
  • gRPC resource name. This applies only for client streaming and bidirectional streaming where we can define only one resource. In order to generate proto file, we need resource name.
clientStreaming boolean
  • gRPC client streaming service flag. This applies only for servicestub streaming and bidirectional streaming. Flag sets to true, if the service is client/bidirectional streaming.
serverStreaming boolean
  • gRPC server streaming service flag. This applies only for client streaming and bidirectional streaming. Flag sets to true, if the service is bidirectional streaming.

public object 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 object PayloadError

Represent all http payload related.

Field Name Data Type Default Value Description
message string

The error message

cause error

The error which caused the entity error

public object 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 object SecureSocket

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

Field Name Data Type Default Value Description
trustStore TrustStore
  • TrustStore related options.
keyStore KeyStore
  • KeyStore related options.
protocol Protocols
  • SSL/TLS protocol related options.
certValidation 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 object ServiceDescriptorData

gRPC service descriptor data.

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

public object 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 ServiceSecureSocket
  • The SSL configurations for the client endpoint.

public object 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 object ServiceSecureSocket

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

Field Name Data Type Default Value Description
trustStore TrustStore
  • TrustStore related options.
keyStore KeyStore
  • KeyStore related options.
protocol Protocols
  • SSL/TLS protocol related options.
certValidation 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 ServiceOcspStapling
  • Enable/disable ocsp stapling.

public object 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 object 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

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

        Sends outbound response to the caller.
    

    Parameter Name Data Type Default Value Description
    res any
    • The outbound response message.
    Return Type Description
    error
  • <CallerAction> complete() returns (error)

        Informs the caller, server finished sending messages.
    

    Return Type Description
    error
  • <CallerAction> isCancelled() returns (boolean)

        Checks whether the connection is closed by the caller.
    

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

        Sends server error to the caller.
    

    Parameter Name Data Type Default Value Description
    statusCode int
    • Error status code.
    message string
    • Error message.
    Return Type Description
    error

public type Client object

Represents the gRPC client endpoint.

  • <Client> init(ClientEndpointConfig config)

        Gets called when the endpoint is being initialize during package init time.
    

    Parameter Name Data Type Default Value Description
    config ClientEndpointConfig
    • The ClientEndpointConfig of the endpoint.
  • <Client> register(typedesc serviceType)

        Gets called every time a service attaches itself to this endpoint - also happens at package init time.
        Not supported in client connector.
    

    Parameter Name Data Type Default Value Description
    serviceType typedesc
    • The type of the service to be registered.
  • <Client> start()

        Starts the registered service.
    

  • <Client> stop()

        Stops the registered.
    

  • <Client> getCallerActions() returns (GrpcClient)

        Returns the client connection that servicestub code uses.
    

    Return Type Description
    GrpcClient

public type GrpcClient object

Represents the gRPC client.

Field Name Data Type Default Value Description
port int
  • The server port.
host string
  • The server host name.
  • <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
  • <GrpcClient> complete() returns (error)

        Informs the server, caller finished sending messages.
    

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

        Sends error response to the server.
    

    Parameter Name Data Type Default Value Description
    statusCode int
    • Error status code.
    message string
    • Error message.
    Return Type Description
    error

public type Headers object

  • <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
  • <Headers> get(string headerName) returns (string | null)

        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 | null
  • <Headers> getAll(string headerName) returns (string[])

        Gets transport headers from the request.
    

    Parameter Name Data Type Default Value Description
    headerName string
    • The header name.
    Return Type Description
    string[]
  • <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 Listener object

Represents the gRPC service endpoint.

Field Name Data Type Default Value Description
id int
  • <Listener> init(ServiceEndpointConfiguration config)

        Gets called when the endpoint is being initialize during package init time.
    

    Parameter Name Data Type Default Value Description
    config ServiceEndpointConfiguration
    • The ServiceEndpointConfiguration of the endpoint.
  • <Listener> register(typedesc serviceType)

        Gets called every time a service attaches itself to this endpoint - also happens at package init time.
        Not supported in client connector.
    

    Parameter Name Data Type Default Value Description
    serviceType typedesc
    • The type of the service to be registered.
  • <Listener> start()

        Starts the registered service.
    

  • <Listener> stop()

        Stops the registered service.
    

  • <Listener> getCallerActions() returns (CallerAction)

        Returns the client connection that servicestub code uses.
    

    Return Type Description
    CallerAction

public type Service object

public type Stub object

gRPC Service Stub for outbound gRPC requests.

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

        Init native function for initialize the Stub.
    

    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) returns ((any,Headers) | error)

        Blocking execute function implementation of the gRPC client stub.
    

    Parameter Name Data Type Default Value Description
    methodID string
    • remote procedure call id.
    payload any
    • Any type of request payload.
    Return Type Description
    (any,Headers) | error
  • <Stub> nonBlockingExecute(string methodID, any payload, typedesc listenerService) returns (error)

        Non Blocking execute function implementation of the gRPC client stub.
    

    Parameter Name Data Type Default Value Description
    methodID string
    • remote procedure call id.
    payload any
    • Any type of request payload.
    listenerService typedesc
    • call back listener service.
    Return Type Description
    error
  • <Stub> streamingExecute(string methodID, typedesc listenerService) returns (Client | error)

        Blocking execute function implementation of the gRPC client stub.
    

    Parameter Name Data Type Default Value Description
    methodID string
    • remote procedure call id.
    listenerService typedesc
    • call back listener service.
    Return Type Description
    Client | error