MetaEngine Protobuf Kotlin Ktor

Generate Kotlin Ktor gRPC-Connect client services and models from Protobuf definitions.

A Maven plugin that produces coroutine-based Ktor HttpClient service clients and kotlinx.serialization data classes from a .proto definition — gRPC over the Connect protocol — with built-in authentication, timeouts, and custom headers, straight into your build at generate-sources.

---

Quick Links

• Maven Central: eu.metaengine:metaengine-protobuf-kotlin-ktor-maven-plugin
• NuGet Package: MetaEngine.Kotlin.Protobuf.Ktor
• Website: metaengine.eu

---

Features

• ✅ Ktor gRPC-Connect client - Coroutine-based suspend fun service clients over the Connect protocol
• ✅ kotlinx.serialization models - Kotlin data class types with @Serializable
• ✅ Authentication - Bearer token, basic auth, and custom headers from environment variables
• ✅ Timeouts - Single timeout, or split connect / read / write timeouts
• ✅ KDoc - Optional doc-comment generation from Protobuf descriptions
• ✅ Validation Annotations - Optional Jakarta Bean Validation annotations on generated data classes
• ✅ Strict Enums - Opt into strict enum handling with no synthetic UNKNOWN fallback
• ✅ Options Object - Collapse long parameter lists into an options object past a threshold

---

Requirements

• JDK 11 or later
• Maven 3.6 or later
• .NET 8.0 runtime (Download) — the plugin runs the bundled MetaEngine generator via dotnet, so the runtime must be on your PATH

---

Quick Start

Add the plugin to your pom.xml and bind it to the generate-sources phase:

<build>
  <plugins>
    <plugin>
      <groupId>eu.metaengine</groupId>
      <artifactId>metaengine-protobuf-kotlin-ktor-maven-plugin</artifactId>
      <version>1.0.0</version>
      <executions>
        <execution>
          <goals><goal>generate</goal></goals>
          <configuration>
            <inputSpec>src/main/resources/service.proto</inputSpec>
            <packageName>com.example.api</packageName>
            <documentation>true</documentation>
          </configuration>
        </execution>
      </executions>
    </plugin>
  </plugins>
</build>

Then generate (the output is added to your compile source roots automatically):

mvn generate-sources

The plugin can also be run directly without a lifecycle binding:

mvn eu.metaengine:metaengine-protobuf-kotlin-ktor-maven-plugin:generate \
  -Dmetaengine.inputSpec=src/main/resources/service.proto \
  -Dmetaengine.packageName=com.example.api

---

Configuration Options

Every option is a <configuration> element, also settable on the command line via its metaengine.* property.

Element	Property	Description	Default
inputSpec (required)	metaengine.inputSpec	Protobuf .proto file path or URL	-
packageName (required)	metaengine.packageName	Kotlin package for generated code	-
outputDirectory	metaengine.outputDirectory	Output directory	${project.build.directory}/generated-sources/metaengine
documentation	metaengine.documentation	Generate KDoc comments	false
bearerAuth	metaengine.bearerAuth	Env var name holding the bearer token	-
bearerAuthHeader	metaengine.bearerAuthHeader	Custom header name for bearer auth	Authorization
basicAuth	metaengine.basicAuth	Env var names for basic auth (USER_VAR,PASS_VAR)	-
customHeaders	metaengine.customHeaders	Custom headers from env vars (Header-Name:ENV_VAR, repeatable)	-
timeout	metaengine.timeout	Request timeout in seconds (connect + read + write)	-
timeoutConnect	metaengine.timeoutConnect	Connect timeout in seconds	-
timeoutRead	metaengine.timeoutRead	Read timeout in seconds (request timeout)	-
timeoutWrite	metaengine.timeoutWrite	Write timeout in seconds (socket I/O)	-
validationAnnotations	metaengine.validationAnnotations	Emit Jakarta Bean Validation annotations on data classes	false
strictEnums	metaengine.strictEnums	Strict string enums — no synthetic UNKNOWN fallback for unrecognized wire values	false
optionsThreshold	metaengine.optionsThreshold	Parameter count that triggers the options-object pattern	4
clean	metaengine.clean	Clean the output directory before generation	false
verbose	metaengine.verbose	Enable verbose logging	false

---

Production-Ready Configuration

<configuration>
  <inputSpec>src/main/resources/service.proto</inputSpec>
  <packageName>com.example.api</packageName>
  <documentation>true</documentation>

  <!-- Auth from environment variables -->
  <bearerAuth>API_TOKEN</bearerAuth>

  <!-- Timeouts -->
  <timeout>30</timeout>
</configuration>

Authentication values are read from environment variables at runtime — secrets never end up in your generated source or your pom.xml.

---

Generated Code Structure

target/generated-sources/metaengine/
  ├── client/        # Ktor gRPC-Connect clients (HttpClient-based, suspend funs)
  │   ├── EntityService.kt
  │   └── BaseHttpClient.kt
  └── model/         # @Serializable data classes, one per Protobuf message
      ├── Entity.kt
      ├── CreateEntityRequest.kt
      └── ...

Each client is a plain Kotlin class — construct it with a Ktor HttpClient and a base URL and call its coroutine suspend fun operations. Models are @Serializable data classes ready for kotlinx.serialization.

---

Support

• Issues: GitHub Issues
• Email: info@metaengine.eu
• Website: metaengine.eu

---

License

MIT License - see LICENSE file for details.

---

About This Repository

This is the documentation and issue tracking repository for MetaEngine Protobuf Kotlin Ktor. The plugin is published to Maven Central.

Source code is proprietary, but the plugin is free to use under the MIT license.