Kora HTTP Client

Kora HTTP Client — declarative outbound calls

Kora sub-skill — obey the kora-v2 meta rules on every task: R0 ground the workspace on Kora 2.0 refs before starting (framework source at tag 2.0.0.RC1 + kora-examples at migration/2.0; kora-docs is 1.x only) · R1 read this sub-skill before writing code · R2 Kora 2.0 APIs only — no Spring/Micronaut/Quarkus, no Kora 1.x APIs, no invented annotations or config keys · R3 journal any incorrect Kora usage. Add comments/Javadoc only if asked.

Version: Kora 2.0 (io.koraframework, 2.0.0.RC1 on Maven Central) | Java: 25 | Kotlin: 2.4 + KSP | Gradle: 9+

Annotate an interface with @HttpClient, declare methods with @HttpRoute, and the annotation processor (Java) or symbol processor (Kotlin) generates $<Name>_ClientImpl plus a $<Name>_Config config interface and a $<Name>_Module that binds it. No reflection, no runtime proxies — inject the client interface like any other component.

Client contracts are synchronous. Every generated method blocks on a virtual thread and returns the decoded value. There is no CompletionStage, no Mono/Flux, and a Kotlin suspend client method is a hard KSP error. See execution-model-reference.

Migrating from Kora 1.x

Most of the table fails the build if you miss it. Three things in this domain do not, and need a test rather than a compiler:

• Telemetry defaults flipped. telemetry.metrics.enabled and telemetry.logging.enabled are false in 2.0 (only tracing is true). A 1.x config that relied on the old defaults comes up green with no client metrics.
• A @Mapping response mapper on a method disables the 2xx status check — the mapper is called for every status and non-2xx stops throwing HttpClientResponseException. Same for an Either return type, by design.
• A redundant @Component on a self-instantiated mapper is latent: it only becomes Multiple components match once something resolves that HttpClientResponseMapper<T> from the graph, which may be a later, unrelated change.

Quick Start

1. Dependencies

gradle.properties:

koraVersion=2.0.0.RC1

Java (build.gradle) — resolve from plain mavenCentral():

configurations {
    koraBom
    annotationProcessor.extendsFrom(koraBom)
    compileOnly.extendsFrom(koraBom)
    implementation.extendsFrom(koraBom)
    testImplementation.extendsFrom(koraBom)
    testAnnotationProcessor.extendsFrom(koraBom)
}

dependencies {
    koraBom platform("io.koraframework:kora-bom:$koraVersion")

    annotationProcessor "io.koraframework:annotation-processors"

    implementation "io.koraframework:http-client-ok"   // or http-client-jdk / http-client-apache
    implementation "io.koraframework:json-common"      // required for @Json bodies
    implementation "io.koraframework:config-hocon"
}

Kotlin (build.gradle.kts):

dependencies {
    implementation(platform("io.koraframework:kora-bom:${property("koraVersion")}"))
    ksp("io.koraframework:symbol-processors:${property("koraVersion")}")

    implementation("io.koraframework:http-client-ok")
    implementation("io.koraframework:json-common")
    implementation("io.koraframework:config-hocon")
}

json-common is a compileOnly dependency of http-common, so it is not pulled in transitively — declare it in every module that uses @Json on a client.

2. Plug the transport module into @KoraApp

@KoraApp
public interface Application extends
        HoconConfigModule,
        JsonModule,
        OkHttpClientModule {

    static void main(String[] args) {
        KoraApplication.run(ApplicationGraph::graph);
    }
}

Exactly one transport module at a time — each one registers HttpClient under the same httpClient base config path.

3. Declare the client interface

@HttpClient("httpClient.userApi")
public interface UserApiClient {

    @HttpRoute(method = HttpMethod.GET, path = "/users/{userId}")
    @Json
    UserResponse getUser(@Path String userId);

    @HttpRoute(method = HttpMethod.GET, path = "/users")
    @Json
    List<UserResponse> listUsers(@Nullable @Query("page") Integer page,
                                @Nullable @Query("size") Integer size);

    @HttpRoute(method = HttpMethod.POST, path = "/users")
    @Json
    HttpResponseEntity<UserResponse> createUser(@Json CreateUserRequest request);

    @HttpRoute(method = HttpMethod.DELETE, path = "/users/{userId}")
    void deleteUser(@Path String userId);
}

@HttpClient value is the full config path. Omit it and the client resolves httpClient.<lowerCamelInterfaceName> — UserApiClient → httpClient.userApiClient.

4. Configuration (HOCON)

httpClient {
  userApi {
    url = "http://localhost:8080"
    url = ${?USER_API_URL}
    requestTimeout = 10s

    telemetry.logging.enabled = true
    telemetry.metrics.enabled = true      # false by default in 2.0

    getUser {                             # per-method override, keyed by method name
      requestTimeout = 3s
    }
  }
}

