IG 7.2.0

ClientHandler

Creates a response to a request by forwarding the request to a third-party service accessible through HTTP, and reconstructing the response from the received bytes.

When IG relays the request to the third-party service, IG is acting as a client of the service. IG is client-side. A third-party service is one that IG calls for data, such as an HTTP API or AM, or one to which IG submits data.

If IG fails to connect to the third-party service, the ClientHandler propagates the error along the chain.

Use ClientHandler to submit requests to third-party services such as AM or HTTP APIs. Do not use it to proxy requests to a protected application. To proxy requests to a protected application, use a ReverseProxyHandler instead.

When uploading or downloading large files, prevent timeout issues by increasing the value of soTimeout, and using a streaming mode, as follows:

  • In standalone mode, configure the streamingEnabled property of AdminHttpApplication.

  • In web container mode, configure the asyncBehaviour property in this handler.

Usage

{
  "name": string,
  "type": "ClientHandler",
  "config": {
    "vertx": object,
    "connections": configuration expression<number>,
    "disableReuseConnection": configuration expression<boolean>,
    "stateTrackingEnabled": configuration expression<boolean>,
    "soTimeout": configuration expression<duration>,
    "connectionTimeout": configuration expression<duration>,
    "connectionTimeToLive": configuration expression<duration>,
    "numberOfWorkers": configuration expression<number>,
    "protocolVersion": configuration expression<enumeration>,
    "http2PriorKnowledge": configuration expression<boolean>,
    "proxyOptions": ProxyOptions reference,
    "temporaryStorage": TemporaryStorage reference,
    "tls": ClientTlsOptions reference,
    "asyncBehavior": configuration expression<enumeration>,
    "retries": object,
    "circuitBreaker": object
  }
}

Properties

"vertx": object, optional

Vert.x-specific configuration for the handler, where IG does not provide its own first-class configuration. Vert.x options are described in HttpClientOptions.

The vertx object is read as a map, and values are evaluated as configuration expressions.

For properties where IG provides its own first-class configuration, Vert.x configuration options are disallowed, and the IG configuration option takes precedence over Vert.x options configured in vertx. The following Vert.x configuration options are disallowed client-side:

  • port

  • connectTimeout

  • idleTimeout

  • idleTimeoutUnit

  • protocolVersion

  • http2ClearTextUpgrade

  • verifyHost

  • ssl

  • enabledSecureTransportProtocols

  • enabledCipherSuites

  • keyStoreOptions

  • keyCertOptions

  • pemKeyCertOptions

  • pfxKeyCertOptions

  • trustOptions

  • trustStoreOptions

  • pemTrustOptions

  • pfxTrustOptions

  • useAlpn

  • alpnVersions

"connections": configuration expression<number>, optional

The maximum number of concurrent HTTP connections in the client connection pool.

Default: 64

"connectionTimeout": configuration expression<duration>, optional

Time to wait to establish a connection, expressed as a duration

Default: 10 seconds

"connectionTimeToLive": configuration expression<duration>, optional

Amount of time before a reusable pooled connection expires.

Set this property to expire reusable pooled connections after a fixed duration. For example, to prevent the reuse of connections set this property in routes for applications where the IP address (baseURI) is not stable or can change.

Default: Unlimited

"disableReuseConnection": configuration expression<boolean>, optional

Not supported in standalone mode.

A flag to disable connection reuse:

  • true: Connection reuse is disabled

  • false: Connection reuse is enabled

Default: false

"stateTrackingEnabled": configuration expression<boolean>, optional

Not supported in standalone mode.

By default, the Apache HTTP Client does not allow connection reuse when a client certificate is used for authentication. However, because the client certificate is defined at the client level, it is acceptable for requests to the same target to share a client certificate.

Use in combination with disableReuseConnection:

disableReuseConnection stateTrackingEnabled Description

false (default)

true (default)

Do not allow connection reuse when a client certificate is used for authentication.

false (default)

false

Allow connection reuse when a client certificate is used for authentication.

true

true (default) or false

Do not allow connection reuse.

Default: true

"numberOfWorkers": configuration expression<number>, optional

Not supported in standalone mode.

The number of worker threads dedicated to processing outgoing requests.

Increasing the value of this attribute can be useful in deployments where a high number of simultaneous connections remain open, waiting for protected applications to respond.

Default: One thread per CPU available to the JVM.

"protocolVersion": configuration expression<enumeration>, optional

Not supported in web container mode.

