url rewriting and dispatching

When you need to rewrite an external URL to a more convenient internal format, like rewriting to *.php files, you can use Resin's rewrite capabilities. Because Resin's rewrite is patterned after Apache's mod_rewrite, you can translate older mod_rewrite rules to Resin's rewrite tags.

<web-app xmlns="http://caucho.com/ns/resin"
            xmlns:resin="urn:java:com.caucho.resin">

  <resin:Dispatch regexp="\.(php|jpg|html|txt|gif|png|js|css)"/>
  
  <resin:Dispatch regexp="^" target="/index.php"/>
	    
</web-app>

<web-app xmlns="http://caucho.com/ns/resin"
            xmlns:resin="urn:java:com.caucho.resin">

  <resin:Dispatch regexp="\.(php|jpg|html|txt|gif|png|js|css)"/>
  
  <resin:Dispatch regexp="^/" target="/index.php?q="/>
	    
</web-app>

<web-app xmlns="http://caucho.com/ns/resin"
            xmlns:resin="urn:java:com.caucho.resin">

  <resin:Dispatch>
    <resin:IfFileExists/>
  </resin:Dispatch>

  <resin:Forward regexp="^" target='/index.php'/>

</web-app>

<web-app xmlns="http://caucho.com/ns/resin"
            xmlns:resin="urn:java:com.caucho.resin">

  <resin:Redirect regexp="^/old-page.html" target="/new-page.html"/>
  <resin:Redirect regexp="^/old/" target="/new/"/>
	    
</web-app>

Resin's dispatching is based on a list of dispatch rules configured in the resin-web.xml or the resin.xml configuration files. Each rule has a regular expression matching request URLs. The first dispatch rule that matches takes control of the request. For example, a <resin:Redirect> sends a HTTP redirect, and a <resin:Dispatch> dispatches the request as normal.

Each matching rule can rewrite the URL using a target attribute. The target uses regexp replacement syntax like Perl's rewrite or sed. The following rule flips the first two segments around, so /foo/bar would become /bar/foo.

<web-app xmlns="http://caucho.com/ns/resin"
            xmlns:resin="urn:java:com.caucho.resin">

  <resin:Redirect regexp="^/([^/]+)/([^/]+)" target="/$2/$1"/>
	    
</web-app>

Some dispatches might depend on request attributes like the security attribute. The <resin:IfSecure> tag checks if the request is an SSL request, i.e. if request.isSecure() is true. For non-SSL requests, the following <resin:Forbidden> applies.

The rewrite conditions can all be used as security conditions, e.g. for <resin:Allow> or <resin:Deny>.

<web-app xmlns="http://caucho.com/ns/resin"
            xmlns:resin="urn:java:com.caucho.resin">

  <resin:Forbidden regexp="^/secret">
    <resin:IfSecure value="false"/>
  </resin:Forbidden>
	    
</web-app>

The rewrite capability can also add standard predefined filters to modify the output, e.g. setting a response header. Filters can use conditions as restrictions, just like the dispatch rules.

<web-app xmlns="http://caucho.com/ns/resin"
            xmlns:resin="urn:java:com.caucho.resin">

  <resin:SetHeader regexp="^/secret" name="Foo" value="bar"/>
	    
</web-app>

<web-app xmlns="http://caucho.com/ns/resin"
            xmlns:resin="urn:java:com.caucho.resin">

  <resin:Dispatch regexp="^/test">
    <mypkg:MyFilter xmlns:my="urn:java:com.foo.mypkg">
      <mypkg:my-param>my-value</mypkg:my-param>
    </mypkg:MyFilter>
  </resin:Dispatch>
	    
</web-app>

Contains one or more conditions and evaluates to true if all of the contained conditions evaluate to true, false if any of the contained conditions does not evaluate to true.

Evaluates to true if the authorization mechanism used in the request is the given value. The comparison is always case insensitive.

If the auth-type is not "none", or if the auth-type of the request is not "none", a Cache-Control header containing "private" is added to the response.

