The URI-space

routing.js

app.routes = {
	'/*': [
		'manual',
		'templates',
		{
			type: 'cacheControl',
			mediaTypes: {
				'image/*': '1m',
				'text/css': '1m',
				'application/x-javascript': '1m'
			},
			next: {
				type: 'less',
				next: 'static'
			}
		}
	],
	'/example1/': '@example', // (dispatched)
	'/example2/': '/example/' // (captured)
}
​
app.hosts = {
	'default': '/myapp/'
}

app.routes

URI Templates

• Variables are strings wrapped in curly brackets. For example, here is a URI template with two variables: "/profile/{user}/{service}/". The variables will match any text until the next "/". You can access the string values of these variables in your resource as conversation.locals.
• A wildcard can be used as the last character in the URI template. For example, "/archive/*" will match any URI that begins with "/archive/". You can access the captured wildcard via the conversation.wildcard API. Note that Prudence will attempt to match non-wildcard URI templates first, so a wildcard URI template can be used as a general fallback for URIs.

Route Configurations

Resource Route Types

The "manual" route type is internally used by Prudence to handle the "dispatch" route type, via a server-side redirect. This introduces two special limitations on its use. First, it means that you must have a "manual" if you want to use "dispatch." Second, you must make sure the "manual" always appears before any use of "dispatch" in app.routes. For example, if you attach the manual to "/*" in a chain (as in the default application template), and you also want to add a "dispatch" to that chain, you need to put the "manual" before the "dispatch" in the chain. Otherwise, you might cause an endless server-side redirect, leading to a stack overflow error. Example of correct use:

app.routes = {
	'/*': [
		'manual',
		'@example', // must appear after the manual
		...
	],
	...
}

Mapping Route Types

Redirecting Route Types

Combining Route Types

Filtering Route Types

Custom Route Types

1. Create a JavaScript class that:
   1. Implements a create(app, uri) method. The "app" argument is the instance of Prudence.Setup.Application, and the "uri" argument is the URI template to which the route type instance should be attached. The method must return an instance of a Restlet subclass.
   2. Accepts a single argument, a dict, to the constructor. The dict will be populated by the route type configuration dict in app.routes.
2. Add the class to Prudence.Setup. Remember that the class name begins with an uppercase letter, but will begin with a lowercase letter when referenced in app.routes.

document.require('/sincerity/classes/')
​
Prudence.Setup.See = Sincerity.Classes.define(function() {
	var Public = {}
​
	Public._inherit = Prudence.Setup.Restlet
	Public._configure = ['uri']
​
	Public.create = function(app, uri) {
		importClass(org.restlet.routing.Redirector)
		var redirector = new Redirector(app.context, this.uri, Redirector.MODE_CLIENT_SEE_OTHER)
		return redirector
	}
​
	return Public
}())
​
app.routes = {
	...
	'/original-uri/': {type: 'see', uri: 'http://newsite.org/new-uri/'}
}

Two Routing Paradigms

1. Resource mapping (page 1): The filesystem hierarchy under an application's "/resources/" subdirectory is directly mapped to URIs (but not URI templates). Both directory- and file-names are mapped in order of depth. By default, Prudence hides filename extensions from the published URIs, but uses these extensions to extracts MIME-type information for the resources. Also, mapping adds trailing slashes by default, by redirecting URIs without trailing slash to include them (on the client's side). Filesystem mapping provides the most "transparent" management of your URI-space, because you do not need to edit any configuration file: to change URIs, you simply move or rename files and directories.
2. URI/resource separation:
   1. Resource capturing. This use case does not belong to the URI/resource separation paradigm.
   2. Resource dispatching (page 1): In your application's routing.js you can map URIs or URI templates to a custom ID, which is then dispatched to your resource handling code. Dispatching provides the cleanest and most flexible separation between URIs and their implementation.

Resource Mapping

