gRPC / Protobuf

This Handler allows you to load gRPC definition files (.proto).

npm i @graphql-mesh/grpc

yarn add @graphql-mesh/grpc

pnpm add @graphql-mesh/grpc

bun add @graphql-mesh/grpc

Now, you can use it directly in your Mesh config file:

sources:
  - name: MyGrpcApi
    handler:
      grpc:
        endpoint: localhost:50051
        source: grpc/proto/Example.proto

Use Reflection instead of proto files

If you have configured reflection in your gRPC server, you don’t need to provide source.

sources:
  - name: gRPC Example
    handler:
      grpc:
        endpoint: localhost:50051

Custom Metadata for Authorization

Here you can use metaData field to pass some custom metadata from the context.

sources:
  - name: MyGrpcApi
    handler:
      grpc:
        endpoint: localhost:50051
        source: grpc/proto/Example.proto
        metaData:
          authorization: 'Bearer {context.headers['x-my-token']}'
          someStaticValue: 'MyStaticValue'

Reflection Metadata (reflectionMetadata)

When using gRPC reflection (no source), use reflectionMetadata to send metadata only on reflection requests — for example routing headers required by your infrastructure:

sources:
  - name: MyGrpcApi
    handler:
      grpc:
        endpoint: localhost:50051
        reflectionMetadata:
          grpc-service: proto.MyGrpcService
          authorization: 'Bearer {env.REFLECTION_TOKEN}'

Channel Options & Timeouts

• requestTimeout sets a per-call deadline (milliseconds from the start of each request).
• channelOptions are passed to the gRPC client constructor (message size limits, keepalive, etc.):

sources:
  - name: MyGrpcApi
    handler:
      grpc:
        endpoint: localhost:50051
        requestTimeout: 5000
        channelOptions:
          grpc.max_receive_message_length: 10000000
          grpc.keepalive_time_ms: 10000
          grpc.keepalive_timeout_ms: 5000
          grpc.keepalive_permit_without_calls: 1

Config API Reference

• endpoint (type: String, required) - gRPC Endpoint
• source - - gRPC Proto file that contains your protobuf schema OR Use a binary-encoded or JSON file descriptor set file One of:
  • object:
    • file (type: String, required)
    • load (type: Object):
      • defaults (type: Boolean)
      • includeDirs (type: Array of String)
  • String
• requestTimeout (type: Int) - Request timeout in milliseconds Default: 200000
• credentialsSsl (type: Object) - SSL Credentials:
  • rootCA (type: String)
  • certChain (type: String)
  • privateKey (type: String)
• useHTTPS (type: Boolean) - Use https instead of http for gRPC connection
• metaData (type: JSON) - MetaData
• prefixQueryMethod (type: Array of String) - prefix to collect Query method default: list, get
• selectQueryOrMutationField (type: Array of Object) - Allows to explicitly override the default operation (Query or Mutation) for any gRPC operation:
  • type (type: String (query | mutation | Query | Mutation), required)
  • fieldName (type: String, required)
• schemaHeaders (type: JSON) - HTTP headers when source points to a remote .graphql SDL
• reflectionMetadata (type: JSON) - gRPC metadata sent with server-reflection requests (e.g. routing / auth metadata). Only used when loading the schema via reflection (no source / empty source).
• channelOptions (type: JSON) - Channel options passed to the gRPC client (e.g. grpc.max_receive_message_length, grpc.keepalive_time_ms). See https://grpc.github.io/grpc/core/group__grpc__arg__keys.html