http_async_client: update README

modules/http_async_client/README

@@ -37,27 +37,27 @@ Federico Cabiddu
               3.1. workers (int)
               3.2. connection_timeout (str)
               3.3. hash_size (str)
-              3.4. tlsversion (int)
-              3.5. tlsverifyhost (int)
-              3.6. tlsverifypeer (int)
+              3.4. tls_version (int)
+              3.5. tls_verify_host (int)
+              3.6. tls_verify_peer (int)
               3.7. curl_verbose (int)
               3.8. memory_manager (string)
-              3.9. tlsclientcert (int)
-              3.10. tlsclientkey (int)
-              3.11. tlscapath (int)
+              3.9. tls_client_cert (int)
+              3.10. tls_client_key (int)
+              3.11. tls_ca_path (int)
 
         4. Functions
 
               4.1. http_async_query(url, [post_data], route_name)
               4.2. http_async_suspend(suspend)
-              4.3. http_verify_host(verify)
-              4.4. http_verify_peer(verify)
+              4.3. tls_verify_host(verify)
+              4.4. tls_verify_peer(verify)
               4.5. http_set_timeout(timeout)
               4.6. http_append_header(header)
               4.7. http_set_method(method)
-              4.8. http_set_ssl_cert(path)
-              4.9. http_set_ssl_key(path)
-              4.10. http_set_ca_path(path)
+              4.8. http_set_tls_client_cert(path)
+              4.9. http_set_tls_client_key(path)
+              4.10. http_set_tls_ca_path(path)
 
         5. Pseudo Variables
         6. Statistics
@@ -72,24 +72,25 @@ Federico Cabiddu
    1.1. Set workers parameter
    1.2. Set connection_timeout parameter
    1.3. Set hash_size parameter
-   1.4. Set tlsversion parameter
-   1.5. Set tlsverifyhost parameter
-   1.6. Set tlsverifypeer parameter
+   1.4. Set tls_version parameter
+   1.5. Set tls_verify_host parameter
+   1.6. Set tls_verify_peer parameter
    1.7. Set curl_verbose parameter
    1.8. Set memory_manager parameter
-   1.9. Set tlsclientcert parameter
-   1.10. Set tlsclientkey parameter
-   1.11. Set tlscapath parameter
+   1.9. Set tls_client_cert parameter
+   1.10. Set tls_client_key parameter
+   1.11. Set tls_ca_path parameter
    1.12. http_async_query() usage
    1.13. http_async_suspend() usage
-   1.14. http_verify_host() usage
-   1.15. http_verify_peer() usage
+   1.14. tls_verify_host() usage
+   1.15. tls_verify_peer() usage
    1.16. http_set_timeout() usage
    1.17. http_append_header() usage
    1.18. http_set_method() usage
-   1.19. http_set_ssl_cert() usage
-   1.20. http_set_ssl_key() usage
-   1.21. http_set_ca_path() usage
+   1.19. http_set_tls_client_cert() usage
+   1.20. http_set_tls_client_key() usage
+   1.21. http_set_tls_ca_path() usage
+   1.22. $http_req(key) variable usage
 
 Chapter 1. Admin Guide
 
@@ -106,27 +107,27 @@ Chapter 1. Admin Guide
         3.1. workers (int)
         3.2. connection_timeout (str)
         3.3. hash_size (str)
-        3.4. tlsversion (int)
-        3.5. tlsverifyhost (int)
-        3.6. tlsverifypeer (int)
+        3.4. tls_version (int)
+        3.5. tls_verify_host (int)
+        3.6. tls_verify_peer (int)
         3.7. curl_verbose (int)
         3.8. memory_manager (string)
-        3.9. tlsclientcert (int)
-        3.10. tlsclientkey (int)
-        3.11. tlscapath (int)
+        3.9. tls_client_cert (int)
+        3.10. tls_client_key (int)
+        3.11. tls_ca_path (int)
 
    4. Functions
 
         4.1. http_async_query(url, [post_data], route_name)
         4.2. http_async_suspend(suspend)
-        4.3. http_verify_host(verify)
-        4.4. http_verify_peer(verify)
+        4.3. tls_verify_host(verify)
+        4.4. tls_verify_peer(verify)
         4.5. http_set_timeout(timeout)
         4.6. http_append_header(header)
         4.7. http_set_method(method)