url is the only required key. Transport-wide settings (connectTimeout, readTimeout, proxy) live at httpClient, transport-specific ones at httpClient.ok / .jdk / .apache.

5. Inject and use

@Component
public final class UserService {

    private final UserApiClient client;

    public UserService(UserApiClient client) {
        this.client = client;
    }

    public UserResponse getUser(String id) {
        return client.getUser(id);
    }
}

When to use vs NOT

Use this skill when:

• Building a typed outbound client with @HttpClient + @HttpRoute.
• Mapping parameters with @Path, @Query, @Header, @Cookie, @Json, @Mapping.
• Adding @InterceptWith interceptors for auth, logging, or extra headers.
• Configuring per-client or per-method timeouts, proxy, HTTP version, or telemetry under httpClient.*.
• Diagnosing No component found for dependency: HttpClientResponseMapper<…> or Multiple components match.

Do NOT use when:

• You have an OpenAPI contract and want a generated client → kora-openapi-generator-client.
• You need the inbound HTTP server (@HttpController) → kora-http-server.
• You are wiring Basic/Bearer/API-key token flows in depth → kora-http-client-auth.

Core rules

Transports

Prefer http-client-ok; http-client-jdk is the dependency-free alternative. http-client-apache is available at RC1 but its integration received fixes on master afterwards — on RC1 it reads connectTimeout / readTimeout / proxy from httpClient.apache rather than from httpClient, and it forwards Content-Length / Transfer-Encoding headers that Apache rejects.

http-client-async / AsyncHttpClientModule do not exist in 2.0 and have no drop-in replacement. Details and every config key: transports-reference.

Which mappers and interceptors need @Component

Decided by how the generated constructor obtains them, not by taste:

For that last row the generator emits private static final X mapper = new X(); when the class is final (Kotlin: not open) and has a public no-arg constructor — in Kotlin, exactly one constructor, taking no arguments. Otherwise — a constructor dependency such as a JsonReader<T>, or a non-final class — it becomes a constructor parameter and must be in the graph.

• Missing where required → No component found for dependency: … (no tags).
• Added on a self-instantiated mapper it is redundant, and it registers a second HttpClientResponseMapper<T> in the graph: as soon as anything resolves that type from the graph, that is Multiple components match.

HttpResponseEntity<Void> needs its own payload mapper

HttpClientResponseMapperModule supplies concrete mappers for String, byte[], ByteBuffer and HttpBodyInput, plus template factories for HttpResponseEntity<T>, Either<T, E> and their @Json variants. The entity factory needs a mapper for the payload T, so HttpResponseEntity<Void> fails the graph:

No component found for dependency: HttpClientResponseMapper<java.lang.Void> (no tags)

Declare the payload mapper as a component and do not reference it with @Mapping:

@Component
final class VoidResponseMapper implements HttpClientResponseMapper<Void> {

    @Override
    public Void apply(HttpClientResponse response) throws IOException {
        try (var body = response.body()) {
            body.asInputStream().readAllBytes();
        }
        return null;
    }
}

@HttpRoute(method = HttpMethod.DELETE, path = "/users/{userId}")
HttpResponseEntity<Void> deleteUser(@Path String userId);

With @Mapping(VoidResponseMapper.class) the generator calls the mapper directly instead of wrapping it, so the mapper would have to produce the whole entity:

error: incompatible types: Void cannot be converted to HttpResponseEntity<Void>

A method that returns plain void (Kotlin Unit) needs no mapper at all.

Kotlin nullability

Kora's HTTP contracts are @NullMarked (JSpecify). HttpClientResponseMapper<T>.apply returns @Nullable T, so a Kotlin mapper that has to return null must declare the nullable type:

@Component
class VoidResponseMapper : HttpClientResponseMapper<Void> {
    override fun apply(response: HttpClientResponse): Void? {
        response.body().use { it.asInputStream().readAllBytes() }
        return null
    }
}

JsonReader<T>.read(...) is nullable too — Kotlin needs requireNotNull(...) inside mappers. An override whose nullability does not match the contract fails with 'apply' overrides nothing, which never mentions nullability.

What's in references/ and assets/

Common pitfalls

Related skills

• kora-http-client-auth — Basic / Bearer / API-key token flows
• kora-http-server — inbound @HttpController
• kora-openapi-generator-client — generate a client from an OpenAPI spec
• kora-json — @Json DTOs, JsonReader/JsonWriter
• kora-aop-resilient — @Retryable, @CircuitBreakable, @Timeout, @Fallback
• kora-telemetry-metrics — Micrometer wiring for http.client.*