1. OpenRepose
  2. Home
Search

HTTP Client Service

The HTTP Client Service provides a centralized way of managing and reusing HTTP clients for outbound communication.

This service introduces the concept of named connection pools. A named connection pool is described by a number of configuration options that dictate how a connection from that pool should behave. Connections from a pool are reused to cut down on the overhead of connection negotiation when resources are frequently accessed. The id/name of the pool corresponds to the connection pool id found in other services' and filters' configurations, indicating that outbound connections from that component should use the matching pool.

While named connection pools are the abstraction presented for configuration, HTTP clients are the abstraction presented for use in code. In reality, an HTTP client manages a connection pool. A developer leveraging this service will interact with the HTTP client abstraction. An operator configuring this service will interact with the named connection pool abstraction.

Configuration

  • Default Configuration: http-connection-pool.cfg.xml

  • Released: v2.8.3

  • Schema

Full Configuration

http-connection-pool.cfg.xml
<http-connection-pools xmlns="http://docs.openrepose.org/repose/http-connection-pool/v1.0">
    <pool id="default" (1)
          default="true" (2)
          cache.ttl="500" (3)
          http.conn-manager.max-total="400" (4)
          http.conn-manager.max-per-route="200" (5)
          http.socket.timeout="30000" (6)
          http.socket.buffer-size="8192" (7)
          http.connection.timeout="30000" (8)
          http.connection.max-line-length="8192" (9)
          http.connection.max-header-count="100" (10)
          http.tcp.nodelay="true" (11)
          http.route.default-proxy="http://example.com:80" (12)
          keepalive.timeout="0" (13)
          keystore-filename="client.jks" (14)
          keystore-password="password" (15)
          key-password="password" (16)
          truststore-filename="servers.jks" (17)
          truststore-password="password"> (18)
        <headers> (19)
            <header name="foo" value="bar"/> (20)
        </headers>
    </pool>
    <pool id="banana"/> (21)
</http-connection-pools>
1 The id/name of this pool, it must be unique. Used to identify this pool for usage by other services/filters. The only required attribute for a pool.
2 Whether or not this pool is the default pool for the connection service. You must have exactly one pool marked as the default. This pool is the one that will be used to make connections to the origin service.
3 Amount of time, in milliseconds, to cache the HTTP interaction (i.e., the sending of the request and receiving of the response). While more than one request may be made to the HTTP client at the same time with the same cache key, only one request will be made by the HTTP client at a time per cache key. In effect, this means the first request made to the HTTP client is cached until the HTTP client receives a response, at which point the response is cached (up to the defined TTL). For example, if request A is made to the HTTP client 1 millisecond before request B and both requests have the same cache key, request A will be sent over the wire by the HTTP client, and both requester A and requester B will await the response for request A. Both requester A and requester B will receive the same response once the response for request A is available. If request C is made 250 milliseconds after request B (with the same cache key, within the defined TTL), requester C will immediately receive the response for request A. This is the same response that requester A and requester B received. If request D is made 501 milliseconds after request B (with the same cache key, not within the defined TTL), request D will be sent over the wire by the HTTP client, and requester D will receive a response different from the response received by requesters A, B, and C.
Default: 500
4 Maximum number of connections opened across all endpoints in this connection pool. If this is set too high, you may run out of memory.
Default: 400
5 Maximum number of connections opened per endpoint in this connection pool.
Default: 200
6 Defines the socket timeout in milliseconds, which is the timeout for waiting for data (or, put differently, a maximum period of inactivity between two consecutive data packets). A timeout value of zero is interpreted as an infinite timeout.
Default: 30000
7 Determines the size of the internal socket buffer used to buffer data while receiving / transmitting HTTP messages.
Default: 8192
8 Determines the timeout in milliseconds until a connection is established. A timeout value of zero is interpreted as an infinite timeout. Please note this parameter can only be applied to connections that are bound to a particular local address.
Default: 30000
9 Determines the maximum line length limit. If set to a positive value, any HTTP line exceeding this limit will cause an IOException. A negative or zero value will effectively disable the check.
Default: 8192
10 Determines the maximum HTTP header count allowed. If set to a positive value, the number of HTTP headers received from the data stream exceeding this limit will cause an IOException. A negative or zero value will effectively disable the check.
Default: 100
11 Determines whether Nagle’s algorithm is to be used. The Nagle’s algorithm tries to conserve bandwidth by minimizing the number of segments that are sent. When applications wish to decrease network latency and increase performance, they can disable Nagle’s algorithm (that is enable http.tcp.nodelay). Data will be sent earlier, at the cost of an increase in bandwidth consumption.
Default: true
12 Optionally defines a proxy host to be used.
If present, requests made using this connection pool will be proxied through the provided proxy host.
If absent, requests made using this connection pool will not be proxied.
The value of this attribute should be in the form {scheme}://{host}:{port}. Note that {scheme} and {port} are optional while {host} is required. If no scheme is provided, http is assumed. If no port is provided, 80 (the default port for http) is assumed. The following are examples of acceptable values for this attribute:
13 If a Keep-Alive header is not present in the response, the value of keepalive.timeout is evaluated. If this value is 0, the connection will be kept alive indefinitely. If the value is greater than 0, the connection will be kept alive for the number of milliseconds specified. Set to 1 to connect:close.
Default: 0
14 The keystore filename either fully qualified or relative to the Repose configuration directory. Used for SSL/TLS Client Authentication.
NOTE: The keystore-filename, keystore-password, and key-password are all mutually required. If one exists, then they all must exist and client authentication is assumed to be required.
15 The password to access the keystore.
NOTE: The keystore-filename, keystore-password, and key-password are all mutually required. If one exists, then they all must exist and client authentication is assumed to be required.
16 The password for the particular key within the keystore.
NOTE: The keystore-filename, keystore-password, and key-password are all mutually required. If one exists, then they all must exist and client authentication is assumed to be required.
17 The truststore filename either fully qualified or relative to the Repose configuration directory. Used when it is necessary to have the certificate of the requested resource’s server.
NOTE: The truststore-filename and truststore-password are mutually required. If one exists, then the other must exist.
18 The password to access the truststore.
NOTE: The truststore-filename and truststore-password are mutually required. If one exists, then the other must exist.
19 Indicates that the configured list of headers should be added to every outbound request on this connection pool. Use is optional.
20 A header to be added to every outbound request from this connection pool. At least on is required when using the optional headers element.
21 A second pool is defined here that uses all the defaults.

