|
HTTP Transport |
This document provides a guide to the tpt_http module which hosts the HTTP transport.
Overview
The HTTP transport is provided by the Jetty HTTP server. Jetty is a high quality embeddable HTTP server used in many high-profile open-source and commercial software platforms. It may be readily customized, extended or modified should a custom HTTP transport be required.
Choice of HTTP server is a very subjective matter. We provide Jetty as a default option. It is a very high performance and proven HTTP server with a great track record and continual development. The tpt_http use of Jetty may be readily customized to suit your deployment. Alternatively Jetty can be configured as a pass-through server behind Apache either by using proxy mapping or by the mod_jk protocol. A detailed discussion of configuring Jetty is provided at the Jetty homepage.
HTTPHandler
The main HTTP handler configured with Jetty is org.ten60.transport.jetty.HTTPHandler. This handler is
configured to serve the entire root '/' context by default. HTTPHandler maps all HTTP requests to NetKernel
requests.
Security - Access Control
Access control can be considered in two stages. A first stage is to apply request filters in a chain on the input stage to the JettyTransport. By default the JettyTransport does not make any security decision for a request. Optional File, IP and Path filters can be added and are available in the org/ten60/transport/jetty/ package. The Jetty website provides details of how Jetty can be configured with input chain filters.
A second more comprehensive stage would be to consider a policy firewall for your application. NetKernel allows security
Access control polices to be applied using XACML. So for example it would be relatively straightforward to direct all HTTP transport requests to an
application landing pad from which access to the core application could be controlled.
Credentials that can be used for policy enforcement include GET/POST data, Session Cookies, and the HTTP header is available as a session context,
which can be obtained within an application using the URI this:session:HTTPHeader.
We will see below how the HTTPHandler handles GET/POST parameters and Cookies.
Please see the security guide for more security considerations.
GET/POST
HTTPHandler issues requests to the Kernel with GET/POST parameters supplied by value. Typically GET or POST requests are issued as the result of HTML Form submissions, these submissions are typically parameterized name-value pairs. The NetKernel can transparently transmute GET and POST parameters into an XML representation. Here is a simple example form
|
<form action="GET" target="dummy.idoc">
<input name="firstname">firstname</input> <input name="surname">surname</input> <input type="submit" value="submit" /> </form> |
the submission of which will produce the following XML parameter document.
<firstname>John</firstname>
<surname>Smith</surname>
<submit>submit</submit>
</nvp>
The processed submission document is used as the parameter in a request to the kernel for a URI.
All transmuted GET/POST parameter data is escaped and is valid XML. Parameter data can be accessed in an application at the URI
this:param
XML Cookies
Cookies are an important non-XML domain state mechanism. HTTPHandler supports cookies and tpt_http module can transparently map cookies in and out of the
XML domain. All inbound cookies are passed as a parameter with a Kernel request they are accessed with the URI this:param:cookie. The HTTPCookie URA
supplied by the tpt_http module, can be used to obtain an XML representation of a cookie which has the following form.
<name>somecookieid</name>
<path>somepath</path>
<domain>somedomain</domain>
<secure>is secure</secure>
<maxage>some expiry</maxage>
<comment>some comment</comment>
<value>some value</value>
</cookie>
Cookies may be set on the HTTP response by using the HTTPCookie accessor to set the cookie. HTTPCookie takes an XML representation of the cookie and sets the true cookie on the response.
Here's an example of an idoc that sets a cookie. The form of the XML cookie is exactly the same as that produced by HTTPCookie for a get cookie request.
<seq> [ ... some process ...]
<instr>
<type>HTTPCookie</type>
<operand>this:response</operand>
<operator>
<cookie>
<set />
</cookie>
</operator>
<param>
<cookie>
<name>sessionid</name>
<value>This is some session identifier</value>
</cookie>
</param>
<target>this:response</target>
</instr>
</seq>
</idoc>
HTTPHandler detects cookies on the the outbound Kernel response and sets the cookies on the HTTP response.
Note: HTTPCookie makes no attempt to parse the value of the cookie payload to XML. It would be a simple matter to do this but this implementation attempts to provide backwards compatibility with existing cookie models. In future it would be very desirable to have a true XML cookie that contained an XML fragment as it's payload. Perhaps the cookie protocol can be extended with an "XML" declaration?
HTTP Header
HTTP applications often require access to the HTTP request header fields. These provide Requestor address, User agent etc. The HTTP header
is available as an XML representation at the URI this:session:HTTPHeader.
HTTP Request URL
It is sometimes useful to know the URL of the HTTP request. This is available as a URI representation from this:session:HTTPURL.
Here is the Header information for the request for this page.
Configuration
By default the HTTP server is configured to provide HTTP access on port 1060. This port may be configured in
ffcpl:/etc/TransportJettyConfig.xml which can be overridden in the <install>/scratch directory of the tpt_transport
module. [See virtual filesystem]. The default config is
<!-- ***************** Jetty HTTP Server ***************** -->
<Configure class="org.mortbay.jetty.Server">
<!-- *********** Add Listeners *********** -->
<!--Start addlisteners-->
<!--Add SocketListener with default port 1060-->
<Call name="addListener">
<Arg>
<New class="org.mortbay.http.SocketListener">
<Set name="Port">1060</Set>
<Set name="MinThreads">5</Set>
<Set name="MaxThreads">100</Set>
<Set name="MaxIdleTimeMs">30000</Set>
<Set name="LowResourcePersistTimeMs">5000</Set>
</New>
</Arg>
</Call>
<!--End addlisteners-->
<!-- ************ Add Server Contexts ************ -->
<!--Default context at root / -->
<Call name="addContext">
<Arg>
<New class="org.mortbay.http.HttpContext">
<!-- Set context Path to default of root '/' -->
<Set name="ContextPath">/</Set>
<!-- **************** Add Jetty Handler Chain for this Context **************** -->
<!--Start Handler Chain-->
<!--Main NetKernel HTTP Transport Handler-->
<Call name="addHandler">
<Arg>
<New class="org.ten60.transport.jetty.HttpHandler">
<!--Exception Handler Application-->
<Arg>ffcpl:/org/ten60/transport/jetty/defaultExceptionHandler.idoc</Arg>
<Set name="TransportName">JettyHTTPTransport</Set>
<Set name="MaxContentLength">50000</Set>
</New>
</Arg>
</Call>
<!--End Handler Chain-->
</New>
</Arg>
</Call>
<!-- ************ Add Loggers ************ -->
<!--Configure Filename to point to log file-->
<!-- Uncomment to enable logging <Set name="RequestLog"> <Arg> <New class="org.mortbay.http.NCSARequestLog"> <Set name="Filename">/var/log/jetty/jetty.log</Set> <Set name="Append" type="boolean">true</Set> <Set name="Buffered" type="boolean">true</Set> </New> </Arg> </Set> -->
</Configure>
<DISABLED> To enable move the Conigure block out of the DISABLED block
<!-- ***************** Jetty SSL HTTP Server ***************** -->
<Configure class="org.mortbay.jetty.Server">
<!-- *********** Add Listeners *********** -->
<!--Start addlisteners-->
<!-- Add SSL Listener with default port 1061 Requires jcert.jar, jnet.jar and jsse.jar and a Certificate in a Java Keystore Certificate should have alias 'jetty' -->
<Call name="addListener">
<Arg>
<New class="org.mortbay.http.SunJsseListener">
<Set name="Port">1061</Set>
<Set name="Keystore">/home/pjr/keystore</Set>
<Set name="Password">password</Set>
<Set name="KeyPassword">password</Set>
</New>
</Arg>
</Call>
<!--End addlisteners-->
<!-- ************ Add Server Contexts ************ -->
<!--Default context at root / -->
<Call name="addContext">
<Arg>
<New class="org.mortbay.http.HttpContext">
<!-- Set context Path to default of root '/' -->
<Set name="ContextPath">/</Set>
<!-- **************** Add Jetty Handler Chain for this Context **************** -->
<!--Start Handler Chain-->
<!--Main NetKernel HTTP Transport Handler-->
<Call name="addHandler">
<Arg>
<New class="org.ten60.transport.jetty.HttpHandler">
<!--Exception Handler Application-->
<Arg>ffcpl:/org/ten60/transport/jetty/defaultExceptionHandler.idoc</Arg>
<Set name="TransportName">JettySSLTransport</Set>
</New>
</Arg>
</Call>
<!--End Handler Chain-->
</New>
</Arg>
</Call>
</Configure>
</DISABLED>
</httpConfig>
The JettyTransport uses Jetty's declarative XML configuration model. The config document has <httpConfig> root element which
may contain multiple Jetty style <Configure> blocks. Each of these will be processed and registered as a Server.
A detailed guide to Jetty configuration and the XML configuration model is available here
For security, to prevent denial of service attacks, the HTTP Handler checks any GET/POST parameter data is a reasonable size. This size can
be configured in the <MaxContentSize> setting. See security guide for other security considerations.
Non-Blocking IO
Jetty supports an experimental ChannelListener that uses JDK 1.4.1 NIO non-blocking IO. NIO allows a much reduced thread count and higher performance. By default we have chosen the stable SocketListener with configurable thread group properties. An example configuration for the ChannelListener is provided and may be experimented with. Future versions of Jetty will support NIO by default.
Error Processing
The HTTPHandler supports XML domain error processing. If the kernel returns an Exception document the HTTPHandler will execute an XML application to process the Exception document. The URI of the Exception processing application is configured as the only Argument to HTTPHandler. Here is the default setting
<!--Exception Handler Application-->
<Arg>ffcpl:/org/ten60/transport/jetty/exception.idoc</Arg>
</New>
SSL
Jetty can be readily configured to support SSL - an example configuration is given in the config.xml file. A detailed discussion and guide to SSL configuration is provided here
|
1060® NetKernelTM Documentation (C) 2003-2004 1060 Research Limited Send Feedback |