Network Working Group M. Schwartz
Internet-Draft NetTopBox, Inc.
Expires: April 23, 2002 M. Rose
Dover Beach Consulting, Inc.
K. Carlberg
University College London
October 23, 2001
The APEX Publish-Subscribe Service
draft-schwartz-apex-pubsub-02
Status of this Memo
This document is an Internet-Draft and is in full conformance with
all provisions of Section 10 of RFC 2026.
Internet-Drafts are working documents of the Internet Engineering
Task Force (IETF), its areas, and its working groups. Note that
other groups may also distribute working documents as Internet-
Drafts.
Internet-Drafts are draft documents valid for a maximum of six months
and may be updated, replaced, or obsoleted by other documents at any
time. It is inappropriate to use Internet-Drafts as reference
material or to cite them other than as "work in progress."
The list of current Internet-Drafts can be accessed at
http://www.ietf.org/ietf/1id-abstracts.txt.
The list of Internet-Draft Shadow Directories can be accessed at
http://www.ietf.org/shadow.html.
This Internet-Draft will expire on April 23, 2002.
Copyright Notice
Copyright (C) The Internet Society (2001). All Rights Reserved.
Abstract
This memo describes the APEX publish-subscribe service, addressed as
the well-known endpoint "apex=pubsub". The pubsub service is used to
manage subscriber lists for a set of topical distribution groups, and
to forward messages to group subscribers.
Schwartz, et. al. Expires April 23, 2002 [Page 1]
Internet-Draft The APEX Publish-Subscribe Service October 2001
Table of Contents
1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 3
2. Topic and Subscription Management . . . . . . . . . . . . . 5
2.1 Defining a New Topic . . . . . . . . . . . . . . . . . . . . 5
2.2 Deleting an Existing Topic . . . . . . . . . . . . . . . . . 6
2.3 Listing Existing Topics . . . . . . . . . . . . . . . . . . 7
2.4 Subscribing to a Topic . . . . . . . . . . . . . . . . . . . 9
2.5 Cancelling a Subscription . . . . . . . . . . . . . . . . . 10
2.6 Distributing Subscription Management . . . . . . . . . . . . 11
3. Publishing . . . . . . . . . . . . . . . . . . . . . . . . . 13
4. The Pubsub Service . . . . . . . . . . . . . . . . . . . . . 15
4.1 Use of XML and MIME . . . . . . . . . . . . . . . . . . . . 16
4.2 The Createtopic Operation . . . . . . . . . . . . . . . . . 17
4.3 The Deletetopic Operation . . . . . . . . . . . . . . . . . 18
4.4 The Listtopics Operation . . . . . . . . . . . . . . . . . . 19
4.5 The Subscribe Operation . . . . . . . . . . . . . . . . . . 20
4.6 The Cancel Operation . . . . . . . . . . . . . . . . . . . . 21
4.7 Data Transmissions . . . . . . . . . . . . . . . . . . . . . 23
4.7.1 Use of APEX Data Messages . . . . . . . . . . . . . . . . . 23
4.8 The Reply Operation . . . . . . . . . . . . . . . . . . . . 23
5. Initial Registrations . . . . . . . . . . . . . . . . . . . 24
5.1 Registration: The Pubsub Service . . . . . . . . . . . . . . 24
6. DTDs . . . . . . . . . . . . . . . . . . . . . . . . . . . . 25
6.1 The Pubsub Service DTD . . . . . . . . . . . . . . . . . . . 25
7. Security Considerations . . . . . . . . . . . . . . . . . . 27
References . . . . . . . . . . . . . . . . . . . . . . . . . 29
Authors' Addresses . . . . . . . . . . . . . . . . . . . . . 29
A. IANA Considerations . . . . . . . . . . . . . . . . . . . . 31
B. Acknowledgements . . . . . . . . . . . . . . . . . . . . . . 32
C. Revision History . . . . . . . . . . . . . . . . . . . . . . 33
C.1 Changes from draft-schwartz-apex-pubsub-01 . . . . . . . . . 33
C.2 Changes from draft-schwartz-apex-pubsub-00 . . . . . . . . . 33
Full Copyright Statement . . . . . . . . . . . . . . . . . . 34
Schwartz, et. al. Expires April 23, 2002 [Page 2]
Internet-Draft The APEX Publish-Subscribe Service October 2001
1. Introduction
Multicast is a form of one-to-many distribution of datagrams. Its
perceived strength relies on the "network" (in whatever form it is
realized), rather than the source, replicating traffic to the
different receivers of a group. The replication topology is a tree
of nodes overlayed on top of a physical network. Traditionally,
multicast has been viewed as a network layer service in which
replication is done by routers.
In this document we describe an application-level multicast service.
Rather than relying on IP layer multicast [1], the service
distributes information through an APEX [2] "relay mesh". The APEX
relaying mesh uses BEEP [3], which in turn runs on top of TCP [4].
This last point allows the service to adapt to congestion in a
fashion that is TCP-friendly.
An application-level multicast service could, for example, allow
implementation of a messaging "exploder" that performs a single
store-and-forward delivery of a group-addressed message across a
trans-oceanic link, after which point messages are delivered to
multiple recipients on the remote side of the link. The service can
be deployed using static tree configuration, and possibly later
augmented with a protocol for automating tree configuration.
The service we describe is called the APEX publish-subscribe (pubsub)
service. The pubsub service is used to manage subscriber lists for a
set of topical distribution groups, and to forward messages to group
subscribers.
Schwartz, et. al. Expires April 23, 2002 [Page 3]
Internet-Draft The APEX Publish-Subscribe Service October 2001
APEX, at its core, provides a best-effort datagram service. Within
an administrative domain, all relays must be able to handle messages
for any endpoint within that domain. APEX services are logically
defined as endpoints but given their ubiquitous semantics they do not
necessarily need to be associated with a single physical endpoint.
As such, they may be provisioned co-resident with each relay within
an administrative domain, even though they are logically provided on
top of the relaying mesh, i.e.,
+----------+ +----------+ +----------+ +---------+
| APEX | | APEX | | APEX | | |
| access | | pubsub | | presence | | ... |
| service | | service | | service | | |
+----------+ +----------+ +----------+ +---------+
| | | |
| | | |
+----------------------------------------------------------------+
| |
| APEX core |
| |
+----------------------------------------------------------------+
That is, applications communicate with an APEX service by exchanging
data with a "well-known endpoint" (WKE).
APEX applications communicate with the pubsub service by exchanging
data with the well-known endpoint "apex=pubsub" in the corresponding
administrative domain, e.g., "apex=pubsub@example.com" is the
endpoint associated with the pubsub service in the "example.com"
administrative domain.
Note that within a single administrative domain, the pubsub service
makes use of the APEX access [5] service to determine whether an
originator is allowed to manage topic and subscription information,
and whether an originator is allowed to publish to a given topic.
Schwartz, et. al. Expires April 23, 2002 [Page 4]
Internet-Draft The APEX Publish-Subscribe Service October 2001
2. Topic and Subscription Management
The APEX pubsub service manages a list of named topics and a list of
subscribers for each topic, and implements delivery for group-
addressed messages using the underlying APEX relay service.
The pubsub service uses hierarchical topic names similar to NNTP [6]
group names. Unlike NNTP's global newsgroup namespace, the pubsub
service defines a distinct topic name space per administrative
domain. The allocation of the topic name space, including any
conventions applied at particular levels in the hierarchy, is an
issue for each local administrative domain. Each administrative
domain is also responsible for setting access control policy for
pubsub operations, and for maintaining state on stable storage about
the currently existing set of topics and subscribers for each topic.
Each of the topic and subscription management operations is described
in the subsections below.
2.1 Defining a New Topic
When an application wants to define a new topic to which group-
delivery messages can be addressed, it sends a createtopic operation
to the service, e.g.,
+-------+ +-------+
| | -- data -------> | |
| appl. | | relay |
| | <--------- ok -- | |
+-------+ +-------+
C: <data content='#Content'>
<originator identity='mike@example.com' />
<recipient identity='apex=pubsub@example.com' />
<data-content Name='Content'>
<createtopic topic='music.jazz.milesdavis'
transID='1' />
</data-content>
</data>
S: <ok />
Schwartz, et. al. Expires April 23, 2002 [Page 5]
Internet-Draft The APEX Publish-Subscribe Service October 2001
The service immediately responds with a reply operation containing
the same transaction-identifier, e.g.,
+-------+ +-------+
| | <------- data -- | |
| relay | | pubsub|
| | -- ok ---------> | svc. |
+-------+ +-------+
C: <data content='#Content'>
<originator identity='apex=pubsub@example.com' />
<recipient identity='mike@example.com' />
<data-content Name='Content'>
<reply code='250' transID='1' />
</data-content>
</data>
S: <ok />
2.2 Deleting an Existing Topic
When an application wants to delete an existing topic, it sends a
deletetopic operation to the service, e.g.,
+-------+ +-------+
| | -- data -------> | |
| appl. | | relay |
| | <--------- ok -- | |
+-------+ +-------+
C: <data content='#Content'>
<originator identity='mike@example.com' />
<recipient identity='apex=pubsub@example.com' />
<data-content Name='Content'>
<deletetopic topic='music.jazz.milesdavis'
transID='2' />
</data-content>
</data>
S: <ok />
Schwartz, et. al. Expires April 23, 2002 [Page 6]
Internet-Draft The APEX Publish-Subscribe Service October 2001
The service immediately responds with a reply operation containing
the same transaction-identifier, e.g.,
+-------+ +-------+
| | <------- data -- | |
| relay | | pubsub|
| | -- ok ---------> | svc. |
+-------+ +-------+
C: <data content='#Content'>
<originator identity='apex=pubsub@example.com' />
<recipient identity='mike@example.com' />
<data-content Name='Content'>
<reply code='250' transID='2' />
</data-content>
</data>
S: <ok />
2.3 Listing Existing Topics
When an application wants to get a list of existing topics, it sends
a listtopics operation to the service, e.g.,
+-------+ +-------+
| | -- data -------> | |
| appl. | | relay |
| | <--------- ok -- | |
+-------+ +-------+
C: <data content='#Content'>
<originator identity='mike@example.com' />
<recipient identity='apex=pubsub@example.com' />
<data-content Name='Content'>
<listtopics />
</data-content>
</data>
S: <ok />
Schwartz, et. al. Expires April 23, 2002 [Page 7]
Internet-Draft The APEX Publish-Subscribe Service October 2001
The service immediately responds with a topiclist operation
containing the list of topics registered with its administrative
domain, e.g.,
+-------+ +-------+
| | <------- data -- | |
| relay | | pubsub|
| | -- ok ---------> | svc. |
+-------+ +-------+
C: <data content='#Content'>
<originator identity='apex=pubsub@example.com' />
<recipient identity='mike@example.com' />
<data-content Name='Content'>
<topiclist>
<topic name="music.jazz.milesdavis" />
<topic name="music.classicrock.zeppelin" />
</topiclist>
</data-content>
</data>
S: <ok />
In addition to the topiclist operation, applications can track
changes to the topic list via the APEX presence service [7]. This
approach is discussed is more detail later.
Schwartz, et. al. Expires April 23, 2002 [Page 8]
Internet-Draft The APEX Publish-Subscribe Service October 2001
2.4 Subscribing to a Topic
When an application wants to subscribe to a topic it sends a
subscribe operation to the service, e.g.,
+-------+ +-------+
| | -- data -------> | |
| appl. | | relay |
| | <--------- ok -- | |
+-------+ +-------+
C: <data content='#Content'>
<originator identity='mike@example.com' />
<recipient identity='apex=pubsub@example.com' />
<data-content Name='Content'>
<subscribe subscriber='mike@example.com'
topic='music.jazz.milesdavis'
duration='9999999'
transID='3' />
</data-content>
</data>
S: <ok />
The service immediately responds with a reply operation containing
the same transaction-identifier, e.g.,
+-------+ +-------+
| | <------- data -- | |
| relay | | pubsub|
| | -- ok ---------> | svc. |
+-------+ +-------+
C: <data content='#Content'>
<originator identity='apex=pubsub@example.com' />
<recipient identity='mike@example.com' />
<data-content Name='Content'>
<reply code='250' transID='3' />
</data-content>
</data>
S: <ok />
Schwartz, et. al. Expires April 23, 2002 [Page 9]
Internet-Draft The APEX Publish-Subscribe Service October 2001
2.5 Cancelling a Subscription
Either the subscriber or the service may cancel a subscription by
sending a cancel operation., e.g.,
+-------+ +-------+
| | -- data -------> | |
| appl. | | relay |
| | <--------- ok -- | |
+-------+ +-------+
C: <data content='#Content'>
<originator identity='mike@example.com' />
<recipient identity='apex=pubsub@example.com' />
<data-content Name='Content'>
<cancel topic='music.jazz.milesdavis' transID='4' />
</data-content>
</data>
S: <ok />
+-------+ +-------+
| | <------- data -- | |
| relay | | pubsub|
| | -- ok ---------> | svc. |
+-------+ +-------+
C: <data content='#Content'>
<originator identity='apex=pubsub@example.com' />
<recipient identity='mike@example.com' />
<data-content Name='Content'>
<reply code='250' transID='4' />
</data-content>
</data>
S: <ok />
or
+-------+ +-------+
| | <------- data -- | |
| relay | | pubsub|
| | -- ok ---------> | svc. |
+-------+ +-------+
C: <data content='#Content'>
<originator identity='apex=pubsub@example.com' />
<recipient identity='mike@example.com' />
<data-content Name='Content'>
<cancel topic='music.jazz.milesdavis' transID='99' />
</data-content>
</data>
S: <ok />
Schwartz, et. al. Expires April 23, 2002 [Page 10]
Internet-Draft The APEX Publish-Subscribe Service October 2001
2.6 Distributing Subscription Management
Servicing publish/subscribe activity from a single location would
present scaling problems. To support distributed subscriber
management, individual administrative domains can field pubsub
servers that send subscribe and cancel requests to other pubsub
servers. In this fashion, it is possible to construct a distributed
tree of servers that handle publish and subscribe activity. Whether
this set of servers is configured manually or through an automated
tree formation protocol is outside the scope of the current document.
When a pubsub server wants to act as a distributor for a particular
topic it sends a subscribe operation to the service, using the
appropriate subaddress as the originator, e.g.,
+-------+ +-------+
| pubsub| -- data -------> | |
| svc. | | relay |
| #2 | <--------- ok -- | |
+-------+ +-------+
C: <data content='#Content'>
<originator
identity='apex=pubsub/music.jazz.milesdavis@redistr.com' />
<recipient identity='apex=pubsub@example.com' />
<data-content Name='Content'>
<subscribe
subscriber=
'apex=pubsub/music.jazz.milesdavis@redistr.com'
topic='music.jazz.milesdavis'
duration='9999999'
transID='5' />
</data-content>
</data>
S: <ok />
Schwartz, et. al. Expires April 23, 2002 [Page 11]
Internet-Draft The APEX Publish-Subscribe Service October 2001
The service immediately responds with a reply operation containing
the same transaction-identifier, e.g.,
+-------+ +-------+
| | <------- data -- | pubsub|
| relay | | svc. |
| | -- ok ---------> | #1 |
+-------+ +-------+
C: <data content='#Content'>
<originator identity='apex=pubsub@example.com' />
<recipient
identity='apex=pubsub/music.jazz.milesdavis@redistr.com' />
<data-content Name='Content'>
<reply code='250' transID='5' />
</data-content>
</data>
S: <ok />
Similarly, a pubsub server would send a cancel request using the
appropriate subaddress as the originator.
Additional processing steps are needed to handle the case where
pubsub servers themselves may originate subscribe and cancel
requests. Specifically, when any subscribe or cancel request is
received, the receiving server must first check whether the
originator falls within the administrative domain of a redistributing
pubsub server for the given topic, and if so, the subscribe or cancel
request is forwarded to that pubsub server. Section 4.5 and Section
4.6 present the algorithmic details.
It is a local provisioning decision whether a redistributing pubsub
server advertises its presence to end users.
Schwartz, et. al. Expires April 23, 2002 [Page 12]
Internet-Draft The APEX Publish-Subscribe Service October 2001
3. Publishing
To publish a message to subscribers of a particular topic, an
application sends an APEX data message to the service, using
subaddressing to specify the topic for which group delivery is
desired, e.g.,
+-------+ +-------+
| | -- data -------> | |
| appl. | | relay |
| | <--------- ok -- | |
+-------+ +-------+
C: <data content='cid:...'>
<originator identity='mike@example.com' />
<recipient
identity='apex=pubsub/music.jazz.milesdavis@example.com' />
</data>
S: <ok />
Schwartz, et. al. Expires April 23, 2002 [Page 13]
Internet-Draft The APEX Publish-Subscribe Service October 2001
In response, the service forwards the message content to each
subscriber of the subaddress-named topic, rewriting the message to
use the dataHopping option (see Section 4 of [8] for details) and to
contain a list of recipients so that the APEX core will relay the
message to each subscriber in turn:
+-------+ +-------+
| | <------- data -- | |
| | | pubsub|
| | -- ok ---------> | svc. |
| | +-------+
+-------+ | |
| | <------- data -- | |
| sub 1 | | relay |
| | -- ok ---------> | |
+-------+ | |
+-------+ | |
| | <------- data -- | |
| sub 2 | | |
| | -- ok ---------> | |
+-------+ +-------+
...
C: <data content='cid:...'>
<originator
identity='apex=pubsub/music.jazz.milesdavis@example.com' />
<recipient identity='subscriber1@example.com' />
<recipient identity='subscriber2@example.com' />
<option internal='dataHopping' targetHop='all'
mustUnderstand='true' transID='86' />
<dataHopping noMoreThan='2' reportErrors='true' />
</option>
</data>
S: <ok />
This subaddress-based topic naming is used rather than defining an
explicit "publish" operation so that sending and receiving
applications need not be aware that they are participating in group
delivery transmissions. The placement of multiple subscribers within
a pubsub message realizes the benefit of a single message being
replicated N times by the APEX relay mesh, versus the transmission of
N messages by the publisher (source) to the relay mesh.
Schwartz, et. al. Expires April 23, 2002 [Page 14]
Internet-Draft The APEX Publish-Subscribe Service October 2001
4. The Pubsub Service
Section 5.1 contains the APEX service registration for the pubsub
service:
o Within an administrative domain, the service is addressed using
the well-known endpoint of "apex=pubsub", or a subaddress of this
well-known endpoint. Consult Section 2.2 of [2] for a discussion
of APEX subaddresses.
o Section 6.1 defines the syntax of the operations exchanged with
the service.
o A consumer of the service initiates communications by sending data
containing the createtopic, deletetopic, subscribe, or cancel
operation to the "apex=pubsub" well-known endpoint; or by sending
any data to a subaddress of this well-known endpoint.
o In addition to replying to these operations, the service may also
initiate communications by sending data containing the cancel
operation or by forwarding data previously sent to a subaddress of
the "apex=pubsub" well-known endpoint.
An implementation of the service must maintain information about in-
progress operations in persistent storage.
Consult Section 6.1.1 of [2] for a discussion on the properties of
long-lived transaction-identifiers.
Schwartz, et. al. Expires April 23, 2002 [Page 15]
Internet-Draft The APEX Publish-Subscribe Service October 2001
4.1 Use of XML and MIME
Section 4.1 of [2] describes how arbitrary MIME content is exchanged
as a BEEP [3] payload. For example, to transmit:
<data content='...'>
<originator identity='mike@example.com' />
<recipient
identity='apex=pubsub/music.jazz.milesdavis@example.com' />
</data>
where "..." refers to: <FavoriteAlbum title="Kind of Blue" />
then the corresponding BEEP message might look like this:
MSG 1 1 . 42 1234
Content-Type: multipart/related; boundary="boundary";
start="<1@example.com>";
type="application/beep+xml"
--boundary
Content-Type: application/beep+xml
Content-ID: <1@example.com>
<data content='cid:2@example.com'>
<originator identity='mike@example.com' />
<recipient
identity='apex=pubsub/music.jazz.milesdavis@example.com' />
</data>
--boundary
Content-Type: application/beep+xml
Content-ID: <2@example.com>
<FavoriteAlbum title="Kind of Blue" />
--boundary--
END
Schwartz, et. al. Expires April 23, 2002 [Page 16]
Internet-Draft The APEX Publish-Subscribe Service October 2001
or this:
MSG 1 1 . 42 1234
Content-Type: application/beep+xml
<data content='#Content'>
<originator identity='mike@example.com' />
<recipient
identity='apex=pubsub/music.jazz.milesdavis@example.com' />
<data-content Name='Content'>
<FavoriteAlbum title="Kind of Blue" />
</data-content>
</data>
END
4.2 The Createtopic Operation
When an application wants to create a new topic to which subscribe
operations and data transmissions can refer, it sends a "createtopic"
element to the service.
The "createtopic" element has a "topic" attribute, a "transID"
attribute, and no content:
o the "topic" attribute specifies the topic name for which this
application wishes to allow future subscribe operations and data
transmissions to be supported; and,
o the "transID" attribute specifies the transaction-identifier
associated with this operation.
Schwartz, et. al. Expires April 23, 2002 [Page 17]
Internet-Draft The APEX Publish-Subscribe Service October 2001
When the service receives a "createtopic" element, the service
performs these steps:
1. If the access entry for the service matching the originator does
not contain a "pubsub:createtopic" token, a "reply" element
having code 537 is sent to the originator.
2. If the "topic" attribute specifies a topic name that already
exists, a "reply" element having code 553 is sent to the
originator.
3. Otherwise:
1. The service records the topic in its non-volatile state, to
enable future subscribe operations and data transmissions
refering to this new topic.
2. The service updates its presence information by adding a
"tuple" element that corresponds to the new topic. The
"destination" attribute of the "tuple" element identifies the
subaddress used for the topic, and the "tupleInfo" attribute
identifies arbitrary descriptive information about the topic
(e.g., a textual description, a specification of the syntax
of data messages transmitted for that topic, PICS [9] labels
rating topic content, etc.) Consult Sections 2.1 and 4.4 of
[7] for further details.
3. A "reply" element having code 250 is immediately sent to the
originator.
When sending the "reply" element, the "transID" attribute is
identical to the value found in the "createtopic" element sent by the
originator.
4.3 The Deletetopic Operation
When an application wants to delete an existing topic (i.e., one for
which a previous createtopic operation completed successfully), it
sends a "deletetopic" element to the service.
Schwartz, et. al. Expires April 23, 2002 [Page 18]
Internet-Draft The APEX Publish-Subscribe Service October 2001
The "deletetopic" element has a "topic" attribute, a "transID"
attribute, and no content:
o the "topic" attribute specifies the topic name for which this
application wishes to disable future subscribe operations and data
transmissions; and,
o the "transID" attribute specifies the transaction-identifier
associated with this operation.
When the service receives a "deletetopic" element, the service
performs these steps:
1. If the access entry for the service matching the originator does
not contain a "pubsub:deletetopic" token, a "reply" element
having code 537 is sent to the originator.
2. If the "topic" attribute specifies a topic name that does not
currently exist, a "reply" element having code 553 is sent to the
originator.
3. Otherwise:
1. The service deletes the topic from its non-volatile state, to
disable future subscribe operations and data transmissions
refering to this topic.
2. The service updates its presence information by removing the
"tuple" element that corresponds to the deleted topic.
3. A "reply" element having code 250 is immediately sent to the
originator.
When sending the "reply" element, the "transID" attribute is
identical to the value found in the "deletetopic" element sent by the
originator.
Note that following a deletetopic operation, data transmissions
refering to this topic may continue to be propagated. Although the
service will all no new data transmissions to start refering to this
topic, in-progress data transmissions may be in transit.
4.4 The Listtopics Operation
When an application wants to get a list of existing topics, it sends
a "listtopics" element to the service.
The "listtopics" element has no content.
Schwartz, et. al. Expires April 23, 2002 [Page 19]
Internet-Draft The APEX Publish-Subscribe Service October 2001
When the service receives a "listtopics" element, the service
performs these steps:
1. If the access entry for the service matching the originator does
not contain a "pubsub:listtopics" token, a "reply" element having
code 537 is sent to the originator.
2. Otherwise, a "topiclist" element is immediately sent to the
originator, having the same "transID" attribute value", and
containing a sequence of "topic" elements each with a single
"name" attribute, enumerating the topics known in this
administrative domain.
4.5 The Subscribe Operation
When an application wants to receive forwarded messages sent to the
service via the data transmissions sent to a particular topic
(subaddress) at a domain, it sends a "subscribe" element to the
service.
The "subscribe" element has a "subscriber" attribute, a "topic"
attribute, a "transID" attribute, a "duration" attribute, and no
content:
o the "subscriber" attribute specifies the endpoint to which data
transmissions should be forwarded;
o the "topic" attribute specifies the topic name for which this
application wishes to have corresponding data transmissions
forwarded;
o the "duration" attribute specifies a non-zero maximum number of
seconds for which the subscriber is interested in receiving
forwarded data transmissions; and,
o the "transID" attribute specifies the transaction-identifier
associated with this operation.
Schwartz, et. al. Expires April 23, 2002 [Page 20]
Internet-Draft The APEX Publish-Subscribe Service October 2001
When the service receives a "subscribe" element, we refer to the
"subscriber" attribute of the "subscribe" element as the "subject",
and the service performs these steps:
1. If the access entry for the service matching the originator does
not contain a "pubsub:subscribe" token, a "reply" element having
code 537 is sent to the originator.
2. If the "topic" attribute specifies a topic name that does not
exist, a "reply" element having code 553 is sent to the
originator.
3. If the duration attribute is less than or equal to zero, a
"reply" element having code 553 is sent to the originator.
4. If the topic already has a subscriber whose local-part is
"apex=pubsub/TOPIC" (where "TOPIC" matches the value of the
"topic" attribute), and whose domain-part matches the domain-part
of the subject, then the service forwards the "subscribe" element
to the existing subscriber.
5. Otherwise:
1. A "reply" element having code 250 is sent to the originator.
2. For up to the amount of time indicated by the "duration"
attribute of the "subscribe" element, if a data transmission
is sent to the service with a subaddress matching the
specified topic, it is forwarded to the subject. (If the
subject is already subscribed, the previous duration is no
longer consulted.) Finally, when the amount of time indicated
by the "duration" attribute expires, a cancel operation
(Section 4.6) is sent to the originator.
When sending the "reply" element, the "transID" attribute is
identical to the value found in the "subscribe" element sent by the
originator.
4.6 The Cancel Operation
When an application no longer wishes to subscribe to a particular
topic, it sends an "cancel" element to the service; similarly, when
the service no longer considers an application to be subscribing, an
"cancel" element is sent to the application.
Schwartz, et. al. Expires April 23, 2002 [Page 21]
Internet-Draft The APEX Publish-Subscribe Service October 2001
The "cancel" element has a "subscriber" attribute, a "topic"
attribute, a "transID" attribute, and no content:
o the "subscriber" attribute specifies the endpoint to which data
transmissions should no longer be forwarded;
o the "topic" attribute specifies the topic name for which this
application wishes to cease having corresponding subscribed data
transmissions forwarded; and,
o the "transID" attribute specifies the transaction-identifier
associated with this operation.
When the service receives an "cancel" element, we refer to the
"subscriber" attribute of the "subscribe" element as the "subject",
and the service performs these steps:
1. If the access entry for the service matching the originator does
not contain a "pubsub:cancel" token, a "reply" element having
code 537 is sent to the originator.
2. If the "topic" attribute specifies a topic name that does not
exist, a "reply" element having code 553 is sent to the
originator.
3. If the topic already has a subscriber whose local-part is
"apex=pubsub/TOPIC" (where "TOPIC" matches the value of the
"topic" attribute), and whose domain-part matches the domain-part
of the subject, then the service forwards the "cancel" element to
the existing subscriber.
4. Otherwise:
1. A "reply" element having code 250 is sent to the originator.
2. The service removes the subject from the list of endpoints to
which data is forwarded for the topic.
When sending the "reply" element, the "transID" attribute is
identical to the value found in the "subscribe" element sent by the
originator.
Note that following a cancel operation, the originator may receive
further data transmissions directed to the specified topic. Although
the service will forward no new data after processing a cancel
operation and sending the reply operation, earlier transmissions may
be in transit.
Schwartz, et. al. Expires April 23, 2002 [Page 22]
Internet-Draft The APEX Publish-Subscribe Service October 2001
4.7 Data Transmissions
4.7.1 Use of APEX Data Messages
When an application wants to transmit information to other
applications subscribed to a particular topic within an
administrative domain, it sends data to the apex=pubsub service at
the given administrative domain using the APEX "data" operation, with
the subaddress set to the desired topic. When the service receives a
data operation so addressed, it performs the following steps:
1. If the subaddress does not match an existing topic at this
administrative domain, then when the APEX core delivers the data
to the pubsub service (Step 5.3 of Section 4.4.4.1 of [2]), the
pubsub service returns an "error" element having code 550.
2. Otherwise, the pubsub service returns an "ok" element, and then
submits a new data element to the relay service, replacing the
recipient with a set of recipients enumerating each endpoint that
had previously successfully performed a "subscribe" operation
specifying a topic name that matches the subaddress and for which
the "subscribe" operation is still active (i.e., its specified
duration has not been exceeded).
4.8 The Reply Operation
While processing operations, the service may respond with a "reply"
element. Consult Sections 10 and 6.1.2 of [2], respectively, for the
definition and an exposition of the syntax of the reply element.
Schwartz, et. al. Expires April 23, 2002 [Page 23]
Internet-Draft The APEX Publish-Subscribe Service October 2001
5. Initial Registrations
5.1 Registration: The Pubsub Service
Well-Known Endpoint: apex=pubsub
Syntax of Messages Exchanged: c.f., Section 6.1
Sequence of Messages Exchanged: c.f., Section 4
Access Control Tokens: pubsub:createtopic, pubsub:deletetopic,
pubsub:listtopics, pubsub:subscribe, pubsub:cancel, core:data
Contact Information: c.f., the "Authors' Addresses" section of this
memo
Schwartz, et. al. Expires April 23, 2002 [Page 24]
Internet-Draft The APEX Publish-Subscribe Service October 2001
6. DTDs
6.1 The Pubsub Service DTD
<!--
DTD for the APEX pubsub service, as of 2001-09-16
Refer to this DTD as:
<!ENTITY % APEXPUBSUB PUBLIC "-//IETF//DTD APEX PUBSUB//EN" "">
%APEXPUBSUB;
-->
<!ENTITY % APEXCORE PUBLIC "-//IETF//DTD APEX CORE//EN" "">
%APEXCORE;
<!--
DTD data types:
entity syntax/reference example
====== ================ =======
topic
TOPIC [a-z][a-z0-9.-_]* finance.vc.findandflip
c.f., Section x.x
-->
<!ENTITY % TOPIC "CDATA">
<!--
Synopsis of the APEX pubsub service
service WKE: apex=pubsub
message exchanges:
consumer initiates service replies
================== ================
createtopic reply
deletetopic reply
listtopics topiclist
subscribe reply
cancel reply
Schwartz, et. al. Expires April 23, 2002 [Page 25]
Internet-Draft The APEX Publish-Subscribe Service October 2001
service initiates consumer replies
================= ================
cancel (nothing)
access control:
operation subject token
----------- ---------- ------------------
createtopic apex=pubsub pubsub:createtopic
deletetopic apex=pubsub pubsub:deletetopic
listtopics apex=pubsub pubsub:listtopics
subscribe apex=pubsub/topic pubsub:subscribe
cancel apex=pubsub/topic pubsub:cancel
data apex=pubsub/topic core:data
-->
<!ELEMENT createtopic EMPTY>
<!ATTLIST createtopic
topic %TOPIC; #REQUIRED
transID %UNIQID; #REQUIRED>
<!ELEMENT deletetopic EMPTY>
<!ATTLIST deletetopic
topic %TOPIC; #REQUIRED
transID %UNIQID; #REQUIRED>
<!ELEMENT listtopics EMPTY>
<!ELEMENT subscribe EMPTY>
<!ATTLIST subscribe
subscriber %ENDPOINT; #REQUIRED
topic %TOPIC; #REQUIRED
transID %UNIQID; #REQUIRED
duration %SECONDS; #REQUIRED>
<!ELEMENT cancel EMPTY>
<!ATTLIST cancel
topic %TOPIC; #REQUIRED
transID %UNIQID; #REQUIRED>
<!ELEMENT topiclist (topic*)>
<!ELEMENT topic EMPTY>
<!ATTLIST name %TOPIC; #REQUIRED>
Schwartz, et. al. Expires April 23, 2002 [Page 26]
Internet-Draft The APEX Publish-Subscribe Service October 2001
7. Security Considerations
Consult [2]'s Section 11 for a discussion of APEX security issues.
The APEX access [5] service provides considerable flexibility to
administrators. For example:
To implement a policy that only allows applications within the
example.com administrative domain to create and delete topics in that
administrative domain, the APEX access service would contain the
entry:
<access owner='apex=pubsub@example.com'
actor='*@example.com'
actions='pubsub:createtopic pubsub:deletetopic' />
To implement a policy that allows any application to subscribe to the
music.jazz.milesdavis topic in the example.com administrative and
that allows a pubsub server in the forwarder.com domain to handle
distributed subscription management for this topic, the APEX access
service would contain the entries:
<access owner='apex=pubsub/music.jazz.milesdavis@example.com'
actor='*@*'
actions='pubsub:subscribe' />
<access owner='apex=pubsub/music.jazz.milesdavis@example.com'
actor='apex=pubsub/music.jazz.milesdavis@forwarder.com'
actions='pubsub:subscribe' />
To implement a policy that allows anyone to publish to the
music.jazz.milesdavis topic in the example.com administrative domain,
the APEX access service would contain the entry:
<access owner='apex=pubsub/music.jazz.milesdavis@example.com'
actor='*@*'
actions='core:data' />
To add an exception list stating that mr.slate@example.com is not
allowed to publish to this topic, the APEX access service would
contain the above entry and also this entry:
<access owner='apex=pubsub/music.jazz.milesdavis@example.com'
actor='mr.slate@example.com'
actions='' />
Schwartz, et. al. Expires April 23, 2002 [Page 27]
Internet-Draft The APEX Publish-Subscribe Service October 2001
To implement a policy that only allows people who are subscribed to a
topic to publish to that topic, the pubsub service would update the
set of access entries whenever a subscribe or cancel operation was
successfully performed. For example, when user barney@rubble.com
subscribes to the music.jazz.milesdavis topic in the example.com
administrative domain, the following token would be added to the APEX
access service:
<access owner='apex=pubsub/music.jazz.milesdavis@example.com'
actor='barney@rubble.com'
actions='core:data' />
Schwartz, et. al. Expires April 23, 2002 [Page 28]
Internet-Draft The APEX Publish-Subscribe Service October 2001
References
[1] Deering, S., "Host extensions for IP multicasting", STD 5, RFC
1112, August 1989.
[2] Rose, M., Klyne, G. and D. Crocker, "The Application Exchange
Core", draft-ietf-apex-core-05 (work in progress), August 2001.
[3] Rose, M., "The Blocks Extensible Exchange Protocol Core", RFC
3080, March 2001.
[4] Rose, M., "Mapping the BEEP Core onto TCP", RFC 3081, March
2001.
[5] Rose, M., Klyne, G. and D. Crocker, "The APEX Access Service",
draft-ietf-apex-access-07 (work in progress), August 2001.
[6] Kantor, B. and P. Lapsley, "Network News Transfer Protocol", RFC
977, Feb 1986.
[7] Rose, M., Klyne, G. and D. Crocker, "The APEX Presence Service",
draft-ietf-apex-presence-05 (work in progress), July 2001.
[8] Dixon, E., Franklin, H., Kint, J., Klyne, G., New, D., Pead, S.,
Rose, M. and M. Schwartz, "The APEX Option Party Pack, Part
Deux!", draft-ietf-apex-party-04 (work in progress), October
2001.
[9] World Wide Web Consortium, "Platform For Internet Content
Selection (PICS)", W3C PICS, October 2001,
<http://www.w3.org/PICS>.
Authors' Addresses
Michael F. Schwartz
NetTopBox, Inc.
EMail: schwartz@CodeOnTheRoad.com
URI: http://www.CodeOnTheRoad.com
Schwartz, et. al. Expires April 23, 2002 [Page 29]
Internet-Draft The APEX Publish-Subscribe Service October 2001
Marshall T. Rose
Dover Beach Consulting, Inc.
POB 255268
Sacramento, CA 95865-5268
US
Phone: +1 916 483 8878
EMail: mrose@dbc.mtview.ca.us
K. Carlberg
University College London
EMail: K.Carlberg@cs.ucl.ac.uk
Schwartz, et. al. Expires April 23, 2002 [Page 30]
Internet-Draft The APEX Publish-Subscribe Service October 2001
Appendix A. IANA Considerations
The IANA makes the registration specified in Section 5.
Schwartz, et. al. Expires April 23, 2002 [Page 31]
Internet-Draft The APEX Publish-Subscribe Service October 2001
Appendix B. Acknowledgements
The authors gratefully acknowledge the contributions of: Jon
Crowcroft, Eric Dixon, Huston Franklin, Carl Malamud, and Bob Wyman.
Schwartz, et. al. Expires April 23, 2002 [Page 32]
Internet-Draft The APEX Publish-Subscribe Service October 2001
Appendix C. Revision History
Note to RFC editor: please remove this entire appendix, and the
corresponding entries in the table of contents, prior to publication.
C.1 Changes from draft-schwartz-apex-pubsub-01
o Moved the dataHopping option to the APEX party pack specification.
C.2 Changes from draft-schwartz-apex-pubsub-00
o dropped references to expired MAPEX Internet Draft
o modified createtopic and deletetopic operation descriptions
(sections 4.2, 4.3) to include interactions with APEX presence
service to track current topic list and to provide pointer to
arbitrary descriptive content about topic (e.g., for PICS labels
or a syntax description of the data messages sent for that topic)
Schwartz, et. al. Expires April 23, 2002 [Page 33]
Internet-Draft The APEX Publish-Subscribe Service October 2001
Full Copyright Statement
Copyright (C) The Internet Society (2001). All Rights Reserved.
This document and translations of it may be copied and furnished to
others, and derivative works that comment on or otherwise explain it
or assist in its implementation may be prepared, copied, published
and distributed, in whole or in part, without restriction of any
kind, provided that the above copyright notice and this paragraph are
included on all such copies and derivative works. However, this
document itself may not be modified in any way, such as by removing
the copyright notice or references to the Internet Society or other
Internet organizations, except as needed for the purpose of
developing Internet standards in which case the procedures for
copyrights defined in the Internet Standards process must be
followed, or as required to translate it into languages other than
English.
The limited permissions granted above are perpetual and will not be
revoked by the Internet Society or its successors or assigns.
This document and the information contained herein is provided on an
"AS IS" basis and THE INTERNET SOCIETY AND THE INTERNET ENGINEERING
TASK FORCE DISCLAIMS ALL WARRANTIES, EXPRESS OR IMPLIED, INCLUDING
BUT NOT LIMITED TO ANY WARRANTY THAT THE USE OF THE INFORMATION
HEREIN WILL NOT INFRINGE ANY RIGHTS OR ANY IMPLIED WARRANTIES OF
MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE.
Acknowledgement
Funding for the RFC Editor function is currently provided by the
Internet Society.
Schwartz, et. al. Expires April 23, 2002 [Page 34]