3/Defaults - a default profile for RestMS

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.

  • Name: www.restms.org/spec:3/Defaults
  • Version: draft/4
  • Editor: Pieter Hintjens <moc.xitami|hp#moc.xitami|hp>
  • Contributors: Steve Vinoski <gro.eeei|iksoniv#gro.eeei|iksoniv>, Brad Clements <moc.skrowkrum|ckb#moc.skrowkrum|ckb>

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.

You should have received a copy of the GNU General Public License along with this program; if not, see <http://www.gnu.org/licenses>.

Change Process

This document is governed by the Digital Standard Organization's Consensus-Oriented Specification System.

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:

  1. Publisher creates a feed (e.g. "weather") of default type
  2. Subscriber creates a pipe of default type
  3. Subscriber creates a join specifying each address it wishes to subscribe to (e.g. "New York", "London", "Delhi")
  4. Publisher posts messages to the feed, specifying address on each message
  5. Subscriber receives selected messages on pipe

This model scales to many publishers and many subscribers. It may not scale to large numbers of different addresses.

Request-response scenario

The Defaults profile can be used for simple request-response from a set of requestors to a service handler:

  1. Service handler creates a request feed (e.g. "services") of default type
  2. Service handler creates a pipe of default type
  3. Service handler creates a join specifying as address its own service name (e.g. "weather info")
  4. Requestor creates a pipe of default type (pipe is automatically joined to default feed)
  5. Requestor posts message to request feed specifying service name as message address, and own pipe name as reply-to property of message.
  6. Service receives message on pipe and processes it, creating a response message.
  7. Service posts response message to default feed, specifying request 'reply-to' as message address.
  8. Requestor receives response message on pipe.

This model scales to many requestors but is restricted to a single service handler.

Checking profile availability

Clients SHOULD check that the server properly announces its support for Defaults before using it. The server indicates that it supports Defaults by listing it as a child of the domain:

Client:
-------------------------------------------------
GET /restms/domain/default

Server:
-------------------------------------------------
HTTP/1.1 200 OK
Content-Type: application/restms+xml

<?xml version="1.0"?>
<restms xmlns = "http://www.restms.org/schema/restms">
    <domain name = "default" title = "Default domain">
        <profile name = "3/Defaults"
            href = "http://www.restms.org/spec:3/Defaults" />
        <feed type = "" name = "default" title = "Default feed"
            href = "http://host.com/restms/feed/default" />
    </domain>
</restms>

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

Edit | Files | Tags | Source | Print | Talk

Use the Talk page to discuss this specification.

Use one of these tags to define the specification's state:

  • raw - new specification
  • draft - has at least one implementation.
  • stable - has been deployed to real users.
  • legacy - is being replaced by newer specifications.
  • retired - has been replaced and is no longer used.
  • deleted - abandoned before becoming stable.
raw