Network Working Group M.T. Rose Internet-Draft Invisible Worlds, Inc. Expires: June 20, 2001 G. Klyne Content Technologies Limited D.H. Crocker Brandenburg Consulting December 20, 2000 The APEX Presence Service draft-mrose-apex-presence-00 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 June 20, 2001. Copyright Notice Copyright (C) The Internet Society (2000). All Rights Reserved. Abstract This memo describes the APEX presence service, addressed as the well-known endpoint "apex=presence". The presence service is used to manage presence information for APEX endpoints. Rose, et. al. Expires June 20, 2001 [Page 1] Internet-Draft The APEX Presence Service December 2000 Table of Contents 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . . 3 2. Management of Presence Information . . . . . . . . . . . . . . 4 2.1 Update of Presence Information . . . . . . . . . . . . . . . . 5 2.2 Distribution of Presence Information . . . . . . . . . . . . . 6 2.3 Distribution of Watcher Information . . . . . . . . . . . . . 9 3. Format of Presence Entries . . . . . . . . . . . . . . . . . . 12 4. The Presence Service . . . . . . . . . . . . . . . . . . . . . 13 4.1 Use of XML and MIME . . . . . . . . . . . . . . . . . . . . . 14 4.2 The Subscribe Operation . . . . . . . . . . . . . . . . . . . 15 4.3 The Watch Operation . . . . . . . . . . . . . . . . . . . . . 17 4.4 The Publish Operation . . . . . . . . . . . . . . . . . . . . 19 4.5 The Terminate Operation . . . . . . . . . . . . . . . . . . . 21 4.6 The Notify Operation . . . . . . . . . . . . . . . . . . . . . 22 4.7 The Reply Operation . . . . . . . . . . . . . . . . . . . . . 22 5. Registration: The Presence Service . . . . . . . . . . . . . . 23 6. The Presence Service DTD . . . . . . . . . . . . . . . . . . . 24 References . . . . . . . . . . . . . . . . . . . . . . . . . . 27 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . 27 A. Changes from IMXP . . . . . . . . . . . . . . . . . . . . . . 28 Full Copyright Statement . . . . . . . . . . . . . . . . . . . 29 Rose, et. al. Expires June 20, 2001 [Page 2] Internet-Draft The APEX Presence Service December 2000 1. Introduction This memo describes a presence service that is built upon the APEX[1] "relaying mesh". The APEX presence service is used to manage presence information for APEX endpoints. APEX, at its core, provides a best-effort datagram service. Although additional APEX services are co-resident with each relay within an administrative domain, they are logically provided on top of the relaying mesh, i.e., +----------+ +----------+ +----------+ +---------+ | APEX | | APEX | | APEX | | | | access | | presence | | report | | ... | | 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 presence service by exchanging data with the well-known endpoint "apex=presence" in the corresponding administrative domain, e.g., "apex=presence@example.com" is the endpoint associated with the presence service in the "example.com" administrative domain. Note that within a single administrative domain, the presence service makes use of the APEX access[3] service in order to determine if an originator is allowed to view or manage presence information. Rose, et. al. Expires June 20, 2001 [Page 3] Internet-Draft The APEX Presence Service December 2000 2. Management of Presence Information Management of presence information falls into three categories: o applications may update the presence entry associated with an endpoint; o applications may subscribe to receive presence information about an endpoint; and, o applications may find out who is subscribed to receive presence information. Each is now described in turn. Rose, et. al. Expires June 20, 2001 [Page 4] Internet-Draft The APEX Presence Service December 2000 2.1 Update of Presence Information When an application wants to modify the presence entry associated with an endpoint, it sends a publish operation to the service, e.g., +-------+ +-------+ | | -- data -------> | | | appl. | | relay | | | <--------- ok -- | | +-------+ +-------+ C: S: The service immediately responds with a reply operation containing the same transaction-identifier, e.g., +-------+ +-------+ | | <------- data -- | | | relay | | pres. | | | -- ok ---------> | svc. | +-------+ +-------+ C: S: Rose, et. al. Expires June 20, 2001 [Page 5] Internet-Draft The APEX Presence Service December 2000 2.2 Distribution of Presence Information When an application wants to (periodically) receive the presence entry associated with an endpoint, it sends a subscribe operation to the service, e.g., +-------+ +-------+ | | -- data -------> | | | appl. | | relay | | | <--------- ok -- | | +-------+ +-------+ C: S: The service immediately responds with a publish operation containing the same transaction-identifier, e.g., +-------+ +-------+ | | <------- data -- | | | relay | | pres. | | | -- ok ---------> | svc. | +-------+ +-------+ C: S: Rose, et. al. Expires June 20, 2001 [Page 6] Internet-Draft The APEX Presence Service December 2000 Subsequently, for up to the specified "duration", the service sends new publish operations whenever there are any changes to the endpoint's presence information. If the "duration" is zero-valued, a one time poll of the presence information is achieved; otherwise, at the end of the "duration", a terminate operation is sent. Note that Step 5 of Section 4.4 requires that the timestamp field of a presence entry be supplied in order to update that entry; accordingly, applications must successfully retrieve an publish entry prior to trying to update that entry. This is usually accomplished by subscribing with a zero-valued duration. Rose, et. al. Expires June 20, 2001 [Page 7] Internet-Draft The APEX Presence Service December 2000 Either the subscriber or the service may cancel a subscription by sending a terminate operation, e.g., +-------+ +-------+ | | -- data -------> | | | appl. | | relay | | | <--------- ok -- | | +-------+ +-------+ C: S: +-------+ +-------+ | | <------- data -- | | | relay | | pres. | | | -- ok ---------> | svc. | +-------+ +-------+ C: S: or +-------+ +-------+ | | <------- data -- | | | relay | | pres. | | | -- ok ---------> | svc. | +-------+ +-------+ C: S: Rose, et. al. Expires June 20, 2001 [Page 8] Internet-Draft The APEX Presence Service December 2000 2.3 Distribution of Watcher Information When an application wants to (periodically) receive notices about endpoints that are subscribed to receive presence information, it sends a watch operation to the service, e.g., +-------+ +-------+ | | -- data -------> | | | appl. | | relay | | | <--------- ok -- | | +-------+ +-------+ C: S: The service immediately responds with a reply operation containing the same transaction-identifier, e.g., +-------+ +-------+ | | <------- data -- | | | relay | | pres. | | | -- ok ---------> | svc. | +-------+ +-------+ C: S: Rose, et. al. Expires June 20, 2001 [Page 9] Internet-Draft The APEX Presence Service December 2000 For each current subscriber, the service immediately sends a notify operation containing the same transaction-identifier, e.g., +-------+ +-------+ | | <------- data -- | | | relay | | pres. | | | -- ok ---------> | svc. | +-------+ +-------+ C: S: Subsequently, for up to the specified "duration", the service sends new notify operations whenever an application subscribes successfully. If the "duration" is zero-valued, a one time poll of the watcher information is achieved; otherwise, at the end of the "duration", a terminate operation is sent. Rose, et. al. Expires June 20, 2001 [Page 10] Internet-Draft The APEX Presence Service December 2000 Either the watcher or the service may cancel the request by sending a terminate operation, e.g., +-------+ +-------+ | | -- data -------> | | | appl. | | relay | | | <--------- ok -- | | +-------+ +-------+ C: S: +-------+ +-------+ | | <------- data -- | | | relay | | pres. | | | -- ok ---------> | svc. | +-------+ +-------+ C: S: or +-------+ +-------+ | | <------- data -- | | | relay | | pres. | | | -- ok ---------> | svc. | +-------+ +-------+ C: S: Rose, et. al. Expires June 20, 2001 [Page 11] Internet-Draft The APEX Presence Service December 2000 3. Format of Presence Entries Each administrative domain is responsible for maintaining a "presence entry" for each of its endpoints (regardless of whether those endpoints are currently attached to the relaying mesh). Section 6 defines the syntax for presence entries. Each presence entry has a "publisher" attribute, a "lastUpdate" attribute, a "publisherInfo" attribute, and contains one or more "tuple" elements: o the "publisher" attribute specifies the endpoint associated with the presence entry; o the "lastUpdate" attribute specifies the date and time that the service last updated the presence entry; o the "publisherInfo" attribute specifies arbitrary information about the publisher (using a URI); and, o each "tuple" element specifies information about an entity associated with the endpoint. Each "tuple" element has a "destination" attribute, an "availableUntil" attribute, a "tupleInfo" attribute, and contains zero or more "capability" elements: o the "destination" attribute identifies the entity as a URI (e.g., "im:fred@example.com" or "mailto:fred@flintstone.com"); o the "availableUntil" attribute specifies the latest date and time that the entity is capable of receiving messages; o the "tupleInfo" attribute specifies arbitrary information about the entity (using a URI); and, o each "capability" element contains a specification as to the kinds of content the entity is capable of receiving. Each "capability" element contains arbitrary character data formatted according to the standard indicated in the element's "baseline" attribute. Rose, et. al. Expires June 20, 2001 [Page 12] Internet-Draft The APEX Presence Service December 2000 4. The Presence Service Section 5 contains the APEX service registration for the presence service: o Within an administrative domain, the service is addressed using the well-known endpoint of "apex=presence". o Section 6 defines the syntax of the operations exchanged with the service. o A consumer of the service initiates communications by sending data containing the subscribe, watch, or publish operation. o In addition to replying to these operations, the service may also initiate communications by sending data containing the terminate, publish, or notify operations. An implementation of the service must maintain information about both presence entries and in-progress operations in persistent storage. Consult Section 6.1.1 of [1] for a discussion on the properties of long-lived transaction-identifiers. Rose, et. al. Expires June 20, 2001 [Page 13] Internet-Draft The APEX Presence Service December 2000 4.1 Use of XML and MIME Section 4.1 of [1] describes how arbitrary MIME content is exchanged as a BEEP[2] payload. For example, to transmit: where "..." refers to: then the corresponding BEEP message might look like this: C: MSG 1 1 . 42 1234 C: Content-Type: multipart/related; boundary="boundary"; C: start="<1@example.com>"; C: type="application/beep+xml" C: C: --boundary C: Content-Type: application/beep+xml C: Content-ID: <1@example.com> C: C: C: C: C: C: --boundary C: Content-Type: application/beep+xml C: Content-Transfer-Encoding: binary C: Content-ID: <2@example.com> C: C: C: --boundary-- C: END or this: C: MSG 1 1 . 42 1234 C: Content-Type: application/beep+xml C: C: C: C: C: C: C: C: C: END Rose, et. al. Expires June 20, 2001 [Page 14] Internet-Draft The APEX Presence Service December 2000 4.2 The Subscribe Operation When an application wants to (periodically) receive the presence entry associated with an endpoint, it sends a "subscribe" element to the service. The "subscribe" element has a "publisher" attribute, a "duration" attribute, a "transID" attribute, and no content: o the "publisher" attribute specifies the endpoint associated with the presence entry; o the "transID" attribute specifies the transaction-identifier associated with this operation; and, o the "duration" attribute specifies the maximum number of seconds for which the originator is interested in receiving updated presence information. Rose, et. al. Expires June 20, 2001 [Page 15] Internet-Draft The APEX Presence Service December 2000 When the service receives a "subscribe" element, we refer to the "publisher" attribute of that element as the "subject", and the service performs these steps: 1. If the subject is outside of this administrative domain, a "reply" element having code 553 is sent as data to the originator. 2. If the subject does not refer to a valid endpoint, a "reply" element having code 550 is sent as data to the originator. 3. If the subject's access entry does not contain a "presence:subscribe" token for the originator, a "reply" element having code 537 is sent as data to the originator. 4. If the originator already has an in-progress subscribe operation for the subject, then the previous subscribe operation is silently terminated, and processing continues. 5. If the "transID" attribute refers to an in-progress subscribe or watch operation for the originator, a "reply" element having code 555 is sent as data to the originator. 6. Otherwise: 1. A "publish" element, corresponding to the subject's presence entry, is immediately sent as data to the originator. 2. For each endpoint currently watching subscribers to the subject's presence information, a "notify" element is immediately as sent as data (c.f., Step 6.3 of Section 4.6). 3. For up to the amount of time indicated by the "duration" attribute of the "subscribe" element, if the subject's presence entry changes, an updated "presence" element is sent as data to the originator using the publish operation (Section 4.4). Finally, when the amount of time indicated by the "duration" attribute expires, a terminate operation (Section 4.5) is sent to the originator. Note that if the duration is zero-valued, then the subscribe operation is making a one-time poll of the presence information. Accordingly, Step 6.3 above does not occur. Regardless of whether a "publish" or "reply" element is sent to the originator, the "transID" attribute is identical to the value found in the "subscribe" element sent by the originator. Rose, et. al. Expires June 20, 2001 [Page 16] Internet-Draft The APEX Presence Service December 2000 4.3 The Watch Operation When an application wants to (periodically) receive notices about endpoints that are subscribed to receive presence information, it sends a "watch" element to the service. The "watch" element has a "publisher" attribute, a "duration" attribute, a "transID" attribute, and no content: o the "publisher" attribute specifies the endpoint associated with the presence entry; o the "transID" attribute specifies the transaction-identifier associated with this operation; and, o the "duration" attribute specifies the maximum number of seconds for which the originator is interested in watching subscribers. Rose, et. al. Expires June 20, 2001 [Page 17] Internet-Draft The APEX Presence Service December 2000 When the service receives a "watch" element, we refer to the "publisher" attribute of that element as the "subject", and the service performs these steps: 1. If the subject is outside of this administrative domain, a "reply" element having code 553 is sent as data to the originator. 2. If the subject does not refer to a valid endpoint, a "reply" element having code 550 is sent as data to the originator. 3. If the subject's access entry does not contain a "presence:watch" token for the originator, a "reply" element having code 537 is sent as data to the originator. 4. If the originator already has an in-progress watch operation for the subject, then the previous watch operation is silently terminated, and processing continues. 5. If the "transID" attribute refers to an in-progress subscribe or watch operation for the originator, a "reply" element having code 555 is sent as data to the originator. 6. Otherwise: 1. A "reply" element having code 250 is sent as data to the originator. 2. For each endpoint currently subscribing to the subject's presence information, a "notify" element is immediately sent as data to the originator (c.f., Section 4.6). Finally, when the amount of time indicated by the "duration" attribute expires, a terminate operation (Section 4.5) is sent to the originator. 3. For up to the amount of time indicated by the "duration" attribute of the "watch" element, whenever a subscribe operation succeeds, a "notify" element is sent as data to the originator. Finally, when the amount of time indicated by the "duration" attribute expires, the a terminate operation (Section 4.5) is sent to the originator. Note that if the duration is zero-valued, then the watch operation is making a one-time poll of the presence information. Accordingly, Step 6.3 above does not occur. Regardless of whether a "notify" or "reply" element is sent to the originator, the "transID" attribute is identical to the value found in the "presence" element sent by the originator. Rose, et. al. Expires June 20, 2001 [Page 18] Internet-Draft The APEX Presence Service December 2000 4.4 The Publish Operation When an application wants to modify the presence entry associated with an endpoint, it sends a "publish" element to the service. In addition, the service sends a "publish" element to endpoints that have subscribed to see presence information (c.f., Section 4.2). The "publish" element has a "publisher" attribute, a "transID" attribute, and contains a "presence" element: o the "publisher" attribute specifies the endpoint to be associated with the presence entry; o the "transID" attribute specifies the transaction-identifier associated with this operation; o the "timeStamp" attribute specifies the current date and time; and, o the "presence" element contains the desired presence entry for the endpoint. When the service sends a "publish" element, the "transID" attribute specifies the transaction-identifier associated with the subscribe operation that caused this "publish" element to be sent, and the "timeStamp" attribute is the service's notion of the current date and time. No reply is sent by the receiving endpoint. Rose, et. al. Expires June 20, 2001 [Page 19] Internet-Draft The APEX Presence Service December 2000 When the service receives a "publish" element, we refer to the "publisher" attribute of that element as the "subject", and the service performs these steps: 1. If the "publisher" attribute of the "publish" element doesn't match the "publisher" attribute of the "presence" element contained in the "publish" element, a "reply" element having code 503 is sent as data to the originator. 2. If the subject is outside of this administrative domain, a "reply" element having code 553 is sent as data to the originator. 3. If the subject does not refer to a valid endpoint, a "reply" element having code 550 is sent as data to the originator. 4. If the subject's access entry does not contain a "presence:publish" token for the originator, a "reply" element having code 537 is sent as data to the originator. 5. If the "lastUpdate" attribute of the "publish" element is not semantically identical to the last update time of the subject's presence entry, a "reply" element having code 555 is sent as data to the originator. (This allows a simple mechanism for atomic updates.) 6. Otherwise: 1. The subject's presence entry is updated from the "publish" element. 2. The last update time of the presence entry is set to the current time. 3. A "reply" element having code 250 is sent as data to the originator. When sending the "reply" element, the "transID" attribute is identical to the value found in the "publish" element sent by the originator. Rose, et. al. Expires June 20, 2001 [Page 20] Internet-Draft The APEX Presence Service December 2000 4.5 The Terminate Operation When an application no longer wishes to subscribe to presence information or to watch endpoints that are subscribed to receive presence information, it sends a "terminate" element to the service; similarly, when the service no longer considers an application to be subscribing or watching, a "terminate" element is sent to the application. The "terminate" element contains only a "transID" attribute that specifies the transaction-identifier associated an in-progress subscribe or watch operation. Section 9.1 of [1] defines the syntax for the "terminate" element. When the service receives a "terminate" element, it performs these steps: 1. If the transaction-identifier does not refer to a previous publish or watch operation for the originator, an "error" element having code 550 is returned. 2. Otherwise, the previous publish or watch operation for the originator is terminated, and a "reply" element having code 250 is sent as data to the originator. Note that following a terminate operation, the originator may receive further presence or watcher updates. Although the service will send no further updates after processing a terminate operation and sending the reply operation, earlier updates may be in transit. Rose, et. al. Expires June 20, 2001 [Page 21] Internet-Draft The APEX Presence Service December 2000 4.6 The Notify Operation The service sends a "notify" element to endpoints that are watching other endpoints subscribed to presence information (c.f., Section 4.3). The "notify" element has a "subscriber" attribute, a "transID" attribute, and no content: o the "subscriber" attribute specifies the endpoint that is subscribed to presence information; and, o the "transID" attribute specifies the transaction-identifier associated with the watch operation that caused this "notify" element to be sent. No reply is sent by the receiving endpoint. 4.7 The Reply Operation While processing operations, the service may respond with a "reply" element. Consult Sections 10.2 and 6.1.2 of [1], respectively, for the syntax and semantics of the reply operation. Rose, et. al. Expires June 20, 2001 [Page 22] Internet-Draft The APEX Presence Service December 2000 5. Registration: The Presence Service Well-Known Endpoint: apex=presence Syntax of Messages Exchanged: c.f., Section 6 Sequence of Messages Exchanged: c.f., Section 4 Access Control Tokens: presence:subscribe, presence:watch, presence:publish Contact Information: c.f., the "Authors' Addresses" section of this memo Rose, et. al. Expires June 20, 2001 [Page 23] Internet-Draft The APEX Presence Service December 2000 6. The Presence Service DTD %APEXCORE; Rose, et. al. Expires June 20, 2001 [Page 24] Internet-Draft The APEX Presence Service December 2000 Rose, et. al. Expires June 20, 2001 [Page 25] Internet-Draft The APEX Presence Service December 2000 Rose, et. al. Expires June 20, 2001 [Page 26] Internet-Draft The APEX Presence Service December 2000 References [1] Rose, M.T., Klyne, G. and D.H. Crocker, "The Application Exchange Framework", draft-mrose-apex-core-00 (work in progress), December 2000. [2] Rose, M.T., "The Blocks Extensible Exchange Protocol Framework", draft-ietf-beep-framework-09 (work in progress), December 2000. [3] Rose, M.T., Klyne, G. and D.H. Crocker, "The APEX Access Service", draft-mrose-apex-access-00 (work in progress), December 2000. Authors' Addresses Marshall T. Rose Invisible Worlds, Inc. 1179 North McDowell Boulevard Petaluma, CA 94954-6559 US Phone: +1 707 789 3700 EMail: mrose@invisible.net URI: http://invisible.net/ Graham Klyne Content Technologies Limited 1220 Parkview Arlington Business Park Theale, Reading RG7 4SA UK Phone: +44 118 930 1300 EMail: gk@acm.org David H. Crocker Brandenburg Consulting 675 Spruce Drive Sunnyvale, CA 94086 US Phone: +1 408 246 8253 EMail: dcrocker@brandenburg.com URI: http://www.brandenburg.com/ Rose, et. al. Expires June 20, 2001 [Page 27] Internet-Draft The APEX Presence Service December 2000 Appendix A. Changes from IMXP o s/IMXP/APEX/g o Indicate that APEX services are co-resident with each APEX relay. o Change data's originator from an attribute to an element. o CPIM mapping moved to another document. Rose, et. al. Expires June 20, 2001 [Page 28] Internet-Draft The APEX Presence Service December 2000 Full Copyright Statement Copyright (C) The Internet Society (2000). 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. Rose, et. al. Expires June 20, 2001 [Page 29]