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 response 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”:
We want to replace their values with a fixed one, thus preventing a data leakage:
3.1. Implementing the
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:
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
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<T>, a templated base class, where T stands for the configuration class associated with our filter instances. In our case, we only need two configuration properties:
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:
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
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.
Now, let’s get a little deeper on
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
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.
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:
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.
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:
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:
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.