7.3 HTTP Client Filters

Often, you need to include the same HTTP headers or URL parameters in a set of requests against a third-party API or when calling another Microservice.

To simplify this, Micronaut includes the ability to define HttpClientFilter classes that are applied to all matching HTTP clients.

As an example say you want to build a client to communicate with the Bintray REST API. It would be terribly tedious to have to specify authentication for every single HTTP call.

To resolve this burden you can define a filter. The following is an example BintrayService:

class BintrayApi {
    public static final String URL = 'https://api.bintray.com'
}
@Singleton
class BintrayService {
    final RxHttpClient client;
    final String org;
    BintrayService(
            @Client(BintrayApi.URL) RxHttpClient client,           (1)
            @Value("${bintray.organization}") String org ) {
        this.client = client;
        this.org = org;
    }
    Flowable<HttpResponse<String>> fetchRepositories() {
        return client.exchange(HttpRequest.GET("/repos/" + org), String.class); (2)
    }
    Flowable<HttpResponse<String>> fetchPackages(String repo) {
        return client.exchange(HttpRequest.GET("/repos/" + org + "/" + repo + "/packages"), String.class); (2)
    }
}

class BintrayApi {
    public static final String URL = 'https://api.bintray.com'
}
@Singleton
class BintrayService {
    final RxHttpClient client
    final String org
    BintrayService(
            @Client(BintrayApi.URL) RxHttpClient client,           (1)
            @Value('${bintray.organization}') String org ) {
        this.client = client
        this.org = org
    }
    Flowable<HttpResponse<String>> fetchRepositories() {
        return client.exchange(HttpRequest.GET("/repos/$org"), String) (2)
    }
    Flowable<HttpResponse<String>> fetchPackages(String repo) {
        return client.exchange(HttpRequest.GET("/repos/${org}/${repo}/packages"), String) (2)
    }
}

class BintrayApi {
    public static final String URL = 'https://api.bintray.com'
}
@Singleton
internal class BintrayService(
        @param:Client(BintrayApi.URL) val client: RxHttpClient, (1)
        @param:Value("\${bintray.organization}") val org: String) {
    fun fetchRepositories(): Flowable<HttpResponse<String>> {
        return client.exchange(HttpRequest.GET<Any>("/repos/$org"), String::class.java) (2)
    }
    fun fetchPackages(repo: String): Flowable<HttpResponse<String>> {
        return client.exchange(HttpRequest.GET<Any>("/repos/$org/$repo/packages"), String::class.java) (2)
    }
}

The Bintray API is secured. To authenticate you need to add an Authorization header for every request. You could modify fetchRepositories and fetchPackages methods to include the necessary HTTP Header for each request. Using a filter is much simpler though:

@Filter("/repos/**") (1)
class BintrayFilter implements HttpClientFilter {
    final String username;
    final String token;
    BintrayFilter(
            @Value("${bintray.username}") String username, (2)
            @Value("${bintray.token}") String token ) { (2)
        this.username = username;
        this.token = token;
    }
    @Override
    public Publisher<? extends HttpResponse<?>> doFilter(MutableHttpRequest<?> request, ClientFilterChain chain) {
        return chain.proceed(
                request.basicAuth(username, token) (3)
        );
    }
}

@Filter('/repos/**') (1)
class BintrayFilter implements HttpClientFilter {
    final String username
    final String token
    BintrayFilter(
            @Value('${bintray.username}') String username, (2)
            @Value('${bintray.token}') String token ) { (2)
        this.username = username
        this.token = token
    }
    @Override
    Publisher<? extends HttpResponse<?>> doFilter(MutableHttpRequest<?> request, ClientFilterChain chain) {
        return chain.proceed(
                request.basicAuth(username, token) (3)
        )
    }
}

