http11

8.16.0.1

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.

(require http11/header)

package: http11

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🔗ℹ

(require url/url/encode)

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).

1	HTTP Data Structures
2	Invoking An HTTP Request
3	Headers
4	Encoding