On this page:
request
8.12

3 Requests🔗ℹ

struct

(struct request (method url header data))

  method : method/c
  url : ok-http-url?
  header : (listof header-field/c)
  data : (or/c #f bytes? (-> output-port? any))

procedure

(request method url [header data])  request?

  method : method/c
  url : (or/c string? ok-http-url?)
  header : (listof in-header-field/c) = null
  data : (or/c #f bytes? (-> output-port? any)) = #f
Represents an HTTP request. The constructor accepts a wider range of inputs and converts them to acceptable field values as described below.

The method field indicates the request method. Only the methods listed in the contract above are currently allowed.

The url field contains the request target. It must be given in absolute form (see the notes below about checks and conversions performed by the constructor).

The header field contains the request header as a list of header fields. A header field may be given in either of the following forms:
  • a string or byte string containing both the field name and value — for example, "User-Agent: racket-http123/0.1"

  • a list (list key value) for example, '(accept-encoding "gzip, deflate") or '(#"accept-encoding" #"gzip, deflate")

The data field contains the request message body. The data field must be one of the following forms:
  • If data is #f, the request has no body.

  • If data is a byte string, it is sent as the message body (and when using HTTP/1.1, a Content-Length header field will be added automatically).

  • If data is a procedure, it is called with an output port to incrementally produce the message body (and when using HTTP/1.1, a Transfer-Encoding: chunked header field will be added automatically). When the output port is closed, the message body is complete; the output port is also closed automatically when the call to data returns. If the call to data raises an exception, the request is canceled (but the server may have already started processing it).

The constructor checks and converts its arguments according to the following rules:
  • If url is a string, it is converted to a URL struct (url?). The URL must satisfy the constraints of ok-http-url?; otherwise, an error is raised.

  • The header is normalized to a list of field entries, where each entry has the form (list key-bytes value-bytes), where key-bytes is a valid header field name with no uppercase letters, and value-bytes is a valid header field value. If a field is not well-formed, then an error is raised.

  • If header contains one of the following header fields, an exception is raised (these header fields are reserved for control by the user agent): Host, Content-Length, Connection, Leep-Alive, Upgrade, Transfer-Encoding, TE, Trailer.

Example:
> (request 'HEAD "https://blog.racket-lang.org/"
           '("If-Modified-Since: Sun, 14 Feb 2021 01:00:00 GMT"))

(request

 'HEAD

 (url "https" #f "blog.racket-lang.org" #f #t (list (path/param "" '())) '() #f)

 '((#"if-modified-since" #"Sun, 14 Feb 2021 01:00:00 GMT"))

 #f)