7.7
http11
Link to this document with
@other-doc['(lib "http11/scribblings/http11.scrbl")]
Link to this document with
@other-doc['(lib "http11/scribblings/http11.scrbl")]
1 HTTP Data Structures
Link to this section with
@secref["HTTP_Data_Structures"
#:doc '(lib "http11/scribblings/http11.scrbl")]
Link to this section with
@secref["HTTP_Data_Structures"
#:doc '(lib "http11/scribblings/http11.scrbl")]
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.
|
| #:transparent) |
| method : Method |
| path : String |
| version : Version |
The HTTP standard header line for a request.
|
| #: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).
|
| #:transparent) |
| version : Version |
| code : Integer |
| msg : String |
The HTTP status line returned by a server responding to a request.
|
| #: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 | | 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.
|
| #: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
Link to this section with
@secref["Invoking_An_HTTP_Request"
#:doc '(lib "http11/scribblings/http11.scrbl")]
Link to this section with
@secref["Invoking_An_HTTP_Request"
#:doc '(lib "http11/scribblings/http11.scrbl")]
The various HTTP actions or methods are defined as a data type.
Method
|
| : (U 'GET 'PUT 'POST 'DELETE 'HEAD 'CONNECT 'OPTIONS 'TRACE) |
A type enumeration of valid HTTP methods.
(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".
Utility method that returns "#t" if a successful (2XX) HTTP code was returned by the server.
Returns the HTTP status code value returned by the server.
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.
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
Link to this section with
@secref["Headers" #:doc '(lib "http11/scribblings/http11.scrbl")]
Link to this section with
@secref["Headers" #:doc '(lib "http11/scribblings/http11.scrbl")]
Headers are name value pairs defined in the HTTP 1.1 specification.
Header : (define-type Header (Pair String String))
|
A Header is typed defined as a pairof strings, the name and value.
Headers : (define-type Headers (Listof Header))
|
A list of Header. No effort is made enforce duplicate "Header" elements.
(Header? any) → Boolean
|
| any : Any |
Type predicate for the Header data type.
(make-header name value) → Header
|
| name : String |
| value : String |
Constructor for the Header type.
(add-header name value headers) → Headers
|
| name : String |
| value : String |
| headers : Headers |
Utility method to add a "Header".
(get-header name headers) → (Option Header)
|
| name : String |
| headers : Headers |
Find and return the first "Header" with the given "name".
(get-header-value name headers) → (Option String)
|
| name : String |
| headers : Header |
Similar to "get-header" except the found "Header"’s value is returned.
(host-header value) → Header
| | value : String |
|
(agent-header value) → Header
| | value : String |
|
(date-header value) → Header
| | value : String |
|
(content-type value) → Header
| | value : String |
|
(content-length value) → Header
| | value : String |
|
(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
Link to this section with
@secref["Encoding" #:doc '(lib "http11/scribblings/http11.scrbl")]
Link to this section with
@secref["Encoding" #:doc '(lib "http11/scribblings/http11.scrbl")]
4.1 URL Encoding / Decoding
Link to this section with
@secref["URL_Encoding___Decoding"
#:doc '(lib "http11/scribblings/http11.scrbl")]
Link to this section with
@secref["URL_Encoding___Decoding"
#:doc '(lib "http11/scribblings/http11.scrbl")]
(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.
(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).
| (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).