=========
vmod_curl
=========

-------------------
Varnish cURL Module
-------------------

SYNOPSIS
========

import curl;

DESCRIPTION
===========

Varnish Module that provides cURL bindings for Varnish so you can use
Varnish as an HTTP client and fetch headers and bodies from backends.

FUNCTIONS
=========

get
---

Prototype
        ::

                get(STRING)
Return value
        VOID
Description
        Performs a GET request to the given URL.  A deprecated alias
        for this function is `fetch`.
Example
        ::

                curl.get("http://example.com/test");
                curl.free();

head
----

Prototype
        ::

                head(STRING)
Return value
        VOID
Description
        Performs a HEAD request to the given URL.
Example
        ::

                curl.head("http://example.com/test");
                curl.free();

post
----

Prototype
        ::

                post(STRING, STRING)
Return value
        VOID
Description
        Performs a POST request to the given URL.  The second
        parameter are the POST parameters.
Example
        ::

                curl.post("http://example.com/test", "a=b");
                curl.free();

header
------

Prototype
        ::

                header(STRING)
Return value
        STRING
Description
        Returns the header named in the first argument.
Example
        ::

                curl.get("http://example.com/test");
                if (curl.header("X-Foo") == "bar") {
                    ...
                }
                curl.free();

free
----

Prototype
        ::

                free()
Return value
        VOID
Description
        Free the memory used by headers.
        Not needed, will be handled automatically if it's not called.

status
------

Prototype
        ::

                status()
Return value
        INT
Description
        Returns the HTTP status code.
Example
        ::

                curl.get("http://example.com/test");
                if (curl.status() == 404) {
                    ...
                }
                curl.free();

error
-----

Prototype
        ::

                error()
Return value
        STRING
Description
        Returns the HTTP error.

body
----

Prototype
        ::

                body()
Return value
        STRING
Description
        Returns the HTTP body content.

set_timeout
-----------

Prototype
        ::

                set_timeout(INT)
Return value
        VOID
Description
        Sets the CURLOPT_TIMEOUT_MS option to the value of the first argument.

set_connect_timeout
-------------------

Prototype
        ::

                set_connect_timeout(INT)
Return value
        VOID
Description
        Sets the CURLOPT_CONNECTTIMEOUT_MS option to the value of the first argument.

set_ssl_verify_peer
-------------------

Prototype
        ::

                set_ssl_verify_peer(INT)
Return value
        VOID
Description
        Sets the CURLOPT_SSL_VERIFYPEER option to either 0L or 1L, depending on the boolean value of the first argument.

set_ssl_verify_host
-------------------

Prototype
        ::

                set_ssl_verify_host(INT)
Return value
        VOID
Description
        Sets the CURLOPT_SSL_VERIFYHOST option to either 0L or 1L, depending on the boolean value of the first argument.

set_ssl_cafile
--------------

Prototype
        ::

                set_ssl_cafile(STRING)
Return value
        VOID
Description
        Sets the CURLOPT_CAINFO option to the value of the first argument.

set_ssl_capath
--------------

Prototype
        ::

                set_ssl_capath(STRING)
Return value
        VOID
Description
        Sets the CURLOPT_CAPATH option to the value of the first argument.

header_add
----------

Prototype
        ::

                header_add(STRING)
Return value
        VOID
Description
        Adds a custom request header.
        If you add a header that is otherwise generated and used by libcurl
        internally, your added one will be used instead. If you add a header
        with no content as in "Accept:" (no data on the right side of the
        colon), the internally used header will get disabled. Thus, using this
        option you can add new headers, replace internal headers and remove
        internal headers. To add a header with no content, make the content be
        two quotes: ""
Example
        ::

                // copy Host: header from request
                curl.header_add("Host: " + req.http.Host);
                // disable Accept header generated by libcurl
                curl.header_add("Accept:");
                // add X-curl-Request header with no content
                curl.header_add("X-curl-Request: " + curl.unescape("%22%22"));
                // alternative using long string syntax
                curl.header_add({"X-curl-Request: """});

header_add_all
--------------

Prototype
        ::

                header_add_all()
Return value
        VOID
Description
        Adds all headers in the req object to the request.
        If used from a backend thread, the bereq object is used.
        Can be used in combination with header_add() and header_remove().
        The rules in header_add() apply to header_add_all().
Example
        ::

                // copy all headers from the req object in context
                curl.header_add_all();

header_remove
-------------

Prototype
        ::

                header_remove(STRING)
Return value
        VOID
Description
        Removes all custom request header fields matching the given header name.
        Only headers added by header_add() can be removed. To disable headers
        generated internally by libcurl *add* the header with no content.
Example
        ::

                curl.header_remove("Host");

escape
------

Prototype
        ::

                escape(STRING)
Return value
        STRING
Description
        URL encodes the given string.

unescape
--------

Prototype
        ::

                unescape(STRING)
Return value
        STRING
Description
        URL decodes the given string.

set_proxy
---------

Prototype
        ::

                set_proxy(STRING)
Return value
        VOID
Description
        Set the proxy to use.  A deprecated alias for this function is `proxy`.
Example
        ::

                curl.set_proxy("http://user:secret@some.server.dom:8080/");

set_method
----------

Prototype
        ::

                set_method(STRING)
Return value
        VOID
Description
        Set a custom string for this request.
        This doesn't actually change how libcurl behaves or acts in
        regards to the particular request method, it will only change
        the actual string sent in the request.
Example
        ::

                curl.set_method("PURGE");
                curl.head("http://example.com/test");

BUGS
====

None.

COPYRIGHT
=========

Development of this VMOD has been sponsored by the Norwegian company
Aspiro Music AS for usage on their WiMP music streaming service.

This document is licensed under the same license as the
libvmod-curl project. See LICENSE for details.

* Copyright (c) 2011-2014 Varnish Software
