This repository has been archived by the owner on Jun 13, 2018. It is now read-only.
-
Notifications
You must be signed in to change notification settings - Fork 7
/
3-defaults.txt
136 lines (86 loc) · 7.65 KB
/
3-defaults.txt
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
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 <[email protected]>
* Contributors: Steve Vinoski <[email protected]>, Brad Clements <[email protected]>
++ 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 [http://www.digistan.org/spec:1/COSS 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 implementers.
++ 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[((bibcite rfc2119))].
++ 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 using the semantics defined in RestMS (it delivers messages to the client one by one as discrete <message> resources, and holds each message until a client deletes it).
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:
# Publisher creates a feed (e.g. "weather") of default type
# Subscriber creates a pipe of default type
# Subscriber creates a join specifying each address it wishes to subscribe to (e.g. "New York", "London", "Delhi")
# Publisher posts messages to the feed, specifying address on each message
# 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:
# Service handler creates a request feed (e.g. "services") of default type
# Service handler creates a pipe of default type
# Service handler creates a join specifying as address its own service name (e.g. "weather info")
# Requestor creates a pipe of default type (pipe is automatically joined to default feed)
# Requestor posts message to request feed specifying service name as message address, and own pipe name as reply-to property of message.
# Service receives message on pipe and processes it, creating a response message.
# Service posts response message to default feed, specifying request 'reply-to' as message address.
# 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:
[[code]]
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>
[[/code]]
++ Guidelines for server implementers
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]]
: rfc2119 : "Key words for use in RFCs to Indicate Requirement Levels" - [http://tools.ietf.org/html/rfc2119 ietf.org]
[[/bibliography]]