Connect-Ktor

Documentation: https://ichizero.github.io/connect-ktor/

Connect-Ktor extends Connect-Kotlin for Ktor servers so you can introduce the Connect Protocol beside existing REST routes.

It is an unofficial community library (not published by the ConnectRPC organization). For Connect itself and Connect-Kotlin clients, prefer the official connectrpc.com docs.

Features

• connect-ktor — Protobuf JSON/binary codecs via Connect-Kotlin, client-streaming, server-streaming, and bidirectional RPCs with envelope framing, optional protovalidate
• protoc-gen-connect-ktor — generates Ktor route handler interfaces (unary, client-streaming Flow<Req>, server-streaming Flow<Res>, and bidi Flow<Req> → Flow<Res>)

Plugins (Connect GET, body limits, compression guards, and more), engine notes, and longer guides live in the documentation site.

Conformance

Connect-Ktor runs the official connectrpc/conformance suite. Summary (details and footnotes: docs):

Feature	Option	CIO	Netty
Protocol	Connect	✅	✅
	gRPC / gRPC-Web	❌	❌
HTTP	1.1	✅	✅
	2	❌	✅
	3	❌	❌
Codec	Proto / JSON	✅	✅
Compression	identity / gzip	✅	✅
	br / zstd / deflate / snappy	❌	❌
Streams	unary / client / server	✅	✅
	half-duplex bidi	✅	✅
	full-duplex bidi (HTTP/2)	❌	✅
TLS / mTLS		❌	✅
Trailers		✅	✅
Connect GET		✅*	✅
Message receive limit	unary / streaming	✅	✅

* CIO Connect GET fails cases that rely on duplicate request headers (upstream CIO limitation). Both engines currently fail gzip streaming cases (per-message streaming compression unimplemented).

mise run conformance

Quick start

dependencies {
    implementation("io.github.ichizero:connect-ktor:0.4.1")
}

Install the generator (brew install ichizero/tap/protoc-gen-connect-ktor or a release binary), then generate:

# buf.gen.yaml (excerpt)
plugins:
  - remote: buf.build/protocolbuffers/java
    out: path/to/code
  - remote: buf.build/protocolbuffers/kotlin
    out: path/to/code
  - remote: buf.build/connectrpc/kotlin
    out: path/to/code
  - local: protoc-gen-connect-ktor
    out: path/to/code

buf generate

Implement the generated handler and register it beside REST:

object ElizaServiceHandler : ElizaServiceHandlerInterface {
    override suspend fun say(
        request: SayRequest,
        call: ApplicationCall,
    ): ResponseMessage<SayResponse> = ResponseMessage.Success(
        sayResponse { sentence = request.sentence },
        emptyMap(),
        emptyMap(),
    )
}

fun main() {
    embeddedServer(CIO, port = 8080) {
        install(Resources)
        routing {
            get("/health") { call.respondText("ok") }
            install(ContentNegotiation) {
                connectJson()
            }
            elizaService(ElizaServiceHandler)
        }
    }.start(wait = true)
}

Full walkthrough: Getting started.

Local development

This repository uses mise for tooling and tasks, plus lefthook for pre-commit hooks.

mise install    # tools + lefthook install (mise postinstall)
mise tasks ls   # build, test, lint, generate, conformance, setup, …

Docs site and formatting from the repo root (docs-site is an alias for pnpm --filter=docs-site):

pnpm install
pnpm docs-site dev      # local preview
pnpm docs-site build    # static export
pnpm docs-site lint     # typecheck (lint → lint:type)
pnpm lint:format        # format check (oxfmt --check)
pnpm lint-fix          # write-format (lint-fix → lint-fix:format)

Verifying release artifacts

Release archives for protoc-gen-connect-ktor ship cosign sigstore bundles and SLSA provenance. See the release notes and:

cosign verify-blob \
  --new-bundle-format \
  --bundle connect-ktor_Linux_x86_64.tar.gz.sigstore.json \
  --certificate-identity-regexp "^https://github.com/ichizero/connect-ktor/\\.github/workflows/release\\.yml@(refs/heads/main|refs/tags/v.*)$" \
  --certificate-oidc-issuer https://token.actions.githubusercontent.com \
  connect-ktor_Linux_x86_64.tar.gz

gh attestation verify connect-ktor_Linux_x86_64.tar.gz --repo ichizero/connect-ktor

License

Offered under the Apache 2 license.

Acknowledgements

Thanks to the authors of the Connect Protocol and Connect-Kotlin.