1. For manual and template resources, Prudence hides filename extensions from the URIs by default. Thus, "/resources/myresource.m.js" would be mapped to "/resources/myresource/". The reasons are two: 1) clients should not have to know about your internal implementation of the resource, and 2) it allows for cleaner and more coherent URIs. Note the filename extensions are used internally by Prudence (differently for manual and template resources). Note that this does not apply to static resources: "/resources/images/logo.png" will be mapped to "/images/logo.png".
2. For manual and template resources, Prudence by default requires trailing slashes for URIs. If clients do not include the trailing slash, they will receive a 404 ("not found") error. Again, the reasons are two: 1) it makes relative URIs always unambiguous, which is especially relevant in HTML and CSS, and 2) it clarifies the extent of URI template variables. As a courtesy to sloppy clients, you can manually add a permanent redirection to a trailing slash, using the "addSlash" route type. For example:

   app.routes = {
   	...
   	'/main', 'addSlash',
   	'/person/profile/{id}': 'addSlash'
   }
   

3. This mapped URI-space can be manipulated using URI hiding and capturing, allowing you to support URI templates and rewrite URIs.

Mapping URI Templates

app.routes = {
	...
	'/user/profile/{userId}/': '/user/profile/'
}

<html>
<body>
<p>
User profile for user <%= conversation.locals.get('userId') %>.
</p>
</body>
</html>

app.routes = {
	...
	'/user/profile/{userId}/': '/user/profile/!'
}

app.routes = {
	...
	'/user/profile/{userId}/': '/user/profile/',
	'/user/profile/': '!'
}

Dynamic Capturing

app.routes = {
	...
	'/user/{userId}/preferences/': '/database/preferences/{m}/?id={userId}'
}

app.routes = {
	...
	'/user/*': '/database/user/?id={rw}'
}

app.routes = {
	...
	'/user/{userId}/preferences/': '/database/preferences/{m}/!'
}

app.routes = {
	...
	'/user/{userId}/preferences/': '/database/preferences/{m}/',
	'/database/preferences/GET/': '!',
	'/database/preferences/POST/': '!'
}

Limitations of Resource Mapping

1. In large URI-spaces you may suffer from having too many files. Though you can use "/libraries/" to share code between your resources, mapping still requires exactly one file per resource type.
2. Mapped manual resources must have all their entry points (handleInit, handleGet, etc.) defined as global functions. This makes it awkward to use object oriented programming or other kinds of code reuse. If you define your resources as classes, you would have to hook your class instance via the global entry points.
3. The URI-space is your public-facing structure, but your internal implementation may benefit from an entirely different organization. For example, some resources my be backed by a relational database, others by a memory cache, and others by yet another subsystem. It may make sense for you to organize your code according to subsystems, rather than the public URI-space. For this reason, you would want the URI-space configuration to be separate from your code organization.

URI/Resource Separation

Resource Capturing

app.routes = {
	...
	'/user/{userId}/preferences/': '/database/preferences/',
	'/user/{userId}/profile/': '/database/profile/',
	'/user/{userId}/session/': '/cache/session/'
}

Under the hood: Prudence's capturing mechanism is implemented as server-side redirection (sometimes called "URI rewriting"), with the added ability to use hidden URIs as the destination. It's this added ability that makes capturing useful for URI/resource separation: hidden URIs include both template resource files in your application's "/libraries/includes/" subdirectory as well as URIs routed to the "hidden" route type.

Resource Dispatching

app.routes = {
	...
	'/session/{sessionId}/': '@session',
	'/user/{userId}/preferences/': '@user'
}

app.routes = {
	...
	'/session/{sessionId}/': {
		type: 'dispatch',
		id: 'session',
		dispatcher: null,
		locals: []
	}
}

app.routes = {
	...
	'/session/{sessionId}/': '@session.{p}'
}

var UserResource = function() {
	this.handleInit = function(conversation) {
		conversation.addMediaTypeByName('text/plain')
	}
​
	this.handleGet = function(conversation) {
		return 'This is user #' + conversation.locals.get('userId')
	}
}
​
resources = {
	session: {
		handleInit: function(conversation) {
			conversation.addMediaTypeByName('text/plain')
		},
		handleGet: function(conversation) {
			return 'This is session #' + conversation.locals.get('sessionId')
		}
	},
	user: new UserResource()
}

app.routes = {
	...
	'/session/{sessionId}/': {
		type: 'dispatch',
		id: 'session',
		dispatcher: 'python'
	}
}

app.routes = {
	...
	'/session/{sessionId}/': '@python:session'
}

