The Gradient extensions

Summary: this page contains a brief summary of how XMPP works, followed by a brief explanation of how clients and server interact over XMPP.

Because Gradient is 99% XMPP, I've prefaced the explanation of what it is that Gradient does with a small explanation on XMPP. If you already know XMPP, then skip down to the next part.

XMPP in brief

XMPP (or Jabber) is an instant messaging protocol that uses XML. A client signs on to a server by opening a socket and sending the opening tag of an XML document. The server responds with another open tag. The client and server exchange elements, referred to as "stanzas". To close the stream, the client sends the tag that closes the document element. Think of it as two XML documents being constructed, one in each direction.

XMPP stanzas are sent and received by XMPP entities. An XMPP entity is identified by its "JID" (Jabber ID), which looks something like "user@server.net/resource". Each user can log on with several resources. The resource is a more-or-less free form string. Entities may also exist server-side, e.g. "server.net/resource", and not be users but robots, chatrooms, services, etc.

There are three main types of element that travel over an authenticated XMPP connection:

IQ

IQ stanzas provide an open-ended RPC mechanism. IQ stanzas have four types - GET, SET, RESULT and ERROR. When you send a GET or SET, you should expect a RESULT or ERROR in return that has an identical stanza ID. Each IQ stanza must contain one child element with a namespace specified in accordance with the standard.

Message

The message stanza is a simple datagram. One client composes a message and sends it to the server, who forwards it onto the target entity.

Presence

The presence stanza is a simple broadcast mechanism. Presence stanzas need not have a recipient specified, in which case the stanza will be broadcasted by the server to all entities subscribed to the sender.

Subscription

If a first entity subscribes to a second, then that the first will receive all presence stanzas (such as availability changes) from the second.

Extension

Because all this takes place in XML, it's possible to send extended datatypes via the server using your own namespaces on elements, provided you stick to the subset of XML allowed by XMPP and put your extensions in the right places. This is how Gradient extends XMPP.

What Gradient does

"Gradient" is my code-name for the various things I've done with XMPP. XMPP itself provides 95% of the functionality necessary to do what the software does, and the code & ideas behind Gradient provides the other 5%.

Gradient does four things with XMPP:

Provides an extension to the IQ mechanism that enables the loading XML documents via XMPP. Documents are requested by path such as "/directory/index.html", and a request may (like HTTP) come with various parameters, e.g. name1=value1&name2=value2.

One difference between Gradient and HTTP is that parameter values may also be XML elements. It seemed like a good idea at the time.
Provides an extension that allows the server to send updates to the client. After document loading, the server could conceivably replace one image with another, add or remove a new section of text, etc.

This extension uses XPath to specify what parts of a document should be modified, and provides an envelope for and extra XML required to modify the document.
Provides an extension that allows the server to target broadcasts according to the path of the loaded document.
Allows RPC against a client with a per-document resolution (as opposed to per-JID), an extension borne of the possibility that each user may (or eventually will be able to) open multiple documents per active JID.

The following pages go into more detail on each part of the extensions to the protocol:

Retrieving documents via XMPP: Explains how documents are loaded in Gradient using the IQ stanzas in XMPP, and notes on using HTTP for large documents.
Updating documents via XMPP: Explains how documents are updated in Gradient and how XPath is used.
Sending data and RPC to documents: Explains how to send targeted data and updates to loaded documents, and make RPC calls to the documents.