Twitch Twirp RPC implementation for Java
Clone or download
Pull request Compare This branch is 6 commits ahead of devork:master.
BenEddy Merge pull request #3 from github/nested-files
Support nested proto files
Latest commit 22f2913 Jan 15, 2019

Flit - Twirp RPC Generator Framework

This project is a generator for the Twitch TV Twirp RPC framework.

It supports the generation of Java based servers with the following flavours supported:

Building & Running


The build has been tested with Oracle's JDK (version 1.8)

The build uses gradle to generate the artifacts. No installation is required as the project uses the gradle wrapper setup.

For testing you will need an installation of the protocol buffers compiler.


The project is split into the following modules:

Module Description
plugin The protoc plugin
runtime:core Core functionality required by generated code
runtime:spring Runtime library for Spring MVC/Boot servers
runtime:undertow Runtime library for Undertow servers


To build the various components, run the following:

git clone
cd flit
./gradlew clean build pack


Currently, the run script only supports *nix but the run script should be fairly easy to migrate to windows.

After building:

cp plugin/build/package/ /usr/local/bin
cd /usr/local/bin
chmod +x protoc-gen-flit


The plugin is executed as part of a protoc compilation step:

protoc \
    --proto_path=. \
    --java_out=../java \
    --flit_out=target=server,type=undertow:../java \


The flit plugin accepts the following plugin parameters:

Name Required Type Description
target Y enum[server] The type of target to generate e.g. server, client etc
type Y enum[spring,undertow,boot] Type of target to generate
context N string Base context for routing, default is /twirp


All development is done in Java using JDK 8 (as mentioned above).

Remote debugging can be performed as follows:

export FLIT_JAVA_OPTS="-agentlib:jdwp=transport=dt_socket,server=y,suspend=y,address=5005,quiet=y"
protoc \
        --proto_path=. \
        --java_out=../java \
        --flit_out=target=server,type=undertow:../java \

When running with the above options, the generator will enable a remote java debug session on port 5005. This is useful for debugging a full generation step.

Test Fixture Generation

The test resources contains a fake plugin that simply dumps the binary request to a file called file.bin. This utility can be used to generate test fixtures which can be fed to tests to drive plugin generation, for example:

$ protoc \
    --plugin=${PWD}/protoc-gen-dump \
    --dump_out=target=server,type=undertow:../java  \
$ mv file.bin helloworld.bin

This can be run from the resources directory to generate a CodeGeneratorRequest protobuf file, which can then be read by tests:

PluginProtos.CodeGeneratorRequest request = null;
try (InputStream is = this.getClass().getClassLoader().getResource("helloworld.bin").openStream()) {
    request = PluginProtos.CodeGeneratorRequest

Plugin plugin = new Plugin(request);


Platform Document