7 The HTTP Client - 7.4 HTTP Client Filters - 《Micronaut v3.0.0 Documentation》

7.4 HTTP Client Filters
- Injecting Another Client into a HttpClientFilter
- Filter Matching By Annotation

7.4 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, you can define HttpClientFilter classes that are applied to all matching HTTP client requests.

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

To resolve this 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 HttpClient client;
    final String org;
    BintrayService(
            @Client(BintrayApi.URL) HttpClient client,           (1)
            @Value("${bintray.organization}") String org ) {
        this.client = client;
        this.org = org;
    }
    Flux<HttpResponse<String>> fetchRepositories() {
        return Flux.from(client.exchange(HttpRequest.GET(
                "/repos/" + org), String.class)); (2)
    }
    Flux<HttpResponse<String>> fetchPackages(String repo) {
        return Flux.from(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 HttpClient client
    final String org
    BintrayService(
            @Client(BintrayApi.URL) HttpClient client, (1)
            @Value('${bintray.organization}') String org ) {
        this.client = client
        this.org = org
    }
    Flux<HttpResponse<String>> fetchRepositories() {
        client.exchange(HttpRequest.GET("/repos/$org"), String) (2)
    }
    Flux<HttpResponse<String>> fetchPackages(String repo) {
        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: HttpClient, (1)
    @param:Value("\${bintray.organization}") val org: String) {
    fun fetchRepositories(): Flux<HttpResponse<String>> {
        return Flux.from(client.exchange(HttpRequest.GET<Any>("/repos/$org"), String::class.java)) (2)
    }
    fun fetchPackages(repo: String): Flux<HttpResponse<String>> {
        return Flux.from(client.exchange(HttpRequest.GET<Any>("/repos/$org/$repo/packages"), String::class.java)) (2)
    }
}

1	An ReactorHttpClient is injected for the Bintray API
2	The organization is configurable via configuration

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

@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) {
        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)
        )
    }
}

1	You can match only a subset of paths with a Client filter.
2	The `username` and `token` are injected via configuration
3	The `basicAuth` method includes HTTP Basic credentials

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

Injecting Another Client into a HttpClientFilter

To create an ReactorHttpClient, Micronaut needs to resolve all HttpClientFilter instances, which creates a circular dependency when injecting another https://micronaut-projects.github.io/micronaut-reactor/latest/api/io/micronaut/reactor/client.ReactorHttpClient or a @Client bean into an instance of a HttpClientFilter.

To resolve this issue, use the BeanProvider interface to inject another ReactorHttpClient or a @Client bean into an instance of HttpClientFilter.

The following example which implements a filter allowing authentication between services on Google Cloud Run demonstrates how to use BeanProvider to inject another client:

import io.micronaut.context.BeanProvider;
import io.micronaut.context.annotation.Requires;
import io.micronaut.context.env.Environment;
import io.micronaut.http.HttpRequest;
import io.micronaut.http.HttpResponse;
import io.micronaut.http.MutableHttpRequest;
import io.micronaut.http.annotation.Filter;
import io.micronaut.http.client.HttpClient;
import io.micronaut.http.filter.ClientFilterChain;
import io.micronaut.http.filter.HttpClientFilter;
import org.reactivestreams.Publisher;
import reactor.core.publisher.Mono;
import java.io.UnsupportedEncodingException;
import java.net.URI;
import java.net.URLEncoder;
@Requires(env = Environment.GOOGLE_COMPUTE)
@Filter(patterns = "/google-auth/api/**")
public class GoogleAuthFilter implements HttpClientFilter {
    private final BeanProvider<HttpClient> authClientProvider;
    public GoogleAuthFilter(BeanProvider<HttpClient> httpClientProvider) { (1)
        this.authClientProvider = httpClientProvider;
    }
    @Override
    public Publisher<? extends HttpResponse<?>> doFilter(MutableHttpRequest<?> request,
                                                         ClientFilterChain chain) {
        return Mono.fromCallable(() -> encodeURI(request))
                .flux()
                .flatMap(uri -> authClientProvider.get().retrieve(HttpRequest.GET(uri) (2)
                        .header("Metadata-Flavor", "Google")))
                .flatMap(t -> chain.proceed(request.bearerAuth(t)));
    }
    private String encodeURI(MutableHttpRequest<?> request) throws UnsupportedEncodingException {
        URI fullURI = request.getUri();
        String receivingURI = fullURI.getScheme() + "://" + fullURI.getHost();
        return "http://metadata/computeMetadata/v1/instance/service-accounts/default/identity?audience=" +
                URLEncoder.encode(receivingURI, "UTF-8");
    }
}