Evaluates to true if the value of a cookie with a given name matches a regular expression regexp, false if it does not or if the cookie does not exist.

The Vary header of the response is updated to include "Cookie", which indicates to the browser and any intervening proxy cache that the response varies based on the submitted value of cookies.

Cron syntax for specifying a time or times that that the rule should be disabled. In conjunction, enable-at and disable-at provide a means for scheduling the enablement of a rule.

If <dispatch> matches the current URL, the rest of the items in the enclosing rewrite-dispatch are not considered and the request passes immediately to normal servlet evaluation. <dispatch> is often used to specify URLs which should be handled normally before a more general pattern which modifies the URL.

For example, the following pattern uses <dispatch> to handle images and *.php files normally, but forward's all other requests to /index.php.

<web-app xmlns="http://caucho.com/ns/resin">

 <rewrite-dispatch>
   <dispatch regexp="\.(php|gif|css|jpg|png)"/>
   <forward regexp="^" target="/index.php"/>
 </rewrite-dispatch>

</web-app>

The dispatch-type lets you configure rewrite-dispatch for REQUEST, FORWARD, or INCLUDE. By default, the rewrite-dispatch is REQUEST.

<web-app xmlns="http://caucho.com/ns/resin">

  <rewrite-dispatch>
    <dispatch-type>FORWARD</dispatch-type>

    <forward regexp="/foo" target="/bar.jsp"/>
  </rewrite-dispatch>

</web-app>

Cron syntax for specifying a time or times that that the rule should be enabled, see <disable-at/>.

Set's the initial state of the rule, default is true. In conjunction with name, an initial enabled value of "false" is valuable for rules which are to be turned on and turned off at runtime.

<forbidden> sents a 403 forbidden message to the browser for a matching URL.

<web-app xmlns="http://caucho.com/ns/resin">

 <rewrite-dispatch>
   <forbidden regexp="^/protected"/>
 </rewrite-dispatch>

</web-app>

<forward> rewrites the current URL, forwarding it to the target using the servlet forward() call. Because <forward> is internal, it will have better performance than a <redirect> when the target URL is on the same server, the browser will not know that the underlying resource has moved.

<web-app xmlns="http://caucho.com/ns/resin">

 <rewrite-dispatch>
   <forward regexp="^/old" target="/new"/>
 </rewrite-dispatch>

</web-app>

Evaluates to true if the value of a header with a given name matches a regular expression regexp, false if it does not or if the header does not exist.

The Vary header of the response is updated to include the header name which indicates to the browser and any intervening proxy cache that the response varies based on the submitted value of the header.

<gone> sents a 410 gone response to the browser for a matching URL.

<web-app xmlns="http://caucho.com/ns/resin">

 <rewrite-dispatch>
   <gone regexp="^/protected"/>
 </rewrite-dispatch>

</web-app>

<import> loads rules from an external xml file.

<web-app xmlns="http://caucho.com/ns/resin"
         xmlns:resin="http://caucho.com/ns/resin/core">

  <rewrite-dispatch>
    <import path='/WEB-INF/rewrite-maintenance.xml' enabled="false"/>
    <import path='/WEB-INF/rewrite-rules.xml'/>
  </rewrite-dispatch>

</web-app>

<rewrite-dispatch xmlns="http://caucho.com/ns/resin"
                  xmlns:resin="http://caucho.com/ns/resin/core">

   <dispatch regexp="\.(css|gif|jpg|pdf|png)"/>

   <forward regexp=".*" target="/maintenance.html"/>

</rewrite-dispatch>

Changes to the external file are checked for at a frequency determined by dependency-check-interval or when the update() operation of the mbean is invoked. If an error occurs when loading the modified file, the contents of the old file are used until the errors are corrected or the server is restarted. The log file will contain details for the error, and the RedeployError property of the mbean wil contain a description of the error.

Each <import> registers an mbean of type RewriteImport, with a full a name like "resin:Host=default,WebApp=/,name=Foo,type=RewriteRule" and an interface of com.caucho.management.server.RewriteImportMXBean. It provides the update(), start() and stop() operations. The update() operations forces an immediate check for modifications to the external file.

<load-balance> forwards requests from a web-tier server to a cluster of app-tier servers for load-balancing. Load balancing provides scalability by splitting load among many application servers and increases reliability by avoiding servers which are upgrading or restarting.

In the following example, the web-tier load-balances all traffic to a cluster of backend application servers. Because the web-tier has a proxy cache, static pages and cached pages will be served directory from the web-tier.

<load-balance> requires Resin Professional.

<resin xmlns="http://caucho.com/ns/resin">

  <cluster id="app-tier">
    <server id="app-a" address="192.168.3.1">
    <server id="app-b" address="192.168.3.2">
    ...
  </cluster>

  <cluster id="web-tier">
    <server id="web-a" address="192.168.2.1">
      <http port="80"/>
    </server>

    <cache/>

    <host id="">
      <web-app id="/">

        <rewrite-dispatch>
          <load-balance regexp="" cluster="app-tier"/>
        </rewrite-dispatch>

      </web-app>
    </host>

</resin>

Evaluates to true if the value of the Locale matches a regular expression, false if it does not. The comparison is always case insensitive.

The Locale is a normalization of the value of the Accept-Language header. For example "fr" remains "fr" and "FR-CA" becomes "fr_CA". If the request does not include the Accept-Language header then the Locale is the default Locale for the server.

<web-app xmlns="http://caucho.com/ns/resin"
         xmlns:resin="http://caucho.com/ns/resin/core">

  <rewrite-dispatch>
    <forward regexp='^/' target='/fr/'>
      <when locale="^fr"/>
    </forward>

    <forward regexp='^/' target='/en/'/>
  </rewrite-dispatch>
</web-app>

Evaluates to true if the value of the request's local port is the specified value, false if it does not. The local port is the port that Resin has bound to and has used to receive the request.

Evaluates to true if the http method used in the request is the given value. The comparison is always case insensitive. Common methods include HEAD, GET, POST, DELETE, OPTIONS, PUT, and TRACE, although a method by any name may be used by a client.

<match> provides a way to group more specific rules based on the url. The contents of the <match> are any rule, and they are considered only if the regexp of the <match> is satsified and the match is enabled.

Judicious use of <match> will provide better performance in situations where there are many rules and some of them contain when or if conditions.

<match> also provides a convenient way to group a set of rules that can be enabled or disabled using an mbean. If the name attribute is specified for the <match> then an mbean with a name like resin:Host=default,WebApp=/,name=name,type=RewriteRule is registered and the start() and stop() operations are available.

The documentation for <rewrite-dispatch> provides a table of all rules. In addition to the rules that can be contained within <match>, the following configuration tags are available.

<moved-permanently> sends a HTTP 301 moved permanently response to the browser, indicating that the resource has moved.

The following example causes all requests to the "old.com" host to be immediately redirected to "new.com". The urls will be maintained, so for example a request to http://old.com/hello/world.html?foo=bar will get redirected to http://new.com/hello/world.html?foo=bar.

  <host id="old.com">
    <web-app id="/">
      <rewrite-dispatch>
        <moved-permanently regexp="^/(.*)$"
                           target="http://new.com/$1"/>
      </rewrite-dispatch>
    </web-app>
  </host>

A rule can be given a name, which causes a JMX mbean to be registered. The mbean has a name like "resin:Host=default,WebApp=/,name=Foo,type=RewriteRule" and an interface of com.caucho.management.server.RewriteRuleMXBean. It provides the start() and stop() operations.

Contains one or more conditions and evaluates to true only if none of the contained conditions evaluate to true, false if any of the contained conditions evaluate to true.

<not-found> sents a 404 not found to the browser for a matching URL.

<web-app xmlns="http://caucho.com/ns/resin">

 <rewrite-dispatch>
   <not-found regexp="^/protected"/>
 </rewrite-dispatch>

</web-app>

