Maven Central NuGet v1.0.0 MIT

Protobuf to Kotlin Ktor Client Generator

eu.metaengine:metaengine-protobuf-kotlin-ktor-maven-plugin

Convert Protobuf 3 to Kotlin Ktor gRPC-Connect client services and message models, delivered as a Maven plugin. Each RPC becomes a suspend fun on a Ktor HttpClient with kotlinx.serialization models over Connect-over-HTTP — bearer/basic auth, custom headers, timeouts, KDoc and Bean Validation — generated straight into your build at generate-sources.

Protobuf 3.xMetaEngine IRKotlin · Ktor
Convert Protobuf to Kotlin Ktor in the browser
Install

Pick your registry

The same generator, published to every ecosystem we support. Install however your project expects.

Maven CentralPrimaryeu.metaengine:metaengine-protobuf-kotlin-ktor-maven-plugin
$eu.metaengine:metaengine-protobuf-kotlin-ktor-maven-plugin
v1.0.0
NuGetMetaEngine.Kotlin.Protobuf.Ktor
$dotnet add package MetaEngine.Kotlin.Protobuf.Ktor
v1.0.0
Usage

Drive it from Maven or programmatically

Maven Central ships a build-time plugin that runs inside your build. NuGet ships the same generator as a C# fluent API — same options, same output.

Maven Central · build-time plugin

Add the plugin to your pom.xml. Its generate goal binds to the generate-sources phase, so the gRPC-Connect client and kotlinx.serialization models are produced — and added to your compile roots — on every mvn compile or package. Point <inputSpec> at a .proto file and set the target Kotlin <packageName>.

Plugin setup
pom.xml
<build>
  <plugins>
    <plugin>
      <groupId>eu.metaengine</groupId>
      <artifactId>metaengine-protobuf-kotlin-ktor-maven-plugin</artifactId>
      <version>1.0.0</version>
      <executions>
        <execution>
          <id>generate-grpc-client</id>
          <goals>
            <goal>generate</goal>
          </goals>
          <configuration>
            <inputSpec>${project.basedir}/src/main/proto/service.proto</inputSpec>
            <packageName>com.example.api</packageName>
          </configuration>
        </execution>
      </executions>
    </plugin>
  </plugins>
</build>

The generate goal binds to the generate-sources phase, so a normal mvn compile (or package) produces the client and registers it as a compile source root — no extra wiring. <inputSpec> accepts a local .proto path, an http(s) URL, or inline proto content. The gRPC transport is Connect-over-HTTP on the Ktor HttpClient.

Configuration examples
Auth, custom header and a request timeout
<configuration>
  <inputSpec>${project.basedir}/service.proto</inputSpec>
  <packageName>com.example.api</packageName>
  <bearerAuth>API_TOKEN</bearerAuth>
  <timeout>30</timeout>
  <customHeaders>
    <customHeader>X-Tenant-ID:TENANT_ID</customHeader>
  </customHeaders>
</configuration>
KDoc and Bean Validation
<configuration>
  <inputSpec>${project.basedir}/service.proto</inputSpec>
  <packageName>com.example.api</packageName>
  <documentation>true</documentation>
  <validationAnnotations>true</validationAnnotations>
</configuration>
Basic auth and granular timeouts from env vars
<configuration>
  <inputSpec>${project.basedir}/service.proto</inputSpec>
  <packageName>com.example.api</packageName>
  <basicAuth>API_USER,API_PASS</basicAuth>
  <timeoutConnect>5</timeoutConnect>
  <timeoutRead>30</timeoutRead>
