On this page:
http-conn?
http-conn-live?
http-conn-liveable?
http-conn
http-conn-open!
http-conn-open
http-conn-close!
http-conn-abandon!
http-conn-enliven!
http-conn-send!
http-conn-recv!
http-conn-sendrecv!
http-sendrecv
http-conn-CONNECT-tunnel
data-procedure/  c
base-ssl?/  c
base-ssl?-tnl/  c
1.1 Troubleshooting and Tips
1.1.1 How do I send properly formatted POST form requests?

1 HTTP Client

The net/http-client library provides utilities to use the HTTP protocol.

procedure

(http-conn? x)  boolean?

  x : any/c
Identifies an HTTP connection.

procedure

(http-conn-live? x)  boolean?

  x : any/c
Identifies an HTTP connection that is "live", i.e. one that is still connected to the server.

procedure

(http-conn-liveable? x)  boolean?

  x : any/c
Identifies an HTTP connection that can be made "live", i.e. one for which http-conn-send! is valid. Either the HTTP connection is already http-conn-live?, or it can auto-reconnect.

procedure

(http-conn)  http-conn?

Returns a fresh HTTP connection.

procedure

(http-conn-open! hc    
  host    
  [#:ssl? ssl?    
  #:port port    
  #:auto-reconnect? auto-reconnect?])  void?
  hc : http-conn?
  host : (or/c bytes? string?)
  ssl? : base-ssl?-tnl/c = #f
  port : (between/c 1 65535) = (if ssl? 443 80)
  auto-reconnect? : boolean? = #f
Uses hc to connect to host on port port using SSL if ssl? is not #f (using ssl? as an argument to ssl-connect to, for example, check certificates.) If auto-reconnect? is #t, then the HTTP connection is going to try to auto-reconnect for subsequent requests. I.e., if the connection is closed when performing http-conn-send! or http-conn-recv!, then http-conn-enliven! is going to be called on it.

If hc is live, the connection is closed.

procedure

(http-conn-open host    
  [#:ssl? ssl?    
  #:port port    
  #:auto-reconnect? auto-reconnect?])  http-conn?
  host : (or/c bytes? string?)
  ssl? : base-ssl?-tnl/c = #f
  port : (between/c 1 65535) = (if ssl? 443 80)
  auto-reconnect? : boolean? = #f
Calls http-conn-open! with a fresh connection, which is returned.

procedure

(http-conn-close! hc)  void?

  hc : http-conn?
Closes hc if it is live.

procedure

(http-conn-abandon! hc)  void?

  hc : http-conn?
Closes the output side of hc, if it is live.

procedure

(http-conn-enliven! hc)  void?

  hc : http-conn?
Reconnects hc to the server, if it is not live but it is configured to auto-reconnect.

procedure

(http-conn-send! hc    
  uri    
  [#:version version    
  #:method method    
  #:close? close?    
  #:headers headers    
  #:content-decode decodes    
  #:data data])  void?
  hc : http-conn-liveable?
  uri : (or/c bytes? string?)
  version : (or/c bytes? string?) = #"1.1"
  method : (or/c bytes? string? symbol?) = #"GET"
  close? : boolean? = #f
  headers : (listof (or/c bytes? string?)) = empty
  decodes : (listof symbol?) = '(gzip deflate)
  data : (or/c false/c bytes? string? data-procedure/c) = #f
Sends an HTTP request to hc to the URI uri using HTTP version version, the method method, and the additional headers given in headers and the additional data data. If method is #"HEAD" (or "HEAD" or 'HEAD), provide the same method when calling http-conn-recv! to avoid attempting to receive content.

If data is a procedure, it will be called once with a procedure of one argument, which is a string or byte string to be written to the request body using chunked transfer encoding.

If headers does not contain an Accept-Encoding header, then a header indicating that encodings from decodes are accepted is automatically added.

If close? is #t and headers does not contain a Connection header, then a Connection: close header will be added (currently, 'gzip and 'deflate are supported).

This function does not support requests that expect 100 (Continue) responses.

Changed in version 7.6.0.9 of package base: Added support for 'deflate decoding.

procedure

(http-conn-recv! hc 
  [#:content-decode decodes 
  #:method method 
  #:close? close?]) 
  
bytes? (listof bytes?) input-port?
  hc : http-conn-liveable?
  decodes : (listof symbol?) = '(gzip deflate)
  method : (or/c bytes? string? symbol?) = #"GET"
  close? : boolean? = #f
Parses an HTTP response from hc for the method method while decoding the encodings listed in decodes.

Returns the status line, a list of headers, and an port which contains the contents of the response. The port’s content must be consumed before the connection is used further.

If close? is #t, then the connection will be closed following the response parsing. If close? is #f, then the connection is only closed if the server instructs the client to do so.

Changed in version 6.1.1.6 of package base: Added the #:method argument.
Changed in version 7.6.0.9: Added support for 'deflate decoding.

procedure

(http-conn-sendrecv! hc 
  uri 
  [#:version version 
  #:method method 
  #:headers headers 
  #:data data 
  #:content-decode decodes 
  #:close? close?]) 
  
bytes? (listof bytes?) input-port?
  hc : http-conn-liveable?
  uri : (or/c bytes? string?)
  version : (or/c bytes? string?) = #"1.1"
  method : (or/c bytes? string? symbol?) = #"GET"
  headers : (listof (or/c bytes? string?)) = empty
  data : (or/c false/c bytes? string? data-procedure/c) = #f
  decodes : (listof symbol?) = '(gzip deflate)
  close? : boolean? = #f
Calls http-conn-send! and http-conn-recv! in sequence.

Changed in version 7.6.0.9 of package base: Added support for 'deflate decoding.

procedure

(http-sendrecv host 
  uri 
  [#:ssl? ssl? 
  #:port port 
  #:version version 
  #:method method 
  #:headers headers 
  #:data data 
  #:content-decode decodes]) 
  
bytes? (listof bytes?) input-port?
  host : (or/c bytes? string?)
  uri : (or/c bytes? string?)
  ssl? : base-ssl?-tnl/c = #f
  port : (between/c 1 65535) = (if ssl? 443 80)
  version : (or/c bytes? string?) = #"1.1"
  method : (or/c bytes? string? symbol?) = #"GET"
  headers : (listof (or/c bytes? string?)) = empty
  data : (or/c false/c bytes? string? data-procedure/c) = #f
  decodes : (listof symbol?) = '(gzip deflate)
Calls http-conn-send! and http-conn-recv! in sequence on a fresh HTTP connection produced by http-conn-open.

The HTTP connection is not returned, so it is always closed after one response, which is why there is no #:closed? argument like http-conn-recv!.

Changed in version 7.6.0.9 of package base: Added support for 'deflate decoding.

procedure

(http-conn-CONNECT-tunnel proxy-host    
  proxy-port    
  target-host    
  target-port    
  [#:ssl? ssl?])  
base-ssl?/c
input-port?
output-port?
(-> port? void?)
  proxy-host : (or/c bytes? string?)
  proxy-port : (between/c 1 65535)
  target-host : (or/c bytes? string?)
  target-port : (between/c 1 65535)
  ssl? : base-ssl?/c = #f
Creates an HTTP connection to proxy-host (on port proxy-port) and invokes the HTTP “CONNECT” method to provide a tunnel to target-host (on port target-port).

The SSL context or symbol, if any, provided in ssl? is applied to the gateway ports using ports->ssl-ports (or ports->win32-ssl-ports).

The function returns four values:
  • If ssl? was #f then #f. Otherwise an ssl-client-context? that has been negotiated with the target.

    If ssl? was a protocol symbol, then a new ssl-client-context? is created, otherwise the current value of ssl? is used

  • An input-port? from the tunnelled service

  • An output-port? to the tunnelled service

  • An abandon function, which when applied either returned port, will abandon it, in a manner similar to tcp-abandon-port

The SSL context or symbol, if any, provided in ssl? is applied to the gateway ports using ports->ssl-ports (or ports->win32-ssl-ports) and the negotiated client context is returned

Contract for a procedure that accepts a procedure of one argument, which is a string or byte string: (-> (-> (or/c bytes? string?) void?) any).

Base contract for the definition of the SSL context (passed in ssl?) of an http-conn-CONNECT-tunnel:

(or/c boolean? ssl-client-context? symbol?).

If ssl? is not #f then ssl? is used as an argument to ssl-connect to, for example, check certificates.

Contract for a base-ssl?/c that might have been applied to a tunnel. It is either a base-ssl?/c, or a base-ssl?/c consed onto a list of an input-port?, output-port?, and an abandon function (e.g. tcp-abandon-port):

(or/c base-ssl?/c (list/c base-ssl?/c input-port? output-port? (-> port? void?)))

1.1 Troubleshooting and Tips

1.1.1 How do I send properly formatted POST form requests?

You should send a Content-Type header with the value application/x-www-form-urlencoded and send the data formatted by net/uri-codec’s form-urlencoded-encode function. For example,

(http-conn-send!
   hc "/login"
   #:method "POST"
   #:data
   (alist->form-urlencoded
    (list (cons 'username "Ryu")
          (cons 'password "Sheng Long")))
   #:headers (list "Content-Type: application/x-www-form-urlencoded"))