> For the complete documentation index, see [llms.txt](https://docs.fortifiedid.se/httpclient/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.fortifiedid.se/httpclient/httpclient.md).

# HttpClient

## Introduction

Platform module for application outbound HTTP requests.

This module is used by other modules to perform outbound HTTP request. 

Multiple instances of the module can be configured to support outbound request with different properties, like timeouts, proxies or SSL/TLS settings. 

Callers targets the requested instance by its name which must be configuration unique.

## Configuration

{% hint style="info" %}
**Module name:** `HttpClient`
{% endhint %}

{% tabs %}
{% tab title="Properties" %}

<table><thead><tr><th width="230.1171875">Name</th><th width="245.609375">Description</th><th>Default</th><th data-type="checkbox">Mandatory</th></tr></thead><tbody><tr><td><code>name</code></td><td>Configuration unique instance name.</td><td><code>"default"</code></td><td>false</td></tr><tr><td><code>follow_redirects</code></td><td>Turn on/off HTTP redirect support. By default redirects are NOT followed, instead the redirect response is returned to caller.</td><td><code>false</code></td><td>false</td></tr><tr><td><code>enable_user_agent</code></td><td>Enables the <code>User-Agent</code> request header.</td><td><code>false</code></td><td>false</td></tr><tr><td><code>user_agent</code></td><td>Custom <code>User-Agent</code> request header value.</td><td><code>"Fortified-HttpClient"</code></td><td>false</td></tr><tr><td><code>enable</code>_<code>keep_alive</code></td><td>Enable HTTP keep-alive.</td><td><code>false</code></td><td>false</td></tr><tr><td><code>enable_ssl</code></td><td>Enable support for SSL. If not enabled HTTPS connections will fail.</td><td><code>true</code></td><td>false</td></tr><tr><td><code>enable_alpn</code></td><td>Enable support for ALPN (Application Layer Protocol Negotiation), required for using HTTP/2 over SSL/TLS.</td><td><code>false</code></td><td>false</td></tr><tr><td><code>request_timeout_ms</code></td><td>Request timeout in ms. If a request takes longer than this amount it is aborted. <code>0</code> means no timeout.</td><td><code>2000</code></td><td>false</td></tr><tr><td><code>connect_timeout_ms</code></td><td>Connection timeout in ms. If a connection takes longer than this amount to connect it is aborted. <code>0</code> means no timeout. Note that if this value is larger than <code>request_timeout_ms</code>, request timeout will occur first.</td><td><code>1000</code></td><td>false</td></tr><tr><td><code>idle_timeout_ms</code></td><td>Connection idle timeout in ms. A connection that has been idle for more than this amount of ms is closed. <code>0</code> means no timeout.</td><td><code>1000</code></td><td>false</td></tr><tr><td><code>ssl_truststore</code></td><td>Configuration truststore object for SSL/TLS.</td><td></td><td>false</td></tr><tr><td><code>ssl_truststore_path</code></td><td>Path to truststore in <code>PKCS12</code> or <code>JKS</code> format.</td><td></td><td>false</td></tr><tr><td><code>ssl_truststore_password</code></td><td>Truststore password.</td><td></td><td>false</td></tr><tr><td><code>ssl_keystore</code></td><td>Configuration keystore object for SSL/TLS.</td><td></td><td>false</td></tr><tr><td><code>ssl_key_alias</code></td><td>Alias of key to use. If NOT specified, the first alias of the key is used.</td><td></td><td>false</td></tr><tr><td><code>ssl_key_password</code></td><td>Key password. If NOT specified, <code>ssl_keystore_password</code> will be used.</td><td></td><td>false</td></tr><tr><td><code>ssl_keystore_path</code></td><td>Path to SSL/TLS keystore in <code>PKCS12</code> or <code>JKS</code> format.</td><td></td><td>false</td></tr><tr><td><code>ssl_keystore_password</code></td><td>Keystore password.</td><td></td><td>false</td></tr><tr><td><code>ssl_keystore_alias</code></td><td>Alias of key to use. <em>Note: this property must be used for alias in combination with <code>ssl_keystore_path</code></em>.</td><td></td><td>false</td></tr><tr><td><code>ssl_trust_all</code></td><td>Flag to enable trust for all server certs - <em>use only for test</em>.</td><td><code>false</code></td><td>false</td></tr><tr><td><code>ssl_verify_host</code></td><td>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). <em>Use only for test.</em></td><td><code>true</code></td><td>false</td></tr><tr><td><code>non_proxy_hosts</code></td><td>List of hosts that should bypass proxy settings.</td><td></td><td>false</td></tr><tr><td><code>use_proxy</code></td><td>Flag turning on/off use of proxy</td><td><code>false</code></td><td>false</td></tr><tr><td><code>proxy</code></td><td>Proxy configuration object.</td><td></td><td>false</td></tr><tr><td><code>proxy.host</code></td><td>Hostname or IP of proxy to use.</td><td><code>"localhost"</code></td><td>false</td></tr><tr><td><code>proxy.port</code></td><td>Proxy port.</td><td><code>3128</code></td><td>false</td></tr><tr><td><code>proxy.username</code></td><td>Proxy username (optional, use only if required by proxy).</td><td></td><td>false</td></tr><tr><td><code>proxy.password</code></td><td>Proxy password (optional, use only if required by proxy).</td><td></td><td>false</td></tr><tr><td><code>circuit_breaker</code></td><td><a href="#circuit-breaker">Circuit breaker</a> configuration.</td><td></td><td>false</td></tr></tbody></table>
{% endtab %}

