Package org.forgerock.openig.handler

Class 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,
       "stateTrackingEnabled": true,
       "soTimeout": "10 seconds",
       "connectionTimeout": "10 seconds",
       "connectionTimeToLive": "30 seconds",
       "waitQueueSize": 4096,
       "numberOfWorkers": 6,
       "proxyOptions": "myProxyOptions",
       "temporaryStorage": {reference to or inline declaration of a TemporaryStorage},
       "asyncBehavior": "streaming" or "non_streaming",
       "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",
           "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 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 numberOfWorkers optional attribute specifies the number of threads dedicated to process outgoing requests. It defaults to the number of CPUs available to the JVM. This attribute is only used if an asynchronous Http client engine is used (that is the default).

    The asyncBehavior optional attribute specifies how the HTTP client should behave with regard to asynchronous responses.

    • streaming: response is processed as soon as all headers have been received (entity content is downloaded in a background thread). May lead to thread starvation issue, but is mandatory for SSE and very large file support
    • non_streaming: response is processed when the entity content is entirely available, latency is higher but thread starvation will not happen. Does not support SSE or very large files (more than 2GB).

    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:
    Duration

    • Field Detail

      • CONFIG_ASYNC_BEHAVIOR

        public static final String CONFIG_ASYNC_BEHAVIOR
        Constant for the configuration asyncBehavior.
        See Also:
        Constant Field Values

      • CONFIG_ENABLE_CONNECTION_STATE

        public static final String CONFIG_ENABLE_CONNECTION_STATE
        Constant for the configuration stateTrackingEnabled.
        See Also:
        Constant Field Values

      • CONFIG_HTTP2_PRIOR_KNOWLEDGE

        public static final String CONFIG_HTTP2_PRIOR_KNOWLEDGE
        Constant for the configuration http2PriorKnowledge.
        See Also:
        Constant Field Values

      • CONFIG_NUMBER_OF_WORKERS

        public static final String CONFIG_NUMBER_OF_WORKERS
        Constant for the configuration numberOfWorkers.
        See Also:
        Constant Field Values

      • CONFIG_PROTOCOL_VERSION

        public static final String CONFIG_PROTOCOL_VERSION
        Constant for the configuration protocolVersion.
        See Also:
        Constant Field Values

      • CONFIG_WAIT_QUEUE_SIZE

        public static final String CONFIG_WAIT_QUEUE_SIZE
        Constant for the configuration waitQueueSize.
        See Also:
        Constant Field Values

    • Constructor Detail

      • HttpClientHandlerHeaplet

        public HttpClientHandlerHeaplet()

    • Method Detail

      • 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.

      • configurationSupported

        protected final boolean configurationSupported​(org.forgerock.openig.http.spi.HttpClientLoader loader,
                                               JsonValue value)
        Is the provided configuration supported by the HttpClientLoader.
        Parameters:
        loader - the HttpClientLoader.
        value - the configuration to know if it is supported or not.
        Returns:
        true if the provided configuration is supported by this HttpClientLoader, false otherwise.

      • 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.

      • 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​(org.forgerock.openig.http.spi.HttpClientLoader loader,
                                        Options options)
                                 throws HeapException
        Returns a list of Filter that will be executed on every request before the HttpClientHandler.
        Parameters:
        loader - the HttpClientLoader associated to that instance.
        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.