INTERNET DRAFT J. Cohen, Microsoft
<draft-cohen-gena-p-base-00.txt>
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 <http-
wg@cuckoo.hpl.hp.com>. Discussions of the working group
are archived at
<URL:http://www.ics.uci.edu/pub/ietf/http/>.
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: <joshco@microsoft.com>
Cohen et al. [Page 16]