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.

Usage

{
  "name": string,
  "type": "ClientHandler",
  "config": {
    "connections": configuration expression<number>,
    "disableReuseConnection": configuration expression<boolean>,
    "stateTrackingEnabled": configuration expression<boolean>,
    "hostnameVerifier": configuration expression<enumeration>,
    "soTimeout": duration string,
    "connectionTimeout": duration string,
    "connectionTimeToLive": duration string,
    "numberOfWorkers": configuration expression<number>,
    "protocolVersion": configuration expression<enumeration>,
    "http2PriorKnowledge": configuration expression<boolean>,
    "proxy": Server reference,
    "systemProxy": boolean,
    "temporaryStorage": string,
    "tls": ClientTlsOptions reference,
    "asyncBehavior": enumeration,
    "retries": object,
    "websocket": object
  }
}

Properties

"connections": configuration expression<number>, optional: When IG is in standalone mode, this property defines the maximum number of concurrent HTTP/1.1 connections in the client connection pool, for each Vert.x HTTP client. The number of Vert.x HTTP clients is configured by the gatewayUnits property of admin.json. For example, when connections = 64, and gatewayUnits = 3, the maximum number of concurrent HTTP/1.1 connections in the client connection pool is 192.

When IG is in web container mode, this property defines the maximum number of concurrent HTTP/1.1 connections in the client connection pool. Default: 64
"connectionTimeout": duration string, optional: Time to wait to establish a connection, expressed as a duration

Default: 10 seconds

"connectionTimeToLive": duration string, optional

Not supported for IG in standalone mode.

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: Supported only for IG in web container mode.

Whether to disable connection reuse.

Default: false

"stateTrackingEnabled": configuration expression<boolean>, optional

Not supported for IG 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

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.

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

"hostnameVerifier": configuration expression<enumeration>, optional

Way to handle hostname verification for outgoing SSL connections. Use one of the following values:

ALLOW_ALL: Allow a certificate issued by a trusted CA for any hostname or domain to be accepted for a connection to any domain.

This setting allows a certificate issued for one company to be accepted as a valid certificate for another company.

To prevent the compromise of TLS connections, use this setting in development mode only. In production, use STRICT.
STRICT: Match the hostname either as the value of the the first CN, or any of the subject-alt names.

A wildcard can occur in the CN, and in any of the subject-alt names. Wildcards match one domain level, so \*.example.com matches www.example.com but not some.host.example.com.

Default: STRICT

"numberOfWorkers": configuration expression<number>, optional

Not supported for IG 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

Supported only for IG in standalone 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

This property is used only when IG is running in standalone mode, and when protocolVersion is HTTP/2.

Specifies whether the client should have prior knowledge that the server supports HTTP/2. This property is for cleartext (non-TLS requests) only.

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

"proxy": Server 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.

If both proxy and systemProxy are defined, proxy takes precedence.

"proxy" : {
  "uri": configuration expression<uri string>,
  "username": configuration expression<string>,
  "passwordSecretId": configuration expression<secret-id>,
  "secretsProvider": SecretsProvider reference
}

uri: configuration expression<uri string>, required: URI of a server to use as a proxy for outgoing requests.

The result of the expression must be a string that represents a valid URI, but is not a real java.net.URI object.
username: configuration expression<string>, required if the proxy requires authentication: Username to access the proxy server.
"passwordSecretId": configuration expression<secret-id>, required if the proxy requires authentication: The secret ID of the password to access the proxy server.

For information about supported formats for secret-id, see secret-id.

"secretsProvider": SecretsProvider reference, optional

The SecretsProvider to query for the proxy’s password. For more information, see SecretsProvider.

Default: The route’s default secret service. For more information, see Default Secrets Object.

In the following example, the ClientHandler passes outgoing requests to the proxy server, which requires authentication:

"handler": {
  "type": "ClientHandler",
  "config": {
     "proxy": {
        "uri": "http://proxy.example.com:3128",
        "username": "proxyuser",
        "passwordSecretId": "myproxy.secret.id",
        "secretsProvider": "SystemAndEnvSecretStore"
     }
  }
}