</configuration>
Configuration
Element
Description
<inputSpec>
Protobuf source — local .proto path, http(s) URL, or inline proto content. Required.
<packageName>
Kotlin package for the generated code, e.g. com.example.api (lowercase, dot-separated). Required.
<outputDirectory>
Output directory [default: ${project.build.directory}/generated-sources/metaengine]. Added to the compile source roots.
<documentation>
Generate KDoc comments [default: false]
<bearerAuth>
Env var holding the bearer token — adds an Authorization header to every request
<bearerAuthHeader>
Custom header name for the bearer token [default: Authorization]. Requires bearerAuth.
<basicAuth>
HTTP Basic auth from env vars, format USER_VAR,PASS_VAR
<customHeaders>
Static headers from env vars (Header-Name:ENV_VAR) as <customHeader> children. Repeatable.
<timeout>
Request timeout in seconds (connect + read + write)
<timeoutConnect>
Connect timeout in seconds
<timeoutRead>
Read timeout in seconds (request timeout)
<timeoutWrite>
Write timeout in seconds (socket I/O)
<validationAnnotations>
Emit Jakarta Bean Validation annotations on generated data classes [default: false]
<strictEnums>
Keep string enums strict — no synthetic UNKNOWN fallback for unknown wire values [default: false]
<optionsThreshold>
Parameter count threshold for the options-object pattern [default: 4]
<clean>
Clean the output directory before generation (remove files not in generation) [default: false]
<verbose>
Enable verbose logging [default: false]
Options reference

Every knob, documented

Every option is available on the C# fluent API as a method; the Maven plugin exposes most as <configuration> elements. Cross-cutting auth, headers, retries and timeouts apply across frameworks.

Ktor Options

2
  • WithValidationAnnotations()Emit Jakarta Bean Validation annotations (@field:NotNull, @field:Size, @field:Pattern, @field:Min / @field:Max, @field:Email) on generated data classes from proto field rules
  • WithStrictEnums()Keep string enums strict (plain @Serializable — kotlinx throws on unknown values). By default a synthetic UNKNOWN member + companion KSerializer absorbs unrecognized wire values instead of crashing deserialization

Auth · Headers · Resilience

8
  • WithBearerAuth()Bearer token from env var (default API_TOKEN) — adds Authorization header
  • WithBearerAuth(string)Bearer token from a specific env var name
  • WithBearerAuth(string, string)Bearer token with custom header name (e.g. X-Api-Key)
  • WithBasicAuth()HTTP Basic auth from default env vars (API_USERNAME / API_PASSWORD)
  • WithBasicAuth(string, string)HTTP Basic auth from username + password env vars
  • WithCustomHeader(string, string)Static header from env var. Repeatable (e.g. X-Tenant-ID ← TENANT_ID)
  • WithTimeout(double)Request timeout in seconds — sets Ktor connect, request and socket timeouts together
  • WithTimeout(double?, double?, double?)Granular timeout: connect · read · write (Ktor HttpTimeout has no connection-pool timeout)

Kotlin Options

3
  • WithDocumentation()Generate KDoc comments on methods and parameters from the spec
  • WithMethodNames(Func)Custom method naming rule
  • WithOptionsObjectThreshold(int)Parameter count for options object (default: 4)

Protobuf Options

5
  • WithDocumentation()Generate KDoc comments from .proto field and service descriptions
  • WithTypeFilter(Func)Filter extracted proto types (messages + enums) before registration — only types returning true are generated
  • WithTypeMapping(string, Type)Override the Kotlin mapping for a protobuf well-known type by fully-qualified name (e.g. google.protobuf.Timestamp → String)
  • WithMethodNames(Func)Custom method naming rule
  • WithOptionsObjectThreshold(int)Parameter count for options object (default: 4)

Naming Transformations

3
  • Types(Func)Transform type names
  • Paths(Func)Transform output paths
  • FileNames(Func)Transform file names

File Management

5
  • CleanDestination()Clean output directory before generation
  • AlwaysOverwrite()Always overwrite existing files
  • OnlyWhenModelChanged()Update only when model changes
  • OnlyWhenNew()Write only new files, preserve existing
  • CleanDirectories(...)Clean specific subdirectories

Diagnostics

2
  • Verbose()Enable verbose logging
  • WithLogger(Action<string>)Route generation log output to a custom sink
Features

Why this package is different

Idiomatic data classes
kotlinx.serialization @Serializable data classes, nullable fields as T? = null, enums as @Serializable enum class.
Coroutine-first
Ktor client calls are suspend functions; streaming and subscriptions surface as Flow<T>.
Sealed hierarchies
Polymorphic payloads become sealed classes — exhaustive when with no else branch.
Deterministic output
Same spec + same options produce byte-identical files. Safe to commit, safe to diff in review, safe to cache in CI.
Flexible naming
Case conventions are configurable per role — types, properties, operations, enums. Idiomatic in the target by default.
Semver-honest
Spec diff drives the version bump. Additive changes = minor, removed operations = major. Never a surprise in your lockfile.