Contains one or more conditions and evaluates to true if any of the contained conditions evaluate to true, false only if all of the contained conditions evaluate to false.

The <proxy> tag proxies HTTP requests to a backend service like <load-balance> proxies requests to a backend Resin service. Frameworks like Ruby can sit behind a Resin instance and deliver requests through the proxy tag.

Evaluates to true if the value of a query parameter with a given name matches a regular expression regexp, false if it does not or if the parameter does not exist.

Form parameters submitted in the body of a POST are not available for the comparison performed by query-param.

<redirect> sends a HTTP 302 redirect response to the browser, indicating that the resource has moved.

<web-app xmlns="http://caucho.com/ns/resin">

  <rewrite-dispatch>
    <redirect regexp="^/(foo)" target="http://$1.bar.com"/>
  </rewrite-dispatch>

</web-app>

  <host ... >
     <rewrite-dispatch>
        <redirect regexp="^" target="https://${host.name}">
          <when secure="false"/>
        </redirect>
      </rewrite-dispatch>
      ...
   </host>

The regular expression in a regexp tag or attribute is a standard Java regular expression.

To make the regexp case insensitive, you can use the (?i:...) syntax:

<web-app xmlns="http://caucho.com/ns/resin"
         xmlns:resin="http://caucho.com/ns/resin/core">
  <rewrite-dispatch>
    <forbidden regexp='(?i:^/foo)'/>
  </rewrite-dispatch>
</web-app>

Evaluates to true if the remote address of the client matches the specified ip address.

A Cache-Control header containing "private" is added to the response.

<web-app xmlns="http://caucho.com/ns/resin"
         xmlns:resin="http://caucho.com/ns/resin/core">
  <rewrite-dispatch>
    <forbidden regexp='^/foo'>
      <unless remote-addr="192.168.2.1/24"/>
    </forbidden>

  </rewrite-dispatch>
</web-app>

Evaluates to true if the user is authenticated and has the specified name.

If there is a current user, a Cache-Control header containing "private" is added to the response.

<rewrite> rewrites the current URL, continuing processing of the <rewrite-dispatch> tags. <rewrite> can be used as an intermediate rewriting stage for more complicated patterns.

<rewrite-real-path> configures an alias for the getRealPath() call, i.e. an enhancement to the <path-mapping> tag. It provides a virtual directory mapping that allows url patterns in the web application to have a local path anywhere on the physical filesystem.

The source path is a URL, the target path is a real filesystem path.

<web-app xmlns="http://caucho.com/ns/resin">

  <rewrite-real-path>
    <real-path regexp="^/images" target="/usr/local/share/images"/>
  </rewrite-real-path>

<web-app xmlns="http://caucho.com/ns/resin">

  <rewrite-real-path>
    <real-path regexp="^/" target="WEB-INF/SugarCE-Full-5.0.0a"/>
  </rewrite-real-path>

<web-app xmlns="http://caucho.com/ns/resin">

  <rewrite-real-path>
    <real-path regexp="^/images" target="merge:(custom-images;images)"/>
  </rewrite-real-path>

<web-app xmlns="http://caucho.com/ns/resin">

  <rewrite-real-path>
    <real-path regexp="^/" target="merge:(WEB-INF/SugarCE-local;WEB-INF/SugarCE-Full-5.0.0a)"/>
  </rewrite-real-path>

<rewrite-dispatch> evaluates the child tags in order. The first matching tag dispatches the request. If no children match, the request uses the standard servlet handling.

The child tags rewrite and dispatch based on regexp patterns.

<web-app xmlns="http://caucho.com/ns/resin">

 <rewrite-dispatch>
   <dispatch regexp="\.(php|gif|css|jpg|png)"/>
   <forward regexp="^" target="/index.php"/>
 </rewrite-dispatch>

</web-app>

<secure> specifies a condition for the ssl status of the request. If secure is true, then the request must be using ssl for the rule to match. If secure is false, then the request must not be using ssl for the rule to match. If secure is not specified, the ssl status of the request is not considered when testing if the rule matches.

