INTERNET DRAFT J. Cohen, Microsoft
<draft-cohen-gena-p-base-01.txt> 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 <http-wg@cuckoo.hpl.hp.com>. Discussions of the
working group are archived at <URL:http://www.ics.uci.edu/pub/ietf/http/>.
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 ,<W3C draft-frystyk-http-mandatory>, March
13, 1998
14 Authors' Addresses
Josh Cohen
Microsoft Corporation
One Microsoft Way
Redmond, WA 98052-6399
Email: <joshco@microsoft.com>
Sonu Aggarwal
Microsoft Corporation
One Microsoft Way
Redmond, WA 98052-6399
Email: sonuag@microsoft.com