Filter Overview

Filters are the core of Zuul’s functionality. They are responsible for the business logic of the application and can perform a variety of tasks. There are three types of filters, each responsible for different tasks and executed on different stages in the lifecycle of a request. Filters have a distinct set of features that influence their behavior. Those are:

Type

Most often defines the stage during the routing flow when the Filter will be applied (although it can be any custom string).

Async

Define if the filter is sync or async, generally meaning do you need to make an external call or just doing work on-box.

Execution Order

Applied within the Type, defines the order of execution across multiple Filters.

Criteria

The conditions required in order for the Filter to be executed.

Action

The action to be executed if the Criteria is met.

Example implementations and further detailed information can be found in the developers section for filters.

Zuul provides a framework to dynamically read, compile, and run these Filters. Filters do not communicate with each other directly - instead they share state through a RequestContext which is unique to each request.

Filters are currently written in Groovy, although Zuul supports any JVM-based language. The source code for each Filter is written to a specified set of directories on the Zuul server that are periodically polled for changes. Updated filters are read from disk, dynamically compiled into the running server, and are invoked by Zuul for each subsequent request.

Groovy filters can be dynamically added into one of the following directories to be applied in production:

Directories:

filters
  |- inbound
  |- endpoint
  |- outbound

Note

Filters are also located in the App Suite Proxy JAR file. Those filters can not be manipulated dynamically and will always be applied. Take this into consideration when adding new filters. Checkout the distinct filter documentation to determine ways of disabling an existing filter or to get its order number.

Filter deactivation

After applying your filters in the previously mentioned directoriesyou can activate/deactivate them through a property in the application.properties. This mechanism can also be used to deactivate already shipped filters, located inside the jar file. In case of groovy files it is mandatory to add a package declaration as described in the developer guide.

The property has the form of zuul.<simple-class-name>.<type>.disable. The <type> value represents the filter type and can be one of in, end or out.

Examples:

zuul.RandomInboundFilter.in.disable=true
zuul.RandomEndpointFilter.end.disable=false
zuul.RandomOutboundFilter.out.disable=true

Note

This properties are not reloadable. You have to restart the proxy to make the deactivation active.

Incoming/Inbound filters

Incoming filters get executed before the request gets proxied to the origin. This is generally where the majority of the business logic gets executed. For example: authentication, dynamic routing, rate limiting, DDoS protection, metrics.

Endpoint filters

Endpoint filters are responsible for handling the request based on the execution of the incoming filters. Zuul comes with a built-in filter (ProxyEndpoint) for proxying requests to backend servers, so the typical use for these filters is for static endpoints. For example: health check responses, static error responses, 404 responses

Outgoing/Outbound filters

Outgoing filters handle actions after receiving a response from the backend. Typically they’re used more for shaping the response and adding metrics than any heavy lifting. For example: storing statistics, adding/stripping standard headers, sending events to real-time streams, gziping responses.