Contact Us 1-800-596-4880
  1. Homepage
  2. APIkit (4.x)
  3. APIkit for gRPC

  4. Module Reference

APIkit for gRPC Module Reference

Implement gRPC APIs in Mule applications with APIkit for gRPC: declare dependencies, namespaces, and configuration elements that wire Protocol Buffer (.proto) services into flows. This reference lists Maven coordinates, XML schema locations, grpc:config, operations, and sources you use when you scaffold or customize gRPC endpoints.

Dependencies

Add the gRPC Connector (server) dependency to your Mule project:

<dependency>
  <groupId>com.mulesoft.connectors</groupId>
  <artifactId>mule-grpc-connector</artifactId>
  <version>LATEST_VERSION</version> (1)
  <classifier>mule-plugin</classifier>
</dependency>
1 To get the LATEST_VERSION, check the APIkit Release Notes .

Namespace and Schema

Use this namespace and schema location in your Mule configuration:

xmlns:grpc="http://www.mulesoft.org/schema/mule/grpc"
xsi:schemaLocation="http://www.mulesoft.org/schema/mule/grpc http://www.mulesoft.org/schema/mule/grpc/current/mule-grpc.xsd"

Configurations

grpc:server-config

Configures the gRPC server that listens for incoming gRPC requests. This element wraps the connection provider, which defines the listening endpoint and the Interface Description Language (IDL) definition that describes the service and message types.

Parameters

Name Type Description Default Value Required

Name

String

Identifier of this element used to reference it in other components.

None

Yes

maxInboundMessageSize

Number

Maximum size in bytes for inbound gRPC messages. Messages exceeding this size are rejected.

4194304 (4 MB)

No

Example

<grpc:server-config name="GRPC_Server_Config">
  <grpc:grpc-server-connection listenerConfig="HTTP_Listener_config">
    <grpc:idl-definition>
      <grpc:single-binary-protobuf protobufDescriptorFile="${grpc.server.descriptor.file}" />
    </grpc:idl-definition>
  </grpc:grpc-server-connection>
</grpc:server-config>

Associated Operations

Associated Sources

grpc:grpc-server-connection

Connection provider for the gRPC server. The gRPC server doesn’t independently configure host, port, or TLS; it uses an existing HTTP listener. This connection references an http:listener-config for the listening endpoint and defines the protobuf descriptor (IDL) that describes the service and message types.

Parameters

Parameter Type Description Default Value Required

listenerConfig

ConfigReference to http:listener-config

Reference to the HTTP listener configuration that defines host, port, and TLS. The gRPC server uses this listener for transport.

None

Yes

Child Elements

grpc:idl-definition

Contains the protobuf descriptor (IDL) for the gRPC service. The grpc:single-binary-protobuf definition is supported.

grpc:single-binary-protobuf

Provides the Protocol Buffer descriptor from a binary file (for example, a compiled .proto descriptor file).

Parameter Type Description Default Value Required

protobufDescriptorFile

String

Path or expression (for example, ${grpc.server.descriptor.file}) that resolves to the binary Protobuf descriptor file.

None

Yes

Operations

grpc:send-stream-message

Sends a message on an active server streaming response. To push messages to the client, use this operation within a flow triggered by grpc:server-streaming-method. This operation doesn’t support bidirectional streaming.

Parameters

Parameter Type Description Default Value Required

config-ref

String (Config Reference)

Reference to the grpc:server-config to use.

None

Yes

Payload

Any

The message payload to send. It should conform to the message type defined in the Interface Description Language (IDL) for the streaming method.

#[payload]

No

Target Variable

String

Name of a variable on which the operation output is placed.

None

No

Target Value

String

Expression evaluated against the operation output. The result is stored in the target variable.

#[payload]

No

Configurations

grpc:end-stream

Ends the current server stream. Call this operation after sending all messages to the client. This operation doesn’t support bidirectional streaming.

Parameters

Parameter Type Description Default Value Required

config-ref

String (Config Reference)

Reference to the grpc:server-config to use.

None

Yes

Target Variable

String

Name of a variable on which the operation output is placed.

None

No

Target Value

String

