From: http://www.ietf.org/internet-drafts/draft-mahy-http-change-notification-via-sip-00.txt
Title: Change Notifications about HyperText Transfer Protocol (HTTP) Resources
via the Session Initiation Protocol (SIP) Event Notification Framework
Reference: IETF WEBDAV Working Group, Internet Draft 'draft-mahy-http-change-notification-via-sip-00.txt'
Date: June 25, 2007
I-D Tracker: http://ietfreport.isoc.org/idref/draft-mahy-http-change-notification-via-sip/
IETF WEBDAV Working Group
http://www.ics.uci.edu/~ejw/authoring/
==============================================================================
WEBDAV WG R. Mahy
Internet-Draft Plantronics
Intended status: Standards Track June 25, 2007
Expires: December 27, 2007
Change Notifications about HyperText Transfer Protocol (HTTP) resources
via the Session Initiation Protocol (SIP) Event Notification Framework
draft-mahy-http-change-notification-via-sip-00.txt
Status of this Memo
By submitting this Internet-Draft, each author represents that any
applicable patent or other IPR claims of which he or she is aware
have been or will be disclosed, and any of which he or she becomes
aware will be disclosed, in accordance with Section 6 of BCP 79.
Internet-Drafts are working documents of the Internet Engineering
Task Force (IETF), its areas, and its working groups. Note that
other groups may also distribute working documents as Internet-
Drafts.
Internet-Drafts are draft documents valid for a maximum of six months
and may be updated, replaced, or obsoleted by other documents at any
time. It is inappropriate to use Internet-Drafts as reference
material or to cite them other than as "work in progress."
The list of current Internet-Drafts can be accessed at
http://www.ietf.org/ietf/1id-abstracts.txt.
The list of Internet-Draft Shadow Directories can be accessed at
http://www.ietf.org/shadow.html.
This Internet-Draft will expire on December 27, 2007.
Copyright Notice
Copyright (C) The IETF Trust (2007).
Abstract
This document describes a SIP event package for notification of
content changes of HTTP-based resources, including WebDAV (HTTP
extensions for Distributed Authoring and Versioning) collections and
XCAP (XML Configuration Access Protocol) resources. It also defines
a new WebDAV property that can be used to identify the URI (Uniform
Resource Idenitifier) of a SIP notification service that can service
the WebDAV resource for which the property is set.
Mahy Expires December 27, 2007 [Page 1]
Internet-Draft HTTP Change Notifications via SIP June 2007
Table of Contents
1. Conventions . . . . . . . . . . . . . . . . . . . . . . . . . 3
2. Introduction . . . . . . . . . . . . . . . . . . . . . . . . . 3
3. Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . 3
4. Discovering a change notifier . . . . . . . . . . . . . . . . 5
5. Subscription Filters: setting hierarchies of interest . . . . 6
6. Notification format . . . . . . . . . . . . . . . . . . . . . 7
7. HTTP Resource Change Notification Event Package . . . . . . . 10
7.1. Event Package Name . . . . . . . . . . . . . . . . . . . . 10
7.2. Event Package Parameters . . . . . . . . . . . . . . . . . 10
7.3. SUBSCRIBE Bodies . . . . . . . . . . . . . . . . . . . . . 10
7.4. Subscription Duration . . . . . . . . . . . . . . . . . . 10
7.5. NOTIFY Bodies . . . . . . . . . . . . . . . . . . . . . . 10
7.6. Subscriber generation of SUBSCRIBE requests . . . . . . . 11
7.7. Notifier Processing of SUBSCRIBE Requests . . . . . . . . 11
7.8. Notifier Generation of NOTIFY Requests . . . . . . . . . . 12
7.9. Subscriber Processing of NOTIFY Requests . . . . . . . . . 12
7.10. Handling of Forked Requests . . . . . . . . . . . . . . . 12
7.11. Rate of notifications . . . . . . . . . . . . . . . . . . 12
7.12. State Agents . . . . . . . . . . . . . . . . . . . . . . . 13
7.13. Behavior of a Proxy Server . . . . . . . . . . . . . . . . 13
8. Formal Schemas . . . . . . . . . . . . . . . . . . . . . . . . 13
8.1. Filter Body . . . . . . . . . . . . . . . . . . . . . . . 13
8.2. Notification Body . . . . . . . . . . . . . . . . . . . . 14
9. Security Considerations . . . . . . . . . . . . . . . . . . . 17
10. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 18
11. References . . . . . . . . . . . . . . . . . . . . . . . . . . 18
11.1. Normative References . . . . . . . . . . . . . . . . . . . 18
11.2. Informational References . . . . . . . . . . . . . . . . . 19
Author's Address . . . . . . . . . . . . . . . . . . . . . . . . . 20
Intellectual Property and Copyright Statements . . . . . . . . . . 21
Mahy Expires December 27, 2007 [Page 2]
Internet-Draft HTTP Change Notifications via SIP June 2007
1. Conventions
The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT",
"SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this
document are to be interpreted as described in RFC-2119 [1].
2. Introduction
This document describes a mechanism to subscribe to changes to HTTP
[2]-based resources, and includes specific considerations for WebDAV
and XCAP extensions to HTTP. WebDAV [3] is a set of standard HTTP
extensions to perform remote web content authoring operations,
including hierarchical manipulation of "collections" which are
analogous to directories in a file system, and per-resource metadata
called "properties". DeltaV [4] adds to WebDAV additional support
for explicit version control including merging and forking. XCAP [5]
(XML [6] Configuration Access Protocol) is a generic configuration
protocol layered on top of HTTP. It uses XPath [7] expressions and
XML document fragments to hierarchically access subtrees of an XML
document. Currently XCAP usages are defined for types of resource
lists [19] and authorization lists [20] used in SIP-based presence
systems.
SIP [8] is a rendezvous protocol for manipulating multimedia
sessions, and for conveying presence [21] and other related events
using the SIP Events Framework [9]. Many SIP implementations use
HTTP for features such as configuration [22], buddy-list
manipulation, and providing pointers to web content [10].
Currently, very specific approaches for changes to XCAP documents
have been proposed in [23] and [24]. Both of these use an XML patch
description format described in [11]. The approach in these
documents allows for change notifications about specific subtrees of
an XML document, but provide no facility for change notifications
about more than one document at a time.
Finally, several approaches for pure HTTP-based event notifications
have been proposed [TODO: add refs]. Many of these proposals are
motivated by a desire to provide HTTP change notification. All these
proposals are concerned with directories or collections of files
changing, but cannot provide detail about changes within a structure
document (such as an XML document).
3. Overview
This event package allows a SIP subscriber to ask a responsible
Mahy Expires December 27, 2007 [Page 3]
Internet-Draft HTTP Change Notifications via SIP June 2007
notifier for notifications about changes to HTTP-based resources for
specific resource hierarchies that the subscriber is interested in.
The subscriber generally includes a filter document in the
subscription request to indicate which hierarchies it is interested
in. For resources that are expressed as an XML document, the
subscription filter can further limit notifications to changes in
specific elements or attributes of the document as described in an
XPath expression. Once the subscription is established, when a new
change is made to a resource of interest, the notifier sends a
notification to the subscriber with a summary of the change. The
notifier can also send the content of the change, and the value of
any properties inline if requested.
Since the SIP events framework is designed to work with subscribers
that can be disconnected from the network from time to time, the
model allows the subscriber to ask for notification about changes
which have occured in the recent past so that the subscriber can
resynchronize its state easily when temporarily disconnected.
Inherent in this approach is the concept of a unique version string
for each atomic change on the HTTP server side. This version string
is expressed either as the version-name if DeltaV version control is
enabled, or the HTTP ETag (preferrably a strong ETag) if it is not.
Immediately after a successful subscription request, the notifier
sends a summary of changes since the version last seen by the
subscriber, to allow the subscriber to "catch up".
Even without DeltaV versioning, the underlying data store or
representation for a set of resources may organize changes that all
occur as an atomic transaction. A simple example for WebDAV is that
when the contents of a file are updated, the modification time
property also changes. Notifications for this event package
similarly group specific changes into atoms, which need to be applied
by the notifier all at once or not at all. In addition, if the
subscriber requests summarization, the notifier can combine several
operations and provide them to the subscriber as a single atom. The
subscriber needs to apply this summarized atom as a single unit. For
example, creating a file then deleting it results in no change when
summarized.
This event package specifically deals with the end-result of changes
made as visible from HTTP. To that end, there is no notification
verb to indicate that a resource was checked-out or checked-in.
Instead there is a notification verb to indicate that a WebDAV
property has been set. The notification format has specific verbs
for created, modified, moved, copied, and deleted resource content
and set and removed properties. While these verbs map very closely
to some HTTP methods (MKCOL, PUT, MOVE, COPY, DELETE, and PROPPATCH),
the content does not need to be modified via HTTP to trigger a
Mahy Expires December 27, 2007 [Page 4]
Internet-Draft HTTP Change Notifications via SIP June 2007
notification.
For WebDAV HTTP servers, this document also defines a new WebDAV
property that can be used to determine the SIP URL for a SIP notifier
to this event package for a specific WebDAV resource. Other
discovery approaches, including manual configuration, are possible
but are out of scope for this document.
4. Discovering a change notifier
When using a WebDAV-enabled HTTP server, the HTTP client can query a
resource of interest for the 'DAV:notifier' property. The value of
the property is a complete URI [2] (including the scheme) where the
HTTP client can subscribe for change notifications.
--> Request <--
PROPFIND /~bob/photos/ HTTP/1.1
Host: http://foo.example.com
Content-type: application/xml; charset="utf-8"
Content-Length: xxxx
--> Response <--
HTTP/1.1 207 Multi-Status
Content-Type: application/xml; charset="utf-8"
Content-Length: xxxx
http://foo.example.com/~bob/photos/
sip:blog-notify-service@sip.example.com
HTTP/1.1 200 OK
Mahy Expires December 27, 2007 [Page 5]
Internet-Draft HTTP Change Notifications via SIP June 2007
5. Subscription Filters: setting hierarchies of interest
This section defines the 'application/davnotify-filter+xml' body
type. This subscription filter format lists HTTP resource
hierarchies of interest to the subscriber. The format starts with a
top-level 'filter' element. The filter element can include an
optional boolean 'summarize' attribute. The 'summarize' attribute is
a hint that the subscriber is willing to accept multiple changes
summarized into larger atoms. When present, the notifier can combine
any set of consecutive atomic changes into a larger change which also
needs to be committed atomically by the subscriber. This is only a
hint, the server does not need to summarize multiple changes into a
smaller number of atoms. If this attribute is not present, or set to
false, the notifier MUST NOT summarize changes.
Each hierarchy of interest is described in a 'path' sub-element.
There are several optional attributes of the 'path' element.
http://foo.example.com/~bob/photos/
http://news.example.com/rss-feed.xml
http://xcap.example.com/resource-lists/users/bob/~~
The 'since-version' attribute is provided by the subscriber to
request changes from a particular version of the resource of
interest. If the resource of interest is under DeltaV version
control, the version number is the value of the DAV:version-name
attribute. If the resource is not under version control, the Etag of
the resource is used. [TODO: add more about unknown versions/Etags
or very old ETags]. When a path element contains this attribute, the
notifier MUST either provide changes about this version of the
resource hierarchy, or return an error for the subscription.
The 'inline' attribute is a hint about whether the subscriber would
like the actual contents of a newly changed or added resource
included "inline" in notifications about that resource. This
attribute is a hint, in that the notifier can still omit the content
(for example, if it is larger than the notifier is willing to send
under the circumstances). The default is to omit inline content.
The subscriber can request no inline content, content inline in the
XML pacth operations format [11], content in an adjacent or external
MIME body [25] described using a Content-ID MIME header, or full
content inline.
Mahy Expires December 27, 2007 [Page 6]
Internet-Draft HTTP Change Notifications via SIP June 2007
The 'propval' attribute is a boolean attribute which indicates if the
server should include the values of any changes WebDAV properties.
The default is to omit property values.
If the path to the resource of interest resolves to a single XML
document, the 'xpath' attribute can be included. The 'xcap'
attribute contains an XPath expression that is expected to resolve to
a single contiguous region (the entire contents of a single element
including any sub-elements, or a single attribute value) of the
document of interest. This attribute is motivated by notifications
for XCAP, but can be used for any XML document, even if the target
HTTP server does not support XCAP.
6. Notification format
This section defines the 'application/davdiff+xml' body type. This
notification body type lists the status of each path in the
subscription fitler as well as the changes which are relevant to the
active subscription filter. This body begins with a 'notification'
top-level element, which has one optional 'status' element followed
by one mandatory 'changes' element.
The 'status' element contains as many 'path' elements as were present
in the subscription filter document. The 'path' element has a
mandatory 'code' attribute that includes a 3-digit response code that
corresponds to a SIP or HTTP success or error response relevant to
the subscribed path. For example, a 403 code indicates that access
to the target resource was forbidden, a 404 indicates that the target
resource did not exist, a 406 code indicates that the notifier cannot
apply an XPath expression to a non-XML file, and a 412 code indicates
that the notifier does not have information about the target resource
for the version requested in 'since-version'. Omission of the
'status' element implies that the subscription filter for all
requested paths was acceptable.
The 'changes' element can contain zero or more 'atom' elements. Each
'atom' element contains a set of changes which need to be applied at
once or not at all by the subscriber. The 'atom' element has
mandatory 'since' and 'until' attributes. The 'atom' element will
contain all the resulting changes between the 'since' version string
and the 'until' version string (inclusive).
Each 'atom' element contains zero or more change notification events,
which closely map to a handful of important HTTP operations. Each of
these elements contains a mandatory target 'url' attribute.
New resources which can contain other resources are called
Mahy Expires December 27, 2007 [Page 7]
Internet-Draft HTTP Change Notifications via SIP June 2007
"collections" in WebDAV. We reuse this terminology for WebDAV
collections, ordinary HTTP resources such as directories, and XCAP
paths before the XCAP "document root" ('~~'). When a new collection
resource is created, the 'mkcol' element is included in the
notification. When a non-collection resource is created or modified,
the 'put' element is included in the notification.
If the subscriber requested inline content, the notifier MAY include
the entire new content in a 'content' element. If the subscriber
requested inline XML patches, the notifier MAY include patches in the
format described in [11] in an 'xml-patch' element. If the
subscriber requested content in separate MIME bodies, the notifier
MAY include a 'mimepart' element with a 'content-id' attribute which
matches the Content-ID MIME header in another MIME body in the same
notification. Even if the subscriber requested inline content or
patches, the notifier can decide not to send inline content due to
policy considerations. The notifier MUST NOT send any form of inline
data unless it was specifically requested by the subscriber.
If a resource was deleted, the 'delete' element is included in the
notification. The semantics of this element for collections is an
infinite-depth delete. If a set of resources was moved, the 'move'
element is included in the notifcation for the root of the move
operation. If a set of resources was copied, the 'copy' element is
included in the notification for the root of the copy operation. For
either operation, the 'url' attribute indicates the original root of
the moved or copied files, and the mandatory 'dest' attribute
indicated the new root of the moved or copied files. Moves are
infinite-depth operations. For copies, the mandatory 'infiniteDepth'
boolean attribute indicates if the copy was infinite-depth or for a
single resource (Depth: 1).
Finally, each new or updated property is indicated with a 'propset'
element. [TODO: talk about namespace handling here]. Each deleted
property is indicated with a 'propremove' element. In both cases,
the mandatory 'propname' attribute contains the name of the relevant
property.
Mahy Expires December 27, 2007 [Page 8]
Internet-Draft HTTP Change Notifications via SIP June 2007
http://foo.example.com/~bob/photos/
http://news.example.com/rss-feed.xml
http://xcap.example.com/resource-lists/users/bob/~~
This is a test
This is a test
Mahy Expires December 27, 2007 [Page 9]
Internet-Draft HTTP Change Notifications via SIP June 2007
7. HTTP Resource Change Notification Event Package
This section provides the details for defining a SIP Event package,
as required by [9].
7.1. Event Package Name
The name of this event-package is "davnotify".
7.2. Event Package Parameters
This package does not define any event package parameters.
7.3. SUBSCRIBE Bodies
This package defines the 'application/davnotify-filter+xml' SUBSCRIBE
body format in Section 5, which is used to filter notifications to
include only paths to resources of interest. A new SUBSCRIBE for the
'davnotify' event package typically contain a filter body. If a
filter body is present in a subsequent SUBSCRIBE, it replaces the
previous filter.
A SUBSCRIBE for this package can also be sent without a body. This
implies the default subscription filtering policy for the subscribed
resource, which is to send 'davnotify' notifications for every HTTP
path covered by the subscribed resource that the subscriber has
permissions to read.
Notifiers which support this specification, MUST support at least the
'application/davnotify-filter+xml' filter body, but can negotiate the
use of other filter bodies.
7.4. Subscription Duration
Subscriptions to this event package MAY range from minutes to weeks.
Subscriptions in hours or days are more typical and are RECOMMENDED.
The default subscription duration for this event package is one hour.
7.5. NOTIFY Bodies
Changes to the state of HTTP-based resources of interest are sent
periodically in NOTIFY requests in any format acceptable to the
subscriber (based on the subscriber inclusion of these formats in an
Accept header). In Section 6, this package defines the 'application/
davdiff+xml' body format to carry these changes. Both subscribers
and notifiers MUST implement the 'application/davdiff+xml' body
format.
Mahy Expires December 27, 2007 [Page 10]
Internet-Draft HTTP Change Notifications via SIP June 2007
Since this package describes changes to the state of HTTP-based
resources, it is possible that the notifier needs to send a NOTIFY
request due solely to normal RFC 3265 [9] overhead when no changes
have been made to the HTTP resources of interest. In this case, a
NOTIFY request is sent with no body.
7.6. Subscriber generation of SUBSCRIBE requests
The subscriber subscribes to a resource and includes a filter. It
can include the summarize parameter. It can include the since-
version parameter. [TODO: finish this]
The subscriber can further use the 'throttle' Event header parameter
defined in [12] to ask the notifier to throttle the notification rate
to a specific rate.
New subscribe requests establish a notification filter. Subsequent
subscriptions keep the same filter unless a new filter is provided.
If a new filter is provided in a subscription, it completely replaces
the previous filter.
Subscriber User Agents will typically SUBSCRIBE to HTTP change
notification information for a period of hours or days, and
automatically attempt to re-SUBSCRIBE well before the subscription is
completely expired. If re-subscription fails, the Subscriber SHOULD
periodically retry again until a subscription is successful, taking
care to backoff to avoid network congestion. If a subscription has
expired, new re-subscriptions MUST use a new Call-ID.
The Subscriber MAY also explicitly fetch the current status at any
time. The subscriber SHOULD renew its subscription immediately after
a reboot, or when the subscriber's network connectivity has just been
re-established.
The Subscriber MUST be prepared to receive and process a NOTIFY with
new state immediately after sending a new SUBSCRIBE, a SUBSCRIBE
renewal, an unsubscribe, or a fetch; or at any time during the
subscription.
7.7. Notifier Processing of SUBSCRIBE Requests
When the notifier receives a SUBSCRIBE request for this event
package, it first MUST authenticate and authorize the subscription
request if the target HTTP resources are themselves subject to
authentication. The notifier MAY authenticate subscribers even for
public HTTP resources. The notifier also examines any filter body
that is present and verifies that the HTTP paths requested are within
its notification scope. Any paths requested which are not covered by
Mahy Expires December 27, 2007 [Page 11]
Internet-Draft HTTP Change Notifications via SIP June 2007
this notifier or do not yet exist are silently ignored by the
notifier. If the filter contains a path to which the subscriber does
not have permission to read, the notifier MAY reject the subscription
with a 403 Forbidden response, as long as sending the error does not
result in leaking information which would otherwise be private.
If the 'since-version' Event header parameter was included in the
SUBSCRIBE request, the notifier should verify that the corresponding
ETag or DAV version string exists, and that the notifier can provide
changes since this version. If not, the notifier rejects the request
with a 412 "Conditional Request Failed" response (defined in [13].
If no specific version is requested, the notifier starts from the
current version. [Editor's Note: Move this feature to the filter
body so different resources can have have difference since-versions.]
If present, the notifier can use the 'throttle' parameter as a hint
from the client to limit notifications. If a throttle is
established, the actual period is returned in the 'throttle'
parameter of each Subscription-State header.
7.8. Notifier Generation of NOTIFY Requests
Immediately after a subscription is accepted or refreshed, the
notifier sends a NOTIFY with the changes since the specified version
(if a version was specified). If there are no changes, the NOTIFY is
sent with an empty body. If several atomic changes were made since
the requested version, the notifier can send several of these changes
at a time. If the 'summarize' parameter was requested, the notifier
can consolidate atomic changes without preserving version history.
The notifier is expected to throttle the rate of notifications to or
below the value of any 'throttle' parameter it provided in the
Subscription-State header.
7.9. Subscriber Processing of NOTIFY Requests
No special requirements are introduced here.
7.10. Handling of Forked Requests
This event package MUST NOT install multiple subscriptions.
7.11. Rate of notifications
Notifiers SHOULD NOT generate NOTIFY requests more frequently than
ten per second, nor more frequently than thirty in a thirty-second
period of time. In addition, notifiers and subscribers MAY implement
the notification throttling mechanism described in [12].
Mahy Expires December 27, 2007 [Page 12]
Internet-Draft HTTP Change Notifications via SIP June 2007
7.12. State Agents
This document does not preclude implementations from building state
agents which support this event package.
7.13. Behavior of a Proxy Server
There are no additional requirements on a SIP Proxy, other than to
transparently forward the SUBSCRIBE and NOTIFY methods as required in
SIP.
8. Formal Schemas
8.1. Filter Body
Below is a Relax NG [14] schema for the change notification filter
format.
Mahy Expires December 27, 2007 [Page 13]
Internet-Draft HTTP Change Notifications via SIP June 2007
none
full
patch
mime
8.2. Notification Body
Below is a Relax NG [14] schema for the change notification format.
Mahy Expires December 27, 2007 [Page 14]
Internet-Draft HTTP Change Notifications via SIP June 2007