.. _filters_dev:

*******
Filters
*******

For an overview and basic explanation, visit the :ref:`filters <filters_ops>` section in the operators guide.

Filters can be either added by implementing one of the various filter interfaces like ``HttpInboundSyncFilter`` in the proxy servers main code or by adding a groovy file in one of the filter directories in the proxy installation folder. Following is a sample implementation of an endpoint Healthcheck filter and inbound Routes filter in groovy. The Routes filter will intercept all requests which have ``healthcheck``  in their path and redirect them to the respective endpoint.

.. note:: Even when writing groovy filters the ``package`` declaration is mandatory. Otherwise the dynamic filter activation / deactivation via application.properties will not work as expected.   


Endpoint filter:

.. code-block:: Java

  package groovy.filters.endpoint
  
  class Healthcheck extends HttpSyncEndpoint {

    @Override
    HttpResponseMessage apply(HttpRequestMessage request) {
        HttpResponseMessage resp = new HttpResponseMessageImpl(request.getContext(), request, 200)
        resp.setBodyAsText("healthy")

        // need to set this manually since we are not going through the ProxyEndpoint
        StatusCategoryUtils.setStatusCategory(request.getContext(), ZuulStatusCategory.SUCCESS)

        return resp
    }
  }

Routes filter:

.. code-block:: Java

  package groovy.filters.inbound
  
  class Routes extends HttpInboundSyncFilter {

    @Override
    int filterOrder() {
        return 0
    }

    @Override
    boolean shouldFilter(HttpRequestMessage httpRequestMessage) {
        return true
    }

    @Override
    HttpRequestMessage apply(HttpRequestMessage request) {
        SessionContext context = request.getContext()
        String path = request.getPath()
        String host = request.getOriginalHost()

        // Route healthchecks to the healthcheck endpoint.;
        if (path.equalsIgnoreCase("/healthcheck")) {
            context.setEndpoint(Healthcheck.class.getCanonicalName())
        }
        else {
            context.setEndpoint(ZuulEndPointRunner.PROXY_ENDPOINT_FILTER_NAME);
            context.setRouteVIP("api")
        }

        return request
    }
  }

:filterOrder(): This orders all loaded filters of a type. Lowest numbers will be executed first.

:shouldFilter(): Which preconditions have to be met, for this filter to be executed.

:apply: What should be done in this filter

.. note:: The ``Context`` object, that is used in the Routes example, is a crucial component of the filter framework used by zuul. With it, the developer can easily transfer data between a filter and its descendants. Each ``Context`` is unique to every request.

For more information about filters, please take a look at the example filters in the Zuul 2 repository, found `here <https://github.com/Netflix/zuul/tree/master/zuul-sample/src/main/groovy/com/netflix/zuul/sample/filters>`_ .