Scieneer Common Lisp 1.3.9 online documentation

http:make-client &key stream-timeout stream-expiration idle-timeout protocol protocol-major protocol-minor pool-enabled-p maximum-server-connections maximum-connections maximum-connection-requests retries retry-interval accept-gzip-encoding-p proxy-host proxy-port non-proxy-hosts certificate key verify-mode verify-depth ciphers ssl-options ssl-context[Function]

Make and return a HTTP client object. The HTTP client object holds parameters used when processing client requests, and may contain a pool of connections. A default client object is available in http:*default-client*.

The stream-timeout, if not nil, is the time in seconds to wait upon individual stream operations before giving up and can be used to timeout if the server stops communicating. The default stream-time is 300 seconds.

The stream-expiration, if not nil, is the total real time in seconds from the start of each request until the stream expires and can be used to timeout if the server communication is too slow even though data may be trickling through. The default stream-expiration is nil. The stream expiration is reset at the start of each request and cleared when idle.

The idle-timeout, if not nil, is the number of seconds to keep idle connections alive in the connection pool before closing them. The default idle-timeout is 300 seconds.

The client protocol may be the default of HTTP/1.1 or alternatively HTTP/1.0. The protocol string and the protocol-major and protocol-minor numbers must be specified if not using the default.

When pool-enabled-p is true, client requests will reuse connections from a connection pool which can improve performance. The connection pool is enabled by default.

The client keeps track of the number of open connections and is able to limit the number of connections to each host port, and also to limit the total number of connections for the client. Limiting the number of connections to a host is often a nice behavior for a client, helping to avoid overloading the server.

A limit may also be placed on the number of requests issued over a persistent pooled connection by specifying the maximum-connection-requests. A persistent connection will be closed when this maximum is reached and a new connection will be opened if necessary. This could be a nice behavior for a client, periodically freeing the server resources for use by other clients. The default value is 200 requests.

The client contains some other default parameters used by the function http:process-uri-request when preparing a request, such as the proxy and SSL parameters for https requests. These parameters may be overridden by arguments supplied to http:process-uri-request. A range of standard Common Lisp file system operations such as open and probe-file can operate on URIs with a http or https scheme, and these operations use the default client parameters in the http:*default-client* object. Applications may change the parameters used by such operations by changing the default parameters in the http:*default-client* or by creating an alternative client object and binding it to http:*default-client* for the extent of the operation.

When accept-gzip-encoding-p is true, http:process-uri-request will include an Accept-Encoding header specifying gzip compression with requests.

A default proxy server may be specified, and will be used by http:process-uri-request when preparing requests. The proxy-host is the hostname string and the proxy-port is the number of the proxy port which defaults to port 80. Requests to hostnames matching a hostname or partial domain name from the non-proxy-hosts list will not use the proxy, see http:client-non-proxy-hosts.

A default number of retries and a retry-interval may be specified for the client, along with the SSL connection parameters: certificate, key, verify-mode, verify-depth, ciphers, ssl-options, ssl-context. These are all used by http:process-uri-request as defaults when preparing a request.