This document defines the Defaults profile for RestMS. The Defaults profile defines the behavior of the default feed, join and pipe types. This profile provides the basis for simple pub-sub (the "Parrot" pattern) and request-response (the "Housecat" pattern) applications.

License

Copyright (c) 2009 by the Editor and Contributors.

This Specification is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation; either version 3 of the License, or (at your option) any later version.

This Specification is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.

Change Process

Goals and structure of this document

This document defines the Defaults profile for RestMS. The Defaults profile defines the behavior of the default feed, join and pipe types. This profile provides the basis for simple pub-sub (the Parrot pattern) and request-response (the Housecat pattern) applications.

We cover these aspects of the Defaults profile:

What the profile is designed for;

What the resources look like and how they work;

Guidelines for client applications;

Guidelines for server implementors.

Language

The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in RFC 2119[1].

Purpose and scope

The Defaults profile aims to provide a minimal useful messaging model that is easy to understand, implement, and use. The name refers to the fact that the feed, join and pipe types this profile exports are empty. Thus, if a client creates a resource without specifying a type it will use the functionality defined in this document.

Defaults provides a single, basic messaging model based on direct addressing within feeds. That is, publishers send messages to feeds, where each message has an arbitrary address. Subscribers receive messages from these feeds, joining on one or more addresses.

Defaults may be extended by other profiles, which specify different types of feed, join, and pipe.

Syntax and semantics

The Defaults profile is formally called "3/Defaults" to distinguish it from future variations.

It defines these feed types:

the default feed type which the client uses by creating a feed with no type property. The default feed type routes each message to each join attached to the feed that has an address pattern identical to the message address. One message can be routed to multiple pipes.

It defines these join types:

the default join type which the client uses by creating a join with no type property. The default join type specifies an address pattern and thus selects all messages, in that feed, which match the address exactly.

It defines these pipe types:

the default pipe type which the client uses by creating a pipe with no type property. The default pipe type delivers messages one by one to the application using the semantics defined in RestMS.

It also specifies the following server behaviour:

The server MUST implement a default public default feed called "default".

The server MUST create a default join from each default pipe to the default feed.

The default join implements a guaranteed Housecat pattern on every default pipe. If clients attempt to delete the default join, or create other joins onto the default feed, the server MUST respond with "403 Forbidden".

Lastly, Defaults specifies synchronous routing notification to publishers. When the client successfully POSTs a message to the a default type feed, the server MUST respond with a structured message document with a single property, "count" that reports the number of joins that matched the message.

Guidelines for clients

Publish-subscribe scenario

The Defaults profile can be used for simple publish-and-subscribe from a set of publishers to a set of subscribers:

Guidelines for servers implementors

The default feed type does not queue messages: it examines its set of joins and copies the message to each pipe that has a matching join, and it then discards the message.

Messages posted before a join is made MAY NOT be routed to pipes. That is, clients may create and destroy joins as a way of enabling and disabling the flow of messages into their pipes.

The message resource provided as response to a feed POST tells publishers how many recipients their message went to (0 or more).

One data structure that server implementers MAY use for the default feed routing is a hash table of addresses, each address containing a linked-list of joins. This allows for a rapid lookup of the message address and routing to all joins that requested it.

Bibliography

1. "Key words for use in RFCs to Indicate Requirement Levels" - ietf.org