Handler API

While I'm going to focus on Lua and Javascript to avoid too much fragmentation, a goal in this project is to eventually support a wide plethora of languages as handlers. Perhaps someday even stuff like NaCL, although Lua's surprising speed heads that need off for awhile.

A handler is a resource in a DEJE document that deals with events and can access other resources. Generally, these will be languages that work well in sandboxed interpreters. The default handler locations are:

• /handler
• /handler.lua
• /handler.js

The document has a "_handler" property that contains the path to the document's handler resource. So, generally, mydocument._handler will be one of those three options. This can be changed with document.set_handler(). You can quickly grab the handler resource with document.handler.

The interpreter is chosen based on the resource type, never the filename, never guessed based on magic numbers or hashbangs or similar complex voodoo. Simple is saner than automagic. If document.handler.type is 'text/javascript', the V8 interpreter will be used. If 'text/lua', then the Lua interpreter will be used. At the time of this writing, only the Lua interpreter works, and it does not have any security features.

Your handler will have a limited set of globals to work with, dependent on language. This is intended to minimize the attack surface, which is an important concern when running untrusted scripts. This includes

The handler will run every time time a document is "activated." Activation is decoupled from document initialization for efficiency, so as not to spin up an interpreter until it's actually needed. Activation is done for you automatically when events happen, so that the handler will be available to handle them. Your interpreter may be deallocated at any time without warning, so the only storage you can really count on are resources and scratchspace, which are available through the API.

deje object

In your handler, you will have access to an object called "deje" in the global namespace. For Lua this is a table, for JavaScript it's an Object. The difference is essentially semantic. This object has properties and functions for interacting with your interpreter's host environment.

deje.get_resource(path)

Get the resource in this document that's available at the given path. Resources have the following properties:

• path
• type (MIME, basically)
• content
• comment

Content can be in any format, all other properties are plain strings.

deje.get_scratch(author)

Get the current value in scratchspace set by the given author. Leave unset to get a table of all scratchspace. Each author's compartment can contain any arbitrary value that can be serialized to JSON.

deje.debug(text)

Print a debug message. At some point this will be disabled by default and only used for unit testing, but currently, such a switch does not exist.

deje.get_ident()

Get the host's current value of self-identity. May be None (or rather, it's equivalent in the handler's language)

deje.set_scratch(author, value)

Sets the value in scratchspace for the given author. This also calls on_scratch_update triggers and the scratchspace publishing mechanisms.

Callback API

You can expose functions in the handler for events - in fact, that's the only useful way to do anything with a handler. Any functions by the following names, available in your interpreter's global namespace, will be called at the appropriate times by the host.

on_scratch_update(author)

Triggered on any change to scratchspace, to report whose data has changed. The new contents are available through deje.get_scratch(author).

on_resource_update(path, property_name, oldpath)

This is triggered on changes to any property of a resource. In most of these cases, oldpath will be None, but if the path property has changed (property_name == path), the previous path is delivered in the oldpath variable. The following are valid results for property_name, see deje.handlers.lua.echo_chamber for more information.

• path
• type
• content
• comment
• add
• remove

---

0.0.1