Expression evaluated against the operation output. The result is stored in the target variable.

#[payload]

No

Configurations

Sources (Listeners)

Unary Method

<grpc:unary-method>

Handles unary RPCs: one request from the client and one response from the server.

Parameters

Parameter Type Description Default Value Required

config-ref

String (Config Reference)

Reference to the grpc:server-config to use.

None

Yes

methodName

String

Fully qualified method name in the format ServiceName/MethodName (for example, com.example.MyService/MyMethod).

None

Yes

Primary Node Only

Boolean

Whether this source runs only on the primary node in a cluster.

false

No

Redelivery Policy

Object

Policy for redelivery of the same message.

None

No

Output

Type

Any (message type from IDL)

Configurations

Client Streaming Method

<grpc:client-streaming-method>

Handles client streaming RPCs: the client sends a stream of messages and the server responds with a single message.

Parameters

Parameter Type Description Default Value Required

config-ref

String (Config Reference)

Reference to the grpc:server-config to use.

None

Yes

methodName

String

Fully qualified method name in the format ServiceName/MethodName (for example, com.example.MyService/MyMethod).

None

Yes

Primary Node Only

Boolean

Whether this source runs only on the primary node in a cluster.

false

No

Redelivery Policy

Object

Policy for redelivery of the same message.

None

No

Child Elements

grpc:output

Optional nested element that defines the response and stream state for the client streaming method. Only grpc:client-streaming-method has this element. Unary and server streaming don’t use this element.

Parameter Type Description Default Value Required

response

TypedValue<InputStream>

Response payload. Only effective on the final flow execution when attributes.streamCompleted is true.

#[payload]

No

streamState

Map<String, Object>

State persisted across messages via attributes.streamState.

#[{}]

No

Specify stream state in two ways:

  • Attribute form (expression): streamState="#[vars.myState]".

  • Nested element form (often generated by the scaffolder): use grpc:stream-states with one or more grpc:stream-state children, each with key and value attributes.

<grpc:output response="#[payload]">
  <grpc:stream-states>
    <grpc:stream-state key="orderId" value="#[vars.orderId]" />
    <grpc:stream-state key="total" value="#[vars.total]" />
  </grpc:stream-states>
</grpc:output>

Output

Type

Stream of Any (message type from IDL)

Configurations

Server Streaming Method

<grpc:server-streaming-method>

Handles server streaming RPCs: the client sends one request and the server responds with a stream of messages. Use grpc:send-stream-message and grpc:end-stream within the flow to send messages and close the stream.

Parameters

Parameter Type Description Default Value Required

config-ref

String (Config Reference)

Reference to the grpc:server-config to use.

None

Yes

methodName

String

Fully qualified method name in the format ServiceName/MethodName (for example, com.example.MyService/MyMethod).

None

Yes

onCapacityOverload

Enum: WAIT, DROP

Backpressure strategy when the flow’s maxConcurrency is reached. See Backpressure Strategy.

WAIT

No

Primary Node Only

Boolean

Whether this source runs only on the primary node in a cluster.

false

No

Redelivery Policy

Object

Policy for redelivery of the same message.

None

No

Output

Type

Any (request message type from IDL); response is sent via grpc:send-stream-message and grpc:end-stream

Configurations

Bidirectional Streaming Method

<grpc:bidirectional-streaming-method>

Handles bidirectional streaming RPCs: both client and server send streams of messages independently. The operations grpc:send-stream-message and grpc:end-stream don’t support bidirectional streaming. Use the nested grpc:stream-output child element to send inline response messages.

Parameters

Parameter Type Description Default Value Required

config-ref

String (Config Reference)

Reference to the grpc:server-config to use.

None

Yes

methodName

String

Fully qualified method name in the format ServiceName/MethodName (for example, com.example.MyService/MyMethod).

None

Yes

Primary Node Only

Boolean

Whether this source runs only on the primary node in a cluster.

false

No

Redelivery Policy

Object

Policy for redelivery of the same message.

None

No

Child Elements

grpc:stream-output

Optional nested element that defines the response and stream state for the bidirectional streaming method. Use it to send inline response messages to the client.

Parameter Type Description Default Value Required

