Struct HttpClient

pub struct HttpClient<C>
where
    C: Handler + Debug + Send + 'static,
{ /* private fields */ }

The HttpClient struct’s job is to wrap and build curl Easy2.

Implementations

impl<C> HttpClient<C>

where C: ExtendedHandler + Debug + Send + 'static,

pub fn new(collector: C) -> Self

Creates a new HTTP Client.

The C is a generic type to be able to implement a custom HTTP response collector whoever uses this crate. There is a built-in Collector in this crate that can be used store HTTP response body into memory or in a File.

pub fn nonblocking<A: Actor<C>>(self, actor: A) -> AsyncPerform<C, A>

This marks the end of the curl builder to be able to do asynchronous operation during perform.

The parameter trait Actor<C> is any custom Actor implemented by the user that must implement a send_request that is non-blocking.

There is a built-in CurlActor that implements the Actor<C> trait that can be cloned to be able to handle multiple request sender and a single consumer that is spawned in the background to be able to achieve non-blocking I/O during curl perform.

pub fn blocking(self) -> SyncPerform<C>

This marks the end of the curl builder to be able to do synchronous operation during perform.

pub fn request<B: CurlBodyRequest>( self, request: Request<B>, ) -> Result<Self, Error<C>>

Sets the HTTP request.

The HttpRequest can be customized by the caller by setting the Url, Method Type, Headers and the Body.

pub fn resume_from(self, offset: BytesOffset) -> Result<Self, Error<C>>

Set a point to resume transfer from

Specify the offset in bytes you want the transfer to start from.

By default this option is 0 and corresponds to CURLOPT_RESUME_FROM_LARGE.

pub fn download_speed(self, speed: Bps) -> Result<Self, Error<C>>

Rate limit data download speed

If a download exceeds this speed (counted in bytes per second) on cumulative average during the transfer, the transfer will pause to keep the average rate less than or equal to the parameter value.

By default this option is not set (unlimited speed) and corresponds to CURLOPT_MAX_RECV_SPEED_LARGE.

pub fn upload_file_size(self, size: FileSize) -> Result<Self, Error<C>>

Set the size of the input file to send off.

By default this option is not set and corresponds to CURLOPT_INFILESIZE_LARGE.

pub fn upload_speed(self, speed: Bps) -> Result<Self, Error<C>>

Rate limit data upload speed

If an upload exceeds this speed (counted in bytes per second) on cumulative average during the transfer, the transfer will pause to keep the average rate less than or equal to the parameter value.

By default this option is not set (unlimited speed) and corresponds to CURLOPT_MAX_SEND_SPEED_LARGE.

pub fn username(self, user: &str) -> Result<Self, Error<C>>

Configures the username to pass as authentication for this connection.

By default this value is not set and corresponds to CURLOPT_USERNAME.

pub fn password(self, pass: &str) -> Result<Self, Error<C>>

Configures the password to pass as authentication for this connection.

By default this value is not set and corresponds to CURLOPT_PASSWORD.

pub fn http_auth(self, auth: &Auth) -> Result<Self, Error<C>>

Set HTTP server authentication methods to try

If more than one method is set, libcurl will first query the site to see which authentication methods it supports and then pick the best one you allow it to use. For some methods, this will induce an extra network round-trip. Set the actual name and password with the password and username methods.

For authentication with a proxy, see proxy_auth.

By default this value is basic and corresponds to CURLOPT_HTTPAUTH.

pub fn port(self, port: u16) -> Result<Self, Error<C>>

Configures the port number to connect to, instead of the one specified in the URL or the default of the protocol.

pub fn cainfo<P: AsRef<Path>>(self, path: P) -> Result<Self, Error<C>>

Specify the path to Certificate Authority (CA) bundle

The file referenced should hold one or more certificates to verify the peer with.

This option is by default set to the system path where libcurl’s cacert bundle is assumed to be stored, as established at build time.

If curl is built against the NSS SSL library, the NSS PEM PKCS#11 module (libnsspem.so) needs to be available for this option to work properly.

By default this option is the system defaults, and corresponds to CURLOPT_CAINFO.

pub fn capath<P: AsRef<Path>>(self, path: P) -> Result<Self, Error<C>>

Specify directory holding CA certificates

Names a directory holding multiple CA certificates to verify the peer with. If libcurl is built against OpenSSL, the certificate directory must be prepared using the openssl c_rehash utility. This makes sense only when used in combination with the ssl_verify_peer option.

