7.3.7 HTTP Responses

(use-modules (web response))

As with requests (see HTTP Requests), Guile offers a data type for HTTP responses. Again, the body is represented separately from the request.

Scheme Procedure: response? obj
Scheme Procedure: response-version response
Scheme Procedure: response-code response
Scheme Procedure: response-reason-phrase response
Scheme Procedure: response-headers response
Scheme Procedure: response-port response

A predicate and field accessors for the response type. The fields are as follows:

version

The HTTP version pair, like (1 . 1).

code

The HTTP response code, like 200.

reason-phrase

The reason phrase, or the standard reason phrase for the response’s code.

headers

The response headers, as an alist of parsed values.

port

The port on which to read or write a response body, if any.

Scheme Procedure: read-response port

Read an HTTP response from port.

As a side effect, sets the encoding on port to ISO-8859-1 (latin-1), so that reading one character reads one byte. See the discussion of character sets in HTTP Responses, for more information.

Scheme Procedure: build-response [#:version=’(1 . 1)] [#:code=200] [#:reason-phrase=#f] [#:headers=’()] [#:port=#f] [#:validate-headers?=#t]

Construct an HTTP response object. If validate-headers? is true, the headers are each run through their respective validators.

Scheme Procedure: adapt-response-version response version

Adapt the given response to a different HTTP version. Return a new HTTP response.

The idea is that many applications might just build a response for the default HTTP version, and this method could handle a number of programmatic transformations to respond to older HTTP versions (0.9 and 1.0). But currently this function is a bit heavy-handed, just updating the version field.

Scheme Procedure: write-response r port

Write the given HTTP response to port.

Return a new response, whose response-port will continue writing on port, perhaps using some transfer encoding.

Scheme Procedure: response-must-not-include-body? r

Some responses, like those with status code 304, are specified as never having bodies. This predicate returns #t for those responses.

Note also, though, that responses to HEAD requests must also not have a body.

Scheme Procedure: response-body-port r [#:decode?=#t] [#:keep-alive?=#t]

Return an input port from which the body of r can be read. The encoding of the returned port is set according to r’s content-type header, when it’s textual, except if decode? is #f. Return #f when no body is available.

When keep-alive? is #f, closing the returned port also closes r’s response port.

Scheme Procedure: read-response-body r

Read the response body from r, as a bytevector. Returns #f if there was no response body.

Scheme Procedure: write-response-body r bv

Write bv, a bytevector, to the port corresponding to the HTTP response r.

As with requests, the various headers that are typically associated with HTTP responses may be accessed with these dedicated accessors. See HTTP Headers, for more information on the format of parsed headers.

Scheme Procedure: response-accept-ranges response [default=#f]
Scheme Procedure: response-age response [default=’()]
Scheme Procedure: response-allow response [default=’()]
Scheme Procedure: response-cache-control response [default=’()]
Scheme Procedure: response-connection response [default=’()]
Scheme Procedure: response-content-encoding response [default=’()]
Scheme Procedure: response-content-language response [default=’()]
Scheme Procedure: response-content-length response [default=#f]
Scheme Procedure: response-content-location response [default=#f]
Scheme Procedure: response-content-md5 response [default=#f]
Scheme Procedure: response-content-range response [default=#f]
Scheme Procedure: response-content-type response [default=#f]
Scheme Procedure: response-date response [default=#f]
Scheme Procedure: response-etag response [default=#f]
Scheme Procedure: response-expires response [default=#f]
Scheme Procedure: response-last-modified response [default=#f]
Scheme Procedure: response-location response [default=#f]
Scheme Procedure: response-pragma response [default=’()]
Scheme Procedure: response-proxy-authenticate response [default=#f]
Scheme Procedure: response-retry-after response [default=#f]
Scheme Procedure: response-server response [default=#f]
Scheme Procedure: response-trailer response [default=’()]
Scheme Procedure: response-transfer-encoding response [default=’()]
Scheme Procedure: response-upgrade response [default=’()]
Scheme Procedure: response-vary response [default=’()]
Scheme Procedure: response-via response [default=’()]
Scheme Procedure: response-warning response [default=’()]
Scheme Procedure: response-www-authenticate response [default=#f]

Return the given response header, or default if none was present.

Scheme Procedure: text-content-type? type

Return #t if type, a symbol as returned by response-content-type, represents a textual type such as text/plain.