The Prudence Manual

Version 2.0-dev14
Main text written by Tal Liron

Part I. Basic Manual

Tutorial

Installing Prudence

Further Exploration

• Start Prudence as a system service
• Logging

At a Glance

/component/

/component/applications/

/component/libraries/scripturian/

/component/libraries/prudence/

/component/libraries/web/

/component/libraries/jars/

/cache/

Further Exploration

• Learn about bootstrapping with Sincerity
• Configure your component

Your First Application

The “prudence” Command

/resources/

/libraries/

/libraries/

Further Exploration

• Configure your application
• Managing the URI-space

Generating HTML

Further Exploration

• Textual Resources
• Adding more languages

A Manual Resource

Further Exploration

• Manual Resources

The URI-space

routing.js

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

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 (page 1↓).
• 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 remainder of the URI via the conversation.reference.remainingPart 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 (page 1↓) 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.Routing.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.Routing. Remember that the class name begins with an uppercase letter, but will begin with a lowercase letter when referenced in app.routes.

Prudence.Routing.See = Sincerity.Classes.define(function() {
	var Public = {}
​
	Public._inherit = Prudence.Routing.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 (page 1↓): Capturing lets you map URI templates to fixed URIs, as well as perform other kinds of internal URI rewrites that are invisible to clients, allowing you to provide a published URI-space, which is different from your internal mapping structure. Note that another common use for capturing is to add support for URI templates in resource mapping, as is explained in resource mapping (page 1↓). 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 scriptlet 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 scriptlet 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 scriptlet 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 (page 1↑). 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/{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 a 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 scriptlet 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: ’javascript’,
		locals: []
	}
}

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

app.dispatchers = {
	javascript: ’/dispatched/’
}

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}/’: ’@python:session’
}
​
app.dispatchers = {
	...
	python: ’/resources/’
}

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’) {
		...
	}
}

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/’
}

if (conversation.reference.baseRef.path == ’/myapp/’) {
	...
}

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 run the risk of the resource code throwing an exception. If that happens, it would cause a 500 status code. If the original error was not 500, then this would confuse the client and complicate debugging. However, if the original status code was 500, then it could be much worse: the error would trigger your error page to be displayed again, which might throw the exception again… resulting in a stack overflow error. For these reasons, it’s probably a good idea to implement your error pages as static resources, at least for production deployments.

app.dispatchers

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 scriptlet resources under your application’s “/resources/” subdirectory. See configuring applications (page 1↓) if you wish to turn this feature off.
• Preheating: This causes an internal (page 1↓) “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/’
]

Implementing Resources

Manual Resources

Mapping vs. Dispatching

handleInit

function handleInit(conversation) {
    conversation.addMediaTypeByName(’application/json’)
    conversation.addMediaTypeByName(’text/plain’) 
}

handleGet

• Numbers: Returns the number as an HTTP status code to the client, with no other content. Usually used for errors. For example, 404 means “not found.” Note that error capturing (page 1↓) can let you take over and return an appropriate error page to the client.
• Arrays of bytes: Used for returning binary representations. Note that some languages (JavaScript, for example) have their own implementations of arrays, which are not exactly compatible with JVM arrays. In such cases, you have to make sure to return JVM arrays. Internally, Prudence represents these values with a ByteArrayRepresentation.
• Representation instances: You can construct and return a Restlet representation directly.
• Other return values: If the conversation.mediaType (page 1↓) is “application/java” the value will be wrapped in an ObjectRepresentation instance. Otherwise, it will be converted into a string if it isn’t a string already, and returned to the client as a textual representation.

handlePost

POST is the only HTTP operation that is not “idempotent,” which means that multiple identical POST operations on a resource may yield different results from a single POST operation. This is why web browsers warn you if you try to refresh a web page that is the result of a POST operation. As such, POST is the correct operation to use for manipulations of a resource that cannot be repeated. See this blog post by John Calcote for an in-depth explanation.

handlePut

PUT, like most HTTP operations, is “idempotent,” which means that multiple identical PUT operations on a resource are expected to yield the same result as a single PUT operation. If you are implementing a “create” operation that cannot be repeated, then you should use POST instead. See note in POST.

handleDelete

• Numbers: Returns the number as an HTTP status code to the client, with no other content. Usually used for errors. For example, 404 means “not found.” Note that error capturing (page 1↓) can let you take over and return an appropriate error page to the client.
• Null: Signifies success.

Note: It’s good practice to always explicitly return null in handleDelete. Some languages return null if no explicit return statement is used. Others, however, return the value of the last executed operation, which could be a number, which would in turn become an HTTP status code for the client. This can lead to some very bizarre bugs, as clients receive apparently random status codes!

handleGetInfo

• Numbers: Considered as Unix timestamps, and converted into the modification date. See conversation.modificationDate (page 1↓).
• JVM Date instances: The modification date. Refer to the Java API documentation for details.
• Strings: Considered as HTTP tags. See conversation.tag (page 1↓).
• Tag instances: You can construct and return your own Restlet tag.
• RepresentationInfo instances: You can construct and return your own Restlet representation info.

1. It could be that you don’t need this optimization. Make sure, first, that you’ve actually identified a problem with performance or scalability, and that you’ve traced it to handleGet on this resource.
2. It could be that you won’t gain anything from this optimization. Caches and other optimizations along the route between your data and your client might already be doing a great job at keeping handleGet as efficient as it could be. If not, improving them could offer far greater benefits overall than a handleGetInfo.
3. It could be that you’ll even hurt your scalability! The reason is that an efficient handleGetInfo implementation would need some mechanism in place to track of data modification, and this mechanism can introduce overhead into your system that causes it to scale worse than without your handleGetInfo.

Controlling the Formats

Client-Side Caching

Server-Side Caching

Integrating Textual Resources

Java Resources

Scriptlet Resources

Scriptlets

Choice of Programming Language

Templating Languages

Markup Languages

Controlling the Format

Server-Side Caching

Client-Side Caching

Scriptlet Plugins

On-the-Fly Scriptlet Resources

app.routes = {
	...
	’/execute/’: ’execute’
}

Because it allows execution of arbitrary code, you very likely do not want its URL publicly exposed. If you use it, make sure to protect its URL on publicly available machines!

curl -v -d "<% println(1+2) %>" "http://localhost:8080/myapp/execute/"

curl -v --data-binary @myscriptfile "http://localhost:8080/myapp/execute/"

<%
document.require(’/sincerity/templates/’)
println(Hello, {0}’.cast(’Linus’))
%>

<%
document.require(’/sincerity/templates/’)
var name = conversation.query.get(’name’) || ’Linus’
println(’Hello, {0}’.cast(name))
%>

curl -v --data-binary @myscriptfile "http://localhost:8080/myapp/execute/?name=Richard"

<%python
name = conversation.query[’name’] or ’Linus’
print ’Hello, %s’ % name
%>

<%
document.require(’/sincerity/json/’)
conversation.mediaTypeName = ’application/json’
println(Sincerity.JSON.to({greeting: ’Hello’}, true))
%>

Static Resources

Configuration

