HTTP Client

Description

The module implements sending of HTTP requests to a server.
It is based on libcurl.

Handled message

Message name http.request.
Parameters:

• url: Required HTTP URL
• method: HTTP method to send. Defaults to GET if missing
• body: Request body to set (plain character string). Ignored if method is GET or HEAD
• accept: Optional Accept header contents
• type: Optional Content-Type header contents
• wait: Boolean (default: false). The sender is synchronously waiting for completion
• notify: Target id for notification. Ignored for synchronous requests
• local_failure_response_async: Boolean (default: false). Always emit a notification on local failure (don't return error in handled message).
  This parameter is ignored for synchronous requests or empty notify.
  This parameter may be used by modules using full asynchronous sending without needing to check if the request started.
  Further message processing by other module(s) will stop if this parameter is set to true.

The following parameters may be used to override the configured defaults: timeout, redirect, agent, max_hdr_length, max_body_length, server_keep_alive, debug.
See Configuration section for all module parameters allowed to be overridden in handled message.

The module will return true if:

• Message was accepted (validated)
  • Synchronous requests: the sender should check the presence of code parameter on return to match success
  • Asynchronous requests: the request was queued
• Request was not accepted but a notification was asynchronously sent (see local_failure_response_async parameter)

The module will return false in all other scenarios. reason and error parameters may be present in the message.

Returning result

Success

• code: Answer code
• code_text: Answer text (e.g. OK)
• xtype: The contents of received Content-Type header
• xcontent_length: The contents of received Content-Length header
• xbody_encoding: hex if received body contains NULL char(s). The returned body is a string containing HEX chars with no spaces

The received body is set in message's return value.

Failure

• reason: Failure reason. Here are some reasons that worth to be mentioned:
  • timeout: Request timed out
  • congestion: An asynchronous request was not taken from queue fast enough by the processing thread
  • protocol-error: The module was not able to parse received response line to detect the code or received a header containing NULL char(s)
  • rejected: The module can't accept the request because it already holds the configured maximum allowed active requests
• error: String describing the failure reason

Notification message

Message: http.notify
Parameters:

• targetid: The value set in the request's notify parameter

See Returning result section for all other parameters.

Status report

Status parameters:

• total: Total number of requests
• maxrequests: Maximum number of active (accepted) requests
• maxqueue: Maximum queue length (asynchronous requests waiting to start)
• total_accepted: Total number of accepted requests
• total_sync: Total number of accepted synchronous requests
• total_async_notify: Total number of accepted asynchronous requests requiring notification
• total_async_no_notify: Total number of accepted asynchronous requests not requiring notification
• queued: Current number of asynchronous requests waiting to be started
• process_async: Current number of running asynchronous requests
• process_sync: Current number of running synchronous requests
• timeout: The number of timed out requests
• congestion: The number of congested requests
• rejected: The number of rejected requests

Configuration

httpclient.conf

[general]
; General settings for the HTTP Client module

; redirect: integer: Enable HTTP 3xx redirects (max number of allowed redirects)
; This parameter is applied on reload and can be overridden in handled message
; Allowed interval: 0..3
; 0: disable redirect
;redirect=0

; timeout: integer: Maximum time, in milliseconds, that the request or a response is allowed to take
; This parameter is applied on reload and can be overridden in handled message
; Allowed interval: 100..600000
;timeout=10000

; max_hdr_length: integer: Maximum length for received headers
; This parameter is applied on reload and can be overridden in handled message
; Minimum allowed value s 200. Defaults to 16384
;max_hdr_length=16384

; max_body_length: integer: Maximum length for received body
; This parameter is applied on reload and can be overridden in handled message
; Minimum allowed value s 200. Defaults to 65535
;max_body_length=65535

; max_requests: integer: Maximum number of concurrent requests (sync or async) handled by the module
; This parameter is applied on reload
; New requests will be rejected by the module when this limit is reached
; Minimum allowed value is 100. Defaults to 20000
;max_requests=20000

; server_keep_alive: boolean: Tell the server we want it to keep the connection alive
; If enabled a 'Connection: Keep-Alive' header will be added to request
; This parameter is applied on reload and can be overridden in handled message
;server_keep_alive=yes

; agent: string: User agent to set in request
; This parameter is applied on reload and can be overridden in handled message
;agent=YATE/${version}

; async_priority: keyword: Priority of the thread processing the asynchronous requests
;async_priority=normal

; priority: integer: Priority level of http.request message handler
;priority=90

; debug: boolean/integer: Debug mode for CURL library (displaying SSL data, headers, sent and received data)
; This parameter is applied on reload and can be overridden in handled message by a debug parameters
; This will translate to a debug level: 0: use output, greater than 0 use debug
; Boolean true is translated to debug level 0 
;debug=no

Testing

url: "http://www.null.ro",