@Filter("/repos/**") (1)
internal class BintrayFilter(
        @param:Value("\${bintray.username}") val username: String, (2)
        @param:Value("\${bintray.token}") val token: String)(2)
    : HttpClientFilter {
    override fun doFilter(request: MutableHttpRequest<*>, chain: ClientFilterChain): Publisher<out HttpResponse<*>> {
        return chain.proceed(
                request.basicAuth(username, token) (3)
        )
    }
}

Now, whenever you invoke the bintrayService.fetchRepositories() method, the Authorization HTTP header is included in the request.

Filter Matching By Annotation

For cases where a filter should be applied to a client, regardless of the URL, filters can be matched by the presence of an annotation applied to both the filter and the client. Given the following client:

import io.micronaut.http.annotation.Get;
import io.micronaut.http.client.annotation.Client;
@BasicAuth (1)
@Client("/message")
public interface BasicAuthClient {
    @Get
    String getMessage();
}

import io.micronaut.http.annotation.Get
import io.micronaut.http.client.annotation.Client
@BasicAuth (1)
@Client("/message")
interface BasicAuthClient {
    @Get
    String getMessage()
}

import io.micronaut.http.annotation.Get
import io.micronaut.http.client.annotation.Client
@BasicAuth (1)
@Client("/message")
interface BasicAuthClient {
    @Get
    fun getMessage(): String
}

The following filter will filter the client requests:

import io.micronaut.http.HttpResponse;
import io.micronaut.http.MutableHttpRequest;
import io.micronaut.http.filter.ClientFilterChain;
import io.micronaut.http.filter.HttpClientFilter;
import org.reactivestreams.Publisher;
import javax.inject.Singleton;
@BasicAuth (1)
@Singleton (2)
public class BasicAuthClientFilter implements HttpClientFilter {
    @Override
    public Publisher<? extends HttpResponse<?>> doFilter(MutableHttpRequest<?> request, ClientFilterChain chain) {
        return chain.proceed(request.basicAuth("user", "pass"));
    }
}

import io.micronaut.http.HttpResponse
import io.micronaut.http.MutableHttpRequest
import io.micronaut.http.filter.ClientFilterChain
import io.micronaut.http.filter.HttpClientFilter
import org.reactivestreams.Publisher
import javax.inject.Singleton
@BasicAuth (1)
@Singleton (2)
class BasicAuthClientFilter implements HttpClientFilter {
    @Override
    Publisher<? extends HttpResponse<?>> doFilter(MutableHttpRequest<?> request, ClientFilterChain chain) {
        chain.proceed(request.basicAuth("user", "pass"))
    }
}

import io.micronaut.http.HttpResponse
import io.micronaut.http.MutableHttpRequest
import io.micronaut.http.filter.ClientFilterChain
import io.micronaut.http.filter.HttpClientFilter
import org.reactivestreams.Publisher
import javax.inject.Singleton
@BasicAuth (1)
@Singleton (2)
class BasicAuthClientFilter : HttpClientFilter {
    override fun doFilter(request: MutableHttpRequest<*>, chain: ClientFilterChain): Publisher<out HttpResponse<*>> {
        return chain.proceed(request.basicAuth("user", "pass"))
    }
}

The @BasicAuth annotation is just an example and can be replaced with your own custom annotation.

import io.micronaut.http.annotation.FilterMatcher;
import java.lang.annotation.*;
@FilterMatcher (1)
@Documented
@Retention(RetentionPolicy.RUNTIME)
@Target({ElementType.TYPE, ElementType.PARAMETER})
public @interface BasicAuth {
}

import io.micronaut.http.annotation.FilterMatcher
import java.lang.annotation.*
@FilterMatcher (1)
@Documented
@Retention(RetentionPolicy.RUNTIME)
@Target([ElementType.TYPE, ElementType.PARAMETER])
@interface BasicAuth {
}

import io.micronaut.http.annotation.FilterMatcher
@FilterMatcher (1)
@MustBeDocumented
@Retention(AnnotationRetention.RUNTIME)
@Target(AnnotationTarget.CLASS, AnnotationTarget.VALUE_PARAMETER)
annotation class BasicAuth