INTERNET DRAFT J. Cohen, Microsoft Expires July, 1998 April 23, 1998 General Event Notification Architecture Base Status of this memo This document is an Internet-Draft. 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 made obsolete 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". To view the entire list of current Internet-Drafts, please check the "1id-abstracts.txt" listing contained in the Internet-Drafts Shadow Directories on ftp.is.co.za (Africa), ftp.nordu.net (Northern Europe), ftp.nis.garr.it (Southern Europe), munnari.oz.au (Pacific Rim), ftp.ietf.org (US East Coast), or ftp.isi.edu (US West Coast). Distribution of this document is unlimited. Please send comments to the HTTP working group at . Discussions of the working group are archived at . Abstract At an ever increasing rate, new protocols are being designed which achieve their desired functionality by building upon HTTP. Many of them make good use of the functionality and flexibility of the HTTP model, however, a theme that is becoming common is the cry for a common event notification architecture. This specification defines a simple notification architecture for URI addressable resources. URI addressable resources can include, but are not limited to, simple resources, html files, resources, URI addressable objects, URI addressable process jobs or URI addressable print jobs. Cohen et al. [Page 1] INTERNET-DRAFT GENA Base April 23, 1998 STATUS OF THIS MEMO...................................................1 ABSTRACT..............................................................1 1 DEFINITIONS ........................................................4 1.1 Subscription ....................................................4 1.2 Subscriber ......................................................4 1.3 Subscribed Resource .............................................4 1.4 Event ...........................................................4 1.5 Event Notification ..............................................4 2 MODEL ..............................................................4 2.1 Subscription Requests ...........................................5 2.1.1 Subscription-scheme: ..............................5 3 SUBSCRIPTION MESSAGES ..............................................5 3.1 New Methods .....................................................5 3.1.1 Subscription Methods ..............................5 3.1.2 Delivery Methods ..................................6 3.2 New Headers .....................................................6 3.2.1 Subscription-scheme: ..............................6 3.2.2 Delivery-scheme: ..................................6 3.2.3 Route-ID: .........................................6 3.2.4 Depth Header ......................................6 3.3 The URI scheme httpu: ...........................................7 4 RESPONSE CODES .....................................................7 4.1.1 241 Subscribed ....................................7 4.1.2 242 Subscription Failed ...........................7 4.1.3 243 Notification Failed ...........................7 4.1.4 244 Notification Acknowledged .....................7 4.1.5 245 Events Follow .................................7 4.1.6 246 No Events Pending .............................7 5 SCHEME DEFINITIONS .................................................7 5.1 Subscription Schemes ............................................7 5.2 Basic ...........................................................7 5.2.1 Trigger-condition .................................8 5.2.2 Subscription response parameters ..................8 5.3 Delivery Schemes ................................................9 5.4 Basic Delivery Scheme ...........................................9 5.4.1 Basic Delivery Scheme request parameters ..........9 5.4.2 Basic Delivery response parameters ...............10 6 COMPOUNDED SUBSCRIPTIONS ..........................................10 7 PROXY ROUTING .....................................................11 7.1 Example OPTIONS request ........................................11 7.2 Routing with a compliant Proxy .................................11 7.3 Routing with a non-compliant Proxy .............................11 8 EXAMPLES ..........................................................12 8.1 Method based Async HTTP Subscription ...........................12 8.1.1 Subscription request .............................12 Cohen et al. [Page 2] INTERNET-DRAFT GENA Base April 23, 1998 8.1.2 Subscription response ............................12 8.1.3 Notification request .............................12 8.1.4 Notification response ............................12 8.2 Method based Polled Subscription ...............................12 8.2.1 Subscription request .............................13 8.2.2 Subscription response ............................13 8.2.3 Poll Request .....................................13 8.2.4 Poll response ....................................13 8.2.5 Poll Request .....................................13 8.2.6 Poll response ....................................13 8.3 Compounded Async UDP Subscription ..............................13 8.3.1 Subscription Request .............................13 8.3.2 Subscription Response ............................14 8.3.3 Event Notification ...............................14 9 SECURITY CONSIDERATIONS ...........................................14 10 IANA CONSIDERATIONS .............................................14 11 COPYRIGHT .......................................................14 12 INTELLECTUAL PROPERTY ...........................................15 13 REFERENCES ......................................................16 13.1 [Bradner, 1996] ................................................16 13.2 [Fielding et al., 1997] ........................................16 14 AUTHORS' ADDRESSES ..............................................16 Introduction By using this protocol, a subscriber can establish a subscription relationship with a resource and be notified when a specified event occurs on that resource. Both asynchronously delivered as well as polled delivery are supported. In addition to the general architecture and model specified, this document defines a subscription scheme and delivery scheme "basic" which provides a simple interface to the mechanism. It is expected that additional, more flexible and more complex schemes will be defined in the future. The protocol definition provides two main layers. The first layer is a subscription protocol which is negotiated over HTTP. This provides semantics and syntax for establishing a relationship between a resource and a subscriber which allows the subscriber to receive notifications of changes or events on that resource. The second layer is the definition of the syntax and semantics of the actual notification delivery mechanisms. Two main classes of delivery mechanisms are defined. Asynchronous notifications allow a subscription server to Cohen et al. [Page 3] INTERNET-DRAFT GENA Base April 23, 1998 send an event notification at any time, without maintaining a persistent network connection or resource with the subscriber. Polled notifications allow a backward compatible, although less elegant, mechanism for notification delivery across a deployed infrastructure of proxy servers and firewalls. While the asynchronous mechanism is truly a "push" mechanism, polled mechanisms are "pull". Depending on the resources in question, their rate of change, and the infrastructure in between a resource and a subscriber, either may be appropriate. . 1 Definitions 1.1 Subscription A subscription is an established relationship where a subscriber is interested in events which happen to a resource. 1.2 Subscriber A subscriber is an entity which negotiates a subscription relationship with a subscription server to receive notifications about events which happen to a resource. 1.3 Subscribed Resource A subscribed resource is a resource which is the subject of a subscription. 1.4 Event An event happens to a resource. The occurrence of an event is potentially a trigger for an event notification. 1.5 Event Notification An event notification is a message delivered to a subscriber describing an event which has happened to a subscribed resource. 2 Model The general model of the architecture takes place as follows: A subscriber declares a subscription request over HTTP via the SUBSCRIBE method. Along with the subscribe method, the subscriber indicates parameters which define the Cohen et al. [Page 4] INTERNET-DRAFT GENA Base April 23, 1998 subscription semantics as well as the notification delivery semantics 2.1 Subscription Requests Subscription requests have two main parameters: 2.1.1 Subscription-scheme: Subscription type specifies a subscription scheme as well as scheme related parameters. Required parameters for a given scheme are: 2.1.1.1 Trigger-condition The trigger condition defines the actions which will cause an event notification to be delivered to the subscriber. Typical trigger-conditions are UPDATE, DELETE, COMPLETED. Exact trigger conditions are defined by the subscription type scheme. 2.1.1.2 Delivery Mechanism The delivery mechanism specifies the requested mechanism for event notification. Typical delivery mechanisms are "poll" or "async" 3 Subscription Messages Subscription messages are transmitted via HTTP messages. Subscription messages contain a subscription method and a subscription command in the form of an XML body. 3.1 New Methods The following are defined for use in the general event notification architecture. 3.1.1 Subscription Methods 3.1.1.1 SUBSCRIBE The SUBSCRIBE method is used to begin a subscription to a resource. The URI included with SUBSCRIBE indicates the resource which is being subscribed to. 3.1.1.2 UNSUBSCRIBE The UNSUBSCRIBE method is used to terminate a subscription. The URI included with UNSUBSCRIBE indicates the resource which is being unsubscribed. Cohen et al. [Page 5] INTERNET-DRAFT GENA Base April 23, 1998 UNSUBCRIBE requires the parameter subscription-ID: to indicate which resource is to be unsubscribed from. Its syntax is dependent on the scheme used. 3.1.2 Delivery Methods 3.1.2.1 NOTIFY NOTIFY is used for asynchronous notification delivery. It is the method used for a subscription server initiated HTTP request message destined for the subscription client. 3.1.2.2 POLL POLL is used to check a resource for pending events. 3.2 New Headers 3.2.1 Subscription-scheme: Subscription-scheme indicates the type of subscription that is requested. Syntax: "Subscription-scheme:" subscription-scheme ";" scheme- options 3.2.2 Delivery-scheme: Delivery-scheme: indicates the type or mechanism of delivery preferred for event notification on the subscription. Syntax: "Delivery-scheme:" delivery-scheme ";" scheme-options 3.2.3 Route-ID: Route-ID: indicates a route identifier for the message. Each proxy or gateway in the path should append a route-id header to the subscription message. When adding a new route-ID header, the proxy should use an integer greater than the current highest in the rid field. Syntax: "Route-ID:" rid ";" route-options rid := integer route-options := "delivery-uri" "=" URI 3.2.4 Depth Header Cohen et al. [Page 6] INTERNET-DRAFT GENA Base April 23, 1998 Depth = "Depth" ":" ("0" | "1" | "infinity") The Depth header is used with methods executed on resources which could potentially have internal members to indicate whether the method is to be applied only to the resource (Depth = 0), to the resource and its immediate children, (Depth = 1), or the resource and all its progeny (Depth = infinity). 3.3 The URI scheme httpu: The URI scheme udp: is defined to include a host and a port to which a UDP datagram can be sent. It is specified as a URI with scheme `httpu'. When used with the notification system, the payload of the UDP datagram is to be the same as the HTTP messages defined here as well. 4 Response Codes In addition to various HTTP messages, GENA messages are also defined. These messages may be returned in the normal HTTP way as response codes, or may be included in the body via XML . 4.1.1 241 Subscribed 4.1.2 242 Subscription Failed 4.1.3 243 Notification Failed 4.1.4 244 Notification Acknowledged 4.1.5 245 Events Follow 4.1.6 246 No Events Pending 5 Scheme Definitions 5.1 Subscription Schemes The currently defined schemes are: Subscription-scheme := "Basic" | "XML" Scheme-options := name "=" value [ , name "=" value ]# Name := quoted-string Value := quoted-string Other future specs may define other subscription schemes which are used with this protocol. 5.2 Basic The basic subscription scheme is used for simple event notification. When using basic subscriptions: Cohen et al. [Page 7] INTERNET-DRAFT GENA Base April 23, 1998 Subscription-scheme := "Basic" Valid request parameters for scheme-options are: 5.2.1 Trigger-condition The trigger type indicates what events will trigger a notification on this subscription. Acceptable values for trigger-condition are: 5.2.1.1 "update" Any event which changes the state of the subscribed resource will cause an update notification to be sent. 5.2.1.2 "delete" Any event which causes the resource to be deleted or be made unavailable shall cause a "delete" notification to be sent. 5.2.1.3 "Completion" Any event on a resource which indicates completion. This is appropriate for job submission objects, process control, or batch environments. 5.2.1.4 "implicit" Implicit trigger events are for use on compounded subscriptions only. In this case, the method compounded upon produces a response which defines the trigger- condition. 5.2.1.5 Lifetime Lifetime indicates the requested lifetime of a subscription. A server may choose to honor the requested lifetime or to adjust it in the response. No matter what the lifetime setting is, a subsequent UNSUBSCRIBE may terminate a subscription. Lifetime is expressed in seconds 5.2.2 Subscription response parameters In response to a subscription message, the subscription server responds with the delivery-scheme: header as included by the client, but possibly with adjusted values. In addition, the server will include: 5.2.2.1 Subscription-ID: Cohen et al. [Page 8] INTERNET-DRAFT GENA Base April 23, 1998 The subscription ID is a unique identifier with references the subscription itself. In addition to identifying the subscription, it can also be used with a polled resource. 5.3 Delivery Schemes This specification defines the "basic" delivery scheme. When using the "basic" delivery mechanism, the delivery- mechanism scheme is set to "basic" 5.4 Basic Delivery Scheme Delivery-scheme := "Basic" | "XML" Scheme-options := name "=" value [ , name "=" value ]# Name := quoted-string Value := quoted-string 5.4.1 Basic Delivery Scheme request parameters 5.4.1.1 Delivery-scheme: 5.4.1.1.1 Asynchronous Asynchronous notification delivery implies that the delivery can occur at any time, without specific action of the subscriber. Delivery occurs as an HTTP message where the subscribed resource owner initiates an HTTP request to the subscriber. This behaves compliant to 13.2 where the traditional roles of server and client are reversed. When using the delivery type "async", the scheme is set to "basic" and scheme options are: "Delivery-type" "delivery-type" "=" "async" "call-back" "call-back:" "=" URI Call-back indicates the URI of the event notification receiver. URIs can be any valid URI type. Such as: http://foo:port/bar Indicates an http transaction via NOTIFY is to be sent upon event notification. httpu://address:port/path Cohen et al. [Page 9] INTERNET-DRAFT GENA Base April 23, 1998 Indicates that a UDP datagram containing an HTTP request with NOTIFY and appropriate subscription-scheme are to be sent. mailto:user@domain Indicates that an email message containing the same HTTP message with NOTIFY is to be sent as the body of an email message. 5.4.1.1.2 Polled Polled delivery indicates that the subscription client will poll the resource at a specified interval agreed upon by the server and the client. When using polled delivery, the basic delivery scheme includes the following scheme-options "poll-interval" "poll-interval" "=" seconds Poll-interval indicates the requests poll interval between POLL requests from a subscriber on a subscription. 5.4.2 Basic Delivery response parameters In response to a subscription message, the subscription server responds with the delivery-scheme: header as included by the client, but possibly with adjusted values. 6 Compounded Subscriptions Subscription requests can be compounded, or added to a general HTTP request such as "GET". To accomplish this, along with "GET" or any other method, the headers following are required. Subscription-scheme: Delivery-scheme: Cache-control: Subscribers may also wish to include an appropriate header to indicate the non-cacheability of this request. Users of HTTP/1.0 proxies should include "pragma: no-cache" and users of HTTP/1.1 should include an appropriate header such as "cache-control: no-store". Cohen et al. [Page 10] INTERNET-DRAFT GENA Base April 23, 1998 Since no specific subscription method is used and no specific subscription response code is present in a response, subscription success can be verified if a subscription-scheme header is returned with a subscription-id parameter. 7 Proxy Routing Often, a client may reach a resource via a proxy server. In this case, with a standard proxy server, asynchronous call-back addresses may not be visible to an external server. Because of this, the Route-ID: header is introduced. Subscription clients should poll their proxy chain to detect which version of HTTP that proxy supports. In addition, they should poll for support of the `route-id' extension. This polling should be done via OPTIONS. 7.1 Example OPTIONS request The proxy is myproxy.my.com on port 8080 OPTIONS * HTTP/1.1 Host: myproxy.my.com:8080 Compliance: uri=http://ietf.org/http-ext/route-id Compliance: uri=http://ietf.org/http/v11 A successful response: HTTP/1.1 200 Ok Compliance: uri=http://ietf.org/http-ext/route-id Compliance: uri=http://ietf.org/http/v11 Lack of a successful response indicates non-compliance with HTTP/1.1 and Route-ID extensions. 7.2 Routing with a compliant Proxy Compliant proxy servers are expected to include a "Route- ID" header as they forward subscription request messages. As they include the route-id header, the rid parameter is to be an integer greater than the highest rid parameter of any other route-id header already in a message. This allows a deterministic route list for the message transit. Servers who send responses to messages which include route-id headers are expected to consume the highest rid parameter route-id header, strip it from the message and use that address as the connection proxy for notification delivery. 7.3 Routing with a non-compliant Proxy Cohen et al. [Page 11] INTERNET-DRAFT GENA Base April 23, 1998 Since no deterministic way exists to determine an appropriate call-back path for notification delivery, subscribers should NOT select asynchronous call-back as a delivery type. 8 Examples This section describes some examples using the notification architecture. 8.1 Method based Async HTTP Subscription Here, as subscriber subscribes to a resource http://server/document.html. The delivery mechanism requested is asynchronous with TCP based HTTP. The call- back address is http://mypc:8080/ 8.1.1 Subscription request SUBSCRIBE http://server/document.html HTTP/1.1 Host: server Subscription-scheme: basic ; trigger-condition="update" Delivery-scheme: basic ; delivery-type="async" ,call- back=http://mypc:8080/ 8.1.2 Subscription response HTTP/1.1 241 Subscribed Server: foo Subscription-scheme: basic ; subscription-id="1049" ,trigger-condition="update" Delivery-scheme: basic ; delivery-type="async" ,call- back=http://mypc:8080/ 8.1.3 Notification request NOTIFY http://mypc:8080/ HTTP/1.1 Host: server Subscription-scheme: basic ; subscription-id="1049" 8.1.4 Notification response HTTP/1.1 244 Notification Acknowledged Server: mypc-server Date: [date] 8.2 Method based Polled Subscription A subscriber subscribes to http://server/document.html with polled delivery. The server overrides the requested poll-interval. Cohen et al. [Page 12] INTERNET-DRAFT GENA Base April 23, 1998 8.2.1 Subscription request SUBSCRIBE http://server/document.html HTTP/1.1 Host: server Subscription-scheme: basic ; trigger-condition="update" Delivery-scheme: basic ; delivery-type="poll" , poll- interval="10" 8.2.2 Subscription response HTTP/1.1 241 Subscribed Server: foo Subscription-scheme: basic ; subscription-id="1049" ,trigger-condition="update" Delivery-scheme: basic ; delivery-type="poll", poll-interval="30" 8.2.3 Poll Request POLL http://server/document.html HTTP/1.1 Host: server Subscription-scheme: basic ; subscription-id="1049" 8.2.4 Poll response HTTP/1.1 246 No events pending Server: mypc-server Date: [date] 8.2.5 Poll Request POLL http://server/document.html HTTP/1.1 Host: server Subscription-scheme: basic ; subscription-id="1049" 8.2.6 Poll response HTTP/1.1 245 Events Pending Server: mypc-server Date: [date] Subscription-scheme: basic ; subscription-id="1049" ,trigger-condition="update" 8.3 Compounded Async UDP Subscription A subscriber requests a subscription on a resource http://www.foo.bar/files/ the subscription is on the children of the collection, not the resource itself. The subscription is compounded on a GET. 8.3.1 Subscription Request Cohen et al. [Page 13] INTERNET-DRAFT GENA Base April 23, 1998 GET /files/ HTTP/1.1 Host: www.foo.bar Depth: 1 Subscription-scheme: basic ; trigger-condition="implicit" Delivery-scheme: basic ; delivery-type="async", call- back="httpu://mypc:8080/app" Content-type: text/xml Content-Length: xyz 8.3.2 Subscription Response HTTP/1.1 200 OK Subscription-scheme: basic ; subscription-id="1049" ,trigger-condition="implicit" Delivery-scheme: basic ; delivery-type="async" ,call- back=http://mypc:8080/app Content-Type: text/html Content-Length: xxxxx 8.3.3 Event Notification Event notification in this case is the server sending a UDP datagram to mypc on port 8000. Note that there is no acknowledgement in this case. [ UDP datagram to host mypc on port 8000 ] [payload contents: ] NOTIFY http://mypc:8080/app HTTP/1.1 Subscription-scheme: basic ; subscription-id="1049" 9 Security Considerations Servers responding to subscription requests should be careful to implement a rational security policy for subscriptions which protects the event notification data about resources as well as the resources themselves. Allowing a subscriber to receive notifications on a resource which that subscriber would not normally have access to may unknowingly reveal information about that resource or the contents itself. 10 IANA Considerations This document introduces no new IANA considerations. 11 Copyright Cohen et al. [Page 14] INTERNET-DRAFT GENA Base April 23, 1998 The following copyright notice is copied from RFC 2026 [Bradner, 1996], Section 10.4, and describes the applicable copyright for this document. Copyright (C) The Internet Society February 10, 1998. 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 assignees. 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. 12 Intellectual Property The following notice is copied from RFC 2026 [Bradner, 1996], Section 10.4, and describes the position of the IETF concerning intellectual property claims made against this document. The IETF takes no position regarding the validity or scope of any intellectual property or other rights that might be claimed to pertain to the implementation or use other technology described in this document or the extent to which any license under such rights might or might not be available; neither does it represent that it has made any effort to identify any such rights. Information on the IETF's procedures with respect to rights in standards- track and standards-related documentation can be found in BCP-11. Copies of claims of rights made available for Cohen et al. [Page 15] INTERNET-DRAFT GENA Base April 23, 1998 publication and any assurances of licenses to be made available, or the result of an attempt made to obtain a general license or permission for the use of such proprietary rights by implementers or users of this specification can be obtained from the IETF Secretariat. The IETF invites any interested party to bring to its attention any copyrights, patents or patent applications, or other proprietary rights which may cover technology that may be required to practice this standard. Please address the information to the IETF Executive Director. 13 References 13.1 [Bradner, 1996] S. Bradner, "The Internet Standards Process - Revision 3." RFC 2026, BCP 9. Harvard University. October, 1996. 13.2 [Fielding et al., 1997] R. Fielding, J. Gettys, J. Mogul, H. Frystyk, T. Berners- Lee, "Hypertext Transfer Protocol -- HTTP/1.1." RFC 2068. U.C. Irvine, DEC, MIT/LCS. January, 1997. 14 Authors' Addresses Josh Cohen Microsoft Corporation One Microsoft Way Redmond, WA 98052-6399 Email: Cohen et al. [Page 16]