By default this option is not set and corresponds to CURLOPT_CAPATH.

pub fn proxy_username(self, user: &str) -> Result<Self, Error<C>>

Configures the proxy username to pass as authentication for this connection.

By default this value is not set and corresponds to CURLOPT_PROXYUSERNAME.

pub fn proxy_password(self, pass: &str) -> Result<Self, Error<C>>

Configures the proxy password to pass as authentication for this connection.

By default this value is not set and corresponds to CURLOPT_PROXYPASSWORD.

pub fn proxy_auth(self, auth: &Auth) -> Result<Self, Error<C>>

Set HTTP proxy authentication methods to try

If more than one method is set, libcurl will first query the site to see which authentication methods it supports and then pick the best one you allow it to use. For some methods, this will induce an extra network round-trip. Set the actual name and password with the proxy_password and proxy_username methods.

By default this value is basic and corresponds to CURLOPT_PROXYAUTH.

pub fn proxy(self, url: &str) -> Result<Self, Error<C>>

Provide the URL of a proxy to use.

By default this option is not set and corresponds to CURLOPT_PROXY.

pub fn proxy_port(self, port: u16) -> Result<Self, Error<C>>

Provide port number the proxy is listening on.

By default this option is not set (the default port for the proxy protocol is used) and corresponds to CURLOPT_PROXYPORT.

pub fn proxy_cainfo(self, cainfo: &str) -> Result<Self, Error<C>>

Set CA certificate to verify peer against for proxy.

By default this value is not set and corresponds to CURLOPT_PROXY_CAINFO.

pub fn proxy_capath<P: AsRef<Path>>(self, path: P) -> Result<Self, Error<C>>

Specify a directory holding CA certificates for proxy.

The specified directory should hold multiple CA certificates to verify the HTTPS proxy with. If libcurl is built against OpenSSL, the certificate directory must be prepared using the OpenSSL c_rehash utility.

By default this value is not set and corresponds to CURLOPT_PROXY_CAPATH.

pub fn proxy_sslcert(self, sslcert: &str) -> Result<Self, Error<C>>

Set client certificate for proxy.

By default this value is not set and corresponds to CURLOPT_PROXY_SSLCERT.

pub fn proxy_sslcert_type(self, kind: &str) -> Result<Self, Error<C>>

Specify type of the client SSL certificate for HTTPS proxy.

The string should be the format of your certificate. Supported formats are “PEM” and “DER”, except with Secure Transport. OpenSSL (versions 0.9.3 and later) and Secure Transport (on iOS 5 or later, or OS X 10.7 or later) also support “P12” for PKCS#12-encoded files.

By default this option is “PEM” and corresponds to CURLOPT_PROXY_SSLCERTTYPE.

pub fn proxy_sslcert_blob(self, blob: &[u8]) -> Result<Self, Error<C>>

Set the client certificate for the proxy using an in-memory blob.

The specified byte buffer should contain the binary content of the certificate, which will be copied into the handle.

By default this option is not set and corresponds to CURLOPT_PROXY_SSLCERT_BLOB.

pub fn proxy_sslkey(self, sslkey: &str) -> Result<Self, Error<C>>

Set private key for HTTPS proxy.

By default this value is not set and corresponds to CURLOPT_PROXY_SSLKEY.

pub fn proxy_sslkey_type(self, kind: &str) -> Result<Self, Error<C>>

Set type of the private key file for HTTPS proxy.

The string should be the format of your private key. Supported formats are “PEM”, “DER” and “ENG”.

The format “ENG” enables you to load the private key from a crypto engine. In this case ssl_key is used as an identifier passed to the engine. You have to set the crypto engine with ssl_engine. “DER” format key file currently does not work because of a bug in OpenSSL.

By default this option is “PEM” and corresponds to CURLOPT_PROXY_SSLKEYTYPE.

pub fn proxy_sslkey_blob(self, blob: &[u8]) -> Result<Self, Error<C>>

Set the private key for the proxy using an in-memory blob.

The specified byte buffer should contain the binary content of the private key, which will be copied into the handle.

By default this option is not set and corresponds to CURLOPT_PROXY_SSLKEY_BLOB.

pub fn proxy_key_password(self, password: &str) -> Result<Self, Error<C>>

Set passphrase to private key for HTTPS proxy.

This will be used as the password required to use the ssl_key. You never needed a pass phrase to load a certificate but you need one to load your private key.

