HttpClient

Introduction

The HttpClient module provides reusable destinations for outbound HTTP requests from other platform modules. Each named instance can use its own timeouts, proxy, TLS, protocol, and circuit-breaker settings.

Configure multiple named instances when callers need different destinations or connection policies. Callers select an instance by its unique name.

Configuration

Note

Module name: HttpClient

Properties

Name	Description	Default	Mandatory
name	Configuration unique instance name.	"default"
follow_redirects	Turn on/off HTTP redirect support. By default redirects are NOT followed, instead the redirect response is returned to caller.	false
enable_user_agent	Enables the User-Agent request header.	true
user_agent	Custom User-Agent request header value.	"Fortified-HttpClient"
enable_keep_alive	Enable HTTP keep-alive.	false
enable_ssl	Enable support for SSL. If not enabled HTTPS connections will fail.	true
enable_alpn	Enable support for ALPN (Application Layer Protocol Negotiation), required for using HTTP/2 over SSL/TLS.	false
protocol_version	Vert.x HTTP protocol version: HTTP_1_0, HTTP_1_1, or HTTP_2.	Vert.x client default
request_timeout_ms	Request timeout in ms. If a request takes longer than this amount it is aborted. 0 means no timeout.	2000
connect_timeout_ms	Connection timeout in ms. If a connection takes longer than this amount to connect it is aborted. 0 means no timeout. Note that if this value is larger than request_timeout_ms, request timeout will occur first.	1000
idle_timeout_ms	Connection idle timeout in ms. A connection that has been idle for more than this amount of ms is closed. 0 means no timeout.	1000
ssl_truststore	Configuration truststore object for SSL/TLS.
ssl_truststore_path	Path to truststore in PKCS12 or JKS format.
ssl_truststore_password	Truststore password.
ssl_keystore	Configuration keystore object for SSL/TLS.
ssl_key_alias	Alias of key to use. If NOT specified, the first alias of the key is used.
ssl_key_password	Key password. If NOT specified, ssl_keystore_password will be used.
ssl_keystore_path	Path to SSL/TLS keystore in PKCS12 or JKS format.
ssl_keystore_password	Keystore password.
ssl_keystore_alias	Compatibility name for the key alias when ssl_keystore_path is used. Prefer ssl_key_alias.
ssl_trust_all	Flag to enable trust for all server certs - use only for test.	false
ssl_verify_host	Flag to disable certificate hostname verification. Setting this flag to false means that client will accept server certificates with non-matching host/dns-name(s). Use only for test.	true
non_proxy_hosts	List of hosts that should bypass proxy settings.
use_proxy	Flag turning on/off use of proxy	false
proxy	Proxy configuration object.
proxy.host	Hostname or IP of proxy to use.	"localhost"
proxy.port	Proxy port.	3128
proxy.username	Proxy username (optional, use only if required by proxy).
proxy.password	Proxy password (optional, use only if required by proxy).
circuit_breaker	Circuit breaker configuration.

Example

{
  "name": "HttpClient",
  "enabled": true,
  "config": {
    "name": "http01",
    "enable_ssl": true,
    "ssl_truststore_path": "<file_path.jks>",
    "ssl_truststore_password": "password",
    "use_proxy": true,
    "non_proxy_hosts": ["10.1.10.10", "10.1.10.11"],
    "proxy": {
      "host": "10.1.1.1",
      "port": 8080
    },
    "circuit_breaker": {
      "enabled": true,
      "default_config": {
        "maxFailures": 10,
        "timeout": 1900,
        "resetTimeout": 8000
      }
    }
  }
}

Metrics

This module produces metrics for each request.

Naming

name	fortified.internal.httpclient_<metric-name>
tags	name=<instance-name>

Metrics

Name	Type	Description
pending	gauge	Number of pending requests
success	counter	Number of successful request
failure	counter	Number of failed request
request	timer	Request time in ms

JMX example

// JMX name for HttpClient request failure counter on
// module instance "default"

metrics:name=fortifiedInternalHttpclient_failure.name.default,type=meters

See separate metrics documentation on how metrics work and how to consume metric data.

Circuit breaker

This module has support for circuit breaker.

The circuit breaker monitor requests and keeps track of the time and the number of failures and opens the circuit when a configurable threshold is reached, resulting in instant failure (i.e no wait for request timeout etc) for a better end user experience and for off-loading the application by reducing resources waiting for a likely timeout.

The circuit breaker does not prevent failures by performing retries etc.

Properties

Name	Description	Default	Mandatory
enabled	Flag turning on/off circuit breaker.	true
default_config.maxFailures	Failure threshold. When the number of failures reaches this value, the circuit is opened and new request will instantly fail.	5
default_config.timeout	Timeout in ms. If a request takes longer then this value it is considered a failure.	2000
default_config.resetTimeout	Time in ms before the circuit is reset/closed. When this time is reached the circuit will be closed to test if problem still remains. If test is successful, circuit is closed, otherwise it will be opened again.	10000

Example

{
  "circuit_breaker": {
    "enabled": true,
    "default_config": {
      "maxFailures": 10,
      "timeout": 1900,
      "resetTimeout": 8000
    }
  }
}

Troubleshooting

Keystore errors

Path to keystore is invalid/not found:

Invalid keystore path: <path>

Path to truststore is invalid/not found:

Invalid truststore path: <path>

Incorrect keystore/truststore password:

Failed to load keystore: Keystore was tampered with, or password was incorrect

Unknown keystore alias:

Failed to get entry '<alias>' from keystore: Entry not found: <alias>

Incorrect key password:

Failed to get entry '<alias>' from keystore:  Cannot recover key

Timeout getting response ("response timeout")

Request did not return within the specified request_timeout_ms period:

The timeout period of <timeout-value>ms has been exceeded while executing <method> /<path> for server <host>:<port>

Timeout establishing a connection ("connect timeout")

Connect timeout occurs when establishing a connection takes too long. Two errors are possible depending on how timeouts are configured.

If request_timeout_ms is shorter than connect_timeout_ms:

The timeout of <timeout-value> ms has been exceeded when getting a connection to <host>:<port>

If connect_timeout_ms is shorter than request_timeout_ms:

connection timed out: /<host>:<port>