Flexible Resource Resolution
Status: DRAFT
Created: 25. November 2008
Author: fmeschbe
JIRA: SLING-249
References: http://markmail.org/message/cibaddpdfk2jwm7p
Introduction
Currently the resource resolver has a limited set of options to resolve incoming requests to resources and to map resource paths to paths to be used in links in the response:
- Vanity URLs – replace requested path with different path
- URL Mappings – replace path prefixes with different prefixes
- Regular Expressions – regular expressions to resolve and map paths
- VanityPath – property set to an absolute path matched against URL
To implement SLING-249 I initially proposed to add another resolution and mapping option:
- VirtualHost – add path prefix based on Host: header (my proposal)
After an internal discussion I proposed a modified implementation, which drops the existing configuration in favor of full flexibiliy on all resources, by allowing a sling:vanityPath
to specify a relative or absolute path or even an URL. Absolute paths and URLs would be used to resolve incoming requests to different locations in the resource tree.
Roy Fielding noted, that allowing any content node to define an absolute entry point for resource resolution would be an open door to bypass delegated security and would also become unmanegeable over time. In his message he proposed a slightly different approach, by specifying a location in the repository, where such root entries would be configured. On the content level, only local aliases are allowed to be defined.
This page is about trying to write up the fine print in this proposal and also document the actual implementation.
Goals
- Separate concerns for root level mappings and local aliases. This allows administrators to define root level mappings preventing regular authors from tampering and allows page authors to define aliases for their pages.
- Allow providing different content trees for different virtual hosts while at the same time allowing to share recources amongst all virtual hosts.
- Provide funtionality to externally and internally redirect. External redirects are implemented by sending a 302/FOUND response with a different
Location
to the client. Internal redirects are handled by just resolving a different actual resource path. - Allow authors to define alias names for their resources which may be used in URLs.
JCR Environment
Properties
When dealing with the new resource resolution we have a number of properties influencing the process:
sling:match
– This property when set on a node in the/etc/map
tree (see below) defines a partial regular expression which is used instead of the node's name to match the incoming request. This property is only needed if the regular expression includes characters which are not valid JCR name characters. The list of invalid characters for JCR names is: /, :, ,, *, ', ", | and any whitespace except blank space. In addition a name without a name space may not be.
or..
and a blank space is only allowed inside the name.sling:redirect
– This property when set on a node in the/etc/map
tree (see below) causes a redirect response to be sent to the client, which causes the client to send in a new request with the modified location. The value of this property is applied to the actual request and sent back as the value ofLocation
response header.sling:internalRedirect
– This property when set on a node in the/etc/map
tree (see below) causes the current path to be modified internally to continue with resource resoltion.sling:alias
– The property may be set on any resource to indicate an alias name for the resource. For example the resource/content/visitors
may have thesling:alias
property set tobesucher
allowing the resource to be addressed in an URL as/content/besucher
.
Node Types
To ease with the definition of redirects and aliases, the following node types are defined:
sling:ResourceAlias
– This mixin node type defines thesling:alias
property and may be attached to any node, which does not otherwise allow setting a property namedsling:alias
sling:MappingSpec
– This mixin node type defines thesling:match
,sling:redirect
andsling:internaleRedirect
properties to define a matching and redirection inside the/etc/map
hierarchy.sling:Mapping
– Primary node type which may be used to easily construct entries in the/etc/map
tree. The node type extends thesling:MappingSpec
mixin node type to allow setting the required matching and redirection. In addition thesling:Resource
mixin node type is extended to allow setting a resource type and thent:hierarchyNode
node type is extended to allow locating nodes of this node type belownt:folder
nodes.
Note, that these node types only help setting the properties. The implementation itself only cares for the properties and their values and not for any of these node types.
Root Level Mappings
Root Level Mappings apply to the request at large including the scheme, host.port and uri path. To accomplish this a path is constructed from the request as {scheme}/{host.port}/{uri_path
}. This string is then matched against mapping entries below /etc/map
which are structured in the content analogously. The longest matching entry string is used and the replacement, that is the redirection property, is applied.
Mapping Entry Specification
Each entry in the mapping table is a regular expression, which is constructed from the resource path below /etc/map
. If any resource along the path has a sling:match
property, the respective value is used in the corresponding segment instead of the resource name. Only resources either having a sling:redirect
or sling:internalRedirect
property are used as table entries. Other resources in the tree are just used to build the mapping structure.
Example
Consider the following content
/etc/map +-- http +-- example.com.80 +-- sling:redirect = "http://www.example.com/" +-- www.example.com.80 +-- sling:internalRedirect = "/example" +-- any_example.com.80 +-- sling:match = ".+\.example\.com\.80" +-- sling:redirect = "http://www.example.com/" +-- localhost_any +-- sling:match = "localhost\.\d*" +-- sling:internalRedirect = "/content" +-- cgi-bin +-- sling:internalRedirect = "/scripts" +-- gateway +-- sling:internalRedirect = "http://gbiv.com" +-- (stories) +-- sling:internalRedirect = "/anecdotes/$1"
This would define the following mapping entries:
Regular Expression |
Redirect |
Internal |
Description |
---|---|---|---|
http/example.com.80 |
http://www.example.com![]() |
no |
Redirect all requests to the Second Level Domain to www |
http/www.example.com.80 |
/example |
yes |
Prefix the URI paths of the requests sent to this domain with the string |
http/.+\.example\.com\.80 |
http://www.example.com![]() |
no |
Redirect all requests to sub domains to www. The actual regular expression for the host.port segment is taken from the |
http/localhost\.\d* |
/content |
yes |
Prefix the URI paths with |
http/localhost\.\d*/cgi-bin |
/scripts |
yes |
Replace the |
http/localhost\.\d*/gateway |
http://gbiv.com![]() |
yes |
Replace the ![]() }} for requests to localhost, regardless of actual port the request was received on. |
http/localhost\.\d*/(stories) |
/anecdotes/stories |
yes |
Prepend the URI paths starting with |
Regular Expression matching
As said above the mapping entries are regular expressions which are matched against path. As such these regular expressions may also contain capturing groups as shown in the example above: http/localhost\.\d*/(stories)
. After matching the path against the regular expression, the replacement pattern is applied which allows references back to the capturing groups.
To illustrate the matching and replacement is applied according to the following pseudo code:
String path = request.getScheme + "/" + request.getServerName() + "." + request.getServerPort() + "/" + request.getPathInfo(); String result = null; for (MapEntry entry: mapEntries) { Matcher matcher = entry.pattern.matcher(path); if (matcher.find()) { StringBuffer buf = new StringBuffer(); matcher.appendReplacement(buf, entry.getRedirect()); matcher.appendTail(buf); result = buf.toString(); break; } }
At the end of the loop, result
contains the mapped path or null
if no entry matches the request path
.