By default this option is not set and corresponds to CURLOPT_PROXY_KEYPASSWD.

pub fn proxy_type(self, kind: ProxyType) -> Result<Self, Error<C>>

Indicates the type of proxy being used.

By default this option is ProxyType::Http and corresponds to CURLOPT_PROXYTYPE.

pub fn noproxy(self, skip: &str) -> Result<Self, Error<C>>

Provide a list of hosts that should not be proxied to.

This string is a comma-separated list of hosts which should not use the proxy specified for connections. A single * character is also accepted as a wildcard for all hosts.

By default this option is not set and corresponds to CURLOPT_NOPROXY.

pub fn http_proxy_tunnel(self, tunnel: bool) -> Result<Self, Error<C>>

Inform curl whether it should tunnel all operations through the proxy.

This essentially means that a CONNECT is sent to the proxy for all outbound requests.

By default this option is false and corresponds to CURLOPT_HTTPPROXYTUNNEL.

pub fn follow_location(self, enable: bool) -> Result<Self, Error<C>>

Follow HTTP 3xx redirects.

Indicates whether any Location headers in the response should get followed.

By default this option is false and corresponds to CURLOPT_FOLLOWLOCATION.

pub fn fresh_connect(self, enable: bool) -> Result<Self, Error<C>>

Force a new connection to be used.

Makes the next transfer use a new (fresh) connection by force instead of trying to re-use an existing one. This option should be used with caution and only if you understand what it does as it may seriously impact performance.

By default this option is false and corresponds to CURLOPT_FRESH_CONNECT.

pub fn forbid_reuse(self, enable: bool) -> Result<Self, Error<C>>

Make connection get closed at once after use.

Makes libcurl explicitly close the connection when done with the transfer. Normally, libcurl keeps all connections alive when done with one transfer in case a succeeding one follows that can re-use them. This option should be used with caution and only if you understand what it does as it can seriously impact performance.

By default this option is false and corresponds to CURLOPT_FORBID_REUSE.

pub fn connect_timeout(self, timeout: Duration) -> Result<Self, Error<C>>

Timeout for the connect phase

This is the maximum time that you allow the connection phase to the server to take. This only limits the connection phase, it has no impact once it has connected.

By default this value is 300 seconds and corresponds to CURLOPT_CONNECTTIMEOUT_MS.

pub fn timeout(self, timeout: Duration) -> Result<Self, Error<C>>

Set maximum time the request is allowed to take.

Normally, name lookups can take a considerable time and limiting operations to less than a few minutes risk aborting perfectly normal operations.

If libcurl is built to use the standard system name resolver, that portion of the transfer will still use full-second resolution for timeouts with a minimum timeout allowed of one second.

In unix-like systems, this might cause signals to be used unless nosignal is set.

Since this puts a hard limit for how long a request is allowed to take, it has limited use in dynamic use cases with varying transfer times. You are then advised to explore low_speed_limit, low_speed_time or using progress_function to implement your own timeout logic.

By default this option is not set and corresponds to CURLOPT_TIMEOUT_MS.

pub fn http_version(self, version: HttpVersion) -> Result<Self, Error<C>>

Set preferred HTTP version.

By default this option is not set and corresponds to CURLOPT_HTTP_VERSION.

pub fn ssl_version(self, version: SslVersion) -> Result<Self, Error<C>>

Set preferred TLS/SSL version.

By default this option is not set and corresponds to CURLOPT_SSLVERSION.

pub fn verbose(self, verbose: bool) -> Result<Self, Error<C>>

Configures this handle to have verbose output to help debug protocol information.

By default output goes to stderr, but the stderr function on this type can configure that. You can also use the debug_function method to get all protocol data sent and received.

By default, this option is false.

pub fn show_header(self, show: bool) -> Result<Self, Error<C>>

Indicates whether header information is streamed to the output body of this request.

This option is only relevant for protocols which have header metadata (like http or ftp). It’s not generally possible to extract headers from the body if using this method, that use case should be intended for the header_function method.

To set HTTP headers, use the http_header method.

By default, this option is false and corresponds to CURLOPT_HEADER.

pub fn progress(self, progress: bool) -> Result<Self, Error<C>>

Indicates whether a progress meter will be shown for requests done with this handle.

This will also prevent the progress_function from being called.

By default this option is false and corresponds to CURLOPT_NOPROGRESS.

pub fn download_buffer_size(self, size: usize) -> Result<Self, Error<C>>

