# (lispkit http)
Library `(lispkit http)` provides an API for downloading data from and uploading data to endpoints specified by URLs using the HTTP family of protocols.
## HTTP sessions
HTTP session objects are used to coordinate a group of related data-transfer tasks. Within each session, typically a series of tasks are created, each of which represents a request for a specific URL. The tasks within a given HTTP session share a common session configuration, which defines connection behavior, like the maximum number of simultaneous connections to make to a single host, whether connections can use the cellular network, etc.
**http-session-type-tag** 
Symbol representing the `http-session` type. The `type-for` procedure of library `(lispkit type)` returns this symbol for all HTTP session objects.
**current-http-session** 
This parameter object represents the current default HTTP session. By default, this is set to a shared multi-purpose session object. Procedures requiring an HTTP session typically make the HTTP session argument optional. If it is not provided, the result of `(current-http-session)` is used instead. The value of `current-http-session` can be overridden with `parameterize`.
**(http-session? *****obj*****)** 
Returns `#t` if *obj* is a HTTP session object; `#f` otherwise.
**(make-http-session)** \
\&#xNAN;**(make-http-session *****proto*****)**\
\&#xNAN;**(make-http-session *****proto timeout*****)**\
\&#xNAN;**(make-http-session *****proto timeout cookies?*****)**\
\&#xNAN;**(make-http-session *****proto timeout cookies? cache*****)**\
\&#xNAN;**(make-http-session *****proto timeout cookies? cache maxcon*****)**\
\&#xNAN;**(make-http-session *****proto timeout cookies? cache maxcon pipe?*****)**\
\&#xNAN;**(make-http-session *****proto timeout cookies? cache maxcon pipe? cell?*****)**
Returns a new HTTP session object. The configuration is copied from the prototype HTTP object *proto*. The arguments following *proto* override individual settings of *proto*. If one of those arguments is set to `()`, then it is ignored.
If *proto* is `#f` (or not provided at all), system-specific defaults are used. If *proto* is `#t`, an *ephemeral* session default is used which is not writing caches, cookies, or credentials to disk. Otherwise, it is assumed *proto* is an HTTP session object whose configuration will be used for the newly created HTTP session object.
*timeout* defines the time in seconds to wait for (additional) data. The default is 60. *cookies?* is a boolean argument determining whether requests should automatically provide cookies from the shared cookie store. The default is `#t`. If set to `#f`, then cookie headers need to be provided manually.
*cache* defines a cache policy. The following policies, specified as symbols, are supported:
* `use-protocol-cache-policy`: Use the caching logic defined in the protocol implementation (default).
* `reload-ignoring-local-cache`: The URL load should be loaded only from the originating source.
* `reload-ignoring-local-remote-cache`: Ignore local cache data, and instruct proxies and other intermediates to disregard their caches so far as the protocol allows.
* `return-cache-data-else-load`: Use existing cache data, regardless or age or expiration date, loading from originating source only if there is no cached data.
* `return-cache-data-dont-load`: Use existing cache data, regardless or age or expiration date, and fail if no cached data is available.
* `reload-revalidating-cache`: Use cache data if the origin source can validate it; otherwise, load from the origin.
Argument *maxcon* specifies the maximum number of simultaneous connections made to each host by requests initiated by this session. The default value is 6. *pipe?* is a boolean argument determining whether HTTP pipelining should be used. *cell?* is a boolean argument specifying whether connections should be made over a cellular network.
**(http-session-copy)** \
\&#xNAN;**(http-session-copy *****session*****)**
Returns a copy of *session*. If argument *session* is not provided, a copy of the current value of parameter object `current-http-session` is returned.
**(http-session-timeout)** \
\&#xNAN;**(http-session-timeout *****session*****)**
Returns the connection timeout for *session*. This is the time in seconds to wait for (additional) data. If argument *session* is not provided, the current value of parameter object `current-http-session` is used as a default.
**(http-session-send-cookies?)** \
\&#xNAN;**(http-session-send-cookies? *****session*****)**
Returns a boolean value determining whether requests sent via *session* automatically provide cookies from the shared cookie store. If argument *session* is not provided, the current value of parameter object `current-http-session` is used as a default.
**(http-session-cache-policy)** \
\&#xNAN;**(http-session-cache-policy *****session*****)**
Returns the cache policy used by *session*. If argument *session* is not provided, the current value of parameter object `current-http-session` is used as a default.
The following cache policies are supported: `use-protocol-cache-policy`, `reload-ignoring-local-cache`, `reload-ignoring-local-remote-cache`, `return-cache-data-else-load`, `return-cache-data-dont-load`, `reload-revalidating-cache`. Details are provided in the description of procedure `make-http-session`.
**(http-session-max-connections)** \
\&#xNAN;**(http-session-max-connections *****session*****)**
Returns the maximum number of simultaneous connections made to each host by requests initiated by *session*. If *session* is not provided, the current value of parameter object `current-http-session` is used as a default.
**(http-session-use-pipelining?)** \
\&#xNAN;**(http-session-use-pipelining? *****session*****)**
Returns a boolean value determining whether HTTP pipelining should be used by *session*. If *session* is not provided, the current value of parameter object `current-http-session` is used.
**(http-session-allow-cellular?)** \
\&#xNAN;**(http-session-allow-cellular? *****session*****)**
Returns a boolean value determining whether connections should be made over a cellular network by *session*. If *session* is not provided, the current value of parameter object `current-http-session` is used.
**(http-session-tasks)** \
\&#xNAN;**(http-session-tasks *****session*****)**
Returns a future which will eventually hold the number of currently ongoing tasks initiated via *session*. If *session* is not provided, the current value of parameter object `current-http-session` is used.
**(http-session-flush!)** \
\&#xNAN;**(http-session-flush! *****session*****)**
Flushes cookies and credentials to disk, clears transient caches, and ensures that future requests sent via *session* occur on a new TCP connection. Returns a future which will eventually be set to `#t` once flush has completed. If *session* is not provided, the current value of parameter object `current-http-session` is used.
**(http-session-reset!)** \
\&#xNAN;**(http-session-reset! *****session*****)**
Empties all cookies, caches and credential stores, removes disk files, flushes in-progress downloads to disk, and ensures that future requests initiated via *session* occur on a new socket. Returns a future which will eventually be set to `#t` once reset has completed. If *session* is not provided, the current value of parameter object `current-http-session` is used.
**(http-session-finish!)** \
\&#xNAN;**(http-session-finish! *****session*****)**
This procedure invalidates the session, allowing any outstanding tasks to finish. It returns immediately without waiting for tasks to finish. Once a session is invalidated, new tasks cannot be created in the session, but existing tasks continue until completion. After invalidation, session objects cannot be reused. To cancel all outstanding tasks immediately, call procedure `http-session-cancel!` instead. If *session* is not provided, the current value of parameter object `current-http-session` is used.
**(http-session-cancel!)** \
\&#xNAN;**(http-session-cancel! *****session*****)**
Cancels all outstanding tasks and then invalidates the session. Once invalidated, outstanding tasks will not complete (e.g. by initializing a future) and the session object cannot be reused.\
To allow outstanding tasks to run until completion, call `http-session-finish!` instead. If *session* is not provided, the current value of parameter object `current-http-session` is used.
**(http-session-send *****request*****)** \
\&#xNAN;**(http-session-send *****request session*****)**
Creates a task that retrieves the contents of a URL via the specified HTTP request object *request*, and eventually stores a HTTP result object in the future returned by `http-session-send`. If *session* is not provided, the current value of parameter object `current-http-session` is used.
## HTTP requests
**http-request-type-tag**
Symbol representing the `http-request` type. The `type-for` procedure of library `(lispkit type)` returns this symbol for all HTTP request objects.
**(http-request? *****obj*****)**
Returns `#t` if *obj* is a HTTP request object; `#f` otherwise.
**(make-http-request *****url meth*****)** \
\&#xNAN;**(make-http-request *****url meth headers*****)**\
\&#xNAN;**(make-http-request *****url meth headers timeout*****)**\
\&#xNAN;**(make-http-request *****url meth headers timeout cookies?*****)**\
\&#xNAN;**(make-http-request *****url meth headers timeout cookies? cache*****)**\
\&#xNAN;**(make-http-request *****url meth headers timeout cookies? cache pipe?*****)**\
\&#xNAN;**(make-http-request *****url meth headers timeout cookies? cache pipe? cell?*****)**
Returns a new HTTP request for *url* using the HTTP method *meth*. Supported are the methods `"GET"`, `"HEAD"`, `"POST"`, `"PUT"`, `"DELETE"`, `"CONNECT"`, `"OPTIONS"`, `"TRACE"`, and `"PATCH"`. *headers* is an association list mapping HTTP header names (strings) into header values (strings). The remaining arguments override settings of the session when the request is sent. `()` denotes that the setting of the session should be used.
*timeout* defines the time in seconds to wait for (additional) data. *cookies?* is a boolean argument determining whether requests should automatically provide cookies from the shared cookie store. *cache* defines a cache policy (see `make-http-request`). *pipe?* is a boolean argument determining whether HTTP pipelining should be used. *cell?* is a boolean argument specifying whether connections should be made over a cellular network.
**(http-request-copy *****req*****)** \
\&#xNAN;**(http-request-copy *****req headers*****)**\
\&#xNAN;**(http-request-copy *****req headers timeout*****)**\
\&#xNAN;**(http-request-copy *****req headers timeout cookies?*****)**\
\&#xNAN;**(http-request-copy *****req headers timeout cookies? cache*****)**\
\&#xNAN;**(http-request-copy *****req headers timeout cookies? cache pipe?*****)**\
\&#xNAN;**(http-request-copy *****req headers timeout cookies? cache pipe? cell?*****)**
Returns a copy of HTTP request *req*. The arguments following *req* override existing settings of *req*. If one of those arguments is set to `()` (or `#f` for non-boolean parameters), then it is ignored.
*headers* is an association list mapping HTTP header names (strings) into header values (strings). *timeout* defines the time in seconds to wait for (additional) data. *cookies?* is a boolean argument determining whether requests should automatically provide cookies from the shared cookie store. *cache* defines a cache policy (see `make-http-request`). *pipe?* is a boolean argument determining whether HTTP pipelining should be used. *cell?* is a boolean argument specifying whether connections should be made over a cellular network.
**(http-request-url *****req*****)**
Returns the ULR of HTTP request *req* as a string.
**(http-request-method *****req*****)**
Returns the HTTP method of HTTP request *req* as a string.
**(http-request-headers *****req*****)**
Returns the headers of HTTP request *req* as an association list mapping HTTP header names (strings) into header values (strings).
**(http-request-header *****req key*****)**
Returns the value for the HTTP header *key* from HTTP request *req* as a string. If header *key* does not exist, then `#f` is returned.
**(http-request-header-set! *****req key value*****)**
Sets the value for the HTTP header *key* (string) in HTTP request *req* to *value*. *value* can either be a fixnum, flonum, boolean, symbol, or string. It is automatically converted into a string and stored as the new header value for *key*. If header *key* existed before, it is overridden with a new value via `http-request-header-set!`.
**(http-request-header-remove! *****req key*****)**
Removes HTTP header *key* (string) from HTTP request *req*. If *key* does not exist, then *req* does not change.
**(http-request-content *****req*****)**
Returns the body of HTTP request *req* as a bytevector. If no body has been defined for *req*, the `#f` is returned.
**(http-request-content-set! *****req bvec*****)** \
\&#xNAN;**(http-request-content-set! *****req bvec start*****)**\
\&#xNAN;**(http-request-content-set! *****req bvec start end*****)**
Assigns bytevector *bvec* between *start* and *end* as the body to HTTP request *req*. If *end* is not provided, it is assumed to be the length of *bytevector*. If *start* is not provided, it is assumed to be 0.
**(http-request-timeout *****req*****)**
Returns the timeout in seconds associated with HTTP request *req*.
**(http-request-timeout-set! *****req timeout*****)**
Sets the timeout in seconds to *timeout* for HTTP request *req*.
**(http-request-send-cookies *****req*****)**
Returns `#t` if HTTP request *req* has been configured to automatically provide cookies from the shared cookie store. If the request has been configured to not provide cookies, then `#f` is returned. Without an explicit configuration of this setting, `()` is returned.
**(http-request-cache-policy *****req*****)**
Returns the caching policy associated with HTTP request *req*, if one was set explicitly. Otherwise, `()` is returned. The following policies, specified as symbols, are supported: `use-protocol-cache-policy`, `reload-ignoring-local-cache`, `reload-ignoring-local-remote-cache`, `return-cache-data-else-load`, `return-cache-data-dont-load`, and `reload-revalidating-cache`.
**(http-request-use-pipelining *****req*****)**
Returns `#t` if HTTP request *req* has been configured to use HTTP pipelining. If the request has been configured to not use pipelining, then `#f` is returned. Without an explicit configuration of this setting, `()` is returned.
**(http-request-allow-cellular *****req*****)**
Returns `#t` if HTTP request *req* has been configured to allow connections over cellular networks. If the request has been configured to not allow cellular connections, then `#f` is returned. Without an explicit configuration of this setting, `()` is returned.
## HTTP responses
**http-response-type-tag**
Symbol representing the `http-response` type. The `type-for` procedure of library `(lispkit type)` returns this symbol for all HTTP response objects.
**(http-response? *****obj*****)**
Returns `#t` if *obj* is a HTTP response object; `#f` otherwise.
**(http-response-content *****resp*****)**
Returns the body of the HTTP response *resp* as a bytevector.
**(http-response-status-code *****resp*****)**
Returns the status code of the HTTP response *resp* as a fixnum.
**(http-response-mime-type *****resp*****)**
Returns the MIME type describing the type of content provided by HTTP response *resp* as a string. If no specific MIME type was included in *resp*, then `#f` is returned.
**(http-response-encoding *****resp*****)**
Returns the text encoding name provided by HTTP response *resp* as a string. If no specific text encoding name was included in *resp*, then `#f` is returned.
**(http-response-url *****resp*****)**
Returns the URL for the HTTP response *resp* as a string. If the URL is unknown, then `#f` is returned.
**(http-response-headers *****resp*****)** \
\&#xNAN;**(http-response-headers *****resp str?*****)**
Returns the headers of HTTP response *resp* as an association list mapping HTTP header names (strings) into header values, which are either fixnums, flonums, booleans, or strings. Header values can be forced to be represented as a string if *str?* is set to `#t` (default is `#f`).
**(http-response-header *****resp key*****)** \
\&#xNAN;**(http-response-header *****resp key str?*****)**
Returns the value for the HTTP header *key* from HTTP request *req* either as a fixnum, flonum, boolean or string. If header *key* does not exist, then `#f` is returned. The result can be forced to be a string if *str?* is set to `#t` (default is `#f`).
## Miscellaneous
**(http-status-code->string *****sc*****)**
Returns a string representation for numeric HTTP status code *sc*.