Inversion of Control (IoC)

app.routes = {
	...
	'/user/{userId}/': {type: 'capture', uri: '/user/', locals: {style: 'simple'}},
	'/user/{userId}/full/': {type: 'capture', uri: '/user/', locals: {style: 'full'}},
	'/user/{userId}/preferences/': {type: 'dispatch', id: 'user', locals: {section: 'preferences'}},
	'/user/{userId}/profile/: {type: 'dispatch', id: 'user', locals: {section: 'profile'}}
}

this.handleGet = function(conversation) {
	var section = conversation.locals.get('section')
	if (section == 'preferences') {
		...
	}
	else if (section == profile') {
		...
	}
}

Pure URI/Resource Separation

app.routes = {
	'/*': [
		'manual',
		'templates',
		'static'
	]
}

app.routes = {
	'/_templates/*': '!templates',
	'/_manual/*': '!manual',
	'/_static/*': '!static',
​
	'/style/*' : '/_static/style/{rw}',
	'/*': '/_templates/page/?id={rw}'
}

app.errors

app.errors = {
	404: '/errors/not-found/',
	500: '/errors/fail/'
}

app.errors = {
	404: '/errors/not-found/!'
}

app.routes = {
	...
	'/errors/not-found/': '!'
}

Warning: If you decide to implement your error pages using a non-static resource, you need to take two things into account. For 404 errors, you must have the resource type handling the page be the first handler in a chain in app.routes. For example, if you are using a template resource, then you must have "templates" first. The reason is that a chain works internally by detecting 404 errors and moving on to the next one: if the first one returns a 404 again, this will result in a recursion and will throw a 500 exception. Second, for any non-static error resource, you want to be very sure that your code there does not throw an exception. If that happens, it would cause a 500 status code, but if the original error was not 500, the result would confuse the user and complicate debugging. However, if the original status code was 500, then it could be much worse: the error would trigger your error resource to be displayed again, which might throw the exception again… resulting in a stack overflow error. Due to these pitfalls, it's probably a good idea to implement your error pages as static resources.

app.hosts

The Bare Minimum

app.hosts = {
	'default': '/myapp/'
}

The Internal Host

app.hosts = {
	'default': '/myapp/',
	internal: '/special/'
}

Multiple Hosts

app.hosts = {
	'default': '/myapp/',
	'privatehost': '/admin/'
}

var host = conversation.host
if (Sincerity.Objects.exists(host) && (host.name == 'privatehost')) {
	...
}

app.dispatchers

Setting the Default Dispatcher

app.routes = {
	'/session/{sessionId}/': '@session'
}
​
app.dispatchers = {
	'default': 'python'
}

Setting the Dispatch Map

app.dispatchers = {
	javascript: '/mylib/mydispatchmap/'
}

app.routes = {
	...
	'/user/{userId}/': '@user',
	'/session/{sessionId}/': '@python:session',
	'/page/{pageId}/': '@groovy:page'
}
​
app.dispatchers = {
	javascript: '/mylib/javascript-dispatchmap/',
	python: '/mylib/python-dispatchmap/',
	groovy: '/mylib/groovy-dispatchmap/'
}

Custom Dispatchers

app.dispatchers = {
	...
	special: {
		dispatcher: '/dispatchers/special-dispatcher/',
		customValue1: 'hello',
		customValue2: 'world'
	}
}

app.dispatchers = {
	...
	javascript: {
		dispatcher: '/dispatchers/my-javascript-dispatcher/',
		resources: '/resources/'
	}
}

app.preheat

• Defrosting: Prudence will by default parse and compile the code for manual and template resources under your application's "/resources/" subdirectory. See configuring applications if you wish to turn this feature off.
• Preheating: This causes an internal "GET" on URIs, which would involve not only compiling the code, but also running it. The response payloads, as well as any errors, are ignored.

app.preheat = [
	'/',
	'/user/x/',
	'/admin/'
]

Executing 3488 startup tasks...
Finished all startup tasks in 1.432 seconds.

Understanding Routing

The Prudence Manual is provided for you under the terms of the Creative Commons Attribution-NonCommercial-ShareAlike 4.0 International License. The complete manual is available for download as a PDF.