INTERNET DRAFT J. Cohen, Microsoft S. Aggarwal, Microsoft Expires January 1, 1999 July 9, 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 learn the current status of any Internet-Draft, please check the "1id- abstracts.txt" listing contained in the Internet-Drafts Shadow Directories on ftp.is.co.za (Africa), nic.nordu.net (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 This specification defines an HTTP notification architecture that transmits notifications between HTTP resources. An HTTP resource could be any object which might need to send or receive a notification, for example a distribution list, buddy list, print job, etc. Cohen et al. [Page 1] INTERNET-DRAFT GENA Base July 9, 1998 Introduction The protocol definition provides two main components notification and subscription that can be used independently or in combination. Any resource can transmit a notification through HTTP to any other resource through the NOTIFY method. Notifications can be triggered by arbitrary events occurring on originating resources for example, a change in the properties of a resource, a notification received by the originating resource, or any other general event. Additionally, a resource can establish a subscription relationship with any other resource and thereby automatically receive a notification when a specified event occurs on the latter resource. The notification framework defined herein thus provides powerful capabilities to track arbitrary properties on resources on a real-time basis, such as remote filesystem properties, buddy list online presence information, device availability, etc. The notification framework also allows for more complex routing schemes, such as routing notifications through a succession or hierarchy of resources or sending a notification to more than one resource. This specification defines the syntax and semantics for asynchronous and polled notification delivery. Asynchronous notifications allow a subscription server to send an event notification at any time, without maintaining a persistent network connection. Polled notifications allow a backward compatible, although less elegant, mechanism for notification delivery across a deployed infrastructure of proxy servers and firewalls. The set of delivery mechanisms is extensible. 1 Definitions 1.1 Resource A resource is any entity with a URI address that wishes to participate in this notifications protocol. 1.2 Event Any change in a resource that potentially needs to trigger an event notification. 1.3 Subscription An established relationship in which a resource has indicated interest in certain events. 1.4 Subscriber A resource that negotiates a subscription with a subscription server. Cohen et al. [Page 2] INTERNET-DRAFT GENA Base July 9, 1998 1.5 Implied Subscriber A resource that did not negotiate a subscription with a subscription server but will still be notified of events on that server. 1.6 Subscribed Resource A subscribed resource is a resource that is the subject of a subscription. 1.7 Event Notification An event notification is a message sent by a subscribed resource to its subscribers, implied and otherwise, notifying them of an event on that resource. 2 New HTTP Methods Notification and subscription messages are transmitted via new HTTP methods. 2.1 Subscription Methods 2.1.1 SUBSCRIBE The SUBSCRIBE method is used to subscribe to a subscription server. 2.1.2 UNSUBSCRIBE The UNSUBSCRIBE method is used to terminate a subscription. 2.2 Delivery Methods 2.2.1 NOTIFY NOTIFY is used for asynchronous notification delivery from one resource to another. The Request-URI is the URI of the resource to be notified. 2.2.2 POLL POLL is used to check a resource for pending events. When a POLL request occurs, the Request-URI is the URI of the subscribed resource. 3 Subscriptions 3.1 SUBSCRIBE request A subscriber subscribes to subscription servers via the SUBSCRIBE method. The Request-URI specifies the URI of the resource being subscribed to. Cohen et al. [Page 3] INTERNET-DRAFT GENA Base July 9, 1998 The following headers are provided (detailed header definitions are given in a later section): 3.1.1 Notification-Type Notification-Type indicates the type of event being subscribed to 3.1.2 Call-Back Call-Back indicates how event notifications are to be delivered from the subscription server to the subscriber 3.1.3 Subscription-Lifetime Subscription-Lifetime indicates when the subscription is to expire. 3.2 SUBSCRIBE responses The response to a SUBSCRIBE method must include a Subscription-ID header that uniquely identifies the subscription. The response must also include the Delivery-Scheme and Subscription- Lifetime headers, with possibly adjusted values. 4 Delivery Mechanisms Subscribers use the call-back or delivery-control header to specify the method requested for delivering notifications, as well as any parameters associated with the method. This document defines two delivery schemes Asynchronous and Polled. The set of delivery schemes is extensible. 4.1 Asynchronous Asynchronous notification delivery occurs through a NOTIFY HTTP message from the subscription server to the subscriber. This behavior may cause problems with some existing systems which expect HTTP requests to initiate from inside of the firewall. 4.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. A Poll-Interval parameter specifies intent to issue the next POLL after the specified Poll-Interval; the server may buffer notifications until the next POLL. Subsequent POLL requests may also have a Poll-Interval header specifying the requested duration until the next POLL. Cohen et al. [Page 4] INTERNET-DRAFT GENA Base July 9, 1998 A wait-timeout parameter specifies a request for the server to keep the SUBSCRIBE connection open until the timeout value expires or a notification is received. [[Issue: does Connection-timeout conflict with HTTP? ]] The wait-timeout header can also appear on a POLL request, with identical semantics. 5 New HTTP Headers 5.1 Notification-Type General Header The Notification-Type request header is used with a SUBSCRIBE request message to indicate the requested notification type. The Notification-Type response header is used with a SUBSCRIBE response to indicate the accepted notification type. Notification-type := notification-Type: ntype Ntype := gena:update | ntype-extension Ntype-extension := < URL > This draft declares one base notification type, gena:update. 5.2 Call-Back General Header The call-back request header is used with a SUBSCRIBE request to indicate the subscriber's preferred call-back addresses. The call-back response header is used with a SUBSCRIBE response to indicate the order in which the subscription server intends to call the listed addresses. If an address submitted with a call-back request header is not listed in the call-back response header then the server has rejected its use. If the server can not accept any of the addresses specified in the call-back request header then the method MUST fail with The format of the call-back header is an ordered list of space separated URIs. The call-back parameter is an ordered series of URIs in a space separated string. Each URI represents an event notification receiver interested in receiving notifications (via NOTIFY or other methods) when a triggering event occurs on the subscribed resource. The call-back with the highest preference is listed first while the call- back with the least preference is listed last in the string. Call-back := Call-Back: URI [ URI ] An example call-back header: Cohen et al. [Page 5] INTERNET-DRAFT GENA Base July 9, 1998 Call-Back: http://switchblade.microsoft.com:8888/mailclient mailto:joshco@microsoft.com This example indicates a preferred call-back via HTTP to the switchblade machine on port 8888 and a secondary call-back via an email to joshco@microsoft.com URIs can be any valid URI type. For example, an http URI like http://foo:port/bar indicates that an http transaction via NOTIFY is to be sent upon event notification. An httpu URI like Httpu://address:port/ indicates that a UDP datagram containing an HTTP request with NOTIFY is to be sent. A mail URI like 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.3 Subscription-Lifetime: This is used on a SUBSCRIBE request as well as response. The requester indicates the timeout it is requesting. The responder may respond with the same or different timeout, but the responder's value is binding. Subscription-Lifetime: 1*DIGIT In seconds. 5.4 Delivery-control: This can be used on a SUBSCRIBE response, or a POLL request or response. (Subscribe requests have an analogous version within the Delivery-Scheme header.) In a request, the value indicates the Delivery-control the client would like; the server responds with the Delivery-control acceptable to it, which may be different from the requested Delivery- control. The Delivery-control header is a generic control mechanism for poll related parameters. Delivery-control := Delivery-control: 1#poll-parameter Poll-parameter := poll-interval | wait-time | poll-provoke | batch-mode Wait-time := wait-time = seconds Poll-Interval := poll-interval = seconds Poll-provoke := poll-provoke Batch-Mode := multipart/related Wait-time: Specifies in seconds how long the client requests the server to keep the connection open (the server may close the connection earlier, at its discretion). Poll-Interval: On request, specifies the requested polling interval initiated by the subscriber. On response, it indicates the servers adjusted recommended poll-interval. Cohen et al. [Page 6] INTERNET-DRAFT GENA Base July 9, 1998 Poll-Provoke: The poll-provoke keyword is typically used in a NOTIFY message, possibly over UDP, to indicate to the subscriber that a notification has occurred and to poll the server for the details. This is included as a security measure for unencrypted and or datagram notifications where eavesdropping is common. This allows the server to enforce ACLs on the subsequent provoked poll. Batch-Mode: The batch mode parameter specifies if and how multiple event notifications may be batched together into a single notification message. In a request, the batch-control parameter indicates the preferred method of batching from the subscriber. In a response, the batch-control parameter indicates the allowed method on the server. This draft specifies a single batch mechanism for multipart/related multipart MIME. It is specified later in this document. Future specifications may define additional batch mechanisms such as XML. Support for batch mode is OPTIONAL. 5.5 Mandatory header for version control: The GENA architecture makes use of the Mandatory specification as part of the HTTP extension framework. [ 13.3 ] 5.6 Mandatory feature use This is included on every request and response, to indicate the notifications protocol version for cross-compatibility. Mandatory := Man: tokenURI This draft specifies the version token URI: http://extensions.iana.org/http/GENA/ This token is expressed as a URI for use with a future http extension framework such as Mandatory [13.3] 5.7 Subscription-ID This is contained in initial SUBSCRIBE responses, on all subsequent SUBSCRIBE requests (for renewing existing subscriptions), on all POLL and UNSUBSCRIBE requests, and on NOTIFY requests generated as a result of a prior subscription. [[Issue: exact subscription ID semantics depends on whether we have a From header.]] Subscription-ID:= subscription-id = string 5.8 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 Cohen et al. [Page 7] INTERNET-DRAFT GENA Base July 9, 1998 route-options := delivery-uri = URI 5.9 Depth Header 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). 5.10 Extended-Response Header Extended-Response := Extended-Response: response-code ; #(ext- param) Ext-param := namespace | comment-field Response-code := numeric-digits Namespace := ns = URI Comment-field := comment = string Example: Extended-Response: 10219 ; ns = http://microsoft.com/gena comment = subscription failed 5.11 The URI scheme httpu: The URI scheme httpu: 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. 6 Response Codes In addition to various HTTP response code messages, GENA response code messages are also defined. These messages are returned through the Extended-response header. GENA responses are comprised of a major response code number and an optional minor response code number. GENA responses always use an appropriate x00 code as the major response code, and a minor response code indicated with the Extended-Response code header. HTTP response codes used for general responses: 200 Success 401 Authorization Required Cohen et al. [Page 8] INTERNET-DRAFT GENA Base July 9, 1998 In other cases, rather than allocate arbitrary response codes from the already limited HTTP response code namespace, extended responses are used. When used to indicate a successful operation, the 200 Ok HTTP response code indicates the major response code, and the minor response code may be: 20241 Subscription Succeeded 20242 Notification Acknowledged 20243 Subscription Terminated When used to indicate an operation failure, the 400 HTTP response code indicates the major response code, and the minor response code may be: 20441 Subscription Failed 20442 No valid call-backs 20443 Unsupported Notification-Type 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. This draft does not address fan-out or aggregation of subscriptions or notification delivery. 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. Cohen et al. [Page 9] INTERNET-DRAFT GENA Base July 9, 1998 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 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 SUBSCRIBE URI HTTP/1.1 Notification-Type: CoreNotificationType Call-back: URI [ URI ] Delivery-control: poll-interval = seconds Subscription-Lifetime: seconds Notification-Version: 1.0 200 Subscribed Notification-Version: 1.0 Call-back: [ accepted callback URIs] Delivery-control: poll-interval = acc Subscription-Lifetime: seconds Subscription-ID: FFFFF NOTIFY cbURI HTTP/1.1 Subscription-ID: FFFF (optional) Notification-Type: UPDATE Notification-Version: 1.0 Content-Type: HTTP/1.1 200 Notification Acknowledged [NOTIFY without subscription-ID is meant for Unsolicited notifications like the IM case.] POLL URI HTTP/1.1 Subscription-ID: FFFF Delivery-control: Wait-time=20 200 None pending Cohen et al. [Page 10] INTERNET-DRAFT GENA Base July 9, 1998 Server: NSERV/1.0 Date: Tue Jan 05, 2068 POLL URI HTTP/1.1 Subscription-ID: FFFF Delivery-control: Wait-time=20 200 Notification Subscription-ID: FFFF Notification-Type: UPDATE UNSUBSCRIBE uri HTTP/1.1 Subscription-Id: NNN Call-back: uri HTTP/1.1 200 Ok Extended-Response: 20243 ; ns=http://extension.iana.org/http/GENA/1/1/1; comment = Subscription Terminated 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 a new entry into an HTTP extension registry. This extension is: http://extension.iana.org/http/GENA/1/1/1 11 Copyright 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 Cohen et al. [Page 11] INTERNET-DRAFT GENA Base July 9, 1998 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 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. 13.3 [Frystyk et al., 1998] Cohen et al. [Page 12] INTERNET-DRAFT GENA Base July 9, 1998 H. Frystyk Nielsen, P. Leach, Microsoft Scott Lawrence, Agranat Systems Mandatory Extensions in HTTP ,, March 13, 1998 14 Authors' Addresses Josh Cohen Microsoft Corporation One Microsoft Way Redmond, WA 98052-6399 Email: Sonu Aggarwal Microsoft Corporation One Microsoft Way Redmond, WA 98052-6399 Email: sonuag@microsoft.com