It is unclear yet whether this document will be submitted to the W3C, either to the XQuery WG or as Community Group. For the time being it lives under the EXQuery project.
This specification defines a set of XPath 3.0 extension functions to extract information from HTTP Requests. It has been designed to be compatible with XQuery 3.0 and XSLT 3.0, as well as any other XPath 3.0 superset.

Introduction

XPath as part of XQuery and XSLT processors is now frequently provided as part of a more complete processing platform, which typically incorporates Web serving capabilities.

XQuery and XSLT have long been recognised as good languages for producing XHTML and HTML from complex data queries, however they are almost completely ignorant of the Web. There are no native mechanisms in XQuery or XSLT to extract information from HTTP Requests when XQuery or XSLT modules are invoked from a Web Server (acting as a server-side scripting language for processing Web requests).

The HTTP Request module provides a set of functions for extracting information from a HTTP Request. The HTTP Request Module aligns with HTTP 1.1 (see [[!HTTP11]]).

Namespaces and Prefixes

The functions and elements discussed in this document are contained in a single namespace (see [[!XML-NAMES]]) and referenced using an xs:QName. The namespace prefix used in this document for functions and elements are solely related to the HTTP Request module is request.

This document uses the prefix reqerr to represent the namespace URI http://exquery.org/ns/request/error, which is the namespace for all HTTP Request Module error codes and messages. This namespace prefix is not predeclared and its use in this document is not normative.

The namespace prefix used for the functions, datatypes and errors can vary, as long as the prefix is bound to the correct URI.

The URIs of the namespaces and the default prefixes associated with them are:

The namespace URI associated with the reqerr prefix is not expected to change from one version of this document to another. The contents of this namespace may be extended to allow additional errors to be returned.

Accessing the HTTP Context

Each function in this module operates on the HTTP Request of a HTTP Context. The HTTP Reqyest is provided to each function by passing another function which returns a model of the context.

By default this module provides a function to access the HTTP Request Context, which returns an XML Document whoose root element is http:request.

The reasons for using function passing to access the HTTP Context include:

  1. Enable easy mocking of the HTTP Context for testing.
  2. Easier optimisation by substitution of the function with an implentation specific version which does not serialize to an XML data model until absolutely nessecary.
  3. Enable the functions of this module to be used with other http:request XML documents, for examples as those used by the EXPath HTTP Client Module.

Functions

Herein where we refer to the HTTP Request, we refer to the HTTP Reqyest that invoked the processing of the module calling the HTTP Request Module function(s).

HTTP Context Access Functions

request:http

request:http() as document-node(element(http:request))

Summary: This function returns an XML model of the HTTP Request of the HTTP Context.

Error Conditions: If there is no HTTP Context this function raises an error with the error code reqerr:REDY0001.

Notes: It is expected that an implementation will heavily optimise the use of this function. Suggested optimisations are to at least:

  1. Only serialize the result of the function to XML when absoluteley required. That is to say, avoid serializing for each Request Module function call that uses this function.

General Functions

request:method

request:method($request-context as function() as document-node(element(http:request))) as xs:string

Summary: This function returns the Method of the HTTP Request. The returned value SHOULD be a valid HTTP 1.1 Method, which is expressed in upper-case, and is one of the constants "OPTIONS", "GET", "POST", "PUT", "DELETE", "TRACE" or "CONNECT". Implementations are free to return other method names as long as the protocol builds on top of HTTP 1.1.

URI Functions

request:scheme

request:scheme($request-context as function() as document-node(element(http:request))) as xs:string

Summary: This function returns the Scheme component of the URI of the HTTP Request.

request:hostname

request:hostname() as xs:string

Summary: This function returns the Hostname fragment of the Authority component of the URI of the HTTP Request.

request:port

request:port() as xs:integer

Summary: This function returns the Port fragment of the Authority component of the URI of the HTTP Request. If the port is not explicitly specified in the URI, then the default port for the HTTP Scheme is returned (i.e. 21 for FTP, 80 for HTTP and 443 for HTTPS).

request:path

request:path() as xs:string

Summary: This function returns the Path component of the URI of the HTTP Request.

request:query

request:query() as xs:string?

Summary: This function returns the Query Component of the HTTP Request URI, if there is no query component then an empty sequence is returned.

request:uri

request:uri() as xs:anyURI

Summary: This function returns the URI of the HTTP Request.

Connection Functions

Functions that deal with the TCP/IP Connection of the HTTP Request.

request:address

request:address() as xs:string

Summary: This functions returns the IP address of the server.

request:remote-hostname

request:remote-hostname() as xs:string

Summary: This functions returns the fully qualified hostname of the client or the last proxy that sent the HTTP Request. If the name of the remote host cannot be established, or an implementation chooses not to establish the remote hostname, this method behaves as request:remote-address(), and returns the IP address.

request:remote-address

request:remote-address() as xs:string

Summary: This functions returns the IP address of the client or the last proxy that sent the HTTP Request.

request:remote-port

request:remote-port() as xs:integer

Summary: This functions returns the TCP port of the client socket or the last proxy that sent the HTTP Request.

HTTP Parameter Functions

A HTTP Parameter is defined as either a fragment of the query portion of the HTTP Request URI or the parameter from a submitted HTML Form where the HTTP Request has the Internet Media Type "application/x-www-form-urlencoded".

request:parameter-names

request:parameter-names() as xs:string*

Summary: This function returns a Sequence containing the names of Parameters available from the HTTP Request.

request:parameter

request:parameter($parameter-name as xs:string) as xs:string*

Summary: This function returns a Sequence containing the values of the named HTTP Parameter in the HTTP Request. If there is no such parameter in the HTTP Request, then an empty sequence is returned. 

request:parameter($parameter-name as xs:string, $default as xs:string*) as xs:string*

Summary: This function returns a Sequence containing the values of the named HTTP Parameter in the HTTP Request. If there is no such parameter in the HTTP Request, then the value specified in $default is returned instead.

HTTP Header Functions

request:header-names

request:header-names() as xs:string+

Summary: This function returns a Sequence containing the names of the HTTP Headers available from the HTTP Request.

request:header

request:header($header-name as xs:string) as xs:string?

Summary: This function returns the value of the named HTTP Header in the HTTP Request. If there is no such header, then an empty sequence is returned. 

request:header($header-name as xs:string, $default as xs:string) as xs:string

Summary: This function returns the value of the named HTTP Header in the HTTP Request. If there is no such header, then the value specified in $default is returned instead.

Cookie Functions

request:cookie-names

request:cookie-names() as xs:string*

Summary: This function returns a Sequence containing the names of the Cookies in the HTTP Headers available from the HTTP Request.

request:cookie

request:cookie($cookie-name as xs:string) as xs:string?

Summary: This function returns the value of the named Cookie in the HTTP Request. If there is no such cookie, then an empty sequence is returned. 

request:cookie($cookie-name as xs:string, $default as xs:string) as xs:string

Summary: This function returns the value of the named Cookie in the HTTP Request. If there is no such cookie, then the value specified in $default is returned instead.

Request Body Functions

TODO

Resources for Implementers

If you plan to implement the HTTP Request Module, there is already a set of common abstraction libraries written in Java which should significantly reduce the ammount of effort involved and avoid re-inventing more wheels. You need just implement a few interfaces and adapters. For more information see the TODO

Acknowledgements

Many thanks to: