alice
library
manual.

Alice Project

The Http structure


________ Synopsis ____________________________________________________

    signature HTTP
    structure Http : HTTP

This structure serves to represent and analyze requests and responses conforming to the HTTP protocol. The current implementation supports a subset of HTTP Version 1.1 as specified by RFC 2616.

See also: Url, HttpClient, HttpServer, Socket


________ Import ______________________________________________________

    import structure Http from "x-alice:/lib/system/Http"
    import signature HTTP from "x-alice:/lib/system/HTTP-sig"

________ Interface ___________________________________________________

    signature HTTP =
    sig
	structure StringMap : IMP_MAP where type key = string

	type request =
	     {method : string, uri : Url.t, protocol : string,
	      headers : string StringMap.t, body : string}
	type response =
	     {protocol : string, statusCode : int, reasonPhrase : string,
	      headers : string StringMap.t, body : string}
	type simple_response =
	     {statusCode : int, contentType : string, body : string}

	datatype word =
	    TOKEN of string
	  | SEPARATOR of char
	  | COMMENT of string
	  | QUOTED_STRING of string

	exception Closed
	exception Format

	val readRequest : Socket.socket -> request
	val readResponse : Socket.socket -> response

	val writeRequest : Socket.socket * request -> unit
	val writeResponse : Socket.socket * response -> unit

	val reasonPhrase : int -> string
	val makeResponse : simple_response -> response

	val parseFieldValue : string -> word list
    end

________ Description _________________________________________________

structure StringMap : IMP_MAP where type key = string

A structure used for representing HTTP headers, which are mappings from strings (names) to strings (values). Names are case-insensitive and are therefore always translated to lower case.

type request = {method : string, uri : Url.t, protocol : string, headers : string StringMap.t, body : string}

The type of HTTP requests. Represents a request with method for uri using protocol version protocol. The type of the body document, if non-empty, must be given as a header in headers.

type response = {protocol : string, statusCode : int, reasonPhrase : string, headers : string StringMap.t, body : string}

The type of HTTP responses. Represents a response with statusCode and reasonPhrase, using protocol version protocol. The type of the body document, if non-empty, must be given as a header in headers.

type simple_response = {statusCode : int, contentType : string, body : string}

The type of simplified HTTP responses. Represents a response with statusCode, carrying document body of type contentType. Can be extended to a full response using the function makeResponse.

datatype word = TOKEN of string | SEPARATOR of char | COMMENT of string | QUOTED_STRING of string

The type of a word in a header field. The meaning of the constructors is defined in RFC 2616. Comments are stripped of the surrounding parentheses. Quoted strings are stripped of the quotes. Escaped characters in the outermost comment level and in quoted strings are processed, that is, replaced by the literal character they represent.

exception Closed

indicates that the socket connection was closed while the functions in this structure attempted to read an HTTP request or response. This exception is never raised directly but only appears as the cause argument to IO.Io exceptions raised by the functions below.

exception Format

indicates that the data received while attempting to read an HTTP request or response from a socket did not conform to the HTTP protocol, Version 1.1.

readRequest sock

attempts to read an HTTP request from sock, parses it, and returns it. Any consecutive white space in header field values is translated to a single space. Raises IO.Io if an error occurs. In particular, a cause field with exception Closed indicates that the connection was closed, and Format indicates that the response was malformed.

readResponse sock

attempts to read an HTTP response from sock, parses it, and returns it. Any consecutive white space in header field values is translated to a single space. Raises IO.Io if an error occurs. In particular, a cause field with exception Closed indicates that the connection was closed, and Format indicates that the response was malformed.

writeRequest (sock, request)

formats request according to the HTTP protocol, Version 1.1, and writes it to sock. Raises IO.Io if an error occurs.

writeResponse (sock, response)

formats response according to the HTTP protocol, Version 1.1, and writes it to sock. Raises IO.Io if an error occurs.

reasonPhrase code

returns a reason phrase describing status code. Implemented to use the reason phrases given in RFC 2616, or "Unknown" if code does not correspond to a status code defined in RFC 2616.

makeResponse simpleResponse

returns a full response corresponding to the response specified by simpleResponse. The headers only specify Content-Type and Content-Length, protocol is fixed to HTTP/1.1, and reasonPhrase is generated using function reasonPhrase.

parseFieldValue s

parses s into a list of words as defined by RFC 2616. Raises Format if the s is not a well-formed header field value. Any linear white space in s must already have been translated to a single space.


________ Examples ____________________________________________________

Examples regarding the use of this structure can be found in HttpClient and HttpServer.



last modified 2007/Mar/30 17:10