-        4.8. http_set_ssl_cert(path)
-        4.9. http_set_ssl_key(path)
-        4.10. http_set_ca_path(path)
+        4.8. http_set_tls_client_cert(path)
+        4.9. http_set_tls_client_key(path)
+        4.10. http_set_tls_ca_path(path)
 
    5. Pseudo Variables
    6. Statistics
@@ -162,14 +163,14 @@ Chapter 1. Admin Guide
    3.1. workers (int)
    3.2. connection_timeout (str)
    3.3. hash_size (str)
-   3.4. tlsversion (int)
-   3.5. tlsverifyhost (int)
-   3.6. tlsverifypeer (int)
+   3.4. tls_version (int)
+   3.5. tls_verify_host (int)
+   3.6. tls_verify_peer (int)
    3.7. curl_verbose (int)
    3.8. memory_manager (string)
-   3.9. tlsclientcert (int)
-   3.10. tlsclientkey (int)
-   3.11. tlscapath (int)
+   3.9. tls_client_cert (int)
+   3.10. tls_client_key (int)
+   3.11. tls_ca_path (int)
 
 3.1. workers (int)
 
@@ -180,7 +181,7 @@ Chapter 1. Admin Guide
 
    Example 1.1. Set workers parameter
 ...
-modparam("async_http", "workers", 2)
+modparam("http_async_client", "workers", 2)
 ...
 
 3.2. connection_timeout (str)
@@ -192,7 +193,7 @@ modparam("async_http", "workers", 2)
 
    Example 1.2. Set connection_timeout parameter
 ...
-modparam("async_http", "connection_timeout", 1000)
+modparam("http_async_client", "connection_timeout", 1000)
 ...
 
 3.3. hash_size (str)
@@ -206,43 +207,43 @@ modparam("async_http", "connection_timeout", 1000)
 
    Example 1.3. Set hash_size parameter
 ...
-modparam("async_http", "hash_size", 1024)
+modparam("http_async_client", "hash_size", 1024)
 ...
 
-3.4. tlsversion (int)
+3.4. tls_version (int)
 
    For HTTPS connections, what's the preferred SSL version.
    http://curl.haxx.se/libcurl/c/CURLOPT_SSLVERSION.html
 
    Default value is 0 (default SSL version).
 
-   Example 1.4. Set tlsversion parameter
+   Example 1.4. Set tls_version parameter
 ...
-modparam("async_http", "tlsversion", 6)
+modparam("http_async_client", "tls_version", 6)
 ...
 
-3.5. tlsverifyhost (int)
+3.5. tls_verify_host (int)
 
    For HTTPS connections, whether the client should verify the server
    host. http://curl.haxx.se/libcurl/c/CURLOPT_SSL_VERIFYHOST.html
 
    Default value is 2 (enabled).
 
-   Example 1.5. Set tlsverifyhost parameter
+   Example 1.5. Set tls_verify_host parameter
 ...
-modparam("async_http", "tlsverifyhost", 0)
+modparam("http_async_client", "tls_verify_host", 0)
 ...
 
-3.6. tlsverifypeer (int)
+3.6. tls_verify_peer (int)
 
    For HTTPS connections, whether the client should verify the server
    identity. http://curl.haxx.se/libcurl/c/CURLOPT_SSL_VERIFYPEER.html
 
    Default value is 1 (enabled).
 
-   Example 1.6. Set tlsverifypeer parameter
+   Example 1.6. Set tls_verify_peer parameter
 ...
-modparam("async_http", "tlsverifypeer", 0)
+modparam("http_async_client", "tls_verify_peer", 0)
 ...
 
 3.7. curl_verbose (int)
@@ -255,7 +256,7 @@ modparam("async_http", "tlsverifypeer", 0)
 
    Example 1.7. Set curl_verbose parameter
 ...
-modparam("async_http", "curl_verbose", 1)
+modparam("http_async_client", "curl_verbose", 1)
 ...
 
 3.8. memory_manager (string)
@@ -273,57 +274,59 @@ modparam("async_http", "curl_verbose", 1)
 
    Example 1.8. Set memory_manager parameter
 ...