{% tab title="Example" %}

```json
{
  "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
      }
    }
  }
}
```

{% endtab %}
{% endtabs %}

## Metrics

This module produces metrics for each request.&#x20;

{% tabs %}
{% tab title="Naming" %}

<table data-header-hidden><thead><tr><th width="95"></th><th></th></tr></thead><tbody><tr><td><code>name</code></td><td><code>fortified.internal.httpclient_&#x3C;metric-name></code></td></tr><tr><td><code>tags</code></td><td><code>name=&#x3C;instance-name></code></td></tr></tbody></table>
{% endtab %}

{% tab title="Metrics" %}

<table><thead><tr><th width="143">Name</th><th width="97">Type</th><th>Description</th></tr></thead><tbody><tr><td><code>pending</code></td><td>gauge</td><td>Number of pending requests</td></tr><tr><td><code>success</code></td><td>counter</td><td>Number of successful request</td></tr><tr><td><code>failure</code></td><td>counter</td><td>Number of failed request</td></tr><tr><td><code>request</code></td><td>timer</td><td>Request time in ms</td></tr></tbody></table>
{% endtab %}

{% tab title="JMX example" %}

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

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

```

{% endtab %}
{% endtabs %}

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.

{% tabs %}
{% tab title="Properties" %}

<table><thead><tr><th>Name</th><th>Description</th><th>Default</th><th data-type="checkbox">Mandatory</th></tr></thead><tbody><tr><td><code>enabled</code></td><td>Flag turning on/off circuit breaker.</td><td><code>true</code></td><td>false</td></tr><tr><td><code>default_config.maxFailures</code></td><td>Failure threshold. When the number of failures reaches this value, the circuit is opened and new request will instantly fail.</td><td><code>5</code></td><td>false</td></tr><tr><td><code>default_config.timeout</code></td><td>Timeout in ms. If a request takes longer then this value it is considered a failure. </td><td><code>2000</code></td><td>false</td></tr><tr><td><code>default_config.resetTimeout</code></td><td>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.</td><td><code>10000</code></td><td>false</td></tr></tbody></table>

{% endtab %}

{% tab title="Example" %}

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

{% endtab %}
{% endtabs %}

## 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.&#x20;

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>
```