Handler API

The following is for reference. For an explanation of how DEJE works, go to the Technical Overview.

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.checkpoint(cp)

Create a checkpoint based on the arbitrary object cp.

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)

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_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

on_host_request(callback, params)

The host can communicate with the document in doctype-specific ways via requests. These are essentially like function calls. The request is delivered to the handler via on_host_request, which supplies a callback to use to return the result, and a params object to specify request type and parameters. From the Python library side, application code can call request functions that return "deferred result" objects, providing a very seamless and idiomatic way for applications to interact with documents according to their abilities - for example, getting or setting the value of a specific cell in a spreadsheet.

A handler can expose more than one request API, and should advertise all available APIs via request_protocols().

on_checkpoint_achieve(cp, author)

Triggered when a checkpoint is achieved. Should return a list of [callback, arg0, arg1 ... argN] lists. Each callback will be called with arguments:

callback(set_resource, arg0, arg1 ... argN)

set_resource is a function that takes arguments:

set_resource(path, value)

allowing you to set the value of any resource, existing or not. Setting to nil/None is equivalent to deletion. This function is invalidated on the host's side after on_checkpoint_achieve returns, causing an error if used. Trying to retain it in the handler code as a global or some other such will only cause a memory leak.

checkpoint_test(cp, author)

Must return a boolean value, whether the handler accepts that the conditions for checkpoint cp are valid, given the current state of the document. This is used for quorums, permissions, sanity checking, etc.

quorum_participants()

Returns a table of identities, representing the nodes that have voting ability to validate checkpoints. Keys are idents, values are vote weights. Total vote weights must equal the number of participants, though distribution may be uneven.

quorum_thresholds()

Returns a table containing the read and write thresholds for the quorum group. Has two properties, "read" and "write", which are numbers such that:

R + W > T
2W    > T
R < T
W < T

Where T is the total number of participants (or, from another point of view, total vote weight). These sanity checks guarantee that a read and a write will always collide, multiple writes will always collide, and neither read nor write is individually impossible. The table will only be used if its values satisfy these conditions.

For optimal performance (unless your application is predominantly write-heavy), you probably want a value for "read" at about T/4.

request_protocols()

A list of strings, each one representing a request protocol provided by the handler. These should be hyphenated and end in a version, for example "odf-spreadsheet-0.2.16". Most protocols will be managed by third parties, beyond the purview of the DEJE specification, but a few will be provided as "stock." These are yet to be determined.

Should return an empty list if no request protocols are supported.

Example return value: ["djdns-5.7", "resourceful-1.2.0"]

---

0.0.2