-modparam("async_http", "memory_manager", "sys")
+modparam("http_async_client", "memory_manager", "sys")
 ...
 
-3.9. tlsclientcert (int)
+3.9. tls_client_cert (int)
 
    For HTTPS connections, the file path of the TLS client certificate to
    be used http://curl.haxx.se/libcurl/c/CURLOPT_SSLCERT.html
 
    Default value is NULL (not used). Default type is PEM.
 
-   Example 1.9. Set tlsclientcert parameter
+   Example 1.9. Set tls_client_cert parameter
 ...
-modparam("async_http", "tlsclientcert", "/etc/kamailio/ssl/clientcert.pem")
+modparam("http_async_client", "tls_client_cert", "/etc/kamailio/ssl/clientcert.p
+em")
 ...
 
-3.10. tlsclientkey (int)
+3.10. tls_client_key (int)
 
    For HTTPS connections, the file path of the TLS client certificate key
    http://curl.haxx.se/libcurl/c/CURLOPT_SSLKEY.html
 
    Default value is NULL (not used).
 
-   Example 1.10. Set tlsclientkey parameter
+   Example 1.10. Set tls_client_key parameter
 ...
-modparam("async_http", "tlsclientkey", "/etc/kamailio/ssl/clientcert.key")
+modparam("http_async_client", "tls_client_key", "/etc/kamailio/ssl/clientcert.ke
+y")
 ...
 
-3.11. tlscapath (int)
+3.11. tls_ca_path (int)
 
    The path of the directory holding the CA certificates.
    http://curl.haxx.se/libcurl/c/CURLOPT_CAPATH.html
 
    Default value is NULL..
 
-   Example 1.11. Set tlscapath parameter
+   Example 1.11. Set tls_ca_path parameter
 ...
-modparam("async_http", "tlscapath", "/etc/kamailio/ssl/ca/")
+modparam("http_async_client", "tls_ca_path", "/etc/kamailio/ssl/ca/")
 ...
 
 4. Functions
 
    4.1. http_async_query(url, [post_data], route_name)
    4.2. http_async_suspend(suspend)
-   4.3. http_verify_host(verify)
-   4.4. http_verify_peer(verify)
+   4.3. tls_verify_host(verify)
+   4.4. tls_verify_peer(verify)
    4.5. http_set_timeout(timeout)
    4.6. http_append_header(header)
    4.7. http_set_method(method)
-   4.8. http_set_ssl_cert(path)
-   4.9. http_set_ssl_key(path)
-   4.10. http_set_ca_path(path)
+   4.8. http_set_tls_client_cert(path)
+   4.9. http_set_tls_client_key(path)
+   4.10. http_set_tls_ca_path(path)
 
 4.1.  http_async_query(url, [post_data], route_name)
 
@@ -372,7 +375,7 @@ route[HTTP_REPLY] {
         xlog("L_INFO", "route[HTTP_REPLY]: status $http_rs\n");
         xlog("L_INFO", "route[HTTP_REPLY]: body   $http_rb\n");
     } else {
-        xlog("L_INFO", "route[HTTP_REPLY]: error  $http_error)\n");
+        xlog("L_INFO", "route[HTTP_REPLY]: error  $http_err)\n");
     }
 }
 ...
@@ -397,7 +400,7 @@ t_reply("200", "Ok");
 
 ...
 
-4.3.  http_verify_host(verify)
+4.3.  tls_verify_host(verify)
 
    For the next HTTPS connection, whether the client should verify the
    server host.
@@ -405,14 +408,14 @@ t_reply("200", "Ok");
    Parameter “verify” set to "1" to enable the host verification, "0" to
    disable. Default: the global value set as verify_host module parameter.
 
-   Example 1.14. http_verify_host() usage
+   Example 1.14. tls_verify_host() usage
 ...
-http_verify_host("0");
+tls_verify_host("0");
 # host verification is disabled for the next query
 http_query("https://example.com/test.php", "HTTP_REPLY");
 ...
 
-4.4.  http_verify_peer(verify)
+4.4.  tls_verify_peer(verify)
 
    For the next HTTPS connection, whether the client should verify the
    server identity.
@@ -421,9 +424,9 @@ http_query("https://example.com/test.php", "HTTP_REPLY");
    to disable. Default: the global value set as verify_peer module
    parameter.
 
-   Example 1.15. http_verify_peer() usage
+   Example 1.15. tls_verify_peer() usage
 ...
-http_verify_peer("0");
+tls_verify_peer("0");
 # server identity verification is disabled for the next query
 http_query("https://example.com/test.php", "HTTP_REPLY");
 ...
@@ -488,49 +491,81 @@ http_set_method("PUT");
 http_query("https://example.com/test.php", "{'foo': 'bar'}", "HTTP_REPLY");
 ...
 
-4.8.  http_set_ssl_cert(path)
+4.8.  http_set_tls_client_cert(path)
 
    For the next HTTPS connection, what client certificate to use.
 
-   Default: the global value set as ssl_cert module parameter.
+   Default: the global value set as tls_client_cert module parameter.
 
-   Example 1.19. http_set_ssl_cert() usage
+   Example 1.19. http_set_tls_client_cert() usage
 ...
-http_set_ssl_cert("/etc/kamailio/ssl/cert.pem");
+http_set_tls_client_cert("/etc/kamailio/ssl/cert.pem");
 # Next query will use the client cert above
 http_query("https://example.com/test.php", "HTTP_REPLY");
 ...
 
-4.9.  http_set_ssl_key(path)
+4.9.  http_set_tls_client_key(path)
 
    For the next HTTPS connection, what client certificate key to use.
 
-   Default: the global value set as ssl_key module parameter.
+   Default: the global value set as tls_client_key module parameter.
 
-   Example 1.20. http_set_ssl_key() usage
+   Example 1.20. http_set_tls_client_key() usage
 ...
-http_set_ssl_key("/etc/kamailio/ssl/cert.key");
+http_set_tls_client_key("/etc/kamailio/ssl/cert.key");
 # Next query will use the client cert key above
 http_query("https://example.com/test.php", "HTTP_REPLY");
 ...
 
-4.10.  http_set_ca_path(path)
+4.10.  http_set_tls_ca_path(path)
 
    For the next HTTP connection, what CA certificate files to use.
 
-   Default: the global value set as ca_path module parameter.
+   Default: the global value set as tls_ca_path module parameter.
 
-   Example 1.21. http_set_ca_path() usage
+   Example 1.21. http_set_tls_ca_path() usage
 ...
-http_set_ssl_key("/etc/kamailio/ssl/ca/");
+http_set_tls_client_key("/etc/kamailio/ssl/ca/");
 # Next query will use the CA certs above
 http_query("https://example.com/test.php", "HTTP_REPLY");
 ...
 
 5. Pseudo Variables
 
-   The following pseudo variables can only be used in the callback routes
-   executed by http_async_query()
+   The $http_req(key) write-only variable can be used to set custom
+   parameters before sending a HTTP query
+
+   setting this variable has the same effect than using the
+   http_set_*()functions
+
+   key can be one of:
+     * all: if set to $null, resets all the parameters to their default
+       value (the ones defined in modparam)
+     * hdr: sets/modifies/remove a HTTP header (see http_append_header()).
+       N.B.: setting this variable multiple times will add several headers
+       to the query.
+     * method: sets the HTTP method (see http_set_method())
+     * timeout: sets the HTTP timeout (see http_set_timeout())
+     * tls_client_cert: sets the client certificate to use (see
+       http_set_tls_client_cert())
+     * tls_client_key: sets the client certificate key to use (see
+       http_set_tls_client_key())
+     * tls_ca_path: sets the CA certificate files to use (see
+       http_set_tls_ca_path())
+
+   Example 1.22. $http_req(key) variable usage
+...
+$http_req(all) = $null;                    # reset the parameters
+$http_req(timeout) = 100;                  # 100 ms
+$http_req(method) = "DELETE";
+$http_req(hdr) = "X-Sip-Call-Id: " + $ci;
+$http_req(hdr) = "X-Foo: bar";             # add a 2nd header
+# the following request will use the above parameters
+http_query("https://example.com/test.php", "HTTP_REPLY");
+...
+
+   The following read-only pseudo variables can only be used in the
+   callback routes executed by http_async_query()
      * $http_ok: 1 if cURL executed the request successfully, 0 otherwise
        (check $ah_err for details)
      * $http_err: cURL error string if an error occured, $null otherwise