1. Introduction
In this tutorial, we’ll look at how we use Spring Cloud Gateway to inspect and/or modify the response body before sending it back to a client.
2. Spring Cloud Gateway Quick Recap
Spring Cloud Gateway, or SCG for short, is a sub-project from the Spring Cloud family that provides an API gateway built on top of a reactive web stack. We’ve already covered its basic usage in earlier tutorials, so we won’t get into those aspects here.
Instead, this time we’ll focus on a particular usage scenario that arises from time to time when designing a solution around an API Gateway: how to process a backend response payload before sending it back to the client?
Here’s a list of some cases where we might use this capability:
- Keep compatibility with existing clients while allowing the backend to evolve
- Masking some fields from the responsibility to comply with regulations like PCI or GDPR
In more practical terms, fulfilling those requirements mean that we need to implement a filter to process backend responses. As filters are a core concept in SCG, all we need to do to support response processing is to implement a custom one that applies the desired transformation.
Moreover, once we’ve created our filter component, we can apply it to any declared route.
3. Implementing a Data Scrubbing Filter
To better illustrate how response body manipulation works, let’s create a simple filter that masks values in a JSON-based response. For instance, given a JSON having a field named “ssn”:
{
"name" : "John Doe",
"ssn" : "123-45-9999",
"account" : "9999888877770000"
}
We want to replace their values with a fixed one, thus preventing data leakage:
{
"name" : "John Doe",
"ssn" : "****",
"account" : "9999888877770000"
}
3.1. Implementing the GatewayFilterFactory
A GatewayFilterFactory is, as the name implies, a factory for filters of a given time. At startup, Spring looks for any @Component-annotated class that implements this interface. It then builds a registry of available filters that we can use when declaring routes:
spring:
cloud:
gateway:
routes:
- id: rewrite_with_scrub
uri: ${rewrite.backend.uri:http://example.com}
predicates:
- Path=/v1/customer/**
filters:
- RewritePath=/v1/customer/(?<segment>.*),/api/$\{segment}
- ScrubResponse=ssn,***
Notice that, when using this configuration-based approach to define routes, it is important to name our factory according to SCG’s expected naming convention: FilterNameGatewayFilterFactory. With that in mind, we’ll name our factory ScrubResponseGatewayFilterFactory.
SCG already has several utility classes that we can use to implement this factory. Here, we’ll use one that’s commonly used by the out-of-the-box filters: AbstractGatewayFilterFactory
- fields: a regular expression used to match against field names
- replacement: the string that will replace the original value
The key method we must implement is apply(). SCG calls this method for every route definition that uses our filter. For instance, in the configuration above, apply() will be called only once since there’s just a single route definition.
In our case, the implementation is trivial:
@Override
public GatewayFilter apply(Config config) {
return modifyResponseBodyFilterFactory
.apply(c -> c.setRewriteFunction(JsonNode.class, JsonNode.class, new Scrubber(config)));
}
It is so simple in this case because we’re using another built-in filter, ModifyResponseBodyGatewayFilterFactory, to which we delegate all the grunt work related to body parsing and type conversion. We use constructor injection to get an instance of this factory, and in apply(), we delegate to it the task of creating a GatewayFilter instance.
The key point here is to use the apply() method variant that, instead of taking a configuration object, expects a Consumer for the configuration. Also important is the fact that this configuration is a ModifyResponseBodyGatewayFilterFactory one. This configuration object provides the setRewriteFunction() method we’re calling in our code.
3.2. Using setRewriteFunction()
Now, let’s get a little deeper on setRewriteFunction().
This method takes three arguments: two classes (in and out) and a function that can transform from the incoming type to the outgoing. In our case, we’re not converting types, so both input and output use the same class: JsonNode. This class comes from the Jackson library and is at the very top of the hierarchy of classes used to represent different node types in JSON, such as object nodes, array nodes, and so forth. Using JsonNode as the input/output type allows us to process any valid JSON payload, which we want in this case.
For the transformer class, we pass an instance of our Scrubber, which implements the required RewriteFunction interface in its apply() method:
public static class Scrubber implements RewriteFunction<JsonNode,JsonNode> {
// ... fields and constructor omitted
@Override
public Publisher<JsonNode> apply(ServerWebExchange t, JsonNode u) {
return Mono.just(scrubRecursively(u));
}
// ... scrub implementation omitted
}
The first argument passed to apply() is the current ServerWebExchange, which gives us access to the request processing context so far. We won’t use it here, but it’s good to know we have this capability. The next argument is the received body, already converted to the informed in-class.
The expected return is a Publisher of instances of the informed out-class. So, as long we don’t do any kind of blocking I/O operation, we can do some complex work inside the rewrite function.
3.3. Scrubber Implementation
So, now that we know the contract for a rewrite function, let’s finally implement our scrubber logic. Here, we’ll assume that payloads are relatively small, so we don’t have to worry about the memory requirements to store the received object.
Its implementation just walks recursively over all nodes, looking for attributes that match the configured pattern and replacing the corresponding value for the mask:
public static class Scrubber implements RewriteFunction<JsonNode,JsonNode> {
// ... fields and constructor omitted
private JsonNode scrubRecursively(JsonNode u) {
if ( !u.isContainerNode()) {
return u;
}
if (u.isObject()) {
ObjectNode node = (ObjectNode)u;
node.fields().forEachRemaining((f) -> {
if ( fields.matcher(f.getKey()).matches() && f.getValue().isTextual()) {
f.setValue(TextNode.valueOf(replacement));
}
else {
f.setValue(scrubRecursively(f.getValue()));
}
});
}
else if (u.isArray()) {
ArrayNode array = (ArrayNode)u;
for ( int i = 0 ; i < array.size() ; i++ ) {
array.set(i, scrubRecursively(array.get(i)));
}
}
return u;
}
}
4. Testing
We’ve included two tests in the example code: a simple unit test and an integration one. The first is just a regular JUnit test used as a sanity check for the scrubber. The integration test is more interesting as it illustrates useful techniques in the context of SCG development.
Firstly, there’s the issue of providing an actual backend where messages can be sent. One possibility is to use an external tool like Postman or equivalent, which poses some issues for typical CI/CD scenarios. Instead, we’ll use JDK’s little-known HttpServer class, which implements a simple HTTP server.
@Bean
public HttpServer mockServer() throws IOException {
HttpServer server = HttpServer.create(new InetSocketAddress(0),0);
server.createContext("/customer", (exchange) -> {
exchange.getResponseHeaders().set("Content-Type", "application/json");
byte[] response = JSON_WITH_FIELDS_TO_SCRUB.getBytes("UTF-8");
exchange.sendResponseHeaders(200,response.length);
exchange.getResponseBody().write(response);
});
server.setExecutor(null);
server.start();
return server;
}
This server will handle the request at /customer and return a fixed JSON response used in our tests. Notice that the returned server is already started and will listen to incoming requests at a random port. We’re also instructing the server to create a new default Executor to manage threads used to handle requests
Secondly, we programmatically create a route @Bean that includes our filter. This is equivalent to building a route using configuration properties but allows us to have full control of all aspects of the test route:
@Bean
public RouteLocator scrubSsnRoute(
RouteLocatorBuilder builder,
ScrubResponseGatewayFilterFactory scrubFilterFactory,
SetPathGatewayFilterFactory pathFilterFactory,
HttpServer server) {
int mockServerPort = server.getAddress().getPort();
ScrubResponseGatewayFilterFactory.Config config = new ScrubResponseGatewayFilterFactory.Config();
config.setFields("ssn");
config.setReplacement("*");
SetPathGatewayFilterFactory.Config pathConfig = new SetPathGatewayFilterFactory.Config();
pathConfig.setTemplate("/customer");
return builder.routes()
.route("scrub_ssn",
r -> r.path("/scrub")
.filters(
f -> f
.filter(scrubFilterFactory.apply(config))
.filter(pathFilterFactory.apply(pathConfig)))
.uri("http://localhost:" + mockServerPort ))
.build();
}
Finally, with those beans now part of a @TestConfiguration, we can inject them into the actual test, together with a WebTestClient. The actual test uses this WebTestClient to drive both the spun SCG and the backend:
@Test
public void givenRequestToScrubRoute_thenResponseScrubbed() {
client.get()
.uri("/scrub")
.accept(MediaType.APPLICATION_JSON)
.exchange()
.expectStatus()
.is2xxSuccessful()
.expectHeader()
.contentType(MediaType.APPLICATION_JSON)
.expectBody()
.json(JSON_WITH_SCRUBBED_FIELDS);
}
5. Conclusion
In this article, we’ve shown how to access the response body of a backend service and modify it using the Spring Cloud Gateway library. As usual, all code is available over on GitHub.