isabella232 / grpc-jersey

[OSS] gRPC<->Jersey bridge

grpc-jersey

protoc plugin for compiling gRPC service endpoints as Jersey/REST endpoints. Uses the HttpRule annotations also used by the grpc-gateway project.

Example Usage

grpc-jersey requires a minimum of Java 8 at this time.

Snapshot artifacts are available on the Sonatype snapshots repository, releases are available on Maven Central.

Example provided here uses the gradle-protobuf-plugin but an example using Maven can be found in examples.

ext {
    protobufVersion = "3.2.0"
    grpcVersion = "1.2.0"
    grpcJerseyVersion = "0.1.3"
}

protobuf {
    protoc {
        artifact = "com.google.protobuf:protoc:${protobufVersion}"
    }
    plugins {
        grpc {
            artifact = "io.grpc:protoc-gen-grpc-java:${grpcVersion}"
        }
        jersey {
            artifact = "com.fullcontact.grpc-jersey:protoc-gen-jersey:${grpcJerseyVersion}"
        }
    }
    generateProtoTasks {
        all()*.plugins {
            grpc {}
            jersey {}
        }
    }
}

You'll also have to be sure to include the jersey-rpc-support package in your service:

compile "com.fullcontact.grpc-jersey:jersey-rpc-support:${grpcJerseyVersion}"

Running ./gradlew build and a protobuf definition that looks roughly like the below

syntax = "proto3";

option java_package = "com.fullcontact.rpc.example";
import "google/api/annotations.proto";

service TestService {
    rpc TestMethod (TestRequest) returns (TestResponse) {
        option (google.api.http).get = "/users/{id}";
    }
    rpc TestMethod2 (TestRequest) returns (TestResponse) {
        option (google.api.http) = {
            post: "/users/",
            body: "*";
        };
    }
}
message TestRequest {
    string id = 1;
}
message TestResponse {
    string f1 = 1;
}

Would compile into a single Jersey resource with one GET handler and one POST handler.

Rules can also be defined in a .yml file.

http:
  rules:
  - selector: TestService.TestMethod4
    get: /users/{id}
  - selector: TestService.TestMethod5
    get: /yaml_users/{s=hello/**}/x/{uint3}/{nt.f1}/*/**/test
  - selector: TestService.TestMethod6
    post: /users/
    body: "*"
    additionalBindings:
      - post: /yaml_users_nested
        body: "nt"

Rules defined this way must correspond to methods in the .proto files, and will overwrite any http rules defined in the proto. The path to your .yml file should be passed in as an option:

 generateProtoTasks {
            all()*.plugins {
                grpc {}
                jersey {
                    option 'proxy,yaml=integration-test-base/src/test/proto/http_api_config.yml'
                }
            }
        }

or

    <configuration>
      <pluginId>grpc-jersey</pluginId>
      <pluginArtifact>com.fullcontact.grpc-jersey:protoc-gen-jersey:0.1.1:exe:${os.detected.classifier}</pluginArtifact>
      <pluginParameter>yaml=integration-test-base/src/test/proto/http_api_config.yml</pluginParameter>
    </configuration>

grpc-jersey can operate in two different modes: direct invocation on service ImplBase or proxy via a client Stub. There are advantages and disadvantages to both, however the primary benefit to the client stub proxy is that RPCs pass through the same ServerInterceptor stack. It's recommended that the client stub passed into the Jersey resource uses a InProcessTransport if living in the same JVM as the gRPC server. A normal grpc-netty channel can be used for a more traditional reverse proxy.

You can find an example of each in the integration-test-proxy and integration-test-serverstub projects.

Project status

ALPHA

This project is in use and under active development.

Short-term roadmap:

• Documentation
• Support recursive path expansion for path parameters
• Support recursive path expansion for query parameters
• Support recursive path expansion for body parameters
• additional_bindings support
• Support for wildcard * and ** anonymous/named path expansion
• Support for endpoint definitions in a .yml file.
• response_body support
• Performance tests
• Generic/pluggable error handling
• Supporting streaming RPCs
• Server streaming
• Client streaming

Build Process

./gradlew clean build

Please use --no-ff when merging feature branches.