[Spike] Interceptor API for REST in the Gateway and Java client

[tmetzke]

Description

Conduct a spike to determine the following items:

• We provide a custom middleware mechanism for the REST API that operates similarly to the custom gRPC interceptor mechanism.
• Middleware should be available for the server (gateway) and client sides.
• It shouldn’t cause any breaking changes.

Resources

• Spike document (internal)

[tmetzke]

Results (preliminary)

• We recommend providing separate APIs for the gateway and client interceptors, dismissing reusable middleware for gRPC and REST.
  • We expose the full gRPC interceptor API, don't know which features are used, and thus cannot efficiently design an API that keeps backward compatibility.
  • The mechanisms provided by REST and gRPC interceptors differ substantially, so efficiently designing a common API that empowers users becomes a complex task.
• We favor jakarta.servlet.Filters for REST gateway interceptors and org.apache.hc.client5.http.async.AsyncExecChainHandlers for REST Java client interceptors.
  • Both classes are the closest REST counterparts to the existing gRPC concepts.
  • The REST gateway interceptors are framework-agnostic, potentially allowing us to move away from Spring in the future if needed without adjusting custom middleware. This also still allows providing a common API for interceptors in the future if we want this.
  • The Java client already exposes the Apache HTTP client through API, so no new dependency is introduced for users. We are increasing the coupling to the Apache HTTP client though. However, providing a custom interceptor API again requires more knowledge about use cases for such client-side interceptors. We would need more time to gather this intel, design a proper API, and maintain & extend this API moving forward.
• The Java client interceptors are directly added to the list of client-side interceptors in the Apache HTTP client.
• The REST gateway interceptors are wrapped in an internal filter wrapper class, ordered by definition, and added to the filter chain in Spring.

[koevskinikola]

Results (final)

The decisions documented in the preliminary results above remain fully valid.

Furthermore, we will use the Spring Web CompositeFilter class as the internal filter wrapper class in the REST gateway interceptors. The Spring Web CompositeFilter class already provides a very nice mechanism for wrapping multiple (Jakarta Servlet) Filter implementations with a VirtualFilterChain that nicely handles any "chain-breaking" logic.

For instantiating the user-defined Filter classes, we will rely on the existing InterceptorRepository mechanism that is already used for gRPC interceptors. A new FilterRespository class will be created with a similar logic.