The version of HTTP protocol to use when processing requests:

  • HTTP/2:

    • For HTTP, process requests using HTTP/1.1.

    • For HTTPS, process requests using HTTP/2.

  • HTTP/1.1:

    • For HTTP and HTTPS, process requests using HTTP/1.1.

  • Not set:

    • For HTTP, process requests using HTTP/1.1.

    • For HTTPS with alpn enabled in ClientTlsOptions, process requests using HTTP/1.1, with an HTTP/2 upgrade request. If the targeted server can use HTTP/2, the client uses HTTP/2.

      For HTTPS with alpn disabled in ClientTlsOptions, process requests using HTTP/1.1, without an HTTP/2 upgrade request.

      Note that alpn is enabled by default in ClientTlsOptions.

    Default: Not set

In HTTP/1.1 request messages, a Host header is required to specify the host and port number of the requested resource. In HTTP/2 request messages, the Host header is not available.

In scripts or custom extensions that use HTTP/2, use UriRouterContext.originalUri.host or UriRouterContext.originalUri.port in requests.
"http2PriorKnowledge": configuration expression<boolean>, optional

Not supported in web container mode.

A flag for whether the client should have prior knowledge that the server supports HTTP/2. This property is for cleartext (non-TLS requests) only, and is used only when protocolVersion is HTTP/2.

  • false: The client checks whether the server supports HTTP/2 by sending an HTTP/1.1 request to upgrade the connection to HTTP/2:

    • If the server supports HTTP/2, the server upgrades the connection to HTTP/2, and subsequent requests are processed over HTTP/2.

    • If the server does not support HTTP/2, the connection is not upgraded, and subsequent requests are processed over HTTP/1.

  • true: The client does not check that the server supports HTTP/2. The client sends HTTP/2 requests to the server, assuming that the server supports HTTP/2.

Default: false

"proxyOptions": ProxyOptions reference>, optional

A proxy server to which requests can be submitted. Use this property to relay requests to other parts of the network. For example, use it to submit requests from an internal network to the internet.

Provide the name of a ProxyOptions object defined in the heap, or an inline configuration.

Default: A heap object named ProxyOptions.

"soTimeout": configuration expression<duration>, optional

Socket timeout, after which stalled connections are destroyed, expressed as a duration.

If SocketTimeoutException errors occur in the logs when you try to upload or download large files, consider increasing soTimeout.

Default: 10 seconds

"temporaryStorage": TemporaryStorage reference, optional

The TemporaryStorage object to buffer the request and response, when the streamingEnabled property of admin.json is false.

Default: A heap object named TemporaryStorage.

tls: ClientTlsOptions reference, optional

Configure options for connections to TLS-protected endpoints, based on ClientTlsOptions. Define the object inline or in the heap.

Default: Connections to TLS-protected endpoints are not configured.

