Section 3.12. HTTP client configuration

3.12. HTTP client configuration

Radiator's HTTP client support is implemented by Radius::HTTPClient module. It provides common configuration to specify HTTP backend servers, HTTP request methods, content encoding, TLS parameters and failure behaviour. HTTP connection establishment and response processing are done asynchronously. This allows non-blocking communication even with slow backends. Radius::HTTPClient module is built on top of Radiator Stream module and provides configuration similar to other stream configuration clauses such as RadSec.

The following configuration clauses utilise Radius::HTTPClient:

<AuthBy REST>
EAP-SIM, EAP-AKA and EAP-AKA' authentication clauses in Radiator SIM Pack.

All HTTP::Client configuration clauses support stream TLS parameters.

3.12.1. URL

This string parameter specifies an URL for a HTTP backend service. HTTPS is supported. Multiple URL parameters are supported. At least one URL must be defined. Optional comma separated priority value may follow an URL. If priority is not defined, it defaults to 1. When URL is configured to use https scheme, TLS client parameters must be configured. For more information, see Section 3.11. TLS configuration

# Service is reachable from two local ports
URL http://127.0.0.1:8888/radius
URL http://127.0.0.1:8889/radius

# Use port 443 and non-default priority
URL https://api.example.com/radius, 2
URL https://api.example.net/radius, 3

Radiator's special formatting characters, see Section 3.3. Special formatters, in URL are processed only when FormatURL is set. The supported formatters are documented for each clause that uses HTTP client parameters. See

AuthBy
                     REST

for an example.

3.12.2. FormatURL

This is an optional flag parameter. When this parameter is set, Radiator special character formatting is first applied to the current URL. The available formatters depend on the clause, see

AuthBy
                        REST

for an example.

3.12.3. RequestMethod

This string parameter defines the HTTP method to use. One of GET, DELETE, POST, PUT or PATCH. Defaults to GET.

# The service we use requires POST
RequestMethod POST

3.12.4. RequestContentType

This string parameter defines the Content-Type HTTP header value for POST, PUT and PATCH request methods. One of:

application/json
application/x-www-form-urlencoded
text/plain
application/text
application/plain

If set to empty or to one of text or plain types, simple keyword=value encoding without escaping is used. Defaults to application/x-www-form-urlencoded

# The service we use requires POSTs in JSON format
RequestContentType application/json

3.12.5. RequestHeader

This string parameter defines an optional HTTP header fields to add to request. You can define one or more RequestHeader parameters. Format is header name, with an optional ':', followed by space and the header value. Defaults to not set.

# Add our custom HTTP header
RequestHeader User-Agent Radiator/4.xx AuthBy REST

3.12.6. HTTP_AuthenticationScheme

This optional string parameter defines the HTTP authentication scheme to use. Supported values is: Basic. Defaults to not set. When HTTP_AuthenticationHook is configured, HTTP_AuthenticationScheme is ignored.

# API access requires HTTP authentication
HTTP_AuthenticationScheme Basic
HTTP_Username mikem
HTTP_Password fred

3.12.7. HTTP_AuthenticationHook

This optional parameter defines a Perl hook for API authentication. Defaults to not set. When HTTP_AuthenticationHook is configured, HTTP_AuthenticationScheme is ignored. The hook is passed the following arguments:

Reference to the current Radius::HTTPClient derived clause
Reference to an instance of HTTP::Request class representing the API request being currently built

The first parameter provides access to the configuration parameters, such as username and password shown in this example.

# API access requires HTTP authentication
HTTP_AuthenticationHook file:"%D/http-auth-hook.pl"
HTTP_Username mikem
HTTP_Password fred

3.12.8. HTTP_Username

This optional string parameter defines username for HTTP authentication when HTTP_AuthenticationScheme is configured. This parameter may also be accessed by hook configured with HTTP_AuthenticationHook. See HTTP_AuthenticationScheme for an example.

3.12.9. HTTP_Password

This optional string parameter defines password for HTTP authentication when HTTP_AuthenticationScheme is configured. This parameter may also be accessed by hook configured with HTTP_AuthenticationHook. See HTTP_AuthenticationScheme for an example.

