README.md

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:

• Spring Boot/Spring MVC
• Undertow
• JAX-RS (Jersey, Apache CFX)
• Jakarta EE

Contents

• Using
  • Runtime libraries
  • Protoc plugin
    • via gradle
    • via protoc
• Development
  • Requirements
  • Modules
  • Gradle commands
  • Remote Debug
• Guides

Using

Runtime libraries

Follow the Working with the Gradle registry docs to set up authentication with GitHub packages.

Published runtime libraries example Gradle setup:

repositories {
    maven {
        name = 'GithubPackages'
        url 'https://maven.pkg.github.com/github/flit'
        credentials {
            username = project.findProperty('gpr.user') ?: System.getenv('GITHUB_ACTOR')
            password = project.findProperty('gpr.key') ?: System.getenv('GITHUB_TOKEN')
        }
        content {
            includeGroup('com.flit')
        }
    }
}

dependencies {
    implementation("com.flit:flit-core-runtime:<version>")
    implementation("com.flit:flit-spring-runtime:<version>")
    implementation("com.flit:flit-jaxrs-runtime:<version>")
    implementation("com.flit:flit-jakarta-runtime:<version>")
    implementation("com.flit:flit-undertow-runtime:<version>")
}

Protoc plugin

Plugin com.flit.flit-plugin shadow jar can be downloaded from here.

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,jakarta,jaxrs]	Type of target to generate
context	N	string	Base context for routing, default is /twirp
request	N	string	If the request parameter should pass to the service

via gradle

The plugin can be called from the Gradle protobuf plugin via additional configuration. For example:

protobuf {
    protoc {
        artifact = "com.google.protobuf:protoc:$protocVersion"
    }
  
    plugins {
        flit {
            path = "${projectDir}/script/protoc-gen-flit"
        }
    }

    generateProtoTasks {
        ofSourceSet('main')*.plugins {
            flit {
                option 'target=server'
                option 'type=spring'
                option 'request=Service'
            }
        }
    }
}

#!/usr/bin/env bash

DIR=$(dirname "$0")

JAR=$(ls -c ${DIR}/flit-plugin-*.jar | head -1)
java ${FLIT_JAVA_OPTS} -jar $JAR $@

Where the plugin jar is located in the same directly as the script.

via protoc

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

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

Development

Requirements

The build has been tested with Zulu's OpenJDK version 17.

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

Optional: to test you will need an installation of the protocol buffers compiler.

Modules

The project is split into the following modules:

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

Gradle commands

• clean ./gradlew clean
• build ./gradlew build
• test ./gradlew test
• publish ./gradlew publish

Remote Debug

Use remote JVM debugging by setting:

export FLIT_JAVA_OPTS="-agentlib:jdwp=transport=dt_socket,server=y,suspend=y,address=5005,quiet=y"

Guides

Platform	Document
Undertow	undertow.md