Using a gRPC client in Play

Akka gRPC has special support to allow for seamless injection of generated clients in Play. To enable this, you need first to enable the gRPC plugin as described in the client docs and then add a source generator in build.sbt:

Scala
import akka.grpc.gen.scaladsl.play.PlayScalaClientCodeGenerator
akkaGrpcExtraGenerators += PlayScalaClientCodeGenerator
Java
import akka.grpc.gen.javadsl.play.PlayJavaClientCodeGenerator
akkaGrpcExtraGenerators += PlayJavaClientCodeGenerator

This will generate a Play module that provides all generated clients for injection. The module must be enabled by adding it to the enabled modules in the application.conf.

You can then put the following helloworld.proto file in app/protobuf:

syntax = "proto3";

option java_multiple_files = true;
option java_package = "example.myapp.helloworld.grpc";
option java_outer_classname = "HelloWorldProto";

package helloworld;

service GreeterService {
    rpc SayHello (HelloRequest) returns (HelloReply) {}
}

message HelloRequest {
    string name = 1;
}

message HelloReply {
    string message = 1;
}
Full source at GitHub

The module file is generated in example.myapp.helloworld.grpc.helloworld.AkkaGrpcClientModule by default for Scala example.myapp.helloworld.grpc.AkkaGrpcClientModule by default for Java, which corresponds to the default value of flat_package for JavaScala. You can read more about this in Services.

The exact package of the module will be based on the package the proto files are generated in, configured through the java_package option in the proto-file (if there are multiple different gRPC generated clients the module will be generated in the longest package prefix shared between the clients).

To hook it into Play, in application.conf:

Scala
// enable the client module
play.modules.enabled += example.myapp.helloworld.grpc.helloworld.AkkaGrpcClientModule
Full source at GitHub
Java
// enable the client module
play.modules.enabled += example.myapp.helloworld.grpc.AkkaGrpcClientModule
Full source at GitHub

The clients are configured with entries under akka.grpc.client named after the client (gRPC package name dot ServiceName), again, in application.conf:

akka.grpc.client {
  "helloworld.GreeterService" {
    host = "example.com"
    port = 9000
    # By default we connect over TLS
    #use-tls = false
  }
}
Full source at GitHub

See Client Configuration for more information on the available options. If the configuration is not present for that client and it is used by some other component, the application start will fail with an exception when injecting the client (see #271).

You can now use the client in a controller by injecting it:

Scala
package controllers

import example.myapp.helloworld.grpc.helloworld.GreeterServiceClient
import example.myapp.helloworld.grpc.helloworld.HelloRequest
import javax.inject.Inject
import javax.inject.Singleton
import play.api.mvc.AbstractController
import play.api.mvc.ControllerComponents

import scala.concurrent.ExecutionContext

@Singleton
class MyController @Inject()(
    implicit greeterClient: GreeterServiceClient,
    cc: ControllerComponents,
    exec: ExecutionContext,
) extends AbstractController(cc) {

  def sayHello(name: String) = Action.async {
    greeterClient
      .sayHello(HelloRequest(name))
      .map { reply =>
        Ok(s"response: ${reply.message}")
      }
  }

}
Full source at GitHub
Java
package controllers;

import example.myapp.helloworld.grpc.GreeterServiceClient;
import example.myapp.helloworld.grpc.HelloRequest;
import play.mvc.Controller;
import play.mvc.Result;

import javax.inject.Inject;
import javax.inject.Singleton;
import java.util.concurrent.CompletionStage;

@Singleton
public class MyController extends Controller {

  private final GreeterServiceClient greeterServiceClient;

  @Inject
  public MyController(GreeterServiceClient greeterServiceClient) {
    this.greeterServiceClient = greeterServiceClient;
  }

  public CompletionStage<Result> sayHello(String name) {
    return greeterServiceClient
        .sayHello(HelloRequest.newBuilder().setName(name).build())
        .thenApply(response -> ok("response: " + response.getMessage()));
  };
}
Full source at GitHub
Found an error in this documentation? The source code for this page can be found here. Please feel free to edit and contribute a pull request.