(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) (make-http-session proto) (make-http-session proto timeout) (make-http-session proto timeout cookies?) (make-http-session proto timeout cookies? cache) (make-http-session proto timeout cookies? cache maxcon) (make-http-session proto timeout cookies? cache maxcon pipe?) (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) (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) (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?) (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) (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) (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?) (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?) (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) (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!) (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!) (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!) (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!) (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) (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) (make-http-request url meth headers) (make-http-request url meth headers timeout) (make-http-request url meth headers timeout cookies?) (make-http-request url meth headers timeout cookies? cache) (make-http-request url meth headers timeout cookies? cache pipe?) (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) (http-request-copy req headers) (http-request-copy req headers timeout) (http-request-copy req headers timeout cookies?) (http-request-copy req headers timeout cookies? cache) (http-request-copy req headers timeout cookies? cache pipe?) (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) (http-request-content-set! req bvec start) (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) (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) (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.