Functions for accessing HTTP requests

The following functions are useful for accessing
properties of a HTTP request, in a Kawa program that is
run either as a servlet or a CGI script. These functions
can be used from plain Scheme, from KRL (whether
in BRL-compatible mode or not), and from XQuery.

The examples below assume the request http://example.com:8080/myapp/foo/bar?val1=xyz&val2=abc, where myapp is the application context.
We also assume that this is handled by a script foo/+default+.

The file testsuite/webtest/info/+default+ in the Kawa source distribution
calls most of these functions.
You can try it as described in Self-configuring page scripts.

Request URL components

Procedure: request-URI

Returns the URI of the request, as a value of type URI.
This excludes the server specification,
but includes the query string.
(It is the combination of CGI variables SCRIPT_NAME,
PATH_INFO, and QUERY_STRING.
Using servlets terminology, it is the combination of
Context Path, Servlet Path, PathInfo, and Query String.)

(request-URI) ⇒ "/myapp/foo/bar?val1=xyz&val2=abc"

Procedure: request-path

Returns the URI of the request, as a value of type URI.
This excludes the server specification and the query string.
Equivalent to (path-file (request-URI)).
(It is the combination of CGI variables SCRIPT_NAME, and
PATH_INFO.
Same as the concatenation of (request-context-path),
(request-script-path), and (request-local-path).
Using servlets terminology, it is the combination of
Context Path, Servlet Path, and PathInfo.)

(request-path) ⇒ "/myapp/foo/bar"

Procedure: request-uri

This function is deprecated, because of possible confusion
with request-URI. Use request-path instead.

Procedure: request-url

Returns the complete URL of the request, except the query string.
The result is a java.lang.StringBuffer.

(request-url) ⇒ "http://example.com:8080/myapp/foo/bar"

Procedure: request-context-path

Returns the context path, relative to the server root.
This is an initial substring of the (request-path).
Similar to the Context Path of a servlet request,
except that it ends with a "/".

(request-context-path) ⇒ "/myapp/"

Procedure: request-script-path

Returns the path of the script, relative to the context.
This is either an empty string, or a string that ends with "/",
but does not start with one. (The reason for this is to produce URIs
that work better with operations like resolve-uri.)
This is conceptually similar to request-servlet-path,
though not always the same, and the "/" conventions differ.

(request-script-path) ⇒ "foo/"

Procedure: request-local-path

Returns the remainder of the request-path,
relative to the request-script-path.

(request-local-path) ⇒ "bar"

Procedure: request-query-string

Returns the query string from an HTTP request. The query string is
the part of the request URL after a question mark.
Returns false if there was no query string.
Corresponds to the CGI variable QUERY_STRING.

(request-query-string) ⇒ "val1=xyz&val2=abc"

Request parameters

Request parameters are used for data returned from forms,
and for other uses.
They may be encoded in the query string or in the request body.

Procedure: request-parametername [default]

If there is a parameter with the given name (a string),
return the (first) corresponding value, as a string.
Otherwise, return the default value,
or #!null if there is no default.

Request a map of all the parameters.
This is a map from strings to a sequence of strings.
(Specifically, a java.util.Map<String,java.util.List<String>>.)

Request headers

The request headers are a set of (keyword, string)-pairs
transmitted as part of the HTTP request, before the request body.

Procedure: request-headername

If there is a header with the given name (a string),
return the corresponding value string.
Otherwise, return #!null.

(request-header "accept-language") ⇒ "en-us,en;q=0.5"

Procedure: request-header-map

Request a map of all the headers.
This is a map from strings to a sequence of strings.
(Specifically, a java.util.Map<String,java.util.List<String>>.)

Request body

Procedure: request-input-port

Return a textual input port for reading the request body,
as a sequence of characters.

Procedure: request-input-stream

Return a binary input stream for reading the request body,
as a sequence of bytes.

Procedure: request-body-string

Return the entire request body as a string

Request IP addresses and ports

Information about the interface and port on which the request was received.

Procedure: request-local-socket-address

The local address on which the request was received.
This is the combination of (request-local-host)
and (request-local-port), as an instance of
java.net.InetSocketAddress.

Procedure: request-local-host

Get the IP address of the interface on which request was received,
as an java.net.InetAddress.

Procedure: request-local-IP-address

Get the IP address of the interface on which request was received,
a string in numeric form:

(request-local-host) ⇒ "127.0.0.1"

Procedure: request-local-port

Get the port this request was received on.

(request-local-port) ⇒ 8080

Information about the interface and port of the remote client that invoked the request.

Procedure: request-remote-socket-address

The address of the remote client (usually a web browser)
which invoked the request.
This is the combination of (request-remove-host)
and (request-remote-port), as an instance of
java.net.InetSocketAddress.

Procedure: request-remote-host

Get the IP address of the remote client which invoked the request,
as an java.net.InetAddress.

Procedure: request-remote-IP-address

Get the IP address of the remote client which invoked the request,
as a string in numeric form.

(request-remote-host) ⇒ "123.45.6.7"

Procedure: request-remote-port

The port used by the remote client.

Miscellaneous request properties

Procedure: request-path-translated

Map the request-path to a file name (a string)
in the server application directory.
Corresponds to the CGI variable PATH_TRANSLATED.

Procedure: request-method

Returns the method of the HTTP request, usually "GET"
or "POST". Corresponds to the CGI variable REQUEST_METHOD.

Procedure: request-scheme

Returns the scheme (protocol) of the request.
Usually "http", or "https".