import io.micronaut.context.annotation.Requires
import io.micronaut.context.env.Environment
import io.micronaut.context.BeanProvider
import io.micronaut.http.HttpResponse
import io.micronaut.http.MutableHttpRequest
import io.micronaut.http.annotation.Filter
import io.micronaut.http.client.HttpClient
import io.micronaut.http.filter.ClientFilterChain
import io.micronaut.http.filter.HttpClientFilter
import org.reactivestreams.Publisher
import reactor.core.publisher.Flux
import reactor.core.publisher.Mono
import static io.micronaut.http.HttpRequest.GET
@Requires(env = Environment.GOOGLE_COMPUTE)
@Filter(patterns = "/google-auth/api/**")
class GoogleAuthFilter implements HttpClientFilter {
    private final BeanProvider<HttpClient> authClientProvider
    GoogleAuthFilter(BeanProvider<HttpClient> httpClientProvider) { (1)
        this.authClientProvider = httpClientProvider
    }
    @Override
    Publisher<? extends HttpResponse<?>> doFilter(MutableHttpRequest<?> request,
                                                  ClientFilterChain chain) {
        Flux<String> token = Mono.fromCallable(() -> encodeURI(request))
                .flatMap(authURI -> authClientProvider.get().retrieve(GET(authURI).header( (2)
                        "Metadata-Flavor", "Google"
                )))
        return token.flatMap(t -> chain.proceed(request.bearerAuth(t)))
    }
    private static String encodeURI(MutableHttpRequest<?> request) {
        String receivingURI = "$request.uri.scheme://$request.uri.host"
        "http://metadata/computeMetadata/v1/instance/service-accounts/default/identity?audience=" +
                URLEncoder.encode(receivingURI, "UTF-8")
    }
}

import io.micronaut.context.BeanProvider
import io.micronaut.context.annotation.Requires
import io.micronaut.context.env.Environment
import io.micronaut.http.HttpRequest
import io.micronaut.http.HttpResponse
import io.micronaut.http.MutableHttpRequest
import io.micronaut.http.annotation.Filter
import io.micronaut.http.client.HttpClient
import io.micronaut.http.filter.ClientFilterChain
import io.micronaut.http.filter.HttpClientFilter
import org.reactivestreams.Publisher
import reactor.core.publisher.Mono
import java.net.URLEncoder
@Requires(env = [Environment.GOOGLE_COMPUTE])
@Filter(patterns = ["/google-auth/api/**"])
class GoogleAuthFilter (
    private val authClientProvider: BeanProvider<HttpClient>) : HttpClientFilter { (1)
    override fun doFilter(request: MutableHttpRequest<*>,
                          chain: ClientFilterChain): Publisher<out HttpResponse<*>?> {
        return Mono.fromCallable { encodeURI(request) }
            .flux()
            .map { authURI: String ->
                authClientProvider.get().retrieve(HttpRequest.GET<Any>(authURI)
                    .header("Metadata-Flavor", "Google") (2)
                )
            }.flatMap { t -> chain.proceed(request.bearerAuth(t.toString())) }
    }
    private fun encodeURI(request: MutableHttpRequest<*>): String {
        val receivingURI = "${request.uri.scheme}://${request.uri.host}"
        return "http://metadata/computeMetadata/v1/instance/service-accounts/default/identity?audience=" +
                URLEncoder.encode(receivingURI, "UTF-8")
    }
}

1	The BeanProvider interface is used to inject another client, avoiding a circular reference
2	The `get()` method of the `Provider` interface is used to obtain the client instance.

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
}

1	The `@BasicAuth` annotation is applied to the client

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 jakarta.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 jakarta.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 jakarta.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"))
    }
}

1	The same annotation, `@BasicAuth`, is applied to the filter
2	Normally the `@Filter` annotation makes filters singletons by default. Because the `@Filter` annotation is not used, the desired scope must be applied

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

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

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

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

1	The only requirement for custom annotations is that the @FilterMatcher annotation must be present