Extending Handlers with BeanShell

This post will show how to extend an existing handler by using BeanShell.
Since PAW 0.96 BeanShell can be used to write handlers (and filters). In earlier versions of PAW handlers and filters had to be provided as Java class file, so a Java development environment was needed. By the use of BeanShell handlers and filters can now be developed directly on an Android device. This is especially handy when developing handler and filters for testing.

PAW Standard Handler Chain

I’ll briefly recap what handlers are good for.
Handlers form the processing chain on HTTP requests. Handler are organized in a list that is processed until a handler processing the request is found. If a handler signals that it can handle the request, the handler will process the request and the list of handlers is no longer processed.

In the example we will extend the BasicAuthHandler which handles the basic authentication to protect a web resource (most often a directory).
The handler will be extended in the way, that it will only request credentials if pages are called from external, localhost request should not need to authenticate.

The standard BasicAuthHandler does not provide this functionality. It always asks for credentials, regardless where the request came from.

Since PAW 0.96 there is a new handler called CallBshHandler which accepts a BeanShell file to act as a handler.

The BeanShell file has the following base structure:

/*
    Variables: server, prefix, handler
*/
init() {

}

/*
    Variables: server, prefix, handler, request
*/
respond() {

}

There are the two methods init() and respond(). Both methods return true on success and false on failure. The init() method receives the server, prefix and handler variables. The server and prefix variables are needed to get configuration parameters specified inside the conf/handler.xml file. The handler variable holds a reference to the calling CallBshHandler  instance. This instance is needed to persist settings (between init() and response()) methods. This is necessary, because init() and response() are not called within the same BeanShell interpreter instance (to make the handler thread safe). To persists objects within the handler, the methods save() and load() are provided. The example will show how these methods are used.

Extending the current BasicAuthHandler will be done in three steps:

1. Disable the BasicAuthHandler
2. Create the new handler
3. Configure the new  handler

Disable the BasicAuthHandler

To disabling the current BasicAuthHandler, find the following handler in the conf/handler.xml file and change the  status property to inactive

<handler status="inactive">
    <name>Basic Auth Handler</name>
   …
</hadler>

Create the New Handler

We will now build a handler that calls the standard BasicAuthHandler only on external requests. Local requests, which have the IP number 127.0.0.1 or ::1 will not be processed and so no credentials will be requested.

To build the new handler, create a directory handler inside the PAW installation folder (paw/handler). Inside that folder create a file called authHandler.bsh with the following content:

import org.paw.handler.BasicAuthHandler;

LOCALHOST = "127.0.0.1";
LOCALHOST_V6 = "::1";

/*
    Variables: server, prefix, handler
*/
init() {
    authHandler = new BasicAuthHandler(); 
    handler.save("authHandler", authHandler);

    return authHandler.init(server, prefix);

}

/*
    Variables: server, prefix, handler, request
*/
respond() {
    ip = request.sock.getInetAddress().getHostAddress();

    if(ip.equals(LOCALHOST) || ip.equals(LOCALHOST_V6)) {
        return false;
    }

    authHandler = handler.load("authHandler");
    return authHandler.respond(request);
}

The code is straightforward. Inside the init() method the BasicAuthHandler is instantiated. That instance is saved within the calling handler by calling handler.save().
The last line of the init() method returns the result of the call to init() of the instantiated BasicAuthHandler class.

If the init() method returns true, the handler will be added to the list of handlers and the respond()method will be called on each request.

When the respond() method is called it first gets the requestor’s IP number and assigns it to the variable ip. If the variable contains a localhost IP (127.0.0.1 or ::1) the method returns false, which indicates that the handler will not handle the request.
In that case no credentials are requested and the handler chain is further processed.

If the request is not initiated by a localhost address, the respond() method of the BasicAuthHandler instance is called and the return value of that method is returned.

Configure the New Handler

To configure the new handler, just place the following handler definition below or above the original BasicAuthHandler definition of the conf/hander.xml file:

<handler status="active">
    <name>BeanShell auth handler</name>
    <description>Auth handler that allows local access</description>
    <removable>true</removable>
    <id>bshAuth</id>
    <files/>
    <params>
      <param name="bshAuth.class" value="org.paw.handler.CallBshHandler" />
      <param name="bshAuth.script" value="[PAW_HOME]/handler/authHandler.bsh" />
      <param name="bshAuth.confdir" value="[PAW_HOME]/webconf/auth" />
    </params>
  </handler>

The parameters describe the class (org.paw.handler.CallBshHandler) and script ([PAW_HOME]/handler/authHandler.bsh) to use. The third parameter called confdir is the standard configuration parameter used by the BasicAuthHandler. The BeanShell handler passes this parameter when calling the BasicAuthHander.init() method from its init() method.

Because the new handler calls the standard handler, the Directory Protection settings from within PAW’s web interface also apply to the new handler.

On next startup of the server the new handler should be active. If the startup fails, increase the log level, restart the server and have a look at the log file.

Testing the Handler

To test the handler, I’ve created a directory test within the html folder (html/test). For the at folder, directory protection has been setup using the Directory Protection page of the web interface.
The localhost connection was tested by using ADB’s TCP forward parameter (adb forward tcp:8080 tcp:8080).

When testing with an IP number, authentication is required:

$ telnet 192.168.178.79 8080
Trying 192.168.178.79...
Connected to 192.168.178.79.
Escape character is '^]'.
GET /test/ HTTP/1.0

HTTP/1.0 401 Unauthorized
WWW-Authenticate: basic realm="Bsh Auth Test"
Date: Sun, 06 Dec 2015 09:05:38 GMT
Server: PAW Server 0.97-android (Brazil/2.0)
Connection: close
Content-Length: 34
Content-Type: text/html

Missing http header: AuthorizationConnection closed by foreign host.

On a localhost request, no authentication is needed and the directory listing is displayed:

$ telnet localhost 8080
Trying 127.0.0.1...
Connected to localhost.
Escape character is '^]'.
GET /test/ HTTP/1.0

HTTP/1.0 200 OK
Set-Cookie: cookie=7th5kto9f4nrf1a5r8pdse; PATH=/
Date: Sun, 06 Dec 2015 09:08:32 GMT
Server: PAW Server 0.97-android (Brazil/2.0)
Connection: close
Content-Length: 99
Content-Type: text/html

<title>Directory Listing</title>
<h1>Directory Listing</h1>
<a href=..><b>parent directory</b></a>
Connection closed by foreign host.