Package org.forgerock.openig.handler

Class ClientHandler

  • All Implemented Interfaces:
    Handler
    public class ClientHandler
extends Object
implements Handler
    Submits requests to remote servers. In this implementation, requests are dispatched through a CHF HttpClient. 
       
   {
     "name": "ClientHandler",
     "type": "ClientHandler",
     "config": {
       "connections": 64,
       "disableReuseConnection": true,
       "hostnameVerifier": "ALLOW_ALL",
       "soTimeout": "10 seconds",
       "connectionTimeout": "10 seconds",
       "connectionTimeToLive": "30 seconds",
       "numberOfWorkers": 6,
       "proxy" : {
           "uri": "http://proxy:3128",
           "username": "proxyuser",
           "passwordSecretId": "password.secret.id",
           "secretsProvider": "mySecretProvider"
       },
       "temporaryStorage": {reference to or inline declaration of a TemporaryStorage},
       "asyncBehavior": "streaming" or "non_streaming",
       "tls": {
           "type": "TlsOptions",
           "config": {
               "sslContextAlgorithm": "TLS",
               "keyManager": [ "RefToKeyManager", ... ],
               "trustManager": [ "RefToTrustManager", ... ],
               "sslEnabledProtocols": [ "SSLv2", ... ],
               "sslCipherSuites": [ "TLS_DH_anon_WITH_AES_256_CBC_SHA256", ... ],
           }
       }
       "retries": {
           "enabled": true,
           "executor" "ScheduledExecutorService",
           "count: "5",
           "delay: "10 seconds"
       },
       "websocket": {
           "enabled": false,
           "soTimeout: "10 seconds",
           "connectionTimeout": "10 seconds",
           "tls": "RefToTlsOptions"
       }
     }
   }
    Note: This implementation verifies hostnames for outgoing SSL connections by default. If this gateway access the SSL endpoint using a raw IP address rather than a fully-qualified hostname, then you need to configure hostnameVerifier to ALLOW_ALL.
    Accepted values are:
    • STRICT (the default)
    • ALLOW_ALL

    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 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 proxy optional attribute specifies a http(s) proxy server to use for any outgoing requests. Within the proxy configuration:

    • The uri is a required item and if a username or password is specified then both username and passwordSecretId(or password) are required.
    • passwordSecretId: a label of a Purpose, required to read the GenericSecret required to authenticate the client.
    • password: [Deprecated since 6.5 in favor of passwordSecretId]. See above.
    • secretsProvider: The SecretsProvider to resolve the proxy's password.

    The systemProxy optional boolean attribute if true, specifies to use the system defined proxy for any outgoing requests. If both proxy and systemProxy are defined, proxy takes precedence.

    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 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 websocket optional attribute, if present gives access to Web Socket specific configuration options. It's disabled by default, and if the inner attributes are not valued, they default to the corresponding attribute's value in the ClientHandler configuration (/websocket/soTimeout -> /soTimeout for instance).

    See Also:
    Duration, KeyManagerHeaplet, TrustManagerHeaplet

    • Constructor Detail

      • ClientHandler

        public ClientHandler​(Handler delegate)
        Creates a new client handler.
        Parameters:
        delegate - The HTTP Handler delegate.

    • Method Detail

      • handle

        public Promise<Response,​NeverThrowsException> handle​(Context context,
                                                           Request request)
        Description copied from interface: Handler
        Returns a Promise representing the asynchronous Response of the given request. If any (asynchronous) processing goes wrong, the promise still contains a Response (probably from the 4xx or 5xx status code family).

        A handler that doesn't hand-off the processing to another downstream handler is responsible for creating the response.

        The returned Promise contains the response returned from the server as-is. This is responsibility of the handler to produce the appropriate error response (404, 500, ...) in case of processing error.

        Note: As of Promise 2.0 implementation, it is not permitted to throw any runtime exception here. Doing so produce unexpected behaviour (most likely a server-side hang of the processing thread).

        Specified by:
        handle in interface Handler
        Parameters:
        context - The request context.
        request - The request.
        Returns:
        A Promise representing the response to be returned to the caller.