`"asyncBehavior": configuration expression<enumeration>, optional
Not supported for IG in standalone mode. For information about how to configure streaming for IG in standalone mode, see the streamingEnabled property of AdminHttpApplication.

Specifies how the HTTP client behaves for asynchronous responses:

  • streaming: Responses are processed as soon as all headers are received. The entity content is downloaded in a background thread. The value is not case-sensitive.

    Streaming mode reduces latency and is mandatory for Server-Sent Events (SSE) and the support of very large files (bigger than 2 GB). If thread starvation occurs, consider increasing numberOfWorkers, the number of worker threads dedicated to processing outgoing requests.

  • non_streaming: Responses are processed when the entity content is entirely available. The value is not case-sensitive.

    Non-streaming mode does not support SSE or very large files. However, it has higher latency, and does not cause thread starvation.

    To prevent timeout issues with large files, consider increasing the value of soTimeout, and setting asyncBehavior to streaming.

Default: non_streaming

"retries": object, optional

Enable and configure retry for requests.

During the execution of a request to a remote server, if a runtime exception occurs, or a condition is met, IG waits for a delay, and then schedules a new execution of the request. IG tries until the allowed number of retries is reached or the execution succeeds.

A warning-level entry is logged if all retry attempts fail; a debug-level entry is logged if a retry succeeds.

"retries": {
  "enabled": configuration expression<boolean>,
  "condition": runtime expression<boolean>,
  "executor": ScheduledExecutorService reference,
  "count": configuration expression<number>,
  "delay": configuration expression<duration>,
  }
}
"enabled": configuration expression<boolean>, optional

Enable retries.

Default: true

"condition": runtine expression<boolean>, optional

An inline IG expression to define a condition based on the response, such as an error code.

The condition is evaluated as follows:

  • If true, IG retries the request until the value in count is reached.

  • If false, IG retries the request only if a runtime exception occurs, until the value in count is reached.

    Default: ${false}

"executor": ScheduledExecutorService reference, optional

The ScheduledExecutorService to use for scheduling delayed execution of the request.

Default: ScheduledExecutorService

See also ScheduledExecutorService.

"count": configuration expression<number>, optional

The maximum number of retries to perform. After this threshold is passed and if the request is still not successful, then the ClientHandler propagates the failure.

Retries caused by any runtime exception or triggered condition are included in the count.

Default: 5

"delay": _configuration expression<duration>, optional

The time to wait before retrying the request.

After a failure to send the request, if the number of retries is below the threshold, a new attempt is scheduled with the executor service after this delay.

Default: 10 seconds

The following example configures a retry when a downstream component returns a 502 Bad Gateway response code:

"retries": {
    "enabled": true,
    "condition": "${response.status.code == 502}"
}

The following example configures the handler to retry the request only once, after a 1-minute delay:

{
  "retries": {
    "count": 1,
    "delay": "1 minute"
  }
}

The following example configures the handler to retry the request at most 20 times, every second:

{
  "retries": {
    "count": 20,
    "delay": "1 second"
  }
}

The following example configures the handler to retry the request 5 times, every 10 seconds (default values), with a dedicated executor:

{
  "retries": {
    "executor": {
      "type": "ScheduledExecutorService",
      "config": {
        "corePoolSize": 20
      }
    }
  }
}
"circuitBreaker": object, optional

Enable and configure a circuit breaker to trip when the number of failures exceeds a configured threshold. Calls to downstream services are stopped, and a runtime exception is returned. The circuit breaker is reset after the configured delay.

{
  "circuitBreaker": {
    "enabled": configuration expression<boolean>,
    "maxFailures":  configuration expression<integer>,
    "openDuration": configuration expression<duration>,
    "openHandler": Handler reference,
    "slidingCounter":  object,
    "executor":  ScheduledExecutorService reference
  }
}
"enabled": configuration expression<boolean>, optional

A flag to enable the circuit breaker.

Default: true

"maxFailures": configuration expression<number>, required

The maximum number of failed requests allowed in the window given by size, before the circuit breaker trips. The value must be greater than zero.

When retries is set, the circuit breaker does not count retried requests as failures. Bear this in mind when you set maxFailures.

In the following example, a request can fail and then be retried three times. If it fails the third retry, the request has failed four times, but the circuit breaker counts only one failure.

{
  "retries": {
    "count": 3,
    "delay": "1 second"
  }
}
"openDuration": configuration expression<duration>, required

The duration for which the circuit stays open after the circuit breaker trips. The executor schedules the circuit to be closed after this duration.

"openHandler": Handler reference, optional

The Handler to call when the circuit is open.

Default: A handler that throws a RuntimeException with a "circuit-breaker open" message.

"slidingCounter": object, optional

A sliding window error counter. The circuit breaker trips when the number of failed requests in the number of requests given by size reaches maxFailures.

The following image illustrates how the sliding window counts failed requests:

Example sliding window error counter. 
{
  "slidingCounter":  {
    "size": configuration expression<number>
  }
}
"size": configuration expression<number>, required

The size of the sliding window in which to count errors.

The value of size must be greater than zero, and greater than the value of maxFailures, otherwise an exception is thrown.

"executor": ScheduledExecutorService reference, optional

A ScheduledExecutorService to schedule closure of the circuit after the duration given by openDuration.

Default: The default ScheduledExecutorService in the heap

Example

The following object configures a ClientHandler named Client:

{
  "name": "Client",
  "type": "ClientHandler",
  "config": {
    "hostnameVerifier": "STRICT",
    "tls": {
      "type": "ClientTlsOptions",
      "config": {
        "sslContextAlgorithm": "TLSv1.2",
        "keyManager": {
          "type": "KeyManager",
          "config": {
            "keystore": {
              "type": "KeyStore",
              "config": {
                "url": "file://${env['HOME']}/keystore.jks",
                "passwordSecretId": "keymanager.keystore.secret.id",
                "secretsProvider": "SystemAndEnvSecretStore"
              }
            },
            "passwordSecretId": "keymanager.secret.id",
            "secretsProvider": "SystemAndEnvSecretStore"
          }
        },
        "trustManager": {
          "type": "TrustManager",
          "config": {
            "keystore": {
              "type": "KeyStore",
              "config": {
                "url": "file://${env['HOME']}/truststore.jks",
                "passwordSecretId": "trustmanager.keystore.secret.id",
                "secretsProvider": "SystemAndEnvSecretStore"
              }
            }
          }
        }
      }
    }
  }
}

More information

org.forgerock.openig.handler.ClientHandlerHeaplet

Copyright © 2010-2022 ForgeRock, all rights reserved.