Common Use Cases/Problems

Need higher concurrency

If the connection pool is filling up, but more resources are available on the machine Repose is running on, the pool can be expanded to allow more concurrent connections. This is most useful if wait times are high or requests are timing out. The size of the pools can be increased by raising http.conn-manager.max-total and http.conn-manager.max-per-route.

partial http-connection-pool.cfg
<pool id="default"
      ... (1)
      http.conn-manager.max-total="800" (2)
      http.conn-manager.max-per-route="300"/> (3)
</pool>
1 The existing pool attributes.
2 The new overall pool size. This is the maximum number of connections this pool will have open at once.
3 The new max number of connections to a single endpoint. If a pool is only ever used for a single endpoint (e.g., foo.com), then this number and http.conn-manager.max-total should be the same. If they aren’t then the max pool size will never be reached.

Requested endpoint requires a static header

Some services require a static header be present just for the purposes of identification; this can easily be done by adding the headers element to the pool configuration.

http-connection-pool.cfg.xml
<http-connection-pools xmlns="http://docs.openrepose.org/repose/http-connection-pool/v1.0">
    <pool id="default">
        <headers> (1)
            <header name="foo" value="bar"/> (2)
        </headers>
    </pool>
</http-connection-pools>
1 The element to add to the pool configuration to trigger this behavior.
2 The header name and value to add to the outbound request. Multiple header elements can be specified if more than one is desired.

Proxy must be used

In certain environments, it may be necessary to utilize a proxy for outbound requests. For example, Repose running on a private network may not be allowed to make direct connections to resources outside of the network. Instead, controlled connections can be made with a proxy which will forward requests to their intended destinations.

To configure the usage of a proxy, simply update the configuration for this service as done below.

partial http-connection-pool.cfg.xml
<http-connection-pools xmlns="http://docs.openrepose.org/repose/http-connection-pool/v1.0">
    <pool id="default"
          default="true"
          http.route.default-proxy="http://example.com:80"/> (1)
</http-connection-pools>
1 The proxy to be used. For details on acceptable values for this attribute, see Full Configuration.

SSL/TLS Client Authentication

See SSL/TLS Client Authentication

Further Information

For more information about the http.* attributes or the underlying connection pool see Apache Connection Management.