http11
1 HTTP Data Structures
Request  Line
Request  Header
Status  Line
Response  Header
HTTPConnection
HTTPPayload
2 Invoking An HTTP Request
Method
http-invoke
http-successful?
http-status-code
http-has-content?
http-close-connection
3 Headers
Header
Headers
Header?
make-header
add-header
get-header
get-header-value
host-header
agent-header
date-header
content-type
content-length
content-md5
4 Encoding
4.1 URL Encoding /   Decoding
url-encode-string
url-decode-string
url-decode-from-input-port
7.0

http11

Raymond Racine <[email protected]>

 (require http11) package: http11

1 HTTP Data Structures

Performs synchronous HTTP 1.1 invocations against a server. Full HTTP 1.1 support is not yet in place. The current incarnation supports gzip compression, SSL and chunk encoding.

struct

(struct RequestLine (method path version)
    #:transparent)
  method : Method
  path : String
  version : Version
The HTTP standard header line for a request.

struct

(struct RequestHeader (request headers)
    #:transparent)
  request : RequestLine
  headers : (Listof Header)
The HTTP protocol header for a requests consisting of the request line, e.g., "GET /index.html HTTP/1.1" and a set of HTTP headers (name value pairs).

struct

(struct StatusLine (version code msg)
    #:transparent)
  version : Version
  code : Integer
  msg : String
The HTTP status line returned by a server responding to a request.

struct

(struct ResponseHeader (status headers)
    #:transparent)
  status : StatusLine
  headers : (Listof Header)
The full HTTP response header from a server responding to a request. Consists of the status line and accompaning HTTP headers (name value pairs).

struct

(struct HTTPConnection (header out in real-in)
    #:transparent)
  header : ResponseHeader
  out : Output-Port
  in : Input-Port
  real-in : (Option Input-Port)
An HTTP connection. "header" HTTP server’s response status and headers. "out" is the output port which the client uses to write the request and any accompaning payload to the server. "in" is the overall effective input port to be used by the user application. "real-in" is the true low-level socket input port. The "in" port may be connected by one or more "pipe"s which, if present, perform one or more transforms on the data read from the raw socket port.

For example, if the HTTP request has Accept-Encoding: gzip in the request header the server response payload at the "real-in" socket port is gzip compressed. The client application reading reading from "in" port receives a gzip uncommpressed stream of data as this library automatically inserts unzipping pipe between the "real-in" port and the client used "HTTPConnection" "in" port.

Similarly for HTTP chunked encoding. This library automatically inserts a "pipe" between the "HTTPConnection" "real-in" port and the client application reads from the "de-chunked" "HTTPConnection" "in" port.

struct

(struct HTTPPayload (mime md5 length inport)
    #:transparent)
  mime : String
  md5 : (Option String)
  length : (Option Index)
  inport : Input-Port
Certain HTTP methods such as PUT and POST requests send payload data from the client. This data structure captures encapsulates a payload as an "Input-Port". If the optional MD5 hash for the payload is provided the hash value is sent to the server as part of the HTTP request.

If the "length" is provided the HTTP request sends this value as a Content-Length HTTP header. If the Content-Length is not provided the HTTPClient library uses Transfer-Encoding: chunked in the request.

Chunked encoding allows a client to send a payload of unknown size to the server (or from the server to the client) by buffering a streamed payload as chunks of data.

The mime type string specifies the format of the request payload, e.g., application/json or application/atom+xml.

2 Invoking An HTTP Request

The various HTTP actions or methods are defined as a data type.

value

Method

 : (U 'GET 'PUT 'POST 'DELETE 'HEAD 'CONNECT 'OPTIONS 'TRACE)
A type enumeration of valid HTTP methods.

procedure

(http-invoke method url headers payload)  HTTPConnection

  method : Method
  url : Uri
  headers : Headers
  payload : (Option Payload)
Invoke an HTTP request. If a "Payload" is provided it is sent to the server as part of the invocation with the appropriate headers implicitly added. The server response if available via the returned "HTTPConnection".

There are several utility functions to quickly check the server’s response. The full server response is available in "ResponseHeader" contained in the "HTTPConnection".

procedure

(http-successful? connection)  Boolean

  connection : HTTPConnection
Utility method that returns "#t" if a successful (2XX) HTTP code was returned by the server.

procedure

(http-status-code connection)  Integer

  connection : HTTPConnection
Returns the HTTP status code value returned by the server.

procedure

(http-has-content? connection)  Boolean

  connection : HTTPConnection
Did the server return any content (a payload) as part of the response. If "#t" this payload is available via the "HTTPConnection-in" accessor procedure.

procedure

(http-close-connection connection)  Void

  connection : HTTPConnection
Properly close the connection to the server. Currently a close must be explicitly performed regardless as to whether the server sent a response payload as part of the response.

3 Headers

Headers are name value pairs defined in the HTTP 1.1 specification.

value

Header : (define-type Header (Pair String String))

A Header is typed defined as a pairof strings, the name and value.

value

Headers : (define-type Headers (Listof Header))

A list of Header. No effort is made enforce duplicate "Header" elements.

procedure

(Header? any)  Boolean

  any : Any
Type predicate for the Header data type.

procedure

(make-header name value)  Header

  name : String
  value : String
Constructor for the Header type.

procedure

(add-header name value headers)  Headers

  name : String
  value : String
  headers : Headers
Utility method to add a "Header".

procedure

(get-header name headers)  (Option Header)

  name : String
  headers : Headers
Find and return the first "Header" with the given "name".

procedure

(get-header-value name headers)  (Option String)

  name : String
  headers : Header
Similar to "get-header" except the found "Header"’s value is returned.

procedure

(host-header value)  Header

  value : String

procedure

(agent-header value)  Header

  value : String

procedure

(date-header value)  Header

  value : String

procedure

(content-type value)  Header

  value : String

procedure

(content-length value)  Header

  value : String

procedure

(content-md5 value)  Header

  value : String
Utility procedures that construct common HTTP header values. Generally are not required as this library generally implicitly inserts these headers. Deprecated and will be removed.

4 Encoding

4.1 URL Encoding / Decoding

procedure

(url-encode-string str space-as-plus)  String

  str : String
  space-as-plus : Boolean
URL encode a string converting reserved characters as percent hex values. If space-as-plus is true spaces are encoded as + chars in lieu of encoding as a %20.

procedure

(url-decode-string str delim decode-plus?)  String

  str : String
  delim : (Option Char)
  decode-plus? : Boolean
URL decode the given string converting percent hex encoded values. If delim decode until the deliminator char otherwise decode until the entire string. If decode-plus? is true + chars decode as a   (a #\space).

procedure

(url-decode-from-input-port str    
  delim    
  decode-plus?)  String
  str : String
  delim : (Option Char)
  decode-plus? : Boolean
Reading chars from the input port URL decoding percent hex encoded values. If delim decode until the deliminator char is found or if not defined until eof-object?. If decode-plus? is true + chars decode as a   (a #\space).