HTTP Connection Pool service

Purpose

The HTTP Connection Pool Service allows Repose to manage and reuse HTTP connections.  The service is using the Apache Connection Management.


Configuration

Repose will use a default set of connection pool configurations, but these can be customized via the http-connection-pool.cfg.xml configuration file.

Default Configuration

The following example shows the default configurations for the Connection Pool service.

Configurable parameters

XML schema definition

Example configuration

The following table provides information about the elements and attributes in the http-connection-pool.cfg.xml file.  Please refer to Apache Connection Management for additional descriptions of the http.* parameters.

ElementsAttributesRequired/ OptionalDescription
<http-connection-pools>-RequiredRoot element for this configuration.
<pool>-RequiredSpecifies the configuration for a new pool.
id
RequiredThe id is the unique name for this set of pool configurations. Use the default unless you have a separate endpoint in your Client AuthN or Client AuthZ filter. Set the endpoint to match your connectionPoolId attribute. (You may use as many pool id's as needed.) Default is default.
default
OptionalThis attribute indicates whether this is the default pool to use. Exactly one pool must be marked as default. Requests made to the origin service will be made using the default pool. Default is false.
chunked-encoding
Optional

Determines whether or not this client should send chunked data when forwarding requests to the origin service.

If set to true or 1, chunked data will always be sent. Using the value 1 is considered deprecated and will be removed in the next major release. If set to false or 0, chunked data will never be sent. Using the value 0 is considered deprecated and will be removed in the next major release. If set to auto, chunked data will only be sent if the original request to Repose was chunked. Note that the auto setting only has meaning for the default connection pool, as that is the only pool that will be used to make requests to the origin service.

WARNING: Setting this attribute to false may cause repose to attempt to retrieve the actual content length through reading the ServletInputStream. This will cause some performance degradation as request body is no longer always streamed through. It is recommended that users leave this value as true unless their service does not support chunked encoding.

http.conn-manager.max-total
OptionalMaximum number of connections that Repose opens across all endpoints in this connection pool. If this is set too high, you may run out of memory. Default is 400.
http.conn-manager.max-per-route
OptionalMaximum number of connections that Repose opens per endpoint in this connection pool. Default is 200.
http.socket.timeout
Optional

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 is 30000.

http.socket.buffer-size
OptionalDetermines the size of the internal socket buffer used to buffer data while receiving / transmitting HTTP messages. Default is 8192.
http.connection.timeout
OptionalDetermines 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 is 30000.
http.connection.max-line-length
OptionalDetermines 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 is 8192.
http.connection.max-header-count
OptionalDetermines 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 is 100.
http.connection.max-status-line-garbage
OptionalMaximum number of lines allotted for garbage. Default is 100.
http.tcp.nodelay
OptionalDetermines 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 is true.
keepalive.timeout
OptionalIf 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.

keystore-filename
Optional

The keystore filename either fully qualified or relative to the Repose configuration directory (/etc/repose is the default).

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.

Introduced in Repose 8.0.2.0

keystore-password
Optional

The password to access the keystore.

Introduced in Repose 8.0.2.0

key-password
Optional

The password for the particular key within the keystore.

Introduced in Repose 8.0.2.0

truststore-filename
Optional

The truststore filename either fully qualified or relative to the Repose configuration directory (/etc/repose is the default).

Introduced in Repose 8.0.2.0

truststore-password
Optional

The password to access the truststore. This attribute is only used if the truststore-filename attribute is present.

Introduced in Repose 8.0.2.0

<headers>-Optional

List of headers to add to each request made using this connection pool.

Introduced in Repose 7.3.3.0

<header>-Required if headers provided

Header with a name and a value.

Introduced in Repose 7.3.3.0

name
Required if header provided

The name of the header to add.

Introduced in Repose 7.3.3.0

value
Required if header provided

The value of the header to add.

Introduced in Repose 7.3.3.0

 

Use cases 

The HTTP Connection Pool Service is used internally by Repose for communicating to the origin service and other third party services (e.g. Identity). The service is used by default and does not need to be included in the system model.  However, there are certain circumstances that require you to add and configure the http-connection-pool.cfg.xml file in your Repose configuration.

If your framework does not support chunked encoding (e.g. WSGI)

If the framework that you are using does not support chunked encoding, you can turn this off in configuration.

  1. Modify the http-connection-pool.cfg.xml file.
    1. e.g. /etc/repose/http-connection-pool.cfg.xml
    2. If you don't already have this configuration file, use the default contents in the section above.

  2. Configure the chunked-encoding attribute to false in the default connection pool.

  3. Remove all of the unnecessary (optional) attributes from the pool as desired.

If you want to achieve higher concurrency

If you want to achieve higher concurrency, you can configure this in a connection pool.

  1. Modify the http-connection-pool.cfg.xml file.
    1. e.g. /etc/repose/http-connection-pool.cfg.xml
    2. If you don't already have this configuration file, use the default contents in the section above.
  2. In the desired connection pool, set the following attributes to the desired values:
    1. http.conn-manager.max-total
    2. http.conn-manager.max-per-route

If you want to specify headers to be added to all requests using a certain pool

Starting in Repose 7.3.3.0, if you want to add specific headers to requests going to third party endpoints (e.g. Identity), you can configure this headers in a connection pool.

  1. Modify the http-connection-pool.cfg.xml file.
    1. e.g. /etc/repose/http-connection-pool.cfg.xml
    2. If you don't already have this configuration file, use the default contents in the section above.
  2. Create a new connection pool with the desired attributes.
    1. Make sure it's not set to be the default pool.
  3. Add the list of desired headers to the connection pool.
  4. Configure the desired filter to use the new connection pool.
    1. e.g. The Keystone V2 filter let's you set the connection-pool-id attribute on the identity-service element.




SSL/TLS Client Authentication


SSL/TLS Client Authentication is being used more and more for communications between different enclaves. This addition to the SSL/TLS handshake involves the Client presenting credentials to the Server in the same manner as the Server does to the Client. If the credentials presented by the Client are not trusted, then the Server will sever the connection just as the Client would have if the situation was reversed. Since a Client initiates contact with the Server, the Server's credentials are simply to validate it is who the Client was trying to contact. This is accomplished through Certificate Authorities (CA) and the Trust Hierarchies built into the Public Key Infrastructure (PKI). Even though you can optionally add a particular Server's credentials directly into a Client so that it will implicitly trust a particular Server essentially bypassing the distributed trust mechanism in favor of a more direct one, this is the only way to build a relationship for a Client to a Server.

To provide SSL/TLS Client Authentication credentials, add the keystore-filename, keystore-password, and key-password attributes to the pool element. With these present, all connections from that pool will present the specified credentials. If the truststore-filename attribute is specified, then only Servers that have a Public Key imported into the trust store will be allowed to provide/receive data. The keystore and truststore are Java Keystore's that can be created/updated using the command line tool named aptly enough, keytool. Below is an example of importing a Server certificate (client.crt) into a truststore (truststore.jks):




For more details, see:


Error scenarios

Error

A GET request is made from Repose and succeeds, but a POST or PUT request with content body fails due to a malformed request or empty request. 

Fix

This indicates that the service may not support chunked encoding. Change the chunked-encoding attribute to false to allow for buffered requests.


Error 

You are unable to get connections in the log.  

Fix

This indicates that you have run out of connections in your pool (i.e. all connections are in flight).  Check your configurations for http.conn-manager.max-total and http.conn-manager.max-per-routeAlso check http.connection.timeout to see if it can be increased and http.socket.timeout to see if it can be decreased.

 

Error

Repose throws a 503 error because a request takes longer than the default socket read timeout. 

Fix 

Raise the http.socket.timeout. (Be careful not to raise it too high because you may reach your max with http.conn-manager.max-total and http.conn-manager.max-per-route.)