<web-app xmlns="http://caucho.com/ns/resin">
  <rewrite-dispatch>
    <redirect regexp='^/foo' target='/secure'>
      <when secure='true'/>
    </redirect>

    <redirect regexp='^/foo' target='/insecure'>
      <when secure='false'/>
    </redirect>

    <redirect regexp='^/bar' target='/public'/>
  </rewrite-dispatch>
</web-app>

http://localhost:8080/foo/index.html
  --> redirect to /insecure/index.html

https://localhost:8080/foo/index.html
  --> redirect to /secure/index.html

http://localhost:8080/bar/index.html
  --> redirect to /public/index.html

https://localhost:8080/bar/index.html
  --> redirect to /public/index.html

Evaluates to true if the value of the request's server name matches the specified regexp, false if it does not. The comparison is always case insensitive. The server name is the name that the client has used to connect to the server and may not be the name of the actual server that is hosting Resin.

Most potential problems that can be solved by server-name are more efficiently solved using virtual hosts and the host-alias tag.

Evaluates to true if the value of the request's server port is the specified value, false if it does not. The server port is the port that the client has used to connect to the server and may not be the actual port that Resin is bound to.

<set> is used to set properties of the request or response before continuing on to the next rule. The properties are maintained after the rewriting is complete, for example a request that becomes secure because of <set> will continue to be regarded as secure when the request eventually reaches a jsp or servlet.

<web-app xmlns="http://caucho.com/ns/resin">

  <rewrite-dispatch>
    <set request-secure="true">
      <when header="X-SSL-cipher"/>
    </set>

    <forward regexp="^/checkout" target="https://hogwarts.com/checkout">
      <when secure="false"/>
    </forward>

  </rewrite-dispatch>

</web-app>

Contains a condition that further refines the match of the enclosing tag beyond the information provided by the url. If the condition does not evaluate to true, then the enclosing tag is applied.

See <when> for a description of possible conditions.

Evaluates to true if the user is authenticated and in the specified role. The special role of '*' means any role.

If the current user is any role, a Cache-Control header containing "private" is added to the response.

Contains a condition that further refines the match of the enclosing tag beyond the information provided by the url. If the condition evaluates to true, then the enclosing tag is applied.

Logging for the name com.caucho.server.rewrite at the "finer" level reveals successful matches. At the "finest" level both successful and unsuccessful matches are logged.

<logger name="com.caucho.server.rewrite" level="finest"/>

[1998/05/08 02:51:31.000] forward ^/foo: '/baz/test.jsp'  no match
[1998/05/08 02:51:31.000] forward ^/bar: '/baz/test.jsp'  no match
[1998/05/08 02:51:31.000] forward ^/baz: '/baz/test.jsp'  -->  '/hogwarts/test.jsp'

    http://anything.com/anything.html
      redirect => https://anything.com/anything.html
  

    <host ...>
      ...
      <rewrite-dispatch>
        <redirect regexp="^" target="https://${host.name}">
          <when secure="false"/>
        </redirect>
      </rewrite-dispatch>
      ...
    </host>
  

    http://hostname/classroom/physics
      forward => http://hostname/physics 

    http://hostname/classroom/physics/anything
      forward => http://hostname/physics/anything
  

    <host>
      <rewrite-dispatch>
        <forward regexp="^/classroom/physics" target="/physics"/>
      </rewrite-dispatch>
       ...
  

    http://gryffindor.hogwarts.com/anything.html
      forward => /gryffindor/*

    http://slytherin.hogwarts.com/anything.html
      forward => /slytherin/anything.html

    http://hogwarts.com/anything.html
      forward => /anything.html
  

    <cluster>
      ...
      <rewrite-dispatch>
        <forward regexp="http://gryffindor\.[^/]+" target="/gryffindor/"/>
        <forward regexp="http://slytherin\.[^/]+" target="/slytherin/"/>
      </rewrite-dispatch>
      ...
    </cluster>