TOC 
Network Working GroupM. Schwartz
Internet-DraftNetTopBox, Inc.
Expires: April 7, 2002M. Rose
 Dover Beach Consulting, Inc.
 K. Carlberg
 University College London
 October 7, 2001

The APEX Publish-Subscribe Service
draft-schwartz-apex-pubsub-01

Status of this Memo

This document is an Internet-Draft and is in full conformance with all provisions of Section 10 of RFC2026.

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 7, 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.



 TOC 

Table of Contents




 TOC 

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.

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.



 TOC 

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 />

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 />

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 />

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.

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 />

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 />

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 />

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. The Subscribe Operation and The Cancel Operation present the algorithmic details.

It is a local provisioning decision whether a redistributing pubsub server advertises its presence to end users.



 TOC 

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: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>

     <album>
         <artist>Miles Davis</artist>
         <title>Kind of Blue</title>
         <date>1959</date>
         <tracks>
             <track>So What</track>
             <track>Freddie Freeloader</track>
             <track>Blue in Green</track>
             <track>All Blues</track>
             <track>Flamenco Sketches</track>
             <track>Flamenco Sketches (Alternate Take)</track>
         </tracks>
     </album>
     --boundary--
  S: <ok />

In response, the service forwards the message content to each subscriber of the subaddress-named topic, rewriting the message 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:2@example.com'>
         <originator
          identity='apex=pubsub/music.jazz.milesdavis@example.com' />
         <recipient identity='subscriber1@example.com' />
         <recipient identity='subscriber2@example.com' />
     </data>
     --boundary
     Content-Type: application/beep+xml
     Content-ID: <2@example.com>
     
     <album>
         <artist>Miles Davis</artist>
         <title>Kind of Blue</title>
         <date>1959</date>
         <tracks>
             <track>So What<track>
             <track>Freddie Freeloader<track>
             <track>Blue in Green<track>
             <track>All Blues<track>
             <track>Flamenco Sketches<track>
             <track>Flamenco Sketches (Alternate Take)<track>
         </tracks>
     </album>
     --boundary--
  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.



 TOC 

4. The Pubsub Service

Registration: The Pubsub Service contains the APEX service registration for the pubsub service:

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.

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

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:

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[8] 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.

The "deletetopic" element has a "topic" attribute, a "transID" attribute, and no content:

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.

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:

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 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.

The "cancel" element has a "subscriber" attribute, a "topic" attribute, a "transID" attribute, and no content:

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.

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.7.2 The dataHopping Option

To detect misconfigurations that cause forwarding loops in the APEX relaying mesh, the APEX pubsub service re-introduces a mechanism similar to the IP TTL[9] mechanism, in the form of an APEX option. Registration: The dataHopping Option contains the APEX option registration for the "dataHopping" option.

If this option is present in the "data" operation (c.f., Section 4.4.4 of [2]) and the value of the "noMoreThan" attribute is non-zero, then:

Further, note that because this option is processed on a per-hop basis, the originator must set the "targetHop" attribute to the value "all" and the "mustUnderstand" attribute to the value "true".

If the APEX report service (c.f., Section 6.2 of [2]) is invoked to send an error report, it issues a data operation with:

For example:

    +-------+                  +-------+
    |       | -- data -------> |       |
    | appl. |                  | relay |
    |       | <--------- ok -- |   #1  |
    +-------+                  +-------+

  C: <data content='cid:1@example.com'>
         <originator identity='appl=pubsub/topic=fred@example.com' />
         <recipient identity='barney@example.com' />
         <option internal='dataHopping' targetHop='all'
                 mustUnderstand='true' transID='86' />
             <dataHopping noMoreThan='2' reportErrors='true' />
         </option>
     </data>
  S: <ok />
                               +-------+                  +-------+
                               |       | -- data -------> |       |
                               | relay |                  | relay |
                               |   #1  | <--------- ok -- |   #2  |
                               +-------+                  +-------+

  C: <data content='cid:1@example.com'>
         <originator identity='appl=pubsub/topic=fred@example.com' />
         <recipient identity='barney@example.com' />
         <option internal='dataHopping' targetHop='all'
                 mustUnderstand='true' transID='86' />
             <dataHopping noMoreThan='1' reportErrors='true' />
         </option>
     </data>
  S: <ok />

relay #2 determines that further relaying is necessary:

    +-------+                  +-------+
    |       | <------- data -- |       |
    | relay |                  | relay |
    |   #1  | -- ok ---------> |   #2  |
    +-------+                  +-------+

  C: <data content='#Content'>
         <originator identity='apex=report@example.com' />
         <recipient identity='appl=pubsub/topic=fred@example.com' />
         <data-content Name='Content'>
             <statusResponse transID='86'>
                 <destination identity='barney@example.com'>
                     <reply code='550' />
                 </destination>
             </statusResponse>
         </data-content>    
     </data>
  S: <ok />

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.



 TOC 

5. Initial Registrations

5.1 Registration: The Pubsub Service

Well-Known Endpoint:
apex=pubsub
Syntax of Messages Exchanged:
c.f., The Pubsub Service DTD
Sequence of Messages Exchanged:
c.f., The Pubsub Service
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

5.2 Registration: The dataHopping Option

The APEX option registration template is defined in Section 7.1 of [2].

Option Identification:
dataHopping
Present in:
APEX's "data" element
Contains:
dataHopping (c.f., The dataHopping Option DTD)
Processing Rules:
c.f., The dataHopping Option
Contact Information:
c.f., the "Authors' Addresses" section of this memo



 TOC 

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

       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>

6.2 The dataHopping Option DTD

<!--
  DTD data types:

       entity        syntax/reference     example
       ======        ================     =======
    hopcount
        HOPS         0..255               17
  -->

<!ENTITY  % HOPS     "CDATA">


<!ELEMENT dataHopping EMPTY>
<!ATTLIST dataHopping
          noMoreThan  %HOPS;            "0"
          reportErrors
                      (true|false)      "false">


 TOC 

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='' />

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' />


 TOC 

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] World Wide Web Consortium, "Platform For Internet Content Selection (PICS)", W3C PICS, October 2001.
[9] Postel, J., "Internet Protocol", STD 5, RFC 791, September 1981.


 TOC 

Authors' Addresses

  Michael F. Schwartz
  NetTopBox, Inc.
EMail:  schwartz@CodeOnTheRoad.com
URI:  http://www.CodeOnTheRoad.com
  
  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


 TOC 

Appendix A. IANA Considerations

The IANA makes the registrations specified in Registration: The dataHopping Option.



 TOC 

Appendix B. Acknowledgements

The authors gratefully acknowledge the contributions of: Jon Crowcroft, Eric Dixon, Huston Franklin, Carl Malamud, and Bob Wyman.



 TOC 

Appendix C. Revision History

C.1 Changes from draft-schwartz-apex-pubsub-00



 TOC 

Full Copyright Statement

Acknowledgement