README.md

Dropwizard gRPC

⚠️ THIS PROJECT IS NOT MAINTAINED ANYMORE. ⚠️

A set of classes to use gRPC server in a Dropwizard application.

The package provides lifecycle-management and configuration factory classes with the most common options for gRPC Server and ManagedChannel classes.

Server

To embed a grpc server, add a GrpcServerFactory to your Configuration class. This enables configuration of the grpc server port and transport security files.

ExampleServiceConfiguration.java:

class ExampleServiceConfiguration extends Configuration {
    @Valid
    @NotNull
    private GrpcServerFactory grpcServer = new GrpcServerFactory();

    @JsonProperty("grpcServer")
    public GrpcServerFactory getGrpcServerFactory() {
        return grpcServer;
    }

    @JsonProperty("grpcServer")
    public void setGrpcServerFactory(final GrpcServerFactory grpcServer) {
        this.grpcServer = grpcServer;
    }
}

The following configuration settings are supported by GrpcServerFactory:

• port: Port number the gRPC server should bind on
• shutdownDuration: How long to wait before giving up when the server is shutdown
• certChainFile: (Optional) Path to the certificate chain file when TLS should be used
• privateKeyFile: (Optional) Path to the private key file when TLS should be used

example-service.yml:

server:
    [...]
logging:
    [...]
grpcServer:
    port: 8000
    shutdownDuration: 10 seconds

In dropwizard's run method, use the GrpcServerFactory class to create a gRPC Server instance. The GrpcServerFactory provides a ServerBuilder via builder() to configure the Server instance, e.g. to add a custom executor or to add gRPC service classes. The created server instance is also automatically added to the dropwizard lifecycle.

ExampleServiceApplication.java:

class ExampleServiceApplication extends Application<ExampleServiceConfiguration> {
    [...]

    @Override
    public void run(final ExampleServiceConfiguration configuration, final Environment environment) throws IOException {
        final Server grpcServer;
        grpcServer = configuration.getGrpcServerFactory()
                .builder(environment)
                .addService(new ExampleService())
                .build();
    }

    [...]
}

Client

To embed a grpc channel for a server, add a GrpcChannelFactory to your Configuration class. This enables configuration of the grpc channel hostname and port.

ExampleServiceConfiguration.java:

class ExampleServiceConfiguration extends Configuration {
    @Valid
    @NotNull
    private GrpcChannelFactory externalService = new GrpcChannelFactory();

    @JsonProperty("externalService")
    public GrpcChannelFactory getExternalGrpcChannelFactory() {
        return externalService;
    }

    @JsonProperty("externalService")
    public void setExternalGrpcChannelFactory(final GrpcChannelFactory externalService) {
        this.externalService = externalService;
    }   

}

The following configuration settings are supported by GrpcChannelFactory:

• hostname: Hostname of the gRPC server to connect to
• port: Port of the gRPC server to connect to
• shutdownDuration: How long to wait before giving up when the channel is shutdown

example-service.yml:

server:
    [...]
logging:
    [...]
externalService:
    hostname: hostname.example.org
    port: 8000
    shutdownDuration: 10 seconds

In dropwizard's run method, use the GrpcChannelFactory class to create a gRPC ManagedChannel instance. The created channel instance is also automatically added to the dropwizard lifecycle. The returned ManagedChannel instance can be used by other application components to send requests to the given server.

ExampleServiceApplication.java:

class ExampleServiceApplication extends Application<ExampleServiceConfiguration> {
    [...]

    @Override
    public void run(final ExampleServiceConfiguration configuration, final Environment environment) throws IOException {
        final ManagedChannel externalServiceChannel;
        externalServiceChannel = configuration.getExternalGrpcChannelFactory()
                .build(environment);

        // use externalServiceChannel
    }

    [...]
}

Artifacts

This project is available on JCenter and Maven Central. To add it to your project simply add the following dependency to your pom.xml:

<dependency>
  <groupId>io.github.msteinhoff</groupId>
  <artifactId>dropwizard-grpc</artifactId>
  <version>1.2.3-2</version>
</dependency>

Or if you are using gradle:

repositories {
    jcenter()
}

dependencies {
    compile 'io.github.msteinhoff:dropwizard-grpc:1.2.3-2'
}

Support

Please file bug reports and feature requests in GitHub issues.

License

Copyright (c) 2016-2018 Mario Steinhoff

This library is licensed under the Apache License, Version 2.0.

See http://www.apache.org/licenses/LICENSE-2.0.html or the LICENSE file in this repository for the full license text.