PingFilter

Info: Available since version 12.2.0.

Overview

The PingFilter is designed for use with load balancers to determine if a cluster node is available to handle requests. When the filter returns HTTP status 200 (HttpServletResponse.SC_OK), the node is ready to serve traffic. If it returns HTTP status 503 (HttpServletResponse.SC_SERVICE_UNAVAILABLE), the node is not yet ready.

The PingFilter is preferred over the PingServlet, especially for projects with large HST configurations. Unlike the PingServlet, the PingFilter responds immediately, regardless of the size of the configuration.

Note: Always use the PingFilter instead of the PingServlet. For projects with large HST configurations, using the PingFilter is strongly recommended.

Starting from version 13.0, new projects created with the archetype use the PingFilter by default.

PingFilter vs. PingServlet

The PingServlet in the site web application returns a response only after the repository is fully initialized and the entire HST in-memory model is loaded. For large HST configurations (for example, with 100,000 configuration JCR nodes), this process can take significant time. If each database fetch takes 1 ms, the initial ping could take at least 100 seconds. During this period, a load balancer may consider the node unavailable and stop sending traffic to it.

In contrast, the PingFilter responds instantly. It returns HTTP 200 if the node is ready or HTTP 503 if not. As the application finishes initializing, repeated pings will eventually receive HTTP 200, indicating readiness.

Prerequisites

To use the default PingFilter setup, do not include the following context-param in your site's web.xml:

<context-param>
  <param-name>hst-lazy-configuration-loading</param-name>
  <param-value>true</param-value>
</context-param>

By default, this parameter is not present. If it is present, it was added in your project implementation.

If you have configured hst-lazy-configuration-loading = true, you can still use the PingFilter by specifying the PingFilter init-param:

<init-param>
  <param-name>hst-availability-check</param-name>
  <param-value>hstServices</param-value>
</init-param>

<init-param>
  <param-name>hst-availability-check</param-name>
  <param-value>repositoryAvailability</param-value>
</init-param>

See the configuration options section below for details on repositoryAvailability and hstServices.

Configure the PingFilter in the Site Web Application

To enable the PingFilter, add it to your site's web.xml before the HstFilter:

<filter>
  <filter-name>PingFilter</filter-name>
  <filter-class>org.hippoecm.hst.container.PingFilter</filter-class>
</filter>

Add the filter mapping before the HstFilter mapping:

<filter-mapping>
  <filter-name>PingFilter</filter-name>
  <url-pattern>/ping/*</url-pattern>
  <dispatcher>REQUEST</dispatcher>
</filter-mapping>

If the PingServlet is present, remove it:

<servlet>
  <servlet-name>PingServlet</servlet-name>
  <servlet-class>org.hippoecm.hst.servlet.HstPingServlet</servlet-class>
</servlet>

And remove its mapping:

<servlet-mapping>
  <servlet-name>PingServlet</servlet-name>
  <url-pattern>/ping/*</url-pattern>
</servlet-mapping>

After this configuration, requests to URLs such as http://www.example.org/ping are handled by the PingFilter.

PingFilter Configuration Options

Use the configuration options below only if you have specific requirements. By default, the PingFilter checks for the availability of HST configuration nodes in memory.

If you want the filter to check only for a running repository, configure it as follows:

<filter>
  <filter-name>PingFilter</filter-name>
  <filter-class>org.hippoecm.hst.container.PingFilter</filter-class>
  <init-param>
    <param-name>hst-availability-check</param-name>
    <param-value>repositoryAvailability</param-value>
  </init-param>
</filter>

If you only require the HST Services (and HST Spring Component Manager) to be available, use:

<filter>
  <filter-name>PingFilter</filter-name>
  <filter-class>org.hippoecm.hst.container.PingFilter</filter-class>
  <init-param>
    <param-name>hst-availability-check</param-name>
    <param-value>hstServices</param-value>
  </init-param>
</filter>

Custom Error Message

Starting with versions 12.5.1 and 12.6.1, the PingFilter supports a custom-error-message parameter. Configure this parameter in web.xml or, preferably, as a context parameter in context.xml. When set, the PingFilter returns HTTP 503 with the custom error message in the response.

<Context>
    <!-- Make org.hippoecm.hst.container.PingFilter return a 503 status -->
    <Parameter name="custom-error-message" value="This site is down on behalf an upgrade"/>
</Context>