"soTimeout": duration string, optional: Socket timeout, after which stalled connections are destroyed, expressed as a duration

Default: 10 seconds

"systemProxy": boolean, optional

Submit outgoing requests to a system-defined proxy, set by the following system properties or their HTTPS equivalents:

http.proxyHost, the host name of the proxy server.
http.proxyPort, the port number of the proxy server. The default is 80.
http.nonProxyHosts, a list of hosts that should be reached directly, bypassing the proxy.

This property can’t be used with a proxy that requires a username and password. Use the property proxy instead.

If both proxy and systemProxy are defined, proxy takes precedence.

For more information, see Java Networking and Proxies.

Default: False.

"temporaryStorage": string, optional

Specifies the heap object to use for temporary buffer storage.

Default: The temporary storage object named TemporaryStorage, declared in the top-level heap.

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": enumeration, optional

Specifies how the HTTP client behaves for asynchronous responses. Set the value to streaming or non_streaming:

streaming: ( Not supported for IG in standalone mode )

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.

Default: non_streaming

"retries": object, optional

Enable and configure retry for requests.

When a runtime error occurs during the execution of a request to a remote server, IG schedules a new execution of the request after the specified delay, until the allowed number of retries is reached or the execution succeeds.

A WARN level entry is logged if all retry attempts fail. A DEBUG level entry is logged if retries succeed, capturing the number of retries.

"enabled": boolean, optional: Enable retries.

Default: true
"executor": ScheduledExecutorService reference, optional: The ScheduledExecutorService to use for scheduling delayed execution of the request.

Default: ScheduledExecutorService

See also ScheduledExecutorService.
"count": 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.

Default: 5
"delay": 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 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
      }
    }
  }
}

"websocket": object, optional

Enable upgrade from HTTP or HTTPS protocol to WebSocket protocol.

For IG in standalone mode, list the subprotocols that are proxied by IG in the vertx property of AdminHttpApplication (admin.json).

For more information and an example of proxying WebSocket traffic, see Proxy WebSocket Traffic

When IG is running in Jetty, it cannot proxy WebSocket traffic.

{
  "websocket": {
    "enabled": boolean,
    "connectionTimeout": duration string,
    "soTimeout": duration string,
    "numberOfSelectors": number,
    "tls": ClientTlsOptions reference,
    "vertx": object
  }
}

For more information, see The WebSocket Protocol, RFC6455.

"enabled": boolean, optional

Enable upgrade from HTTP protocol and HTTPS protocol to WebSocket protocol.

Default: false

"connectionTimeout": duration string, optional

The maximum time allowed to establish a WebSocket connection.

Default: The value of handler’s main connectionTimeout.

"soTimeout": duration string, optional

The time after which stalled connections are destroyed.

If there can be long delays between messages, consider increasing this value. Alternatively, keep the connection active by using WebSocket ping messages in your application.

Default: The value of handler’s main soTimeout.

"numberOfSelectors": number, optional

The maximum number of worker threads.

In deployments with a high number of simultaneous connections, consider increasing the value of this property.

Default: 2

tls: ClientTlsOptions reference, optional

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

Default: Use ClientTlsOptions defined for the handler

vertx: object, optional

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

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
proxyOptions
keyStoreOptions
keyCertOptions
pemKeyCertOptions
pfxKeyCertOptions
trustOptions
trustStoreOptions
pemTrustOptions
pfxTrustOptions
useAlpn
alpnVersions

The following default vertx configuration provided by this handler overrides the Vert.x defaults:

tryUsePerFrameWebSocketCompression = true
tryUsePerMessageWebSocketCompression = true

The following example configures the maximum frame size and message size for Websocket connections:

"vertx": {
  "maxWebSocketFrameSize": 200000000,
  "maxWebSocketMessageSize": 200000000,
  "tryUsePerMessageWebSocketCompression": true
}

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

IG 7.1.2

ClientHandler

Usage

Properties

Example

More Information