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 parameters 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 (see Configuration section): timeout, redirect, agent, max_hdr_length, max_body_length, server_keep_alive, debug

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

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