3.12.10. HTTP_Version

This optional string parameter defines the HTTP version to use. Supported values are: 1.0 and 1.1. Defaults to 1.1.

# API access requires HTTP/1.0
HTTP_Version 1.0

3.12.11. NoreplyTimeout

This optional integer parameter defines time in seconds to wait for response. Defaults to 2 seconds. This example shows all customised failure related parameters.

# Time related values are in seconds.
NoreplyTimeout 5
FailureBackoffTime 60
MaxFailedRequests 3
MaxFailedGraceTime 10

3.12.12. FailureBackoffTime

This optional parameter sets the backoff time in seconds for failed backends. During the backoff time the backend is not used. Backend is considered failed after MaxFailedRequests consecutive failures. Backend failure occurs when a backend does not respond or HTTP response status code indicates a failure. Defaults to not set. See NoreplyTimeout for an example.

3.12.13. MaxFailedRequests

This optional parameter sets the number of consecutive failures before FailureBackoffTime is triggered. Defaults to not set. See NoreplyTimeout for an example.

3.12.14. MaxFailedGraceTime

MaxFailedGraceTime specifes the time period (in seconds) over which MaxFailedRequests failures will cause the backend to be be assumed to be failed. Defaults to not set. The default value lets the HTTP client to choose a reasonable value which is typically very large. Very short values require a high number of failures to set target host as failed. This value should only be changed in special cases.

3.12.15. Connections

This integer parameter sets the initial number of connections per a backend URL. Defaults to 10.

# Backend allows only a small number of connections
Connections 1
MaxConnections 10

3.12.16. MaxConnections

This integer parameter sets the maximum number of connections per a backend URL. Defaults to 100. See Connections for an example.

3.12.17. ReconnectTimeout

This optional parameter specifies the number of seconds to wait before attempting to reconnect a failed, dropped or disconnected connection. It also specifies the timeout for the initial connect.

3.12.18. ConnectOnDemand

This optional flag parameter tells Radiator not to connect to the server as soon as possible, but to wait until a message must be sent to that server. After the connection has been established and message has been delivered, the connection remains as long as possible. If the connection is lost for any reason, it is only re-established when and if there is another message to be sent.

3.12.19. MapResponseHook

This optional parameter defines a Perl hook for pre-processing HTTP server responses. Defaults to not set. The hook is passed the following arguments:

Reference to a hash with server response and response related information

MapResponseHook has full access to a complete server response. This allows the hook to do any local modifications that are needed.

# Do some pre-processing before passing response to upper layers.
MapResponseHook file:"%D/http-map-response-hook.pl"

Here's an example of how to update a decoded JSON array response to a format described by

AuthBy
                        REST

.

# Replace an array reference with the array's first member
# Received JSON: [ { "a1": 1 }, { "b2": 2 }]
# AuthBy REST needs just the first object, the one with key "a1"
<AuthBy REST>
  # Parameters, location within AuthBy does not matter
  MapResponseHook sub { $_[0]->{server_response} = $_[0]->{server_response}->[0]; }
  # More parameters
</AuthBy>

3.12.20. LocalAddress and LocalPort

These parameters control the address and optionally the port number used for the client source port, although this is usually not necessary. LocalPort is a string, it can be a port number or name. It binds the local port if LocalAddress is defined. If LocalPort is not specified or if it is set to 0, a port number is allocated in the usual way.

When SCTP multihoming is supported, multiple comma separated addresses can be configured. All addresses defined with LocalAddress must be either IPv4 or IPv6 addresses.

LocalAddress 203.63.154.29
LocalPort 12345

3.12.21. MaxBufferSize

This optional advanced parameter specifies the maximum number of octets that are output and input buffered by Radiator's Stream modules. This advanced parameter usually does not need adjusting.

3.12.22. Debug

This optional flag parameter enables debug logging of both HTTP requests and responses. Debug logging is done with Trace level 5 EXTRA_DEBUG. The example below shows how to enable HTTP request and response logging with Trace level 5.

# Enable global extra debugging
Trace 5

# AuthBy REST is a HTTP::Client
<AuthBy REST>
    Debug
    # Other paramters
</AuthBy>