Request Routing

Overview

GoAhead includes a powerful request routing engine that manages how client HTTP requests are processed. The router is configured with a set of routes from a configuration file called route.txt. This file is loaded when GoAhead starts. When a request is received, the router tests various routes and selects the best route to handle the request. In the process, routes may redirect or rewrite the request as required.

A GoAhead configuration will typically have many routes. The configured routes are tested in-order by matching the route URI pattern against the request URL. A route may require that further preconditions be met before it is suitable to process the request. If the required conditions are not met, the next route in the configuration will be tested. There is always a catch-all route that will process the request if all prior routes fail to qualify.

Route Configuration

Routes are defined in the route.txt configuration file via a series of route directives. For example:

route uri=/cgi-bin dir=cgi-bin handler=cgi
route uri=/action handler=action
route uri=/ extensions=jst,asp handler=jst
route uri=/ methods=OPTIONS|TRACE handler=options

Each line defines a new route. While route directives may have many optional parameters, every route will have a uri keyword that defines a URI prefix that qualifying requests must begin with. If a client request has a URI that does not being with the route URI prefix, then the route will be skipped.

Route Ordering

When multiple routes are defined in the configuration file, the router will test each route in the order in which they are declared in the configuration file. So ordering is very important. For routes with similar leading characters, define the route with the longer URI first in the route.txt file.

Route Keywords

A route directive is comprised of a collection of keyword=value pairs. All routes must have a uri keyword, other keywords are optional. Here are the supported route keywords:

abilities

The abilities keyword specifies the required user abilities to access resources described by this route. Multiple abilities are separated using comma. If multiple abilities are specified, all the abilities are required. For example:

route uri=/auth/basic/ auth=basic abilities=create,edit,view

To activate testing the user's abilities, an auth keyword must be specified to enable user authentication and authorization. See User Authentication for more information.

auth

The auth keywords specifies the authentication scheme to use. Authentication is the process of asking for the users's name and password and then validating those credentials and determining the user's authorized abilities. Supported authentication schemes are: basic for Basic authentication, digest for Digest authentication and form for web-form based authentication.

If the user's credentials cannot be authenticated, the user is redirected to a new URI specified by the redirect keyword. When authentication fails, GoAhead responds with a HTTP 401 status code which means unauthorized access. A redirect keyword with a 401 status code will specify the redirection target when authentication fails. For example:

route uri=/ auth=form handler=continue redirect=401@/pub/login.html

The required abilities are specified by the abilities keyword. See User Authentication for more information.

dir

The dir keyword defines the filesystem directory containing documents for this route. This overrides the default documents directory. If the client is requesting a physical document, the request URI path is appended to this directory to locate the file to serve.

extensions

The extensions keyword specifies the set of valid filename extensions for documents served by this route. For example:

route uri=/ extension=cgi|fcgi|mycgi handler=cgi

This will use the CGI handler for any documents with the extensions: cgi, fcgi or mycgi.

handler

The handler keyword specifies the GoAhead handler that will be responsible for generating the response. If unspecified, it defaults to the file handler. Valid handler names include: action, cgi, file, jst, options and redirect.

methods

A route can define the a set of acceptable HTTP methods. Multiple methods should be separated by |. For example:

route uri=/put/ methods=PUT|DELETE

The standard HTTP methods are: DELETE, GET, OPTIONS, POST, PUT and TRACE.

protocol

A route can be restricted to a specific protocol such as HTTP or HTTPS via the protocol keyword. For example, this route will only apply to SSL requests:

route uri=/ protocol=https

redirect

The redirect keyword specifies target URIs to which the client will be redirected based on the response HTTP status code. The format of the redirect keyword value is: redirect=STATUS@URI, where STATUS is a valid HTTP status code and URI is a valid target destination URI. For example:

route uri=/old-content/ redirect=404@/upgrade-message.html

Unlike other keywords, multiple redirect keywords with different status values can be present in a single route.

uri

The uri keyword is mandatory for all routes and defines the URI prefix for matching requests. All requests URIs that begin with the specified uri value will match. It is good practice to include a trailing / to match directories. For example:

route uri=/confidential/ auth=form abilities=top-secret

Keyword Value Separators

Some keyword values may contain multiple values (abilities, extensions, methods). In these cases, values are separated using either "|" or ",". While both separators are valid, the convention is to use "," when all the specified values are required, and to use "|" is used when only one of the specified values is required. Specifically, abilities should be separated by "," and extensions and methods should be separated by "|".

Route Processing

To process a request, the GoAhead route engine examines each of the configured routes to determine the best matching route for a request. It does this by considering each route in the order they are defined in the configuration file. Each route is tested over a sequence of steps. If a route fails to match at a step, the route is discarded and the next route is considered.

Routing Steps

1. Protocol Matching — Test if the request protocol matches.
2. Method Matching — Test if the request method matches.
3. Extension Matching — Test if the request extension matches.
4. URI Matching — Test if the request URI matches the route URI.

Protocol Matching

Protocol matching is an optional step. Routes can be configured to match a specific protocol, either http or https. By default a route supports all protocols.

Method Matching

Method matching is an optional step. Routes can be configured to only match certain HTTP methods. Method matching tests the actual request HTTP method against the supported route methods. By default a route supports all methods.

Extension Matching

Extension matching is an optional step. Routes can be configured to only match certain filename extensions. Extension matching tests the actual request filename against the supported route extensions. By default a route supports all extensions.

URI Matching

URI matching is a mandatory stop. The route URI is tested against the start of the request URI.

Route Examples

Redirecting Requests

To redirect requests for old documents to newer versions:

route uri=/oldfile.html redirect=/newfile.html

Redirecting HTTP to SSL

To redirect all traffic over SSL:

route uri=/ protocol=http redirect=https

Controlling Access with Digest Authentication

To secure private content via Digest Authentication:

route uri=/ auth=digest

Enable the TRACE and OPTIONS methods

The TRACE and OPTIONS methods are disabled by default to enhance security. These methods should not be enabled for all routes. To selectively enable:

route uri=/partition/ methods=OPTIONS|TRACE handler=options

Define a New Extension

To ensure that requests for content with given file extensions are handled by a specific handler, you can use the extensions and handler keywords:

route uri=/ extensions=jst,asp handler=jst

Catch-All Route

If all prior routes file to match a request, a catch-all route can be used to respond universally.

route uri=/

Note: if the handler is not specified, the file handler is used.