Specify the preferred receive buffer size, in bytes.

This is treated as a request, not an order, and the main point of this is that the write callback may get called more often with smaller chunks.

By default this option is the maximum write size and corresopnds to CURLOPT_BUFFERSIZE.

pub fn upload_buffer_size(self, size: usize) -> Result<Self, Error<C>>

Specify the preferred send buffer size, in bytes.

This is treated as a request, not an order, and the main point of this is that the read callback may get called more often with smaller chunks.

The upload buffer size is by default 64 kilobytes.

pub fn buffer_size(self, size: usize) -> Result<Self, Error<C>>

Specify the preferred receive buffer size, in bytes.

This is treated as a request, not an order, and the main point of this is that the write callback may get called more often with smaller chunks.

By default this option is the maximum write size and corresopnds to CURLOPT_BUFFERSIZE.

pub fn reset(&mut self)

Re-initializes this handle to the default values.

This puts the handle to the same state as it was in when it was just created. This does, however, keep live connections, the session id cache, the dns cache, and cookies.

pub fn url(self, url: &str) -> Result<Self, Error<C>>

Provides the URL which this handle will work with.

The string provided must be URL-encoded with the format:

scheme://host:port/path

The syntax is not validated as part of this function and that is deferred until later.

By default this option is not set and perform will not work until it is set. This option corresponds to CURLOPT_URL.

pub fn custom_request(self, request: &str) -> Result<Self, Error<C>>

Set a custom request string

Specifies that a custom request will be made (e.g. a custom HTTP method). This does not change how libcurl performs internally, just changes the string sent to the server.

By default this option is not set and corresponds to CURLOPT_CUSTOMREQUEST.

pub fn fetch_filetime(self, fetch: bool) -> Result<Self, Error<C>>

Get the modification time of the remote resource

If true, libcurl will attempt to get the modification time of the remote document in this operation. This requires that the remote server sends the time or replies to a time querying command. The filetime function can be used after a transfer to extract the received time (if any).

By default this option is false and corresponds to CURLOPT_FILETIME

pub fn nobody(self, enable: bool) -> Result<Self, Error<C>>

Indicate whether to download the request without getting the body

This is useful, for example, for doing a HEAD request.

By default this option is false and corresponds to CURLOPT_NOBODY.

pub fn in_filesize(self, size: u64) -> Result<Self, Error<C>>

Set the size of the input file to send off.

By default this option is not set and corresponds to CURLOPT_INFILESIZE_LARGE.

pub fn upload(self, enable: bool) -> Result<Self, Error<C>>

Enable or disable data upload.

This means that a PUT request will be made for HTTP and probably wants to be combined with the read callback as well as the in_filesize method.

By default this option is false and corresponds to CURLOPT_UPLOAD.

pub fn max_filesize(self, size: u64) -> Result<Self, Error<C>>

Configure the maximum file size to download.

By default this option is not set and corresponds to CURLOPT_MAXFILESIZE_LARGE.

pub fn time_condition(self, cond: TimeCondition) -> Result<Self, Error<C>>

Selects a condition for a time request.

This value indicates how the time_value option is interpreted.

By default this option is not set and corresponds to CURLOPT_TIMECONDITION.

pub fn time_value(self, val: i64) -> Result<Self, Error<C>>

Sets the time value for a conditional request.

The value here should be the number of seconds elapsed since January 1, 1970. To pass how to interpret this value, use time_condition.

By default this option is not set and corresponds to CURLOPT_TIMEVALUE.

pub fn cookie_session(self, session: bool) -> Result<Self, Error<C>>

Start a new cookie session

Marks this as a new cookie “session”. It will force libcurl to ignore all cookies it is about to load that are “session cookies” from the previous session. By default, libcurl always stores and loads all cookies, independent if they are session cookies or not. Session cookies are cookies without expiry date and they are meant to be alive and existing for this “session” only.

By default this option is false and corresponds to CURLOPT_COOKIESESSION.

pub fn get(self, enable: bool) -> Result<Self, Error<C>>

Ask for a HTTP GET request.

By default this option is false and corresponds to CURLOPT_HTTPGET.

pub fn post(self, enable: bool) -> Result<Self, Error<C>>

Make an HTTP POST request.

This will also make the library use the Content-Type: application/x-www-form-urlencoded header.

POST data can be specified through post_fields or by specifying a read function.

By default this option is false and corresponds to CURLOPT_POST.