Package org.forgerock.openig.handler

Class HttpClientHandlerHeaplet

java.lang.Object
org.forgerock.openig.heap.GenericHeaplet
org.forgerock.openig.handler.HttpClientHandlerHeaplet
All Implemented Interfaces:
Heaplet
Direct Known Subclasses:
ClientHandlerHeaplet, ReverseProxyHandlerHeaplet
public abstract class HttpClientHandlerHeaplet extends GenericHeaplet
Abstract Heaplet to create HTTP clients with different behaviors. In this implementation, requests are dispatched through a CHF HttpClient. All types created from this Heaplet with support the following configuration items: 
   
     "config": {
       "protocolVersion": "HTTP/2",
       "connections": 64,
       "disableReuseConnection": true,
       "soTimeout": "10 seconds",
       "connectionTimeout": "10 seconds",
       "connectionTimeToLive": "30 seconds",
       "propagateDisconnection": true,
       "waitQueueSize": 4096,
       "proxyOptions": "myProxyOptions",
       "temporaryStorage": {reference to or inline declaration of a TemporaryStorage},
       "tls": {
           "type": "ClientTlsOptions",
           "config": {
               "sslContextAlgorithm": "TLS",
               "keyManager": [ "RefToKeyManager", ... ],
               "trustManager": [ "RefToTrustManager", ... ],
               "sslEnabledProtocols": [ "SSLv2", ... ],
               "sslCipherSuites": [ "TLS_DH_anon_WITH_AES_256_CBC_SHA256", ... ],
               "alpn": {
                   "enabled": true
               }
           }
       }
       "retries": {
           "enabled": true,
           "executor" "ScheduledExecutorService",
           "count": "5",
           "delay": "10 seconds",
           "runtimeExceptionCondition": "${exception.message.contains(\"GOAWAY\")}",
           "condition": "${response.status.code == 502}"
       },
       "circuitBreaker": {
           "enabled": true,
           "maxFailures": 10,
           "openDuration": "1 minute",
           "openHandler": "myHandlerReference",
           "slidingCounter": {
               "size": 100
           }
       }
     }
The soTimeout optional attribute specifies a socket timeout (the given amount of time a connection will live before being considered a stalled and automatically destroyed). It defaults to 10 seconds.
The connectionTimeout optional attribute specifies a connection timeout (the given amount of time to wait until the connection is established). It defaults to 10 seconds.
The connectionTimeToLive optional attribute specifies a connection time-to-live (the amount of time before a reusable pooled connection expires). It defaults to never expiring. An example of where changing this from the default so connections from the pool expire would be where ClientHandler connections to an application go through a load-balancer and the load-balancer's IP address has changed due to resource changes so new connections should end up at the new IP based on underlying DNS updates.

The connections optional attribute defines both the maximum available HTTP/1 and HTTP/2 connections. If not supplied, it defaults to 64 each.

The propagateDisconnection optional attribute defines if a user-agent disconnection is propagated down to the appSide client connection. When not enabled, if the user-agent disconnects before the response has been completed then the appSide client will continue to stream the response until it has completed. This setting is currently only supported when PingGateway is in streaming mode and the response Transfer-Encoding header is set to chunked. If not supplied, it defaults to false.

The waitQueueSize optional attribute defines the size of the wait queue that is used to hold outbound requests when no downstream connections are available. It is used as a safety net to prevent undue memory usage should there be a backlog of outbound requests (for example should the protected application or third-party service be slow). This may be set to unlimited with value WAIT_QUEUE_SIZE_UNLIMITED, though be aware that this bypasses stability safeguards. If unset, this defaults according to the following rules:

  1. use the square of the connections value (or its default, if not configured)
  2. if the connections is so large that the above would exceed technical limits then the default waitQueueSize is set to the maximum possible integer value less connections.

The retries optional attribute, if supported by the Heaplet and enabled, will retry the failed request a number of times, each separated by a delay. It is disabled by default, unless the retries attribute is provided, and its enabled setting not set to false (defaults to true).

The circuitBreaker optional attribute, will add a CircuitBreakerFilter in front of the HTTP client. When circuitBreaker and retries are both set, the CircuitBreakerFilter fronts the RetryFilter, which means you should account for retries when defining the maxFailures. For example: if each request is retried 3 times, then on connection failure 3 request retry attempts will only count for 1 failure.

The protocolVersion optional attribute specifies the protocol to use when sending the requests. It defaults to 'HTTP/1.1'. The other possible value is 'HTTP/2'.

The http2PriorKnowledge optional attribute specifies the strategy to use when sending HTTP/2 requests. If false (default value), then when issuing non-TLS requests using the HTTP/2 protocol, the client will first send an HTTP/1.1 requesting an upgrade to HTTP/2, that may be accepted or not by the server. If true, then when issuing non-TLS requests using the HTTP/2 protocol, the client will send directly an HTTP/2 request, requiring some prior knowledge that the server effectively supports HTTP/2.

See Also:

  • Constructor Details

    • HttpClientHandlerHeaplet

      public HttpClientHandlerHeaplet()

  • Method Details

    • create

      public final Object create() throws HeapException
      Description copied from class: GenericHeaplet
      Called to request the heaplet create an object. Called by Heaplet.create(Name, JsonValue, Heap) after initializing the protected field members. Implementations should parse configuration but not acquire resources, start threads, or log any initialization messages. These tasks should be performed by the GenericHeaplet.start() method.
      Specified by:
      create in class GenericHeaplet
      Returns:
      The created object.
      Throws:
      HeapException - if an exception occurred during creation of the heap object or any of its dependencies.

    • retryFilter

      protected final Optional<Filter> retryFilter(JsonValue config, org.forgerock.monitoring.api.instrument.MeterRegistry meterRegistry) throws HeapException
      Returns a RetryFilter if the provided configuration enabled its usage, or empty if not.
      Parameters:
      config - the whole configuration.
      meterRegistry - The MeterRegistry to use.
      Returns:
      a RetryFilter if the provided configuration enabled its usage, or empty if not.
      Throws:
      HeapException - if any error occurs during the setup of the RetryFilter.

    • circuitBreakerFilter

      protected final Optional<Filter> circuitBreakerFilter(JsonValue config) throws HeapException
      Create a circuit breaker filter from configurations.
      Parameters:
      config - the configurations
      Returns:
      a new CircuitBreakerFilter instance if enabled.
      Throws:
      HeapException - should there be a configuration error

    • destroy

      public void destroy()
      Description copied from interface: Heaplet
      Called to indicate that the object created by the heaplet is going to be dereferenced. This gives the heaplet an opportunity to free any resources that are being held prior to its dereference.
      Specified by:
      destroy in interface Heaplet
      Overrides:
      destroy in class GenericHeaplet

    • filters

      protected abstract List<Filter> filters(Options options) throws HeapException
      Returns a list of Filter that will be executed on every request before the HttpClientHandler.
      Parameters:
      options - the options that will be used to create the HttpClientHandler.
      Returns:
      A list of Filter that will be executed on every request before the HttpClientHandler.
      Throws:
      HeapException - if any error occurs during the setup of the filters.