app.routes = {
	’/*’: ’static’
}

app.routes = {
	’/*’: {
		type: ’static’,
		roots: [
			’resources’,
			sincerity.container.getLibrariesFile(’web’)
		],
		listingAllowed: false,
		negotiate: true,
		compress: true,
		compressThreshold: ’1kb’,
		compressExclude: []
	}
}

app.routes = {
	’/*’: [
		{type: ’static’, root: ’resources’},
		{type: ’static’, root: sincerity.container.getLibrariesFile(’web’)}
	]
}

app.routes = {
	’/*’: [
		’manual’,
		’scriptlet’,
		’static’
	]
}

MIME Types and Compression

Client-Side Caching

app.routes = {
	’/*’: {
		type: ’cacheControl’,
		mediaTypes: {
			’image/*’: ’10m’,
			’text/css’: ’10m’,
			’application/x-javascript’: ’10m’
		},
		next: ’static’
	}
}

<img src="/media/logo.png" />

<img src="/media/logo.png?_=1" />

app.routes = {
	’/*’: {
		type: ’cacheControl’,
		mediaTypes: {
			’image/*’: ’farFuture’
		},
		next: ’static’
	}
}

What happens to cache entries that have been marked to expire in 10 years, but are no longer used by your site? They indeed will linger in your client’s web browser cache. This isn’t too bad: web browsers normally are configured with a maximum cache size and the disk space will be cleared and reused if needed. It’s still an inelegant waste, for which unfortunately there is no solution in HTTP and HTML.

JavaScript and CSS Optimization

app.routes = {
	’/*’: {
		type: ’javaScriptUnifyMinify’,
		next: ’static’
	}
}

app.routes = {
	’/*’: {
		type: ’javaScriptUnifyMinify’,
		roots: [
			’resources/scripts’,
			sincerity.container.getLibrariesFile(’web’, ’scripts’)
		],
		next: ’static’
	}
}

/resources/scripts/jquery.js
/resources/scripts/jquery.highlight.js
/resources/scripts/jquery.popup.js

<head>
	...
	<script src="/scripts/all.min.js"></script>
</head>

app.routes = {
	’/*’: {
		type: ’javaScriptUnifyMinify’,
		next: {
			type: ’cssUnifyMinify’,
			next: ’static’
		}
	}
}

<head>
	...
	<link rel="stylesheet" type="text/css" href="/style/all.min.css" />
</head>

ZUSS to CSS

app.routes = {
	’/*’: {
		type: ’zuss’,
		next: ’static’
	}
}

<head>
	...
	<link rel="stylesheet" type="text/css" href="/style/dark/main.min.css" />
</head>

Other Effects

function handleAfter(conversation) {
	var entity = conversation.response.entity
	if (entity.mediaType.name == ’application/pdf’) {
		entity.disposition.type = ’attachment’
	}
}

app.routes = {
	’/*’: {
		type: ’filter’,
		library: ’/filters/download-pdf/’,
		next: ’static’
	}
}

Resource Type Comparison Table

Web Data

Prudence is a minimalist RESTful platform, not a data-driven web framework, though such frameworks are built on top of it. Check out our Diligence, which is a full-blown framework based on Prudence and MongoDB. You may also be interested in the Model-View-Controller (MVC) chapter (page 1↓), which guides you through an approach to integrating data backends.

URLs

Query Parameters

http://mysite.org/myapp/user?name=Albert%20Einstein&enabled=true

document.require(’/prudence/resources/’)
​
var query = Prudence.Resources.getQuery(conversation, {
	name: ’text’,
	enabled: ’bool’
})

var query = Prudence.Resources.getQuery(conversation, {
	name: ’text[]’,
	enabled: ’bool’
})

var query = {
	name: conversation.query.get(’name’),
	enabled: conversation.query.get(’enabled’) == ’true’
}

The Wildcard

Fragments

<a name="top" /><h1>This is the top!</h1>
<p>Click <a href="#top">here</a> to go to the top</p>

conversation.redirectSeeOther(conversation.base + ’#top’)

Request Payloads

document.require(’/prudence/resources/’)
​
var data = Prudence.Resources.getEntity(conversation, ’json’)

document.require(’/sincerity/json/’)
​
var text = conversation.entity.text
var data = Sincerity.JSON.from(text)

MIME Types

var type = conversation.entity.mediaType.name
if (type == ’application/json’) {
	var data = Prudence.Resources.getEntity(conversation, ’json’)
	...
} else if (type == ’image/png’) {
	var data = Prudence.Resources.getEntity(conversation, ’binary’)
	...
}

Consumption

print(conversation.entity.text)
print(conversation.entity.text)

var text = conversation.entity.text
print(text)
print(text)

Parsing Formats

A decent starting point is Restlet’s ecosystem of extensions, which can handle several data formats and conversions. However, these are likely more useful in pure Java Restlet programming, where they can plug into Restlet’s sophisticated annotation-based conversion system. In Prudence, you will usually be applying any generic parsing library to the raw textual or binary data. Still, the Restlet extensions are useful for response payloads (page 1↓).

Cookies

From the Client

var session = conversation.getCookie(’session’)
if (null !== session) {
	print(session.value)
}

• name: (read only)
• version: (integer) per a specific cookie
• value: textual, or text-encoded binary data (note that most clients have strict limits on how much total data is allowed to be stored in all cookies per domain)
• domain: the client should only use the cookie with this domain and its subdomains (web browsers will not let you set a cookie for a domain which is not the domain of the request or a subdomain of it)
• path: the client should only use the cookie with URIs that begin with this path (“/”, the default, would mean to use it with all URIs)

To the Client

var session = conversation.getCookie(’session’)
if (null !== session) {
	session.value = ’newsession’
	session.save()
}

var session = conversation.createCookie(’session’)
session.value = ’newsession’
session.save()

• maxAge: age in seconds, after which the client should delete the cookie; maxAge=0 deletes the cookie immediately, while maxAge=-1 (the default) asks the client to keep the cookie only for the duration of the “session” (this is defined by the client; for most web browsers this means that the cookie will be deleted when the browser is closed)
• secure: true if the cookie is meant to be used only in secure connections (defaults to false)
• accessRestricted: true if the cookie is meant to be used only in authenticated connections (defaults to false)
• comment: some clients store this, some discard it

Security Concerns

Redirection

By Routing

app.routes = {
	...
	’/images/*’: ’>/media/{rr}’
}

By API

conversation.redirectSeeOther(conversation.base + ’/help/’)

In HTML

Go <a href="<%= conversation.base + ’/elsewhere/’ %>">elsewhere</a>.

Server-Side Redirection

HTML Forms

• “get”: The form fields are all turned into query params and appended to the “action” URL. It is important to remember that an HTTP “GET” is idempotent and should not be used to store new data, but rather as a way to represent existing data in a particular way. Actually, “get” forms are not that useful, and are mostly an odd legacy from the early days of the World Wide Web, where “GET” was the only the supported HTTP verb on some platforms. See query parameters (page 1↑) for handling.
• “post”: The form fields are actually encoded in the same way that query params are, but instead of being affixed to the URL, they are sent as the payload with an “application/x-www-form-urlencoded” MIME type. Though you can of course access this payload directly (page 1↑), it is recommended to use the specialized APIs detailed here.

<form action="<%= conversation.base + ’/user/’ %>" method="post">
	<p>Name: <input type="text" name="name"></p>
	<p>Enabled: <input type="radio" name="enabled" value="true"></p>
	<p>Disabled: <input type="radio" name="enabled" value="false"></p>
	<p><button type="submit">Send</button></p>
</form>

document.require(’/prudence/resources/’)
​
var form = Prudence.Resources.getForm(conversation, {
	name: ’text’,
	enabled: ’bool’
})

var form = Prudence.Resources.getForm(conversation, {
	name: ’text[]’,
	enabled: ’bool’
})

var form = {
	name: conversation.form.get(’name’),
	enabled: conversation.form.get(’enabled’) == ’true’
}

Accepting Uploads

<form action="<%= conversation.base + ’/user/’ %>" method="post" enctype="multipart/form-data">
	<p>Name: <input type="text" name="name"></p>
	<p>Upload your avatar (an image file): <input name="avatar" type="file" /></p>
	<p><button type="submit">Send</button></p>
</form>

<%
var name = conversation.form.get(name’)
var tmpAvatar = conversation.form.get(’avatar’).file
​
// The metadata service can provide us with a default extension for the media type
var mediaType = conversation.form.get(’avatar’).mediaType
var extension = application.application.metadataService.getExtension(mediaType)
​
// We will put all avatars under the "/resources/avatars/" directory, so that they
// can be visible to the world
var avatars = new File(document.source.basePath, ’avatars’)
avatars.mkdirs()
var avatar = new File(avatars, name + ’.’ + extension)
​
// Move the file to the new location
tmpAvatar.renameTo(avatar)
%>
<p>Here’s the avatar you uploaded, <%= name %></p>
<img src="<%= conversation.base + ’/avatars/’ + avatar.name %>" />

Response Payloads

Textual and Binary Payloads

function handleGet(conversation) {
	return ’My payload’
}

document.require(’/sincerity/jvm/’)
​
function handleGet(conversation) {
	var payload = Sincerity.JVM.newArray(10, ’byte’)
	for (var i = 0; i < 10; i++) {
		payload[i] = i
	}
	return payload
}

function handleGet(conversation) {
	return String(404)
}

function handleGet(conversation) {
	conversation.statusCode = 404
	return ’Not found!’
}

function handleGet(conversation) {
	conversation.setResponseText(’Not found!’, null, null, null)
	return 404
}

Restlet Data Extensions

function handleGet(conversation) {
	return new org.restlet.representation.StringRepresentation(’My payload’)
}

var payload = new org.restlet.representation.StringRepresentation(’My payload’)
conversation.response.entity = payload

conversation.setResponseText(’My payload’, null, null, null)

Overriding the Negotiated Format

function handleInit(conversation) {
	conversation.addMediaTypeByName(’text/html’)
	conversation.addMediaTypeByName(’text/plain’)
}
​
function handleGet(conversation) {
	if (conversation.query.get(’format’) == ’html’) {
		conversation.mediaTypeName = ’text/html’
	}
	return ’<html><body>My page</body></html>’
}

function handleInit(conversation) {
	conversation.addMediaTypeByNameWithLanguage(’text/html’, ’en’)
	conversation.addMediaTypeByNameWithLanguage(’text/html’, ’fr’)
}
​
function handleGet(conversation) {
	if (conversation.query.get(’language’) == ’fr’) {
		conversation.languageName = ’fr’
	}
	if (conversation.languageName == ’fr’) {
		...
	}
	else {
		...
	}
}

Avoid Serialization for Internal Requests

function handleInit(conversation) {
	conversation.addMediaTypeByName(’application/json’)
	if (conversation.internal) {
		conversation.addMediaTypeByName(’application/java’)
	}
}
​
function handleGet(conversation) {
	var data = ...
	if (conversation.mediaTypeName == ’application/java’) {
		return data
	}
	return Sincerity.JSON.to(data)
}

return new org.restlet.representation.ObjectRepresentation(data)

Browser Downloads

Item,Cost,Sold,Profit
Keyboard,$10.00,$16.00,$6.00
Monitor,$80.00,$120.00,$40.00
Mouse,$5.00,$7.00,$2.00
,,Total,$48.00
<%
conversation.mediaTypeName = ’text/csv’
conversation.disposition.type = ’attachment’
conversation.disposition.filename = bill.csv’
%>

External Requests

It’s not a good idea to send an external request while handling a user request, because it could potentially cause a long delay and hold up the user thread. It would be better to use a background task (page 1↓). A possible exception is requests to servers that you control yourself, and that represent a subsystem of your application. In that case, you should still use short timeouts (page 1↓) and fail gracefully.

document.require(’/prudence/resources/’)
var weather = Prudence.Resources.request({
	uri: ’http://marsweather.ingenology.com/v1/latest/’,
	mediaType: ’application/json’
})
if (null !== weather) {
	print(’The max temperature on Mars today is ’ + weather.report.max_temp + ’ degrees’)
}

var newUser = Prudence.Resources.request({
	uri: ’http://mysite.org/user/newton/’,
	method: ’put’,
	mediaType: ’application/json’,
	payload: {
		type: ’json’,
		value: {
			name: ’Isaac’,
			nicknames: [’Izzy’, ’Zacky’, ’Sir’]
		}
	}
})

document.require(’/sincerity/json’)
var resource = document.external(’http://marsweather.ingenology.com/v1/latest/’)
resource.accept(org.restlet.data.MediaType.valueOf(’application/json’))
result = resource.get()
if (null !== result) {
	weather = Sincerity.JSON.from(result.text)
	print(’The max temperature on Mars today is ’ + weather.report.max_temp + ’ degrees’)
}

Timeout

RESTful Files

var data = Prudence.Resources.request({
	file: ’/tmp/weather.json’,
	mediaType: ’application/json’
})

var data = Prudence.Resources.request({
	uri: ’file:///tmp/weather.json’,
	mediaType: ’application/json’
})

Caching

Introduction: Integrated Caching

Server-Side Caching

document.cacheDuration

document.cacheTags

document.cacheKeyPattern

document.cacheKey

Client-Side Caching

Conditional Requests

Two Caching Strategies

Cautious: Short-Term Caching

app.routes = {
	’/*’: [
		...
		{
			type: ’scriptlet’,
			clientCachingMode: ’conditional’ // this is actually the default
		},
		...
		{
			type: ’cacheControl’,
			mediaTypes: {
				’image/png’: ’1h’,
				’image/gif’: ’1h’,
				’image/jpeg’: ’1h’,
				’text/css’: ’1h’,
				’application/x-javascript’: ’1h’
			},
			next: {
				type: ’zuss’,
				next: ’static’
			}
		}
		...

document.require(’/sincerity/localization/’)
​
app.globals = {
	...
	cacheDuration = ’1m’.toMilliseconds()
}

Confident: Indefinite Caching

app.routes = {
	’/*’: [
		...
		{
			type: ’scriptlet’,
			clientCachingMode: ’offline’,
			maxClientCachingDuration: ’5m’.toMilliseconds()
		},
		...
		{
			type: ’cacheControl’,
			mediaTypes: {
				’image/png’: ’farFuture’,
				’image/gif’: ’farFuture’,
				’image/jpeg’: ’farFuture’,
				’text/css’: ’farFuture’,
				’application/x-javascript’: ’farFuture’
			},
			next: {
				type: ’zuss’,
				next: ’static’
			}
		},
		...

Paranoid: No Caching

app.routes = {
	’/*’: [
		...
		{
			type: ’scriptlet’,
			clientCachingMode: ’disabled’
		},
		...
		{
			type: ’zuss’,
			next: ’static’
		}
		...

Configuring Applications

Prudence, as of version 2.0, does not support live re-configuring of applications. You must restart Prudence in order for changed settings to take hold. The one exception is crontab (page 1↓): changes there are picked up on-the-fly once per minute.

Overview

• settings.js: This required file, detailed in this chapter, includes settings used by Prudence as well as your own custom settings (page 1↓).
• routing.js: This required file defines the application’s URI-space (page 1↑).
• crontab: This optional file defines regularly scheduled background tasks (page 1↓).
• default.js: This required file is used to load the other configuration files above. You should not normally need to edit this file, but feel free to examine it to understand the application bootstrapping process.

settings.js

app.settings = {
	description: {
		name: ’myapp’,
		description: ’Skeleton for myapp application’,
		author: ’The Author’,
		owner: ’The Project’
	},
	errors: {
		debug: true,
		homeUrl: ’http://threecrickets.com/prudence/’, // Only used when debug=false
		contactEmail: ’info@threecrickets.com’ // Only used when debug=false
	}, 
	code: {
		libraries: [’libraries’], // Handlers and tasks will be found here
		defrost: true,
		minimumTimeBetweenValidityChecks: ’1s’,
		defaultDocumentName: ’default’,
		defaultExtension: ’js’,
		defaultLanguageTag: ’javascript’,
		sourceViewable: true
	}, 
	uploads: {
		root: ’uploads’,
		sizeThreshold: ’0kb’
	}, 
	mediaTypes: {
		php: ’text/html’
	}
} 

Numeric Shortcuts

• Durations: numerically as milliseconds, or using ’ms’, ’s’, ’m’, ’h’ or ’d’ suffixes for milliseconds, seconds, minutes, hours or days. Fractions can be used, and are rounded to the nearest millisecond, for example: “1.5d”.
• Data sizes: numerically as bytes, or using ’b’, ’kb’, ’mb’, ’gb’ or ’tb’ suffixes. Magnitude uses the binary rather than decimal system: 1kb = 1024b. Fractions can be used, and are rounded to the nearest byte, for example: “1.5mb”.

app.settings.description

app.settings.errors

Exception Handling

Caching

• X-Cache: the cache event, either “hit” or “miss”
• X-Cache-Expiration: a timestamp in standard HTTP format
• X-Cache-Key: the cache key
• X-Cache-Tags: comma-separated list of cache tags

Scriptlet

app.settings.code

• libraries: An array of paths where importable libraries will be found. If relative, they will be based on the application’s root subdirectory.
• defrost: When true will attempt to “defrost” manual and scriptlet resources under the “/resources/” subdirectory. Defrosting means pre-parsing and sometimes pre-compiling the code: this allows for faster startup times on first hits to these resources. Note that defrosting is not pre-heating: the former only pre-compiles, the latter actually does a “GET” on your resources, which would ensure that services used by your resources are also warmed up. See app.preheat (page 1↑).
• minimumTimeBetweenValidityChecks: Scripturian makes sure to reload (and thus re-compile) code if the source files are changed, for which it compares the file’s modification dates to the cached values. For high-volume deployments, this might involve constantly checking the filesystem, potentially resulting in performance problems on some operating systems. This value allows you to enforce a delay between these checks. It’s a good idea to set it to anything greater than zero.
• defaultDocumentName: When a document name specifies to a directory, Scripturian will internally change the specification to a document with this name in the subdirectory (excluding the extension). Example, if the value is “default” and you are calling “document.require(’/mylibrary/’)” and “/libraries/mylibrary/” is a directory, the it would specify “/libraries/mylibrary/default.*”.
• defaultExtension: If more than one file in a directory has the same name but different extensions, then this extension will be preferred. For example, if the value is “js” and a directory has both “mylibrary.js” and “mylibrary.py”, then the former file will be preferred.
• defaultLanguageTag: If a scriptlet tag does not specify a language, then this value will be the default.

app.settings.uploads

• root: This is where uploaded files are stored. If relative, it will be based on the application’s root subdirectory.
• sizeThreshold: The file upload mechanism can optimize by caching small files in memory instead of saving them to disk. Only if files are greater in size will be they be stored. Set to zero to save all files to disk.

app.settings.mediaTypes

app.settings = {
	...
	mediaTypes: {
		webm: ’video/webm’,
		msh: ’model/mesh’
	}
}

Note for PHP: You may notice that the “default” template’s settings.js sets the “text/html” MIME type for the “php” extension. The reason for this is that “.php” files you put in resources are usually expected to output HTML. You may change if you require a different behavior.

app.globals

app.globals = {
	database: {
		driver: ’mysql’,
		table: {
			db: ’myapp’,
			name: ’users’
		}
	}
}

app.globals = {
	’database.driver’: ’mysql’,
	’database.table.db’: ’myapp’,
	’database.table.name’: ’users’
}

var driver = application.globals.get(’database.driver’)

Lazy Initialization

Programming

Powered by Scripturian

JavaScript

Other Languages

State

application.globals

conversation.locals

1. To easily share conversation-scope state between scriptlets written in different languages.
2. To share state for deferred conversations---see conversation.defer (page 1↓). In such cases, your language’s globals would not persist across the thread boundaries.
3. They are Prudence’s general mechanism for sending state to your code in a conversation. For example, captured URI segments are stored here (page 1↓) as well as document.cacheKeyPattern (page 1↓) variables.

Global Variables

The exception to this is code in /resources/, in which language globals might persist. To improve performance, Prudence caches the global context for these in memory, with the side effect that your language globals persist beyond a single user request. For various reasons, however, Prudence may reset this global context. You should not rely on this side effect, and instead always use application.globals (page 1↑).

application.globals vs. application.sharedGlobals

1. To save resources. For example, if an application detects that a database connection has already been opened by another application in the Prudence instance, and stored in application.sharedGlobals, then it could use that connection rather than create a new one. This would only work, of course, if a few applications share the same database, which is common in many deployments.
2. To send messages between applications. This would be necessary if operations in one application could affect another. For example, you could place a task queue in application.sharedGlobals, where applications could queue required operations. A thread in another application would consume these and act accordingly. Of course, you will have to plan for asynchronous behavior, and especially allow for failure. What happens if the consumer application is down? It may make more sense in these cases to use a persistent storage, such as a database, for the queue.

Note for Clojure flavor: All Clojure vars are VM-wide globals equivalent in scope to executable.globals. You usually work with namespaces that Prudence creates on the fly, so they do not persist beyond the execution. However, if you explicitly define a namespace, then you can use it as a place for shared state. It will then be up to you to make sure that your namespace doesn’t collide with that of another application installed in the Prudence instance. Though this approach might seem to break our rule of thumb here, of preferring application.globals to application.sharedGlobals, it is more idiomatic to Clojure and Lisps generally.

application.sharedGlobals vs. executable.globals

Concurrency

Note for Clojure flavor: Though Clojure goes a long way towards simplifying concurrent programming, it does not solve the problem of concurrent access to global state. You still need to read this section!

def get_connection()
	data_source = application.globals[’myapp.data.source’]
	if data_source is None:
		data_source = data_source_factory.create()
		application.globals[’myapp.data.source’] = data_source
	return data_source.get_connection()

This may seem like a very rare occurrence to you: another thread would have to set the value exactly between our comparison and our set. If your application has many concurrent users, and your machine has many CPU cores, it can actually happen quite frequently. And, even if rare, your application has a chance of breaking if just two users use it at the same time. This is not a problem you can gloss over, even for simple applications.

def get_connection()
	data_source = application.globals[’myapp.data.source’]
	if data_source is None:
		data_source = data_source_factory.create()
		data_source = application.getGlobal(’myapp.data.source’, data_source)
	return data_source.get_connection()

def get_connection()
	lock = application.getGlobal(’myapp.data.source.lock’, RLock())
	lock.acquire()
	try:
		data_source = application.globals[’myapp.data.source’]
		if data_source is None:
			data_source = data_source_factory.create()
			application.globals[’myapp.data.source’] = data_source
		return data_source.get_connection()
	finally:
		lock.release()

def get_connection(lock_access=False)
	if lock_access:
		lock = application.getGlobal(’myapp.data.source.lock’, RLock())
		lock.acquire()
	try:
		data_source = application.globals[’myapp.data.source’]
		if data_source is None:
			data_source = data_source_factory.create()
			if lock_access:
				application.globals[’myapp.data.source’] = data_source
			else:
				data_source = application.getGlobal(’myapp.data.source’, data_source)
		return data_source.get_connection()
	finally:
		if lock_access:
			lock.release()

APIs

Using the Documentation

The Prudence team has spent a great amount of time on meticulously documenting the APIs. Please send us a bug report if you find a mistake, or think that the documentation can use some clarification!

JavaScript: conversation.redirectSeeOther(’http://newsite.org/’)
Python:     conversation.redirectSeeOther(’http://newsite.org/’)
Ruby:       $conversation.redirect_see_other ’http://newsite.org/’
PHP:        $conversation->redirectSeeOther(’http://newsite.org/’);
Lua:        conversation:redirectSeeOther(’http://newsite.org/’)
Groovy:     conversation.redirectSeeOther(’http://newsite.org/’)
Clojure:    (.. conversation redirectSeeOther "http://newsite.org/")

Prudence APIs

Scripturian API

JavaScript Libraries

• /sincerity/calendar/: Sincerity.Calendar
• /sincerity/classes/: Sincerity.Classes
• /sincerity/cryptography/: Sincerity.Cryptography
• /sincerity/files/: Sincerity.Files
• /sincerity/iterators/: Sincerity.Iterators
• /sincerity/json/: Sincerity.JSON
• /sincerity/jvm/: Sincerity.JVM
• /sincerity/localization/: Sincerity.Localization
• /sincerity/lucene/: Sincerity.Lucene
• /sincerity/mail/: Sincerity.Mail
• /sincerity/objects/: Sincerity.Objects
• /sincerity/rhino/: Sincerity.Rhino
• /sincerity/templates/: Sincerity.Templates
• /sincerity/xml/: Sincerity.XML

• /prudence/blocks/: Prudence.Blocks
• /prudence/lazy/: Prudence.Lazy
• /prudence/logging/: Prudence.Logging
• /prudence/resources/: Prudence.Resources
• /prudence/tasks/: Prudence.Tasks

• /sincerity/annotations/: Sincerity.Annotations
• /sincerity/container/: Sincerity.Container
• /prudence/routing/: Sincerity.Routing
• /prudence/lazy/: Sincerity.Lazy

Execution Environments

Bootstrap

Manual Resources and Handlers

Scriptlet Resources

Execute Resource

Cron Tasks

Debugging

Logging

application.logger

application.getSubLogger

Configuring Logging

Debug Page

Live Execution

FAQ

Technology

How is REST different from RPC?

How is Prudence different from Node.js?

Actually, because Prudence uses Jetty as its driver, you have the option to change it to a blocking server, which may behave better in some controlled workloads. See configuring servers (page 1↓). Generally, Jetty is designed from the ground-up for web services, and behaves smartly and exceptionally well under high volumes.

If you like Node.js but JavaScript is not your favorite dynamic language, similarly excellent asynchronous platforms are available: check out Tornado and Twisted for Python, and EventMachine for Ruby.

Performance and Scalability

How well does Prudence perform? How well does it scale?

I heard REST is very scalable. Is this true? Does this mean Prudence can support many millions of users?

Errors

How to avoid the “Adapter not available for language: xml” parsing exception for XML files?

<?xml version=’1.0’ encoding=’UTF-8’?>

<% %><?xml version=’1.0’ encoding=’UTF-8’?>

Licensing

The author is not a lawyer. This is not legal advice, but a personal, and possibly wrong interpretation. The wording of the license itself supersedes anything written here.

Does the LGPL mean I can’t use Prudence unless my product is open sourced?

Why the LGPL and not the GPL?

Part II. Advanced Manual

The Internal URI-space

The RIAP Pseudo-Protocol

• “riap://application/*”: This will route to the current application. The remainder will exactly match the relative URIs you’ve mapped in app.routes (page 1↑).
• “riap://component/{internal host}/*”:

Internal Requests

Configuring the Internal URI-space

Implementing Internal Resources

String Interpolation

• Captured URI targets, via the “capture” route type (page 1↑)
• Redirection URI targets, via the “redirect” route type (page 1↑)
• Cache keys (page 1↑)

Request URIs

Prefixes

• {r-}: actual URI (reference)
• {h-}: virtual host URI
• {o-}: the application’s root URI on the current virtual host
• {f-}: the referring URI (sent by some clients: usually means that the client clicked a hyperlink or was redirected here from elsewhere)

Suffixes

• {-i}: the complete URI (identifier)
• {-h}: the host identifier (protocol + authority)
• {-a}: the authority (for URLs, this is the host or IP address)
• {-p}: the path (everything after the authority)
• {-r}: the remaining part of the path after the base URI (see below)
• {-e}: a relative path from the URI to the application’s base URI (see below; note that this is a constructed value, not merely a string extracted from the URI)
• {-q}: the query (everything after the “?”)
• {-f}: the fragment (the tag after the “#”; note that web browsers handle fragments internally and never send them to the server, however fragments may exist in URIs sent from the server: see the “{R-}” variable mentioned below)

Base URIs

Interpolating the Wildcard

app.routes = {
	...
	’/assets/*’: ’/files/media/{rr}’
}

Request Attributes

• {p}: the protocol (“http,” “https,” “ftp,” etc.)
• {m}: the method (in HTTP, it would be “GET,” “POST,” “PUT,” “DELETE,” etc.)
• {d}: date (as a Unix timestamp)

Client Attributes

• {cia}: client IP address
• {ciua}: client upstream IP address (if the request reached us through an upstream load balancer)
• {cig}: client agent name (for example, and identifier for the browser)

Payload Attributes

• {es}: entity size (in bytes)
• {emt}: entity media (MIME) type
• {ecs}: entity character set
• {el}: entity language
• {ee}: entity encoding
• {et}: entity tag (HTTP ETag)
• {eed}: entity expiration date
• {emd}: entity modification date

Response Attributes

• {S}: the HTTP status code
• {SIA}: server IP address
• {SIP}: server port number
• {SIG}: server agent name
• {R-}: the redirection URI (see “Request URIs” above for a list of suffixes, which must also be in uppercase)

conversation.locals

app.routes = {
	...
	"/person/{id}/": ">http://newsite.org/profile/?id={id}"
}

Model-View-Controller (MVC)

Background

Tutorial

Models

var Models = Models || {}
​
/**
 * Retrieve a person model from the database.
 */
Models.getPerson = function(name) {
	var person = new Models.Person()
	person.setUsername(name)
	return person
}
​
Models.Person = function() {
	this.getUsername = function() {
		return this.username
	}
​
	this.setUsername = function(username) {
		this.username = username
	}
​
	this.getComments = function() {
		return this.comments
	}
​
	this.comments = new Models.Messages()
}
​
Models.Messages = function() {
	this.get = function() {
		return this.messages
	}
​
	this.add = function(message) {
		this.messages.append(message)
	}
​
	this.messages = []
}

Views

There are some who shudder at the thought of mixing dynamic languages and HTML. This likely comes from bad experience with poorly-designed PHP/JSP/ASP applications, where everything gets mixed together into the “view” file. If you’re afraid of losing control, then you can simply make yourself a rule that only templating languages are allowed in scriptlets. It’s purely a matter of project management discipline. We recommend, however, relaxing some of that extremism: for example, you can make the rule that no “business logic” should appear together with HTML, while still allowing some flexibility for using server-side JavaScript, but only for UI-related work. Still unconvinced? We’ll show you below how to use your favorite pure templating engine with Prudence (page 1↓).

<html>
<%
var context = conversation.entity.object
var person = context.person
var comments = person.getComments().get()
%>
<body>
	<p>These are the comments for user: <%= person.getUsername() %></p>
	<table>
<% for (var c in comments) { %>
		<tr><td><%= comments[c] %></td></tr>
<% } %>
	</table>
	<p>You may add a comment here:</p>
	<form>
		<input name="comment" />
		<input type="submit" />
	</form>
</body>
</html>

Presenters

document.require(
	’/models/user/’,
	’/prudence/resources/’,
	’/sincerity/objects/’)
​
function handleInit(conversation) {
	conversation.addMediaTypeByName(’text/html’)
	conversation.addMediaTypeByName(’text/plain’)
}
​
function handleGet(conversation) {
	var name = conversation.locals.get(’name’)
	var person = Models.getPerson(name)
	return getView(’user/comments’, {person: person})
}
​
function handlePost(conversation) {
	var name = conversation.locals.get(’name’)
	var comment = conversation.form.get(’comment’)
	var person = Models.getPerson(name)
	person.getComments().add(comment)
	return getView(’user/comments’, {person: person})
}
​
function getView(view, context) {
   var page = Prudence.Resources.request({
        uri: ’/views/’ + view + ’/’,
        internal: true,
        method: ’post’,
        mediaType: ’text/*’,
        payload: {
            type: ’object’,
            value: context
        }
    })
	return Sincerity.Objects.exists(page) ? page : 404
}

• We can request URIs that are hidden: in this case, anything under “/libraries/includes/”.
• We can transfer “POST” payloads directly using the “object” type.

app.routes = {
	...
	’/user/{name}/comments/’: ’/user/comments!’
}

Implications for Caching

View Templates

StringTemplate Example

sincerity attach maven-central : add org.antlr ST4 : install

document.require(’/sincerity/objects/’)
​
function handleInit(conversation) {
	conversation.addMediaTypeByName(’text/html’)
	conversation.addMediaTypeByName(’text/plain’)
}
​
function handlePost(conversation) {
	if (!conversation.internal) {
		return 404
	}
	var id = String(conversation.locals.get(’com.threecrickets.prudence.dispatcher.id’))
	if (id.endsWith(’/’)) {
		id = id.substring(0, id.length - 1)
	}
	var st = getDir().getInstanceOf(id)
	if (!Sincerity.Objects.exists(st)) {
		return 404
	}
	if (Sincerity.Objects.exists(conversation.entity)) {
		var context = conversation.entity.object
		if (Sincerity.Objects.exists(conversation.context)) {
			for (var key in context) {
				var value = context[key]
				if (Sincerity.Objects.isArray(value)) {
					for (var v in value) {
						st.add(key, value[v])
					}
				}
				else {
					st.add(key, value)
				}
			}
		}
	}
	return st.render()
}
​
function getDir() {
	var dir = new org.stringtemplate.v4.STRawGroupDir(application.root + ’/libraries/views/’)
	dir.delimiterStartChar = ’$’
	dir.delimiterStopChar = ’$’
	return dir
}

• We’ve allowed only internal requests through: we want to hide this dispatcher from the public URI space because it should only accessed by our presenters.
• We’re stripping trailing slashes from the ID because STRawGroupDir doesn’t support them.
• We’ve switched to the older “$” delimiters because the default “<” and “>” delimiters are awkward to use with HTML.
• STRawGroupDir does not pick up template file changes on-the-fly, so we’re recreating it per request. Because it caches compiled templates, it would be more efficient to make it a global, but they you would have to find an alternative way for invalidating it for live application edits.

app.routes = {
	...
	’/views/*’: ’@st:{rr}’
}
​
app.dispatchers = {
	...
	st: {
		dispatcher: ’/dispatchers/st/’
	}
}

<html>
<body>
	<p>These are the comments for user: $username$</p>
	<table>
		$comments:{c | <tr><td>$c$</td></tr>}$
	</table>
</body>
</html>

comments(username, comments) ::= <<
<html>
<body>
	<p>These are the comments for user: $username$</p>
	<table>
		$comments:row()$
	</table>
</body>
</html>
>>
​
row(content) ::= <<
<tr><td>$content$</td></tr>
>>

var person = Models.getPerson(name)
...
return getView(’comments’, {
	username: person.getUsername(),
	comments: person.getComments().get()
})

Jinja2 Example

sincerity add python : install : easy_install Jinja2==2.6 simplejson

Note that Jinja2 version 2.7 doesn’t work in Jython (might be fixed for version 2.8), but version 2.6 does, so that’s what we use here.

import simplejson, urllib
from org.restlet.representation import ObjectRepresentation
​
def handle_init(conversation):
    conversation.addMediaTypeByName(’text/html’)
    conversation.addMediaTypeByName(’text/plain’)
​
def handle_post(conversation):
    if not conversation.internal:
        return 404
    id = conversation.locals[’com.threecrickets.prudence.dispatcher.id’]
    if id[-1] == ’/’:
        id = id[0:-1]
    id += ’.html’
    context = {}
    if conversation.entity:
        if conversation.entity.mediaType.name == ’application/java’:
            context = conversation.entity.object
        else:
            context = conversation.entity.text
            if context:
                context = simplejson.loads(context)
    payload = ObjectRepresentation({
        ’context’: context,
        ’uri’: str(conversation.reference),
        ’base_uri’: str(conversation.reference.baseRef)})
    resource = document.internal(’/jinja-template/’ + urllib.quote(id, ’’) + ’/’, ’text/html’)
    result = resource.post(payload)
    if not result:
        return 404
    return result.text

• We’ve allowed only internal requests through: we want to hide this dispatcher from the public URI space because it should only be accessed by our presenters.
• Jinja2’s FileSystemLoader requires the full filename, so we’re stripping trailing slashes and adding “.html”.
• We’re forwarding a few useful attributes of the request: the original URI and the original base URI. We’ll show you later how to use those for our custom tags.
• We’re supporting “application/java” payloads (page 1↑), but also JSON payloads. Avoiding serialization is fine for Python-to-Python calls, but if we call from another programming language---say, JavaScript---the native structures are incompatible. Thus, we’re allowing the use of JSON as an interchange format. On the other side, when we send the payload to “/jinja-template/”, it’s fine to send a raw object, because it’s Python-to-Python.

<%python
import urllib
from jinja2 import Environment, FileSystemLoader
from jinja2.exceptions import TemplateNotFound
from os import sep
​
id = urllib.unquote(conversation.locals[’id’])
payload = conversation.entity.object
context = payload[’context’]
​
loader = application.globals[’jinaj2.loader’]
if not loader:
    loader = FileSystemLoader(application.root.path + sep + ’libraries’ + sep + ’views’)
    loader = application.getGlobal(’jinja2.loaded’, loader)
env = Environment(loader=loader)
​
try:
    template = env.get_template(id)
    print template.render(context)
except TemplateNotFound:
    conversation.statusCode = 404
%>

app.routes = {
	...
	’/views/*’: ’@jinja:{rr}’,
	’/jinja-template/{id}/’: ’/jinja-template/!’
}
​
app.dispatchers = {
	...
	jinja: {
		dispatcher: ’/dispatchers/jinja/’
	}
}

<html>
<body>
	<p>These are the comments for user: {{username}}</p>
	<table>
{% for comment in comments %}
		<tr><td>{{comment}}</td></tr>
{% endfor %}
	</table>
</body>
</html>

function getView(view, context) {
   var page = Prudence.Resources.request({
        uri: ’/views/’ + view + ’/’,
        internal: true,
        method: ’post’,
        mediaType: ’text/*’,
        payload: {
            type: ’json’,
            value: context
        }
    })
	return Sincerity.Objects.exists(page) ? page : 404
}

from jinja2 import nodes
from jinja2.ext import Extension
from org.restlet.data import Reference
​
class Prudence(Extension):
    # a set of names that trigger the extension
    tags = set([’current_uri’, ’application_uri’, ’to_base’, ’cache_duration’, ’cache_tags’])
​
    def __init__(self, environment):
        super(Prudence, self).__init__(environment)
​
        # add the defaults to the environment
        environment.extend(
            prudence_document=None,
            prudence_uri=None,
            prudence_base_uri=None
        )
​
    def parse(self, parser):
        token = parser.stream.next()
        tag = token.value
        lineno = token.lineno
        
        if tag == ’current_uri’:
            return _literal(self.environment.prudence_uri, lineno)
​
        elif tag == ’application_uri’:
            return _literal(self.environment.prudence_base_uri, lineno)
​
        elif tag == ’to_base’:
            base = Reference(self.environment.prudence_base_uri)
            reference = Reference(base, self.environment.prudence_uri)
            
            # reverse relative path to the base
            relative = base.getRelativeRef(reference).path
            
            return _literal(relative, lineno)
​
        elif tag == ’cache_duration’:
            duration = parser.parse_expression().as_const()
            self.environment.prudence_document.cacheDuration = duration
​
        elif tag == ’cache_tags’:
            tags = [parser.parse_expression().as_const()]
            while parser.stream.skip_if(’comma’):
                tags.append(parser.parse_expression().as_const())
​
            cache_tags = self.environment.prudence_document.cacheTags
            for tag in tags:
                cache_tags.add(tag)
            
        return _literal(’’, lineno)
​
def _print(text, lineno):
    return nodes.Output([nodes.TemplateData(text)]).set_lineno(lineno)

env = Environment(loader=loader, extensions=[’jinja_extensions.Prudence’])
env.prudence_document = document
env.prudence_uri = payload[’uri’]
env.prudence_base_uri = payload[’base_uri’]

<html>
{% cache_duration 5000 %}
{% cache_tags ’tag1’, ’tag2’ %}
<body>
<p>This page is cached for 5 seconds.</p>
<p><b>current_uri</b>: {% current_uri %}</p>
<p><b>application_uri</b>: {% application_uri %}</p>
<p><b>to_base</b>: {% to_base %}</p>
</body>
</html>

RESTful Models

Tutorial

document.require(
	’/models/user/’,
	’/sincerity/json’)
​
function handleInit(conversation) {
	conversation.addMediaTypeByName(’application/json’)
	if (conversation.internal) {
		conversation.addMediaTypeByName(’application/java’)
	}
}
​
function handleGet(conversation) {
	var name = conversation.locals.get(’name’)
	var person = Models.getPerson(name)
	var result = {
		username: person.getUsername(),
		comments: person.getComments().get()
	}
	return conversation.mediaTypeName == ’application/java’ ? result : Sincerity.JSON.to(result)
}
​
function handlePost(conversation) {
	var name = conversation.locals.get(’name’)
	var payload = Sincerity.JSON.from(conversation.entity.text)
	if (payload.comment) {
		var person = Models.getPerson(name)
		person.getComments().add(comment)
		var result = {
			username: person.getUsername(),
			comments: person.getComments().get()
		}
		return conversation.mediaTypeName == ’application/java’ ? result : Sincerity.JSON.to(result)
	}
	return 400
}

function handleGet(conversation) {
	var name = conversation.locals.get(’name’)
	var person = getModel(’person/’ + encodeURIComponent(name))
	return getView(’comments’, {person: person})
}
​
function handlePost(conversation) {
	var name = conversation.locals.get(’name’)
	var comment = conversation.form.get(’comment’)
	var person = postModel(’person/’ + encodeURIComponent(name), {comment: comment})
	return getView(’comments’, {person: person})
}
​
function getModel(model) {
   return Prudence.Resources.request({
        uri: ’/models/’ + model + ’/’,
        internal: true
    })
}
​
function postModel(model, payload) {
   return Prudence.Resources.request({
        uri: ’/models/’ + model + ’/’,
        internal: true,
        method: ’post’
        payload: {
            type: ’object’,
            value: payload
        }
    })
}

app.routes = {
	...
	’/models/person/{name}/’: ’/models/person/!’
}

Background Tasks

crontab

startup

Task API

Filtering

Tutorial

app.routes = {
	...
	’/*’: {
		type: ’filter’,
		library: ’/my-filter/’,
		next: [
			’manual’,
			’scriptlet’,
			’static’
		]
	}
}

function handleAfter(conversation) {
	application.logger.info(’We got a request for a resource at: ’ + conversation.reference)
}

function handleBefore(conversation) {
	application.logger.info(’We got a request for a resource at: ’ + conversation.reference)
	return ’continue’
}

• “continue” or 0: Continue to the “next” handler
• “skip” or 1: Skip the “next” route type and go immediately to our own handleAfter
• “stop” or 2: Stop our handling altogether: the same as “skip,” but handleAfter is not called (note that if a filter was installed before us, it would still be called)

Examples

Changing the Request

function handleBefore(conversation) {
	conversation.client.acceptedEncodings.clear()
	return ’continue’
}

Overriding the Response

function handleAfter(conversation) {
	if (!isAuthorized(conversation)) {
		var content = ’<html><body>’ + conversation.reference + ’ is blocked to you!</body></html>’
		conversation.setResponseText(content, ’text/html’, ’en’, ’UTF-8’)
	}
}
​
function isAuthorized(conversation) {
	var cookie = conversation.getCookie(’admin’)
	return (null !== cookie) && (cookie.value == ’magic123’)
}

function handleAfter(conversation) {
	if (!isAuthorized(conversation)) {
		conversation.redirectSeeOther(conversation.base + ’/blocked/’)
	}
}

Note on changing the response: You might think that filters could be useful to affect the content of responses, for example to “filter out” inappropriate language in HTML pages. Actually, Prudence filters are not a good way to do this, because there’s no guarantee that response payloads returned from resources are textual, even if the content is text: they could very well be compressed (gzip) and also chunked. You would then need to decode, disassemble, make your changes, and then reassemble such responses, which is neither trivial nor efficient. Content filtering should best be handled at the level of the resource code itself, before the response payload is created.

Side Effects

document.require(’/sincerity/templates/’)
​
importClass(
	java.util.concurrent.ConcurrentHashMap,
	java.util.concurrent.atomic.AtomicInteger)
​
var logger = application.getSubLogger(’statistics’)
​
function handleBefore(conversation) {
	var agent = conversation.client.agentName
	var os = conversation.client.agentAttributes.get(’osData’)
​
	getCounter(’agent’, agent).incrementAndGet()
	getCounter(’os’, os).incrementAndGet()
​
	logger.info(’Agent stats: ’ + application.globals.get(’counters.agent’))
	logger.info(’OS stats: ’ + application.globals.get(’counters.os’))
​
	return ’continue’
}
​
function getCounter(section, name) {
	var counters = application.getGlobal(’counters.’ + section, new ConcurrentHashMap())
	var counter = counters.get(name)
	if (null === counter) {
		counter = new AtomicInteger()
		var existing = counters.putIfAbsent(name, counter)
		if (null !== existing) {
			counter = existing
		}
	}
	return counter
}

Built-in Filters

Inversion of Control (IoC) via Injection

app.routes = {
	...
	’/user/{name}/’: {
		type: ’injector’,
		locals: {
			deployment: ’production’
		},
		next: ’@user’
	}
}

var deployment = conversation.locals.get(’deployment’)
if (deployment == ’production’) {
	...
}

You can inject any kind of object using an injector, though keep in mind that the native types of JavaScript may not be easily accessible in other programming languages. For example, if you’re injecting a dict or an array, it would not be automatically converted to, say, a Python dict or vector. However, primitive types such as strings and numbers would be OK for all supported languages.

app.routes = {
	...
	’/user/{name}/’: {
		type: ’injector’,
		locals: {
			protocol: new org.restlet.routing.Template(’{p}’),
			deployment: ’production’
		},
		next: ’@user’
	}
}

HTTP Authentication

app.routes = {
	...
	’/*’: {
		type: ’httpAuthenticator’,
		realm: ’Authorized users only!’,
		credentials: {
			moderator: ’moderatorpassword’,
			admin: ’adminpassword’
		},
		next: [
			’manual’,
			’scriptlet’
		]
	}
}

Configuring the Component

/component/servers/

/component/clients/

/component/hosts/

/component/services/

/component/services/prudence/caching

/component/services/prudence/distributed

/component/services/prudence/executor

/component/services/log

/component/services/prudence/singleton

/component/services/prudence/scheduler

/component/services/prudence/status

/component/services/prudence/version

/component/templates/

Servers and Hosts

Configuring Servers

var server = new Server(Protocol.HTTP, 8080)
server.name = ’myserver’
component.servers.add(server)

server.address = [string]

server.context.parameters.set(’minThreads’, ’6’)
server.context.parameters.set(’maxThreads’, ’12’)

server.context.parameters.set(’type’, ’1’) // blocking NIO

Secure Servers (HTTPS)

var server = new Server(Protocol.HTTPS, 443)
server.name = ’secure’
component.servers.add(server)
​
// Configure it to use our security keys
server.context.parameters.set(’keystorePath’, ’/path/prudence.jks’)
server.context.parameters.set(’keystorePassword’, ’mykeystorepassword’)
//server.context.parameters.set(’keyPassword’, ’mykeypassword’)
​
// Add support for the X-FORWARDED-FOR header used by proxies
server.context.parameters.set(’useForwardedForHeader’, ’true’)

keytool -keystore /path/prudence.jks -alias mykey -genkey -keyalg RSA

keytool -importkeystore -srcstoretype PKCS12 -srckeystore /path/prudence.pkcs12 -destkeystore /path/prudence.jks

openssl pkcs12 -inkey /path/mykey.key -in /path/mykey.crt -export -out /path/prudence.pkcs12 

if (conversation.reference.schemeProtocol.name == ’HTTPS’) {
	...
}

Configuring Hosts

var host = new VirtualHost(component.context)
host.name = ’privatehost’
component.hosts.add(host)

host.resourceScheme = [string]
host.resourceDomain = [string]
host.resourcePort = [string]
host.serverAddress = [string]
host.serverPort = [string]
host.hostScheme = [string]
host.hostDomain = [string]
host.hostPort = [string]

• “resourceScheme”, “resourceDomain” and “resourcePort” refer to the actual incoming URI. Thus “resourcePort” would be meaningful only if URIs explicitly include a port number. To match a host to a specific server you would likely want to use “serverPort”.
• “hostScheme”, “hostDomain” and “hostPort” are for matching the “Host” HTTP header used by some proxies.

The Hungry Host

• 1-public.js
• 2-private.js
• 3-default.js (this is the hungry host)

Deploying Multiple Sites

1. Possibly simpler deployment: you are using a single base directory for the entire project, which might be easier for you. Because all configuration is done by JavaScript inside the container, it is very flexible.
2. Less memory use than running multiple JVMs.
3. Shared memory: you can use application.sharedGlobals to share state between applications.

1. Possibly simpler deployment: several base directories can mean separate code/distribution repositories, which might be easier for you. Configuration will be at your web frontend (reverse proxy).
2. Robustness: crashes/deadlocks/memory leaks in one VM won’t affect others. With this in mind, it may even be worth having each single application running in its own JVM/container.
3. Run-time flexibility: you can restart the JVM for one container without affecting others that are running.

Well, there are caveats to that statement: Linux can group threads per running process for purposes of prioritization, but this is only really done for desktop applications. The feature could be possibly useful when running several containers, if you want to guarantee high thread priority to one of the containers over the others. Any of this would only effect very high concurrency and highly CPU-bound deployments.

Routing In-Depth

Working in a Cluster

Distributed Globals

Task Farming

Deploying

The Joys of Sincerity

Configuration-by-Script

Plugins

Deployment Strategies

Synchronization

Packaging

Version Control

Directory Organization

Sincerity Standalone

Operating System Service

Monitoring

Security

SSL

HTTP Authentication

Locked-Down User

Firewall

Proxying

Nginx

Apache

The “Host” Header

Deploying Clusters

Loadbalancing

Security Concerns

Configuring Hazelcast

Cache Backends

Utilities for Restlet

Utility Restlets

• CacheControlFilter: A Filter that adds cache control directives to responses.
• Injector: A Filter that adds values to the request attributes before moving to the next restlet. It allows for a straightforward implementation of IoC (Inversion of Control).
• StatusRestlet: A restlet that always sets a specific status and does nothing else.

Client Data

• CompressedStringRepresentation: This is a ByteArrayRepresentation that can be constructed using text and an encoding, which it then compresses into bytes according the encoding. This is an alternative to using an Encoder filter, allowing you direct control over and access to the final representation.
• ConversationCookie: A modifiable extension of a regular Cookie. Tracks modifications, and upon calling save() stores them as a CookieSetting, likely in the Response. Also supports cookie deletion via remove().
• FormWithFiles: A form that can parse MediaType.MULTIPART_FORM_DATA entities by accepting file uploads. Files will appear as parameters of type FileParameter.

Redirection

• CapturingRedirector: A Redirector that keeps track of the captured reference.
• NormalizingRedirector: A Redirector that normalizes relative paths. This may be unnecessary in future versions of Restlet. See Restlet issue 238.

Fallback Routing

• Fallback: A restlet that delegates Restlet.handle(Request, Response) to a series of targets in sequence, stopping at the first target that satisfies the condition of wasHandled. This is very useful for allowing multiple restlets a chance to handle a request, while “falling back” to subsequent restlets when those “fail.”
• FallbackRouter: A Router that takes care to bunch identical routes under Fallback restlets.

Resolver Selection

• ResolvingTemplate: A Template that allows control over which Resolver instances it will use.
• ResolvingRedirector: A Redirector that uses ResolvingTemplate.
• ResolvingRouter: A Router that uses ResolvingTemplate for all routes.

Web Filters

• CssUnifyMinifyFilter: A Filter that automatically unifies and/or compresses CSS source files, saving them as a single file. Unifying them allows clients to retrieve the CSS via one request rather than many. Compressing them makes their retrieval faster. Compression is done via CSSMin.
• JavaScriptUnifyMinifyFilter: A Filter that automatically unifies and/or compresses JavaScript source files, saving them as a single file. Unifying them allows clients to retrieve the JavaScript via one request rather than many. Compressing them makes their retrieval faster. Compression is done via John Reilly's Java port of Douglas Crockford’s JSMin.
• ZussFilter: A Filter that automatically parses ZUSS code and renders CSS. Also supports minifying files, if the “.min.css” extension is used.
• CustomEncoder: A more localized alternative to using the EncoderService.

Upgrading from Prudence 1.1

Upgrading Applications

1. Start with a new application based on the default template.
   1. Rename old application (add “-old”), for example: “myapp-old”
   2. Use the “prudence” tool to create a new application for your application name:

      sincerity prudence create myapp
      

2. Copy over individual settings from settings.js, using the new manual (page 1↑) to find equivalences.
3. Redo your routing.js, using the new manual (page 1↑) to find equivalences. Prudence 2.0 uses a far more powerful and clearer routing configuration.
4. Rename “/resources/” files to add a “.m.” pre-extension (they are now called “manual resources”). Under Unix-like operation systems, you can rename the all files in the tree via a Perl expression using something like this:

   find . -name "*.js" -exec rename -v ’s/\.js$/\.m.js/i’ {} \;
   

5. Rename “/web/dynamic/” files to add a “.s.” pre-extension (they are now called “scriptlet resources”). Under Unix-like operation systems, you can rename the all files in the tree via a Perl expression using something like this:

   find . -name "*.html" -exec rename -v ’s/\.html$/\.s.html/i’ {} \;
   

6. Merge “/web/dynamic/” and “/web/static/” into “/resources/”.
7. Move “/web/fragments/” to “/libraries/includes”.

Upgrading the Component

Part III. Articles

The Case for REST

Resources

Identifiers

/animal/dog/3/
/animal/cat/12/image/
/animal/cat/12/image/large/
/animal/cat/12/specs/

Delete

Read

Update

Create

Create: /animal/cat/13/ -> Error, already exists
Create: /animal/cat/14/ -> Error, already exists
Create: /animal/cat/15/ -> Error, already exists
...
Create: /animal/cat/302041/ -> Success!

Read: /animal/cat/next/ -> 14
Create: /animal/cat/14/ -> Oops, someone else beat us to 14!
Read: /animal/cat/next/ -> 15
Create: /animal/cat/15/ -> Success!

Create: /animal/cat/ -> We send the data for the cat without the ID, and get back the same cat with an ID

Aggregate Resources

/animal/cats/

/animal/cats/100/200/

Read(100, 200): /animal/cats/

Formats

Read(UTF-8, Russian): /animal/cat/13/

Shared State

Summary of Features

Transactions… Not!

Let’s Do It!

The Punchline

It’s important to note a dependency and possible limitation of HTTP: it is bound to TCP/IP. Indeed, all identifiers are URLs: Uniform Resource Locators. In URLs, the first segment is reserved for the domain, either an IP address or a domain name translatable to an IP address. Compare this with the more general URIs (Uniform Resource Identifiers), which do not have this requirement. Though we’ll often be tied to HTTP in REST, you’ll see the literature attempting, at least, to be more generic. There are definitely use cases for non-HTTP, and even non-TCP/IP addressing schemes. In Prudence, it’s possible to address internal resources with URIs that are not URLs; see internal APIs (page 1↓).

It’s All About Infrastructure

Does REST Scale?

Prudence

URI-space Architecture

Nouns vs. Verbs

• Good: “/service/{id}/status/”
• Bad: “/service/{id}/start/”, “/service/{id}/stop/”

Do You Really Need REST?

Hierarchies

1. A descendant resource belongs to its ancestor, such that resources have cascading relationships in the hierarchy. This implies two rules:
   1. Operations on a resource may affect descendants. This rule is most obvious when applied to the DELETE verb: for example, if you delete “/user/{id}/”, then it is expected that the resources at “/user/{id}/profile/” and “/user/{id}/preferences/” also be deleted. A PUT, too, would also affect the descendant resources.
   2. Operations on a resource should not affect ancestors. In other words, a descendant’s state is isolated from its ancestors. For example, if I send a POST to “/user/{id}/profile/”, the representation at “/user/{id}/” should remain unaltered.
2. A descendant resource belongs to its ancestor and also represents an aspect of its ancestor, such that operations on a resource can be fine-tuned to particular aspects of it. This implies three rules:
   1. Descendant representations are included in ancestor representations. For example, a GET on “/service/{id}/” would include information about the status that you would see if you GET on “/service/{id}/status/”. The latter URI makes it easier for the client to direct operations at the status aspect.
   2. Operations on a resource may affect descendants. See above.
   3. Operations on a resource will affect ancestors. This is the opposite of the above: the descendant’s state is not isolated from its ancestors. For example, a POST to “/service/{id}/status/” would surely also affect “/service/{id}/”, which includes the status.

Formats

Plural vs. Singular

/animal/cat/12/ -> Just one cat
/animal/cat/ -> All cats

/animal/cat/12/ -> Just one cat
/animal/cats/ -> All cats

Documenting Your URI-Space

/*
 * This resource represents a service running on the server. Servers have unique
 * IDs defined by integers. A service can be either active or inactive.
 *
 * Use POST to change the name or status of an existing service. You may
 * not use it change the ID of an existing service. PUT will create a new
 * service, and DELETE will stop and remove it.
 *
 * Implementation note: if you PUT a service with an ID that already exists, then
 * it will only stop and restart the service rather than removing/recreate it,
 * which would be too resource intensive. Use DELETE if you absolutely need the
 * service to be removed first, or set the "clean" query param to "true" to
 * force removal.
 *
 * @URI /service/{id:decimal}/
 * @Aspect /service/{id:decimal}/status/
 * @Verb GET, POST, PUT, DELETE
 * @MediaType application/json, application/xml, text/plain = as JSON
 * @Query {decimal} indent If non-zero will return a human-readable indented version
 *          of the representation with lines indented by the integer value
 * @Query {boolean} clean If "true" or "yes" or "1" wil force removal of an existing
 *         service during a PUT operation on an existing service
 *
 * @Representation {application/json}
 *  {
 *   "id": number,
 *   "name": string (the service name),
 *   "status": string:"active"|"inactive"
 *  }
 *
 * @Payload {application/json}
 *  {
 *   "name": ...
 *   "status": ...
 *  }
 */
​
/*
 * This resource represents the status of a service. 
 *
 * DELETE on this resource is identical to PUT or POST with "inactive".
 * PUT and POST are handled identically.
 *
 * @URI /service/{id:decimal}/status/
 * @AspectOf /service/{id:decimal}/
 * @Verb GET, POST, PUT, DELETE
 * @MediaType text/plain
 *
 * @Representation {text/plain}
 *   "active"|"inactive"
 */

Scaling Tips

Performance Does Not Equal Scalability

1. Performant Can Mean Less Scalable

2. Wasted Effort

Pitfalls

Speed of execution can actually help scalability in its financial aspect: If your application servers are constantly at maximum CPU load, then a faster execution platform would let you cram more web threads into each server. This could help you reduce costs. For example, see Facebook's HipHop: they saved millions by translating their PHP code to C. Because Prudence is built on the fast JVM platform, you’re in good hands in this respect. Note, however, that there’s a potential pitfall to high performance: more threads per machine would also mean more RAM requirements per machine, which also costs money. Crunch the numbers and make sure that you’re actually saving money by increasing performance. Once again, performance does not equal scalability.

Analysis

Optimizing for Scalability

Requests are hot potatoes: Pass them on!

It’s better to have many short requests than one long one.

Caching

Note that even very small cache durations can make a big difference in application stability. Consider it the maximum throttle for load. For example, a huge sudden peak of user load, or even a denial-of-service (DOS) attack, might overrun your thread pool. However, a cache duration of just 1 second would mean that your page would never be generated more than once every second. You are instantly protected against a destructive scenario.

Cache Warming

1. Consider mechanisms to make sure that your warmer does not overload your system or take too much bandwidth from actual users. The best warmers are adaptive, changing their load according to what the servers can handle. Otherwise, consider shutting down your site for a certain amount of time until the cache is sufficiently warm.
2. If the scope is very large, you will have to pick and choose which pages to warm up. In Prudence, this is supported via app.preheat (page 1↑). You would want to choose only the most popular pages, in which case you might need a system to record and measure popularity. For example, for a blog, it’s not enough just to warm up, say, the last two weeks of blog posts, because a blog post from a year ago might be very popular at the moment. Effective warming would require you to find out how many times certain blog posts were hit in the past two weeks. It might make sense to embed this auditing ability into the cache backend itself.

Pre-Filling the Cache

1. It may be that of the thousands of organization schemes only a few are commonly used, so it’s worth caching the output of just those.
2. It could be that these schemes are similar enough to each other that you could generate them all in one operation, and save them each separately in the cache. Even if cache entries will barely be used, if they’re cheap to create, it still might be worth creating them.

Prudence is a “frontend” platform, in that it does not specify which data backend, if at all, you should use. Its cache, however, is general purpose, and you can store in it anything that you can encode as a string.

Caching the Data Backend

Cache Backends

Actually, Hazelcast offers fail-safe, live backups. While it’s not quite as permanent as a database, it might be good enough for your needs. And memcached has various plugins that allow for real database persistence, though using them would require you to deal with the scalability challenges of database backends (page 1↓).

Client-Side Caching

Actually, doing a poor job with client-side caching can help you scale: users will hate your site and stop using it---voila, less hits you have to deal with. OK, that was a joke!

Upstream Caching

1. Decoupling caching logic from your application means losing many features. For example, invalidating portions of the cache is difficult if not impossible. It’s because of upstream caching, indeed, that so many web sites do a poor job at showing up-to-date information.
2. Filtering actually implements a kind of partitioning, but one that is vertical rather than horizontal. In horizontal partitioning, a “switch” decides to send requests to one cluster of servers or another. Within each cluster, you can control capacity and scale. But in vertical partitioning, the “filter” handles requests internally. Not only is the “filter” more complex and vulnerable than a “switch” as a frontend connector to the world, but you’ve also complicated your ability to control the capacity of the caching layer. It’s embedded inside your frontend, rather than being another cluster of servers. We’ll delve into backend partitioning (page 1↓) below.

Dealing with Lengthy Requests

Deferrable Tasks

Necessary Tasks

File Uploads

Asynchronous Request Processing

1. Requests for which processing is made of independent operations. (They’ll likely be required to work in sequence, but if they can be processed in parallel, even better!)
2. Requests that must access backend services with non-deterministic response times.

Backend Partitioning

Reads vs. Writes

By Feature

By Section

Coding Tips for Partitioning

def get_blogger_profile(user_id):
	connection = blogger_pool.get_connection()
	...
	connection.close()
​
def get_blog_post_and_comments(blog_post_id):
	shard_id = object.id % 3
	connection = blog_pools[shard_id].get_connection()
	...
	connection.close()

Data Backends

Graph Databases

Document Databases

We’ve started a project to better integrate Prudence JavaScript with MongoDB. It is included in the “Savory JavaScript” edition.

Column Databases

Best of All Worlds