http_header.pl -- Handling HTTP headers

The library library(http/http_header) provides primitives for parsing and composing HTTP headers. Its functionality is normally hidden by the other parts of the HTTP server and client libraries.

http_read_request(+FdIn:stream, -Request) is det

Read an HTTP request-header from FdIn and return the broken-down request fields as +Name(+Value) pairs in a list. Request is unified to end_of_file if FdIn is at the end of input.

http_read_reply_header(+FdIn, -Reply)

Read the HTTP reply header. Throws an exception if the current input does not contain a valid reply header.

http_reply(+Data, +Out:stream) is det

http_reply(+Data, +Out:stream, +HdrExtra) is det

http_reply(+Data, +Out:stream, +HdrExtra, -Code) is det

http_reply(+Data, +Out:stream, +HdrExtra, +Context, -Code) is det

http_reply(+Data, +Out:stream, +HdrExtra, +Context, +Request, -Code) is det

Compose a complete HTTP reply from the term Data using additional headers from HdrExtra to the output stream Out. ExtraHeader is a list of Field(Value). Data is one of:

html(HTML): HTML tokens as produced by html//1 from html_write.pl
file(+MimeType, +FileName): Reply content of FileName using MimeType
file(+MimeType, +FileName, +Range): Reply partial content of FileName with given MimeType
tmp_file(+MimeType, +FileName): Same as file, but do not include modification time
bytes(+MimeType, +Bytes): Send a sequence of Bytes with the indicated MimeType. Bytes is either a string of character codes 0..255 or list of integers in the range 0..255. Out-of-bound codes result in a representation error exception.
stream(+In, +Len): Reply content of stream.
cgi_stream(+In, +Len): Reply content of stream, which should start with an HTTP header, followed by a blank line. This is the typical output from a CGI script.
Status: HTTP status report as defined by http_status_reply/4.

Arguments:

`HdrExtra`	- provides additional reply-header fields, encoded as Name(Value). It can also contain a field `content_length(-Len)` to retrieve the value of the Content-length header that is replied.
`Code`	- is the numeric HTTP status code sent

To be done

- Complete documentation

http_reply_data(+Data, +Out, +HdrExtra, +Method, -Code) is semidet[private]

Fails if Data is not a defined reply-data format, but a status term. See http_reply/3 and http_status_reply/6.

Errors: - Various I/O errors.

http_status_reply(+Status, +Out, +HdrExtra, -Code) is det

http_status_reply(+Status, +Out, +HdrExtra, +Context, -Code) is det

http_status_reply(+Status, +Out, +HdrExtra, +Context, +Request, -Code) is det

Emit HTML non-200 status reports. Such requests are always sent as UTF-8 documents.

Status can be one of the following:

authorise(Method)

Challenge authorization. Method is one of

basic(Realm)
digest(Digest)

authorise(basic, Realm)

Same as authorise(basic(Realm)). Deprecated.

bad_request(ErrorTerm)

busy

created(Location)

forbidden(Url)

moved(To)

moved_temporary(To)

no_content

not_acceptable(WhyHtml)

not_found(Path)

method_not_allowed(Method, Path)

not_modified

resource_error(ErrorTerm)

see_other(To)

switching_protocols(Goal, Options)

server_error(ErrorTerm)

unavailable(WhyHtml)

status_page_hook(+Term, +Code, +Context, -HTMLTokens) is det[private]

Calls the following two hooks to generate an HTML page from a status reply.

http:status_page(Term, Context, HTML)
http:status_page(Status, Context, HTML)

http_join_headers(+Default, +Header, -Out)

Append headers from Default to Header if they are not already part of it.

http_update_encoding(+HeaderIn, -Encoding, -HeaderOut)