response

TypedValue<InputStream>

Response payload sent to the client.

#[payload]

No

streamState

Map<String, Object>

State persisted across messages via attributes.streamState.

#[{}]

No

Specify stream state in two ways. Attribute form: streamState="[vars.state]". Nested element form: use grpc:stream-states with grpc:stream-state children (each with key and value attributes), for example <grpc:stream-state key="orderId" value="[vars.orderId]" />.

Output

Type

Stream of Any (message type from IDL). Send response messages using the nested grpc:stream-output element.

Configurations

Backpressure Strategy

The gRPC connector uses Mule’s built-in backpressure mechanism. To define how many requests can be processed concurrently, set maxConcurrency on the <flow> element (for example, <flow name="MyFlow" maxConcurrency="3">). When that limit is reached, the source applies a backpressure strategy to new incoming requests. The connector does not implement its own concurrency limit. Instead it responds to Mule runtime’s concurrency control.

For more information, see Back-Pressure and MaxConcurrency.

  • onCapacityOverload (server streaming only): For grpc:server-streaming-method, the onCapacityOverload attribute chooses the behavior when the flow’s maxConcurrency is reached. Other sources use a fixed mode (see table below).

    • WAIT: New requests wait until a concurrency slot becomes available. The request is eventually processed.

    • DROP: New requests are rejected immediately. The client receives gRPC status RESOURCE_EXHAUSTED (8).

    • FAIL: New requests are rejected immediately. The client receives gRPC status UNAVAILABLE (14). This is the only mode for unary.

Source Default Mode Supported Modes Notes

grpc:unary-method

FAIL

FAIL

Excess requests are immediately rejected with UNAVAILABLE.

grpc:server-streaming-method

WAIT

WAIT, DROP

Configurable via onCapacityOverload attribute on the source (default WAIT).

grpc:client-streaming-method

WAIT

WAIT

Incoming messages queue until a slot is available.

grpc:bidirectional-streaming-method

WAIT

WAIT

Incoming messages queue until a slot is available.

Error Handling

gRPC uses status code 0 (OK) for successful responses. This is not an error type. The following sections describe error conditions (status codes 1–16) and how they map to Mule error types.

Error Type Hierarchy

All gRPC protocol errors extend the base type GRPC:GRPC_ERROR. In error handlers, reference GRPC:GRPC_ERROR to catch any gRPC protocol error, or reference a specific type for finer-grained handling.

gRPC Protocol Errors

The Mule error types in this table map to gRPC status codes. These errors extend GRPC:GRPC_ERROR.

Mule Error Type gRPC Code Description

GRPC:CANCELLED

1

Request was cancelled

GRPC:GRPC_UNKNOWN

2

Unknown error

GRPC:INVALID_ARGUMENT

3

Invalid argument

GRPC:DEADLINE_EXCEEDED

4

Deadline exceeded

GRPC:NOT_FOUND

5

Resource not found

GRPC:ALREADY_EXISTS

6

Resource exists

GRPC:PERMISSION_DENIED

7

Permission denied

GRPC:RESOURCE_EXHAUSTED

8

Resource exhausted

GRPC:FAILED_PRECONDITION

9

Failed precondition

GRPC:ABORTED

10

Operation aborted

GRPC:OUT_OF_RANGE

11

Argument out of range

GRPC:UNIMPLEMENTED

12

Operation not implemented

GRPC:INTERNAL

13

Internal error

GRPC:UNAVAILABLE

14

Service unavailable

GRPC:DATA_LOSS

15

Data loss

GRPC:UNAUTHENTICATED

16

Request not authenticated

Connector-Level Errors

The error types in this table are thrown by the connector for validation, transformation, and connectivity issues. They’re not gRPC protocol status codes but Mule error types used by the gRPC connector.

Error Type Description

GRPC:VALIDATION

Thrown after request or message validation fails (for example, schema or IDL validation).

GRPC:TRANSFORMATION

Thrown after message transformation fails (for example, serialization or deserialization of Protobuf messages).

GRPC:CONNECTIVITY

Thrown after a connectivity issue occurs (for example, connection refused or transport error).

See Also