Allow for rewrite of the header, adjusting the encoding. We distinguish three options. If the user announces `text', we always use UTF-8 encoding. If the user announces charset=utf-8 we use UTF-8 and otherwise we use octet (raw) encoding. Alternatively we could dynamically choose for ASCII, ISO-Latin-1 or UTF-8.

mime_type_encoding(+MimeType, -Encoding) is semidet[private]

Encoding is the (default) character encoding for MimeType. Hooked by mime_type_encoding/2.

http:mime_type_encoding(+MimeType, -Encoding) is semidet[multifile]

Encoding is the (default) character encoding for MimeType. This is used for setting the encoding for HTTP replies after the user calls format('Content-type: <MIME type>~n'). This hook is called before mime_type_encoding/2. This default defines utf8 for JSON and Turtle derived application/ MIME types.

http_update_connection(+CGIHeader, +Request, -Connection, -Header)

Merge keep-alive information from Request and CGIHeader into Header.

connection(+Header, -Connection)[private]

Extract the desired connection from a header.

http_update_transfer(+Request, +CGIHeader, -Transfer, -Header)

Decide on the transfer encoding from the Request and the CGI header. The behaviour depends on the setting http:chunked_transfer. If never, even explitic requests are ignored. If on_request, chunked encoding is used if requested through the CGI header and allowed by the client. If if_possible, chunked encoding is used whenever the client allows for it, which is interpreted as the client supporting HTTP 1.1 or higher.

Chunked encoding is more space efficient and allows the client to start processing partial results. The drawback is that errors lead to incomplete pages instead of a nicely formatted complete page.

transfer(+Header, -Connection)[private]

Extract the desired connection from a header.

content_length_in_encoding(+Encoding, +In, -Bytes)[private]

Determine hom many bytes are required to represent the data from stream In using the given encoding. Fails if the data cannot be represented with the given encoding.

http_post_data(+Data, +Out:stream, +HdrExtra) is det

Send data on behalf on an HTTP POST request. This predicate is normally called by http_post/4 from http_client.pl to send the POST data to the server. Data is one of:

html(+Tokens) Result of html//1 from html_write.pl
xml(+Term) Post the result of xml_write/3 using the Mime-type text/xml
xml(+Type, +Term) Post the result of xml_write/3 using the given Mime-type and an empty option list to xml_write/3.
xml(+Type, +Term, +Options) Post the result of xml_write/3 using the given Mime-type and option list for xml_write/3.
file(+File) Send contents of a file. Mime-type is determined by file_mime_type/2.
file(+Type, +File) Send file with content of indicated mime-type.
memory_file(+Type, +Handle) Similar to file(+Type, +File), but using a memory file instead of a real file. See new_memory_file/1.
codes(+Codes) As codes(text/plain, Codes).
codes(+Type, +Codes) Send Codes using the indicated MIME-type.
bytes(+Type, +Bytes) Send Bytes using the indicated MIME-type. Bytes is either a string of character codes 0..255 or list of integers in the range 0..255. Out-of-bound codes result in a representation error exception.
atom(+Atom) As atom(text/plain, Atom).
atom(+Type, +Atom) Send Atom using the indicated MIME-type.
cgi_stream(+Stream, +Len) Read the input from Stream which, like CGI data starts with a partial HTTP header. The fields of this header are merged with the provided HdrExtra fields. The first Len characters of Stream are used.
form(+ListOfParameter) Send data of the MIME type application/x-www-form-urlencoded as produced by browsers issuing a POST request from an HTML form. ListOfParameter is a list of Name=Value or Name(Value).

form_data(+ListOfData) Send data of the MIME type multipart/form-data as produced by browsers issuing a POST request from an HTML form using enctype multipart/form-data. ListOfData is the same as for the List alternative described below. Below is an example. Repository, etc. are atoms providing the value, while the last argument provides a value from a file.

...,
http_post([ protocol(http),
            host(Host),
            port(Port),
            path(ActionPath)
          ],
          form_data([ repository = Repository,
                      dataFormat = DataFormat,
                      baseURI    = BaseURI,
                      verifyData = Verify,
                      data       = file(File)
                    ]),
          _Reply,
          []),
...,

List If the argument is a plain list, it is sent using the MIME type multipart/mixed and packed using mime_pack/3. See mime_pack/3 for details on the argument format.

post_header(+Data, +HeaderExtra)//[private]

Generate the POST header, emitting HeaderExtra, followed by the HTTP Content-length and Content-type fields.

http_reply_header(+Out:stream, +What, +HdrExtra) is det

Create a reply header using reply_header//3 and send it to Stream.

reply_header(+Data, +HdrExtra, -Code)// is det[private]

Grammar that realises the HTTP handler for sending Data. Data is a real data object as described with http_reply/2 or a not-200-ok HTTP status reply. The following status replies are defined.

moved(+URL, +HTMLTokens)
created(+URL, +HTMLTokens)
moved_temporary(+URL, +HTMLTokens)
see_other(+URL, +HTMLTokens)
status(+Status)
status(+Status, +HTMLTokens)
authorise(+Method, +Realm, +Tokens)
authorise(+Method, +Tokens)

See also: - http_status_reply/4 formulates the not-200-ok HTTP replies.

vstatus(+Status, -Code)// is det[private]

vstatus(+Status, -Code, +HdrExtra)// is det[private]

Emit the HTTP header for Status

status_number(?Status, ?Code)// is semidet[private]

Parse/generate the HTTP status numbers and map them to the proper name.

See also: - See the source code for supported status names and codes.

status_number(+Status:atom, -Code:nonneg) is det[private]

status_number(-Status:atom, +Code:nonneg) is det[private]

Relates a symbolic HTTP status names to their integer Code. Each code also needs a rule for status_comment//1.

throws: - type_error If Code is instantiated with something other than an integer.; - domain_error If Code is instantiated with an integer outside of the range [100-599] of defined HTTP status codes.

status_comment(+Code:atom)// is det[private]

Emit standard HTTP human-readable comment on the reply-status.

content_length(+Object, ?Len)// is det[private]

Emit the content-length field and (optionally) the content-range field.

Arguments:

Len

- Number of bytes specified

content_range(+Unit:atom, +From:int, +RangeEnd:int, +Size:int)// is det[private]

Emit the Content-Range header for partial content (206) replies.

header_field(-Name, -Value)// is det[private]

header_field(+Name, +Value) is det[private]

Process an HTTP request property. Request properties appear as a single line in an HTTP header.

read_field_value(-Codes)//[private]

Read a field eagerly upto the next whitespace

http_parse_header_value(+Field, +Value, -Prolog) is semidet

Translate Value in a meaningful Prolog term. Field denotes the HTTP request field for which we do the translation. Supported fields are:

content_length: Converted into an integer
cookie: Converted into a list with Name=Value by cookies//1.
set_cookie: Converted into a term set_cookie(Name, Value, Options). Options is a list consisting of Name=Value or a single atom (e.g., secure)
host: Converted to HostName:Port if applicable.
range: Converted into bytes(From, To), where From is an integer and To is either an integer or the atom end.
accept: Parsed to a list of media descriptions. Each media is a term media(Type, TypeParams, Quality, AcceptExts). The list is sorted according to preference.
content_disposition: Parsed into disposition(Name, Attributes), where Attributes is a list of Name=Value pairs.
content_type: Parsed into media(Type/SubType, Attributes), where Attributes is a list of Name=Value pairs.

known_field(?FieldName, ?AutoConvert)[private]

True if the value of FieldName is by default translated into a Prolog data structure.

field_to_prolog(+Field, +ValueCodes, -Prolog) is semidet[private]

Translate the value string into a sensible Prolog term. For known_fields(_,true), this must succeed. For maybe, we just return the atom if the translation fails.

parse_header_value(+Field, +ValueCodes, -Value) is semidet[private]

Parse the value text of an HTTP field into a meaningful Prolog representation.

value_options(+List, +Field)//[private]

Emit field parameters such as ; charset=UTF-8. There are three versions: a plain key (secure), token values and quoted string values. Seems we cannot deduce that from the actual value.

accept(-Media)// is semidet[private]

Parse an HTTP Accept: header

content_disposition(-Disposition)//[private]

Parse Content-Disposition value

parse_content_type(-Type)//[private]

Parse Content-Type value into a term

media(Type/SubType,
Parameters)

rank_specialised(+Type, +TypeParam, -Key) is det[private]

Although the specification linked above is unclear, it seems that more specialised types must be preferred over less specialized ones.

To be done: - Is there an official specification of this?

value_parameters(-Params:list) is det[private]

Accept (";" <parameter>)*, returning a list of Name=Value, where both Name and Value are atoms.

token(-Name)// is semidet[private]

Process an HTTP header token from the input.

quoted_string(-Text)// is semidet[private]

True if input starts with a quoted string representing Text.

header_fields(+Fields, ?ContentLength)// is det[private]

Process a sequence of [Name(Value), ...] attributes for the header. A term content_length(Len) is special. If instantiated it emits the header. If not it just unifies ContentLength with the argument of the content_length(Len) term. This allows for both sending and retrieving the content-length.

field_name(?PrologName)[private]

Convert between prolog_name and HttpName. Field names are, according to RFC 2616, considered tokens and covered by the following definition:

token          = 1*<any CHAR except CTLs or separators>
separators     = "(" | ")" | "<" | ">" | "@"
               | "," | ";" | ":" | "\" | <">
               | "/" | "[" | "]" | "?" | "="
               | "{" | "}" | SP | HT

separators(-CharCodes) is det[private]

CharCodes is a list of separators according to RFC2616

now//[private]

Current time using rfc_date//1.

rfc_date(+Time)// is det[private]

Write time according to RFC1123 specification as required by the RFC2616 HTTP protocol specs.

http_timestamp(+Time:timestamp, -Text:atom) is det

Generate a description of a Time in HTTP format (RFC1123)

request_uri_parts(+RequestURI, -Parts, ?Tail) is det[private]

Process the request-uri, producing the following parts:

path(-Path): Decode path information (always present)
search(-QueryParams): Present if there is a ?name=value&... part of the request uri. QueryParams is a Name=Value list.
fragment(-Fragment): Present if there is a #Fragment.

request_header(+In:stream, -Header:list) is det[private]

Read the remainder (after the request-uri) of the HTTP header and return it as a Name(Value) list.

cookies(-List)// is semidet[private]

Translate a cookie description into a list Name=Value.

cookie_option(-Option)// is semidet[private]

True if input represents a valid Cookie option. Officially, all cookie options use the syntax <name>=<value>, except for secure. M$ decided to extend this to include at least httponly (only the Gods know what it means).

Arguments:

Option

- Term of the form Name=Value

bug

- Incorrectly accepts options without = for M$ compatibility.

range(-Range)// is semidet[private]

Process the range header value. Range is currently defined as:

bytes(From, To): Where From is an integer and To is either an integer or the atom end.

reply(+In, -Reply:list)// is semidet[private]

Process the first line of an HTTP reply. After that, read the remainder of the header and parse it. After successful completion, Reply contains the following fields, followed by the fields produced by http_read_header/2.

http_version(Major-Minor)
status(Code, Status, Comment): Code is an integer between 100 and 599. Status is a Prolog internal name. Comment is the comment following the code as it appears in the reply's HTTP status line. @see status_number//2.

http_read_header(+Fd, -Header) is det

Read Name: Value lines from FD until an empty line is encountered. Field-name are converted to Prolog conventions (all lower, _ instead of -): Content-Type: text/html --> content_type(text/html)

http_parse_header(+Text:codes, -Header:list) is det

Header is a list of Name(Value)-terms representing the structure of the HTTP header in Text.

Errors: - domain_error(http_request_line, Line)

address//[private]

Emit the HTML for the server address on behalve of error and status messages (non-200 replies). Default is

SWI-Prolog httpd at <hostname>

The address can be modified by providing a definition for the multifile predicate http_address//0.

http:http_address// is det[multifile]

HTML-rule that emits the location of the HTTP server. This hook is called from address//0 to customise the server address. The server address is emitted on non-200-ok replies.

http:status_page(+Status, +Context, -HTMLTokens) is semidet[multifile]

Hook called by http_status_reply/4 and http_status_reply/5 that allows for emitting custom error pages for the following HTTP page types:

401 - authorise(AuthMethod)
403 - forbidden(URL)
404 - not_found(URL)
405 - method_not_allowed(Method,URL)

The hook is tried twice, first using the status term, e.g., not_found(URL) and than with the code, e.g. 404. The second call is deprecated and only exists for compatibility.

Arguments:

`Context`	- is the 4th argument of http_status_reply/5, which is invoked after raising an exception of the format `http_reply(Status, HeaderExtra, Context)`. The default context is `[]` (the empty list).
`HTMLTokens`	- is a list of tokens as produced by html//1. It is passed to print_html/2.

http_reply(+Data, +Out:stream) is det

http_reply(+Data, +Out:stream, +HdrExtra) is det

http_reply(+Data, +Out:stream, +HdrExtra, -Code) is det

http_reply(+Data, +Out:stream, +HdrExtra, +Context, -Code) is det

http_reply(+Data, +Out:stream, +HdrExtra, +Context, +Request, -Code) is det

Compose a complete HTTP reply from the term Data using additional headers from HdrExtra to the output stream Out. ExtraHeader is a list of Field(Value). Data is one of:

html(HTML): HTML tokens as produced by html//1 from html_write.pl
file(+MimeType, +FileName): Reply content of FileName using MimeType
file(+MimeType, +FileName, +Range): Reply partial content of FileName with given MimeType
tmp_file(+MimeType, +FileName): Same as file, but do not include modification time
bytes(+MimeType, +Bytes): Send a sequence of Bytes with the indicated MimeType. Bytes is either a string of character codes 0..255 or list of integers in the range 0..255. Out-of-bound codes result in a representation error exception.
stream(+In, +Len): Reply content of stream.
cgi_stream(+In, +Len): Reply content of stream, which should start with an HTTP header, followed by a blank line. This is the typical output from a CGI script.
Status: HTTP status report as defined by http_status_reply/4.

Arguments:

`HdrExtra`	- provides additional reply-header fields, encoded as Name(Value). It can also contain a field `content_length(-Len)` to retrieve the value of the Content-length header that is replied.
`Code`	- is the numeric HTTP status code sent

To be done

- Complete documentation

http_reply(+Data, +Out:stream) is det

http_reply(+Data, +Out:stream, +HdrExtra) is det

http_reply(+Data, +Out:stream, +HdrExtra, -Code) is det

http_reply(+Data, +Out:stream, +HdrExtra, +Context, -Code) is det

http_reply(+Data, +Out:stream, +HdrExtra, +Context, +Request, -Code) is det

Compose a complete HTTP reply from the term Data using additional headers from HdrExtra to the output stream Out. ExtraHeader is a list of Field(Value). Data is one of:

html(HTML): HTML tokens as produced by html//1 from html_write.pl
file(+MimeType, +FileName): Reply content of FileName using MimeType
file(+MimeType, +FileName, +Range): Reply partial content of FileName with given MimeType
tmp_file(+MimeType, +FileName): Same as file, but do not include modification time
bytes(+MimeType, +Bytes): Send a sequence of Bytes with the indicated MimeType. Bytes is either a string of character codes 0..255 or list of integers in the range 0..255. Out-of-bound codes result in a representation error exception.
stream(+In, +Len): Reply content of stream.
cgi_stream(+In, +Len): Reply content of stream, which should start with an HTTP header, followed by a blank line. This is the typical output from a CGI script.
Status: HTTP status report as defined by http_status_reply/4.

Arguments:

`HdrExtra`	- provides additional reply-header fields, encoded as Name(Value). It can also contain a field `content_length(-Len)` to retrieve the value of the Content-length header that is replied.
`Code`	- is the numeric HTTP status code sent

To be done

- Complete documentation

http_reply(+Data, +Out:stream) is det

http_reply(+Data, +Out:stream, +HdrExtra) is det

http_reply(+Data, +Out:stream, +HdrExtra, -Code) is det

http_reply(+Data, +Out:stream, +HdrExtra, +Context, -Code) is det

http_reply(+Data, +Out:stream, +HdrExtra, +Context, +Request, -Code) is det

Compose a complete HTTP reply from the term Data using additional headers from HdrExtra to the output stream Out. ExtraHeader is a list of Field(Value). Data is one of:

html(HTML): HTML tokens as produced by html//1 from html_write.pl
file(+MimeType, +FileName): Reply content of FileName using MimeType
file(+MimeType, +FileName, +Range): Reply partial content of FileName with given MimeType
tmp_file(+MimeType, +FileName): Same as file, but do not include modification time
bytes(+MimeType, +Bytes): Send a sequence of Bytes with the indicated MimeType. Bytes is either a string of character codes 0..255 or list of integers in the range 0..255. Out-of-bound codes result in a representation error exception.
stream(+In, +Len): Reply content of stream.
cgi_stream(+In, +Len): Reply content of stream, which should start with an HTTP header, followed by a blank line. This is the typical output from a CGI script.
Status: HTTP status report as defined by http_status_reply/4.

Arguments:

`HdrExtra`	- provides additional reply-header fields, encoded as Name(Value). It can also contain a field `content_length(-Len)` to retrieve the value of the Content-length header that is replied.
`Code`	- is the numeric HTTP status code sent

To be done

- Complete documentation

http_reply(+Data, +Out:stream) is det

http_reply(+Data, +Out:stream, +HdrExtra) is det

http_reply(+Data, +Out:stream, +HdrExtra, -Code) is det

http_reply(+Data, +Out:stream, +HdrExtra, +Context, -Code) is det

http_reply(+Data, +Out:stream, +HdrExtra, +Context, +Request, -Code) is det

Compose a complete HTTP reply from the term Data using additional headers from HdrExtra to the output stream Out. ExtraHeader is a list of Field(Value). Data is one of:

html(HTML): HTML tokens as produced by html//1 from html_write.pl
file(+MimeType, +FileName): Reply content of FileName using MimeType
file(+MimeType, +FileName, +Range): Reply partial content of FileName with given MimeType
tmp_file(+MimeType, +FileName): Same as file, but do not include modification time
bytes(+MimeType, +Bytes): Send a sequence of Bytes with the indicated MimeType. Bytes is either a string of character codes 0..255 or list of integers in the range 0..255. Out-of-bound codes result in a representation error exception.
stream(+In, +Len): Reply content of stream.
cgi_stream(+In, +Len): Reply content of stream, which should start with an HTTP header, followed by a blank line. This is the typical output from a CGI script.
Status: HTTP status report as defined by http_status_reply/4.

Arguments:

`HdrExtra`	- provides additional reply-header fields, encoded as Name(Value). It can also contain a field `content_length(-Len)` to retrieve the value of the Content-length header that is replied.
`Code`	- is the numeric HTTP status code sent

To be done

- Complete documentation

http_status_reply(+Status, +Out, +HdrExtra, -Code) is det

http_status_reply(+Status, +Out, +HdrExtra, +Context, -Code) is det

http_status_reply(+Status, +Out, +HdrExtra, +Context, +Request, -Code) is det